MCP Boilerplate 服务器（Model Context Protocol 后端）

关键词

Model Context ProtocolSSE工具执行服务端JSON-RPC

以下是对该仓库作为有效 MCP 服务器实现的使用说明，按步骤帮助你快速理解、安装、配置和使用。

项目简介

  • 本仓库实现了一个生产就绪的 MCP 服务器（Model Context Protocol），通过 SSE（服务器推送事件）传输与客户端进行交互，支持：
    • 列出可用工具并暴露给客户端
    • 根据客户端请求调用工具并返回结果
    • 服务器端心跳与日志通知，帮助监控连接状态
    • 基础的错误处理与重试机制
    • 资源、工具和提示模板的框架化管理，便于扩展

主要功能点

  • 使用 MCP 服务器对象（Server）定义并暴露能力：资源订阅、工具、日志等
  • 提供工具集合（当前示例中包含 calculator 工具），并实现参数校验、输入输出结构
  • 处理工具调用请求并在失败时进行重试，同时可向客户端发送通知
  • 通过 SSE 传输实现服务器向客户端的异步推送和心跳机制
  • 提供健康检查接口，便于运维和健康监控
  • 具备完善的异常处理和清理逻辑，能够在关闭时释放资源

安装步骤

  • 获取代码
    • 下载或克隆本仓库到本地开发环境
  • 安装依赖
    • 在项目根目录执行依赖安装（例如 npm install）
  • 构建与运行
    • 构建前端/后端类型脚本（若使用 TypeScript，需要进行编译）并启动服务器
    • 启动后服务器监听配置的端口与主机，默认端口和主机来自配置文件
  • 访问与测试
    • 通过 health 接口检查服务是否正常
    • 使用 /sse 端点建立 SSE 流，与 MCP 客户端进行通信
    • 使用 /messages 端点透传 JSON-RPC 请求/响应（包含对 ping 的快速响应支持）

服务器配置（MCP 客户端启动所需的配置，JSON 格式）

以下配置用于 MCP 客户端在启动时知道如何启动并连接到 MCP 服务器。客户端需要在连接时提供 serverName、command、args 等信息来建立连接；MCP 客户端本身不需要实现服务器端逻辑。

{ "serverName": "mcp-boilerplate", "command": "node", "args": ["dist/index.js"], "environment": { "PORT": "4005", "HOST": "localhost", "API_KEY": "your_api_key" }, "notes": "该配置用于指示 MCP 客户端如何启动服务器进程及连接参数。实际参数（如端口、主机、API_KEY）请根据部署环境设置。客户端只需要知道服务器启动命令与参数即可建立连接。" }

  • 说明
    • serverName 对应仓库中配置的 server.name
    • command/args 指定启动服务器的命令和参数（如通过编译后的入口 dist/index.js 启动）
    • environment 可选，包含端口、主机和认证所需的 API KEY
    • 该配置仅用于 MCP 客户端初始化和连接，不影响服务器端实现本身

基本使用方法

  • 启动与连接
    • 按照上述配置启动 MCP 服务端进程
    • 使用 MCP 客户端通过指定的传输（本实现使用 SSE）建立会话，订阅资源、请求工具列表、调用工具等
  • 与服务器交互的常见流程
    • 客户端发送工具列表请求，服务器返回可用工具及其输入结构
    • 客户端请求调用某个工具，服务器执行并返回结果，同时可发送运行状态通知
    • 客户端可通过心跳/通知保持连接活跃，服务器根据活跃连接情况发送心跳与日志信息
  • 监控与维护
    • 通过 /health 接口查看服务器状态
    • 通过 SSE 的 keepalive 与通知机制监控连接健康状态
    • 关注错误通知，必要时重试工具调用

注：具体参数、端口和部署环境请根据 config.ts 的设置进行调整，默认端口与主机可通过环境变量覆盖。示例工具（calculator）可作为起点进行扩展，添加更多自定义工具时只需在 toolConfigs 中追加配置即可。

服务器信息

访问项目