关键词

Todo ListAI Agent 工具服务HTTP StreamingServer-Sent Events上下文协议

项目简介

本项目是一个基于 Model Context Protocol (MCP) 的服务器实现示例，重点展示如何构建一个为大型语言模型 (LLM) 代理提供上下文信息（特别是工具调用能力）的应用后端。它包含两个服务器实现：一个使用 Streamable HTTP 协议，另一个使用 Server-Sent Events (SSE) 协议。这两个服务器都提供了一组管理待办事项 (Todo) 列表的工具，LLM 客户端/Host 可以通过 MCP 协议调用这些工具来与待办事项数据进行交互。此外，项目还包含一个简单的 MCP Host/客户端，用于连接服务器并演示如何使用这些工具。

主要功能点

  • MCP 服务器实现: 提供基于 Streamable HTTP 和 SSE 协议的 MCP 服务器端点。
  • 工具注册与执行: 服务器注册了一组用于管理待办事项（添加、列出、完成、删除）的工具，并能接收客户端的调用请求并执行相应的数据库操作。
  • 数据库集成: 使用 PostgreSQL 数据库持久化存储待办事项数据，供工具使用。
  • 能力声明: 服务器声明了支持工具（Tools）功能。
  • 日志记录: 内置日志记录机制，方便开发和调试。

项目目前实现了 MCP 协议中的工具（Tools）功能，但资源（Resources）和 Prompt 模板（Prompts）功能在当前版本中标记为待实现。

安装步骤

  1. 确保已安装 Node.js (版本 22 或更高) 和 npm。
  2. 推荐安装 Docker，用于运行 PostgreSQL 数据库和可选的服务器容器。
  3. 克隆仓库到本地。
  4. 在项目根目录，分别为 Host 和两个服务器子项目安装依赖： 
    npm install --prefix mcp-host
npm install --prefix mcp-server-http
npm install --prefix mcp-server-sse
  5. 配置 LLM 提供商（如 OpenAI, Azure OpenAI, GitHub Models）所需的 API 密钥或端点，通常在 '.env' 文件中设置相应的环境变量。具体配置方法请参考仓库 README。

服务器配置

MCP 服务器通常需要通过一个配置清单（Manifest）或直接提供连接参数（如 URL）来被 MCP 客户端（Host）发现和连接。

对于基于 Node.js SDK 的 MCP 客户端，典型的服务器配置格式为 JSON 对象，其中包含一个 'servers' 字段，键为服务器名称（自定义），值为该服务器的连接信息。例如：

{
  "servers": {
    "mcp-todo-http": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    },
    "mcp-todo-sse": {
      "type": "sse",
      "url": "http://localhost:3001/sse"
    }
  }
}
  • '"mcp-todo-http"' / '"mcp-todo-sse"': 自定义的 MCP 服务器实例名称。
  • '"type"': 指定连接协议类型，可以是 '"http"' (代表 Streamable HTTP) 或 '"sse"' (代表 Server-Sent Events)。
  • '"url"': MCP 服务器的访问地址和路径。默认情况下，HTTP 服务器在 'http://localhost:3000/mcp'，SSE 服务器在 'http://localhost:3001/sse'。如果服务器部署在其他地址或端口，需要相应修改此 URL。

MCP 客户端/Host 会读取此配置，并尝试连接列出的 MCP 服务器以发现其能力（如工具列表）。

基本使用方法

  1. 启动数据库和 MCP 服务器:
    • 使用 Docker Compose (推荐): 在项目根目录运行 'docker compose up -d --build'。这将启动 PostgreSQL 数据库、HTTP 服务器和 SSE 服务器。
    • 手动启动: 分别在三个独立的终端窗口中运行以下命令启动数据库和两个服务器： 
      # 启动 PostgreSQL (如果未用 Docker Compose)
# npm start --prefix mcp-server-http # 假设 db.ts 会自动连接
# 或使用 Docker 启动 Postgres: docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d postgres

# 启动 HTTP 服务器
npm start --prefix mcp-server-http

# 启动 SSE 服务器
npm start --prefix mcp-server-sse
    • 请确保 '.env' 文件中的数据库连接信息（如 'POSTGRES_HOST'）配置正确，指向你的 PostgreSQL 实例。
  2. 启动 MCP Host/客户端:
    • 如果使用 Docker Compose: 运行 'docker exec -it mcp-host bash' 进入 Host 容器，然后在容器内运行 'npm start'.
    • 如果手动启动服务器: 在一个新的终端窗口中运行 'npm start --prefix mcp-host'.
  3. MCP Host 启动后，会连接配置的 MCP 服务器并加载工具列表。你将看到提示信息和可用的工具列表。
  4. 在 MCP Host 的命令行界面中输入与待办事项相关的指令，例如：
    • 'Add buy groceries'
    • 'List all my tasks'
    • 'Complete task 1' (假设任务 ID 为 1)
    • 'Delete task 2' (假设任务 ID 为 2)
    • LLM 代理将根据你的输入判断需要调用的工具，并通过 MCP 协议发送调用请求给 MCP 服务器。服务器执行工具并返回结果给 Host，Host 再将结果展示或反馈给 LLM 代理。

信息

分类

生产力应用

访问项目