构建 CSS Tutor MCP 服务器

此仓库包含一个使用 Node.js 和 TypeScript 构建的简单模型上下文协议 (MCP) 服务器。它充当一个“CSS Tutor”，为连接的 AI 客户端提供关于 CSS 功能的个性化更新。

此服务器演示了关键的 MCP 概念：定义资源 (Resources)、工具 (Tools) 和 提示 (Prompts)。此演示的目标是帮助您从这里开始，构建更大、更有趣的代理能力。

前提条件

• Node.js (建议 v18 或更高版本)
• 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 Settings > MCP > Add new global MCP server。
   • 将与上面 Claude Desktop 步骤中相同的 JSON 粘贴进去，并具有所有相同的注意事项。

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

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

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

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

     You are a helpful assistant connecting to a CSS knowledge server. Your goal is to provide the user with personalized updates about new CSS features they haven't learned yet.
     
     Available Tools:
     1.  `get_latest_updates`: Fetches recent general news and articles about CSS. Use this first to see what's new.
     2.  `read_from_memory`: Checks which CSS concepts the user already knows based on their stored knowledge profile.
     3.  `write_to_memory`: Updates the user's knowledge profile. Use this when the user confirms they have learned or already know a specific CSS concept mentioned in an update.
     
     Workflow:
     1.  Call `get_latest_updates` to discover recent CSS developments.
     2.  Call `read_from_memory` to get the user's current known concepts (if any).
     3.  Compare the updates with the known concepts (if any). Identify 1-2 *new* concepts relevant to the user. **Important: They _must_ be from the response returned by `get_latest_updates` tool.**
     4.  Present these new concepts to the user, adding any context as needed, in addition to the information returned by the `get_latest_updates`.
     5.  Ask the user if they are familiar with these concepts or if they've learned them now.
     6.  If the user confirms knowledge of a concept, call `write_to_memory` to update their profile for that specific concept.
     7.  Focus on providing actionable, personalized learning updates.
     

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 客户端并启动您的服务器，向您显示通信流程。

从项目根目录的终端运行 inspector：

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

说明：

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

Inspector 的环境变量：

请注意，inspector 将您的服务器作为子进程启动。如果您的服务器依赖于环境变量（例如 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 客户端的提示。

希望此演示可以帮助您了解如何构建比此服务器复杂得多（且更有用）的服务器！

（另外，如果您遇到任何 🐛bugs，请随时提出问题。）