MCP Server Boilerplate (TypeScript)

基本能力

产品定位

MCP Server Boilerplate 是一个用于快速构建 MCP 服务器的模板项目，适用于开发人员快速搭建符合 MCP 协议的服务端应用。

核心功能

• TypeScript 支持：使用现代、类型安全的 JavaScript 开发。
• MCP SDK 集成：内置官方 @modelcontextprotocol/sdk 支持。
• 基础工具示例：包括 greet（可配置前缀的问候工具）和 add（简单计算器工具）。
• 资源管理：提供 welcome 欢迎消息资源示例。
• 提示功能：包含 summarize 主题摘要提示示例。
• 配置管理：通过 .env 文件和环境变量加载配置。
• 输入验证：使用 zod 进行参数验证。
• 结构化日志：使用 pino 记录结构化日志，开发环境下日志可读性高。
• 错误处理：自定义错误类和一致的 try/catch 模式。
• 容器化支持：提供多阶段 Dockerfile 用于生产环境镜像构建。
• 代码质量工具：集成 ESLint 和 Prettier 进行代码格式化和检查。
• 测试支持：使用 Vitest 进行单元测试。

适用场景

• 快速开发符合 MCP 协议的服务端应用
• 为 AI 助手提供自定义工具
• 构建可扩展的后端服务
• 开发与 Cursor 等工具集成的服务

工具列表

1. greet：可配置前缀的问候工具
2. add：简单计算器工具
3. summarize：主题摘要提示工具
4. welcome：欢迎消息资源

常见问题解答

1. JSON-RPC 协议问题：所有调试日志必须写入 stderr，stdout 仅用于 JSON-RPC 消息。
2. 工具名称前缀：Cursor 会自动为工具名称添加前缀，避免手动注册带前缀的工具名称。
3. MCP 工具调用：工具由 AI 助手调用，用户无法直接在聊天界面调用。

使用教程

使用依赖

• Node.js (v18 或更高版本)
• npm (通常随 Node.js 一起安装)
• Docker (可选，用于容器化运行)

安装教程

1. 克隆仓库：

git clone <repository-url>
cd mcp-server-boilerplate

1. 安装依赖：

npm install

1. 配置环境（可选）：

cp .env.example .env

调试方式

1. 开发模式（带热重载）：

npm run dev

1. 生产模式：

npm run build
npm start

1. 使用 Docker 运行：

docker build -t mcp-server-boilerplate .
docker run -i --rm --name mcp-server-stdio mcp-server-boilerplate

许可证

该项目遵循 MIT 开源许可条款，请参阅 MIT 了解完整条款。