Toy MCP

toyMCP待办事项列表服务器

这是一个简单的示例服务器，使用模型上下文协议（MCP）概念，特别是使用HTTP上的JSON-RPC 2.0实现To-Do-list CRUD API。

它使用Node.js、Express和PostgreSQL（通过Docker）实现持久性。

设置

1. 先决条件：

- Node.js（推荐LTS版本） - npm（通常随Node.js一起提供） - Docker和Docker Compose

1. 克隆存储库（如果适用）：

   # git clone ...
   # cd toyMCP

1. 安装依赖关系：

   npm install

1. 启动PostgreSQL数据库：

确保Docker桌面（或Docker守护进程）正在运行。

   docker compose up -d db

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

1. 运行服务器：

   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

1. 运行脚本：

   ./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/ 目录，反映了单元和集成测试的覆盖范围。

运行端到端测试脚本

该项目包括一个编排脚本(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文档

交互式API文档可通过Swagger UI在本地（当服务器运行时）和通过GitHub Pages部署：

• 本地Swagger用户界面： http://localhost:3000/api-docs
• GitHub页面交换用户界面： https://izaqyos.github.io/toyMCP/swagger-ui/

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

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

向发送POST请求 http://localhost:3000/rpc 随着 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/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" \
       -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" \
       -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
  }

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

  # Request to remove ID 999 which doesn't exist
  curl -X POST -H "Content-Type: application/json" \
       -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
  }