toyMCP 待办事项列表服务器

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

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

设置

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 环境变量指定的端口）。 MCP 端点是 http://localhost:3000/mcp。

运行测试

确保 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 # 确保脚本是可执行的
./run_full_test.sh

API 用法（通过 HTTP POST 的 JSON-RPC 2.0）

将 POST 请求发送到 http://localhost:3000/mcp，其中 Content-Type: application/json，并且正文包含 JSON-RPC 2.0 有效负载。

示例工具： curl

• 添加项目 (todo.add)

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

  成功响应：

  {
      "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" \
       -d '{"jsonrpc": "2.0", "method": "todo.list", "id": 2}' \
       http://localhost:3000/mcp
  

  成功响应（示例）：

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

• 删除项目 (todo.remove) （假设存在 ID 为 1 的项目）

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

  成功响应：

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

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

  # 请求删除不存在的 ID 999
  curl -X POST -H "Content-Type: application/json" \
       -d '{"jsonrpc": "2.0", "method": "todo.remove", "params": {"id": 999}, "id": 4}' \
       http://localhost:3000/mcp
  

  响应：

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