构建一个CSS导师MCP服务器

此仓库包含了一个使用Node.js和TypeScript构建的简单Model Context Protocol (MCP)服务器。它充当“CSS导师”，向连接的AI客户端提供关于CSS特性的个性化更新。

该服务器演示了关键的MCP概念：定义资源、工具和提示。本演示的目标是帮助您在此基础上构建更大且更有趣的代理能力。

预备条件

• Node.js（推荐版本18或更高）
• npm（或您首选的Node.js包管理器如yarn或pnpm）
• 能够连接到MCP服务器的AI客户端（例如，Claude桌面应用）
• OpenRouter API密钥（用于通过Perplexity获取实时CSS更新）

快速开始

按照以下步骤快速启动服务器：

1. 克隆仓库：

   git clone https://github.com/3mdistal/css-mcp-server.git
   cd css-mcp-server
   

2. 安装依赖项：

   npm install # 或：yarn install / pnpm install
   

3. 准备API密钥： get_latest_updates工具需要一个OpenRouter API密钥。从OpenRouter获取您的密钥。您将在第5步中将此密钥提供给您的MCP客户端。

4. 构建服务器： 编译TypeScript代码。

   npm run build # 或：yarn build / pnpm run build
   

5. 配置您的MCP客户端： 告诉您的客户端如何启动服务器，并将API密钥作为环境变量提供。这里是一个针对Claude桌面应用的claude_desktop_config.json示例：

   {
     "mcpServers": {
       "css-tutor": {
         "command": "node",
         "args": [
           "/full/path/to/your/css-mcp-server/build/index.js"
         ],
         "env": {
           "OPENROUTER_API_KEY": "sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxx"
         }
       }
     }
   }
   

   (确保args中的路径是系统上构建好的index.js文件的正确绝对路径。替换占位符API密钥。)

6. 连接： 从您的MCP客户端开始连接。客户端将启动服务器进程（带有环境中的API密钥），您可以开始交互！

使用Cursor

Cursor是一款以AI为中心的代码编辑器，可以作为MCP客户端。设置此服务器与Cursor的连接非常简单，但需要额外一步来指导提示。

1. 在Cursor中配置服务器：

   • 进入Cursor设置 > MCP > 添加新的全局MCP服务器。
   • 在Claude桌面步骤中粘贴相同的JSON，所有注意事项都相同。

2. 创建Cursor项目规则以供提示： 目前Cursor不会自动使用服务器提供的MCP提示。相反，您需要使用Cursor的项目规则功能来提供指导。

   • 如果不存在，请在项目根目录下创建.cursor/rules目录。

   • 在其中创建一个名为css-tutor.rule（或任何.rule文件名）的文件。

   • 将以下指导文本粘贴到css-tutor.rule中：

     您是一个连接到CSS知识服务器的有用助手。您的目标是为用户提供有关他们尚未学习的新CSS特性的个性化更新。
     
     可用工具：
     1.  `get_latest_updates`：获取关于CSS的最新通用新闻和文章。首先使用此工具查看有什么新内容。
     2.  `read_from_memory`：根据用户存储的知识概况检查用户已经知道哪些CSS概念。
     3.  `write_to_memory`：更新用户的知识概况。当用户确认他们已了解或已经知道更新中提到的具体CSS概念时使用此工具。
     
     工作流程：
     1.  调用`get_latest_updates`以发现最近的CSS发展。
     2.  调用`read_from_memory`以获取用户当前已知的概念（如果有）。
     3.  将更新与已知概念进行比较（如果有）。识别1-2个对用户相关的*新*概念。**重要：它们必须来自`get_latest_updates`工具返回的响应。**
     4.  向用户呈现这些新概念，如有必要，添加任何上下文信息，以及`get_latest_updates`返回的信息。
     5.  询问用户是否熟悉这些概念或现在是否已学会。
     6.  如果用户确认了解某个概念，则调用`write_to_memory`以更新其特定概念的概况。
     7.  专注于提供可操作的个性化学习更新。
     

3. 连接并使用：

   • 确保在Cursor的MCP设置中启用了css-tutor服务器。
   • 开始一个新的聊天或代码生成请求（例如，Cmd+K），并在请求中包括@css-tutor-rule（或您命名的规则文件名）。这告诉Cursor加载规则的内容，其中包括如何使用连接的MCP服务器提供的read_from_memory、write_to_memory和get_latest_updates工具的指令。

