Building a CSS Tutor MCP Server

构建 CSS Tutor MCP 服务

此代码库包含一个使用 Node.js 和 TypeScript 构建的简单 Model Context Protocol（MCP）服务。它充当“CSS Tutor”，向连接的 AI 客户端提供个性化的 CSS 功能更新。

此服务演示了 MCP 的核心概念：定义资源、工具和提示词。本示例旨在帮助你在此基础上继续构建规模更大、功能更有趣的 Agent 能力。

前提条件

• Node.js（建议使用 v18 或更高版本）
• npm（或你偏好的 Node.js 包管理器，例如 yarn 或 pnpm）
• 能够连接到 MCP 服务的 AI 客户端（例如 Claude 桌面应用）
• OpenRouter API Key（用于通过 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 Key： get_latest_updates 工具需要 OpenRouter API Key。请从 OpenRouter 获取密钥。你将在第 5 步将此密钥提供给 MCP 客户端。

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

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

5. 配置 MCP 客户端： 告知客户端如何启动服务，并将 API Key 作为环境变量提供。以下是 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 Key。）

6. 连接： 从 MCP 客户端启动连接。客户端会启动服务进程（并在其环境中提供 API Key），随后你即可开始交互！

在 Cursor 中使用

Cursor 是一款以 AI 为先的代码编辑器，可充当 MCP 客户端。使用 Cursor 配置此服务很简单，但需要额外设置提示词。

1. 在 Cursor 中配置服务：

   • 前往 Cursor Settings > MCP > Add new global MCP server。
   • 粘贴与 Claude Desktop 步骤中相同的 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 模式。
  • 用于文件读写的 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 文件可能不会自动加载。通常可以在命令前添加环境变量：

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

# Example on Windows (Command Prompt)
set OPENROUTER_API_KEY=sk-or-xxxxxxxxxx && npx @modelcontextprotocol/inspector node ./build/index.js

# Example on 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。）