Data Engineering Tutor MCP Server

数据工程导师 MCP 服务

此仓库包含一个使用 Node.js 和 TypeScript 构建的简单 Model Context Protocol（MCP）服务。它充当“数据工程导师”，为连接的 AI 客户端提供有关数据工程概念、模式和技术的个性化更新。

此服务展示了 MCP 的核心概念：定义资源、工具和提示词，从而创建有状态的交互式 Agent 助手。

先决条件

• Node.js（建议使用 v18 或更高版本）
• npm（或你偏好的 Node.js 包管理器，例如 yarn 或 pnpm）
• 能够连接到 MCP 服务的 AI 客户端（例如 Cursor、Claude 桌面应用）
• OpenRouter API 密钥（用于通过 Perplexity 获取实时数据工程更新）

设置

1. 克隆仓库：

   # 如果你还没有克隆
   # git clone <repository-url>
   # cd <repository-directory>
   

2. 安装依赖项：

   npm install
   

3. 准备 API 密钥： de_tutor_get_updates 工具需要 OpenRouter API 密钥。

   • 从 OpenRouter 获取密钥。
   • 在项目根目录中创建一个 .env 文件（可以复制 .env.example）。
   • 将密钥添加到 .env 文件中：

     OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxx
     

     （请将占位符替换为你的实际密钥。）

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

   npm run build
   

运行服务

你可以直接使用 Node 运行服务：

node build/index.js

或者，配置 MCP 客户端（例如 Cursor 或 Claude 桌面应用）以启动此服务。服务名称为 de-tutor，二进制文件名（客户端配置需要时）也为 de-tutor。

客户端配置示例（例如 Claude Desktop）：

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

（请确保 args 中的路径是系统上已构建的 index.js 文件的正确绝对路径。如果你已经使用 .env 文件，则可能不需要在此处添加 env 部分，因为服务会通过 dotenv 直接加载该文件。）

在 Cursor 中使用

Cursor 是一款 AI 优先的代码编辑器，可作为 MCP 客户端。要在 Cursor 中设置此服务，需要配置服务启动方式，并且可能需要设置 Project Rule 来提供指导提示词，不过 Cursor 也可能会自动读取服务提供的提示词。

1. 在 Cursor 中配置服务：

   • 前往 Cursor Settings > MCP > Add new global MCP server。
   • 粘贴与上方客户端配置示例相同的 JSON，并确保 build/index.js 的路径适用于你的系统。

2. （可选）为提示词创建 Cursor Project Rule： 如果你更喜欢明确的规则，或者发现 Cursor 没有自动使用服务的提示词，可以通过 Cursor 的 Project Rules 功能提供指导。

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

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

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

     你是一名友好的助手，连接到一个数据工程知识服务。你的目标是根据用户尚未接触过的数据工程概念、模式和技术，为用户提供个性化的最新资讯。
     
     可用工具：
     1.  `de_tutor_get_updates`：获取近期的数据工程新闻和文章。首先使用此工具了解最新动态。
     2.  `de_tutor_read_memory`：根据用户存储的知识档案，检查用户已经了解哪些数据工程概念。
     3.  `de_tutor_write_memory`：更新用户档案，标记用户是否已学会或已经了解更新中提到的特定数据工程概念。
     
     工作流：
     1.  调用 `de_tutor_get_updates`，了解近期的数据工程进展。
     2.  调用 `de_tutor_read_memory`，了解用户当前的知识库。
     3.  向用户介绍最新进展，重点说明他们可能不了解的内容。
     4.  如果用户确认自己了解或已经学会某个概念，调用 `de_tutor_write_memory` 更新其档案。
     
     请简明扼要，专注于提供与用户现有知识相关的新信息。
     

3. 连接并使用：

   • 确保在 Cursor 的 MCP 设置中启用了 de-tutor 服务。
   • 如果使用规则文件，请开始新的聊天或代码生成请求（例如 Cmd+K），并在请求中加入 @de-tutor-rule（或你为规则文件指定的名称）。这会告知 Cursor 加载该规则的内容，并提供如何使用这些工具的说明。
   • 如果依赖服务提示词，只需开始与 Cursor 交互；它应该能够访问这些工具以及服务提供的指导提示词。

功能与用法

此服务提供以下功能：

• 资源（data_engineering_knowledge_memory）： 在 data/data-engineering-knowledge.json 中存储一个简单的 JSON 对象，将已知概念（字符串）映射为布尔标记（true）。
• 工具：
  • de_tutor_read_memory：从 JSON 文件中读取当前已知的概念。
  • de_tutor_write_memory：更新 JSON 文件，将某个概念标记为已知（true）或未知（false）。输入参数为 concept（字符串）和 known（布尔值）。
  • de_tutor_get_updates：使用你的 OpenRouter API 密钥查询 Perplexity（perplexity/sonar-small-online），获取近期的数据工程新闻、模式和技术。
• 提示词（data-engineering-tutor-guidance）： 为连接的 AI 客户端提供如何在工作流中使用这些工具的说明：
  1. 获取最新资讯。
  2. 从记忆中读取已知概念。
  3. 向用户介绍新信息。
  4. 根据用户反馈更新记忆。

开发与调试

• 构建： npm run build 会将 TypeScript 编译为 JavaScript，并输出到 build/ 目录。
• 代码结构： 有关实现细节，请参阅 src/：
  • src/index.ts：服务入口点。从特定 SDK 路径导入 McpServer 和 StdioServerTransport。实例化 McpServer。从其他模块导入并调用注册函数（registerPrompts、registerResources、registerTools），并传入服务实例。使用 StdioServerTransport 设置并连接服务。
  • src/prompts/index.ts：定义指导提示词文本。导出 registerPrompts，该函数接收 McpServer 实例，并使用 server.prompt() 及其回调注册静态指导提示词。
  • src/resources/index.ts：导出 KnowledgeMemory 类型和用于对 data/data-engineering-knowledge.json 进行文件读写的辅助函数（readMemoryFile、writeMemoryFile）。导出 registerResources，该函数接收 McpServer 实例，并使用 server.resource() 注册 data_engineering_knowledge_memory 资源及其特定 URI 和 ReadResourceCallback。
  • src/tools/index.ts：导出 registerTools，该函数接收 McpServer 实例，并使用 server.tool() 注册各个工具（de_tutor_read_memory、de_tutor_write_memory、de_tutor_get_updates）。在需要时使用 Zod 定义输入架构（用于 write_memory）。工具函数使用 resources/index.ts 中的辅助函数或 fetch 执行操作，并以预期格式返回结果。
• MCP Inspector： 使用 @modelcontextprotocol/inspector 查看原始消息流：

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

  （如果以这种方式运行，且不单纯依赖服务自身加载的 .env 文件，请确保环境中已设置 OPENROUTER_API_KEY。）

注意事项

• 此服务使用简单的文件（data/data-engineering-knowledge.json）存储用户知识。对于更健壮的应用，请考虑使用合适的数据库。
• 错误处理较为基础；生产环境中的服务需要更全面的错误管理。

总结

本演示展示了使用 TypeScript SDK 和 McpServer 类创建可用 MCP 服务所涉及的核心步骤。我们定义了用于管理状态的资源、用于执行操作（包括与外部 API 交互）的工具，以及用于指导 AI 客户端的提示词。

这为使用 MCP 构建更复杂、更实用的 Agent 能力奠定了基础。

（另外，如果你遇到任何 🐛错误，欢迎提交 issue。）