toyMCP To-Do List Server

toyMCP 待办事项列表服务

这是一个简单的示例服务，使用模型上下文协议（MCP）的概念实现待办事项列表 CRUD API，具体采用基于 HTTP 的 JSON-RPC 2.0。

它使用 Node.js、Express 和 PostgreSQL（通过 Docker）进行持久化。

组件

该项目由两个主要组件构成：

1. MCP Server：用于管理待办事项的 JSON-RPC API 服务
2. Agent Framework：使用 AI 模型与 MCP 服务交互的自然语言界面

设置

1. 先决条件：

   • Node.js（建议使用 LTS 版本）
   • npm（通常随 Node.js 一起安装）
   • Docker 和 Docker Compose

2. 克隆仓库（如适用）：

   # git clone ...
   # cd toyMCP
   

3. 安装依赖：

   npm install
   

4. 启动 PostgreSQL 数据库： 确保 Docker Desktop（或 Docker 守护进程）正在运行。

   docker compose up -d db
   

   这会在后台启动一个名为 toymcp_db 的 PostgreSQL 容器，并为其数据创建一个持久卷。

5. 运行服务：

   npm start
   

   服务会在必要时初始化数据库架构，并开始监听 http://localhost:3000（或 PORT 环境变量指定的端口）。 JSON-RPC 端点为 http://localhost:3000/rpc。 Swagger API 文档界面位于 http://localhost:3000/api-docs。

全新启动服务

如果需要确保服务从全新的数据库启动（例如，在运行手动端到端测试之前或重置状态时），可以使用 clean_start.sh 脚本：

1. 停止正在运行的服务（如有），在其运行所在的终端中按 Ctrl+C。
2. 确保脚本可执行：

   chmod +x clean_start.sh
   

3. 运行脚本：

   ./clean_start.sh
   

   此脚本会停止并移除数据库容器（docker compose down），重新启动它（docker compose up -d db），然后启动 Node.js 服务（npm start）。

运行测试

确保 PostgreSQL 容器正在运行（docker compose up -d db）。

测试分为 tests/unit_tests 和 tests/integration_tests。以下命令会运行所有测试：

npm test

生成覆盖率报告

npm run coverage

这会在终端输出摘要，并在 coverage/lcov-report/ 目录中生成详细的 HTML 报告，反映单元测试和集成测试的覆盖率。

运行端到端测试脚本

该项目包含一个编排脚本（run_full_test.sh），它会使用 curl 对运行中的服务执行完整的测试流程，包括事先清理数据库并提供摘要报告。建议使用此脚本进行手动端到端检查。

先决条件： curl、jq

chmod +x run_full_test.sh test_server.sh # Ensure scripts are executable
./run_full_test.sh

API 文档

可通过 Swagger UI 查看交互式 API 文档，包括本地版本（服务运行时）和通过 GitHub Pages 部署的版本：

• 本地 Swagger UI： http://localhost:3000/api-docs
• GitHub Pages Swagger UI： https://izaqyos.github.io/toyMCP/swagger-ui/

文档会使用 swagger-jsdoc，根据 src/swagger_definitions.js 中的 JSDoc 注释自动生成。

API 用法

身份验证

大多数 API 端点都需要使用 JSON Web Token（JWT）进行身份验证。

1. 登录： 首先，向 /auth/login 发送 POST 请求，并在 JSON 请求体中提供用户名和密码：

   curl -X POST -H "Content-Type: application/json" \
        -d '{"username": "testuser", "password": "password123"}' \
        http://localhost:3000/auth/login
   

   成功响应：

   {
       "message": "Login successful",
       "user": { "id": 1, "username": "testuser" },
       "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
   }
   

2. 使用令牌： 复制收到的 token 值。后续向受保护端点（如 /rpc）发送请求时，请将其作为 Bearer 令牌包含在 Authorization 标头中：

   TOKEN="YOUR_JWT_TOKEN_HERE" # 替换为实际令牌
   curl -X POST -H "Content-Type: application/json" \
        -H "Authorization: Bearer $TOKEN" \
        -d '{"jsonrpc": "2.0", "method": "mcp.discover", "id": 1}' \
        http://localhost:3000/rpc
   

JSON-RPC 端点（/rpc）

向 http://localhost:3000/rpc 发送 POST 请求，并在请求中设置 Content-Type: application/json、Authorization: Bearer <token> 标头，以及 JSON-RPC 2.0 格式的请求体。

可用方法：