请注意，如果没有提示/规则，Cursor仍然可以在您要求时使用单个工具。提示提供了调用工具和读写内存的工作流程和顺序。

了解代码

本节提供了一个高层次的概述，说明服务器是如何实现的。

使用的MCP概念

• 资源（css_knowledge_memory）： 表示用户已知的CSS概念，持久地存储在data/memory.json中。
• 工具： 服务器可以执行的操作：
  • get_latest_updates：从OpenRouter/Perplexity获取CSS新闻。
  • read_from_memory：读取css_knowledge_memory资源的内容。
  • write_to_memory：修改css_knowledge_memory资源。
• 提示（css-tutor-guidance）： 静态指令，指导AI客户端如何有效地与工具和资源互动。

代码结构

代码组织如下：

• data/memory.json：一个简单的JSON文件，充当已知CSS概念的数据库。默认版本包含在仓库中。
• src/resources/index.ts：定义css_knowledge_memory资源。它包括：
  • 使用Zod验证数据的模式。
  • 文件I/O的readMemory和writeMemory函数。
  • 使用server.resource注册，指定memory://URI方案和读写权限。读取处理器返回data/memory.json的内容。
• src/tools/index.ts：使用server.tool定义三个工具：
  • read_from_memory：调用readMemory。
  • write_to_memory：接受concept和known作为输入（使用Zod定义的模式），使用readMemory和writeMemory更新JSON文件。
  • get_latest_updates：需要OPENROUTER_API_KEY，使用node-fetch和perplexity/sonar-pro模型调用OpenRouter API，返回AI生成的摘要。
• src/prompts/index.ts：使用server.prompt定义静态的css-tutor-guidance提示。提示文本直接嵌入代码中。
• src/index.ts：主服务器入口点。
  • 初始化来自@modelcontextprotocol/sdk的McpServer实例。
  • 导入并调用其他模块中的registerPrompts、registerResources和registerTools函数。
  • 使用StdioServerTransport处理标准输入/输出通信。
  • 将服务器连接到传输，并包括基本错误处理。
• package.json：定义依赖项（@modelcontextprotocol/sdk、dotenv、node-fetch、zod）和build脚本（tsc）。
• .env.example / .env：用于存储OPENROUTER_API_KEY（如果使用选项A进行配置）。
• .gitignore：配置为忽略node_modules、build、.env以及data/的内容，除了默认的data/memory.json。
• tsconfig.json：标准TypeScript配置。

使用MCP Inspector调试

如果您需要调试服务器或检查交换的原始JSON-RPC消息，可以使用@modelcontextprotocol/inspector工具。此工具充当基本的MCP客户端并启动您的服务器，显示通信流。

在项目根目录下的终端运行检查器：

npx @modelcontextprotocol/inspector node ./build/index.js

解释：

• npx @modelcontextprotocol/inspector：下载（如果需要）并运行检查器包。
• node：用于执行您的服务器的命令。
• ./build/index.js：相对于您的项目根目录的编译服务器入口点的路径。

检查器的环境变量：

注意，检查器作为子进程启动您的服务器。如果您的服务器依赖于环境变量（如get_latest_updates工具所需的OPENROUTER_API_KEY），您需要确保它们在运行npx命令的环境中可用。.env文件在这种情况下可能不会自动加载。通常可以前置命令：

# Linux/macOS示例
OPENROUTER_API_KEY="sk-or-xxxxxxxxxx" npx @modelcontextprotocol/inspector node ./build/index.js

# Windows（命令提示符）示例
set OPENROUTER_API_KEY=sk-or-xxxxxxxxxx && npx @modelcontextprotocol/inspector node ./build/index.js

# Windows（PowerShell）示例
$env:OPENROUTER_API_KEY="sk-or-xxxxxxxxxx"; npx @modelcontextprotocol/inspector node ./build/index.js

替换sk-or-xxxxxxxxxx为您实际的密钥。

总结

此演示展示了使用TypeScript SDK创建功能性MCP服务器的核心步骤。我们定义了一个资源来管理状态，定义了执行操作的工具（包括与外部API交互），并定义了一个提示来指导AI客户端。

希望这个演示能帮助您理解如何构建比这个更复杂（且有用的）服务器！

（如果您遇到任何🐛问题，请随时打开一个issue。）