构建CSS导师MCP服务器
此仓库包含一个使用Node.js和TypeScript构建的简单模型上下文协议（MCP）服务器。它充当“CSS导师”，为连接的AI客户端提供有关CSS功能的个性化更新。
此服务器演示了MCP的关键概念：定义 资源, 工具，以及 鼓励。本演示的目标是帮助您从这里继续前进，构建更大、更有趣的代理功能。
先决条件
- Node.js（建议使用v18或更高版本）
npm（或者你喜欢的Node.js包管理器，比如yarn或pnpm)- 能够连接到MCP服务器的AI客户端（例如Claude桌面应用程序）
- 一 OpenRouter API密钥 （用于通过Perplexity获取实时CSS更新）
快速开始
按照以下步骤快速运行服务器：
- 克隆存储库：
git clone https://github.com/3mdistal/css-mcp-server.git
cd css-mcp-server- 安装依赖关系：
npm install # Or: yarn install / pnpm install- 准备API密钥： 这
get_latest_updates工具需要一个OpenRouter API密钥。从以下位置获取密钥 OpenRouter 的。您将在步骤5中向MCP客户端提供此密钥。
- 构建服务器： 编译TypeScript代码。
npm run build # Or: yarn build / pnpm run build- 配置您的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键。)*
- 连接： 从MCP客户端启动连接。客户端将启动服务器进程（在其环境中使用API密钥），然后您就可以开始交互了！
与光标一起使用
光标 是一个AI优先的代码编辑器，可以充当MCP客户端。使用Cursor设置此服务器很简单，但需要额外的指导提示步骤。
- 在游标中配置服务器：
- 首选 Cursor Settings > MCP > Add new global MCP server. - 在Claude Desktop步骤中粘贴与上述相同的JSON，并添加所有相同的注意事项。
- 为提示创建游标项目规则： Cursor当前不会自动使用服务器提供的MCP提示。相反，您需要使用Cursor的 项目规则 功能。
- 创建目录 .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.- 连接和使用：
- 确保 css-tutor 服务器已在Cursor的MCP设置中启用。 - 启动新的聊天或代码生成请求（例如Cmd+K），并包括 @css-tutor-rule （或您命名的规则文件）。此操作将告诉Cursor加载规则的内容，其中包括有关如何使用 read_from_memory, write_to_memory，以及 get_latest_updates 由连接的MCP服务器提供的工具。
请注意 _没有_ 提示/规则，如果您要求，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 文件I/O的函数。 - 注册使用 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，使用调用OpenRouter API node-fetch 和那个 perplexity/sonar-pro 模型，返回AI生成的摘要。
src/prompts/index.ts：定义静态css-tutor-guidance提示使用server.prompt提示文本直接嵌入到代码中。src/index.ts：主服务器入口点。
- 初始化 McpServer 实例来自 @modelcontextprotocol/sdk. - 进口和调用 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检查器进行调试
如果您需要调试服务器或检查正在交换的原始JSON-RPC消息，可以使用 @modelcontextprotocol/inspector 工具。此工具充当基本的MCP客户端，并启动您的服务器，向您显示通信流。
从项目根目录中的终端运行检查器：
npx @modelcontextprotocol/inspector node ./build/index.js说明：
npx @modelcontextprotocol/inspector：下载（如果需要）并运行检查器包。node：用于执行服务器的命令。./build/index.js：编译后的服务器入口点的路径（相对于项目根）。
检查器的环境变量：
请注意，检查器将您的服务器作为子进程启动。如果您的服务器依赖于环境变量（如 OPENROUTER_API_KEY 为了 get_latest_updates 工具），您需要确保它们在运行的环境中可用 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客户端的提示。
希望这个演示能帮助你理解如何构建比这个更复杂（也更有用）的服务器！
（另外，如果你遇到任何🐛bug，请随时提出问题。）