• todo.list：列出所有待办事项。
• todo.add：添加新的待办事项（params: { "text": "..." }）。
• todo.remove：移除待办事项（params: { "id": ... }）。
• mcp.discover：描述服务及其可用方法。

工具示例： curl（假设你已通过 /auth/login 获取有效的 $TOKEN）

• 发现服务（mcp.discover）

  curl -X POST -H "Content-Type: application/json" \
       -H "Authorization: Bearer $TOKEN" \
       -d '{"jsonrpc": "2.0", "method": "mcp.discover", "id": 1}' \
       http://localhost:3000/rpc
  

  成功响应（示例）：

  {
      "jsonrpc": "2.0",
      "result": {
          "mcp_version": "1.0.0",
          "name": "ToyMCP Todo Service",
          "description": "A simple To-Do list manager implementing MCP concepts.",
          "methods": [
              {"name": "todo.list", ...},
              {"name": "todo.add", ...},
              {"name": "todo.remove", ...},
              {"name": "mcp.discover", ...}
          ]
      },
      "id": 1
  }
  

• 添加事项（todo.add）

  curl -X POST -H "Content-Type: application/json" \
       -H "Authorization: Bearer $TOKEN" \
       -d '{"jsonrpc": "2.0", "method": "todo.add", "params": {"text": "Buy groceries"}, "id": 1}' \
       http://localhost:3000/rpc
  

  成功响应：

  {
      "jsonrpc": "2.0",
      "result": {
          "id": 1,
          "text": "Buy groceries",
          "created_at": "2025-04-07T16:15:00.123Z"
      },
      "id": 1
  }
  

• 列出事项（todo.list）

  curl -X POST -H "Content-Type: application/json" \
       -H "Authorization: Bearer $TOKEN" \
       -d '{"jsonrpc": "2.0", "method": "todo.list", "id": 2}' \
       http://localhost:3000/rpc
  

  成功响应（示例）：

  {
      "jsonrpc": "2.0",
      "result": [
          {
              "id": 1,
              "text": "Buy groceries",
              "created_at": "2025-04-07T16:15:00.123Z"
          }
          // ... other items
      ],
      "id": 2
  }
  

• 移除事项（todo.remove） （假设存在 ID 为 1 的事项）

  curl -X POST -H "Content-Type: application/json" \
       -H "Authorization: Bearer $TOKEN" \
       -d '{"jsonrpc": "2.0", "method": "todo.remove", "params": {"id": 1}, "id": 3}' \
       http://localhost:3000/rpc
  

  成功响应：

  {
      "jsonrpc": "2.0",
      "result": {
          "id": 1,
          "text": "Buy groceries",
          "created_at": "2025-04-07T16:15:00.123Z"
      },
      "id": 3
  }
  

• 错误响应示例（未找到事项）

  curl -X POST -H "Content-Type: application/json" \
       -H "Authorization: Bearer $TOKEN" \
       -d '{"jsonrpc": "2.0", "method": "todo.remove", "params": {"id": 999}, "id": 4}' \
       http://localhost:3000/rpc
  

  响应：

  {
      "jsonrpc": "2.0",
      "error": {
          "code": 1001,
          "message": "Todo item with ID 999 not found"
      },
      "id": 4
  }
  

Agent 框架

此代码仓库包含一个 AI 驱动的 Agent 框架，为 MCP 服务提供自然语言接口。该 Agent 使用本地 Ollama 模型或 OpenAI 的云端模型来理解用户指令，并对待办事项列表执行相应操作。

架构

┌───────────────┐    ┌────────────────┐    ┌───────────────┐
│ LLM Provider  │◄───┤ Agent Framework├───►│  toyMCP API   │
│ (Ollama/Cloud)│    │                │    │  (Todo Server)│
└───────────────┘    └────────────────┘    └───────────────┘

设置和使用

Agent 框架位于 agent-framework/ 目录中。使用方法：

1. 设置环境：

   cd agent-framework
   npm install
   cp .env-example .env    # Configure settings as needed
   npm run build
   

2. 使用自然语言管理待办事项列表：

   # Add a task
   node index.js "Add milk to my shopping list"
   
   # List all tasks
   node index.js "What's on my todo list?"
   
   # Remove a task
   node index.js "Remove the shopping task"
   
   # Debug mode
   node index.js --debug "Add a reminder to call mom"
   

有关 Agent 框架的详细文档，请参阅：

• agent-framework/README.md：设置和使用说明
• agent-framework/ARCHITECTURE.md：技术设计和交互流程
• agent-framework/CHANGELOG.md：开发历史和变更