MCP Server Boilerplate (TypeScript)

MCP 服务脚手架（TypeScript）

一个结构完善、易于维护且可扩展的脚手架项目，用于使用 TypeScript 构建 Model Context Protocol（MCP）服务。此脚手架旨在加快开发速度、促进一致性，并在创建 MCP 集成时采用最佳实践。

功能

• TypeScript： 现代、类型安全的 JavaScript。
• MCP SDK： 使用官方的 @modelcontextprotocol/sdk。
• 专注的实现： 精简实现，支持 stdio 传输，简单可靠。
• 示例原语： 包含以下基础示例：
  • 工具：greet（使用可配置前缀的问候语）和 add（简单计算器）
  • 资源：welcome（欢迎消息资源）
  • 提示词：summarize（主题摘要提示词）
• 配置： 从 .env 文件和环境变量加载配置（src/config.ts）。
• 验证： 使用 zod 对原语参数进行可靠验证。
• 结构化日志： 使用 pino 记录结构化 JSON 日志（src/logger.ts）。开发环境中会输出美化日志。
• 错误处理： 自定义错误类（src/errors.ts），并在所有处理程序中采用一致的 try/catch 模式。
• 容器化： 使用多阶段 Dockerfile 创建经过优化的生产镜像。
• Lint/格式化： 配置了 ESLint 和 Prettier。
• 测试： 使用 Vitest 搭建测试环境。包含配置加载（tests/config.test.ts）和 greet 工具处理程序（tests/greet.test.ts）的示例测试。

前置条件

• Node.js（建议使用 v18 或更高版本）
• npm（通常随 Node.js 一起安装）
• Docker（可选，用于在容器中运行）

设置和安装

1. 克隆仓库（或将其用作模板）：

   # 如果已克隆
   git clone <repository-url>
   cd mcp-server-boilerplate
   

2. 安装依赖项：

   npm install
   

3. 配置环境（可选）：

   • 复制示例环境文件：

     cp .env.example .env
     

   • 编辑 .env 文件以设置所需配置（请参阅配置部分）。

配置

通过环境变量管理配置。本地开发时，可以从 .env 文件加载这些变量。

• LOG_LEVEL：日志记录的最低级别（例如，trace、debug、info、warn、error、fatal）。（默认值：info）。
• NODE_ENV：设置为 production 时，将生成经过优化的构建并输出标准 JSON 日志。默认值为 development（启用美化日志）。
• CUSTOM_GREETING_PREFIX：问候工具的可选前缀（例如，“👋 ”）。默认值为空。

运行服务

开发模式（热重载和美化日志）

此命令使用 tsx 直接运行 TypeScript 代码，并通过管道将输出传递给 pino-pretty。

npm run dev

注意：dev 脚本需要安装 pino-pretty（npm install --save-dev pino-pretty）。

• 日志将以美化格式输出到控制台。

生产模式（编译后的 JavaScript）

1. 构建 TypeScript 代码：

   npm run build
   

   此命令会将代码编译到 dist/ 目录。

2. 运行服务：

   # 示例：使用表情符号设置自定义问候前缀
   set CUSTOM_GREETING_PREFIX=👋 
   set NODE_ENV=production
   npm start
   

   日志将采用 JSON 格式。

使用 Docker 运行

1. 构建 Docker 镜像：

   docker build -t mcp-server-boilerplate .
   

2. 运行容器：

   # 使用 stdio 传输运行
   # （需要交互式终端）
   docker run -i --rm --name mcp-server-stdio mcp-server-boilerplate
   

   • 根据需要调整环境变量（-e）。

扩展样板项目

1. 添加工具：

   • 在 src/index.ts（或单独的 src/tools/ 目录）中为参数定义 Zod 架构。
   • 使用 server.tool(name, schemaDefinition, handler)。
   • 实现处理程序逻辑；如需保持一致性，可以使用 src/errors.ts 中的自定义错误。
   • **重要：**注册工具时只使用简单名称（例如 "add"，而不是 "mcp_minimal_add"）。Cursor 会自动为 AI 工具调用添加前缀。

2. 添加资源：

   • 对于静态资源：server.resource(name, uri, metadata, handler)。
   • 对于动态资源：定义 ResourceTemplate，并使用 server.resource(name, template, metadata, handler)。
   • 实现处理程序逻辑。

3. 添加提示词：

   • 为参数定义 Zod 架构。
   • 使用 server.prompt(name, schemaDefinition, handler)。
   • 实现处理程序逻辑，返回所需的消息结构。

4. 添加配置：

   • 在 .env.example 中添加新的环境变量。
   • 从 src/config.ts 中读取并导出经过验证的值。

MCP 工具调用

使用 MCP 工具时，了解它们的调用方式非常重要：

1. **AI 工具调用：**MCP 工具旨在由 AI 助手调用，而非由用户直接调用。AI 可以使用带前缀的名称直接调用工具。

2. 工具命名：

   • 注册工具时使用简单名称（例如 "add"）。
   • AI 会看到带前缀的工具名称（例如 "mcp_mcp_minimal_add"）。
   • 不要使用带前缀的名称注册工具，否则会造成重复。

3. 日志注意事项：

   • 在 stdio 模式下，所有日志都必须写入 stderr，绝不能写入 stdout。
   • stdout 专用于 JSON-RPC 消息。
   • 使用 console.log() 会破坏 JSON-RPC 协议；请使用将内容写入 stderr 的自定义日志记录器。

4. 用户界面：

   • 用户无法在聊天界面中直接调用 MCP 工具。
   • AI 助手会作为中间方，代表用户调用工具。

常见问题

根据我们开发此样板项目的经验，以下是一些需要注意的常见问题：

1. JSON-RPC 协议问题：

   • 发送到 stdout 的任何非 JSON-RPC 消息（例如 console.log 的输出）都会破坏 stdio 传输机制。所有调试日志都必须写入 stderr。
   • 在 stdio 模式下，只能向 stdout 发送有效的 JSON-RPC 消息。

2. 工具名称前缀：

   • Cursor 会在 AI 助手调用工具时自动添加前缀。例如，如果你的服务名为 "mcp_minimal"，且注册的工具名为 "add"，AI 会以 "mcp_mcp_minimal_add" 调用它。
   • 避免同时使用简单名称和带前缀的名称注册工具，否则会在 AI 可用的工具列表中产生重复条目。

3. MCP 工具调用：

   • MCP 工具旨在由 AI 助手调用，而非由用户在聊天中直接调用。用户无法在聊天界面中使用 "@Tool" 语法调用 MCP 工具。
   • AI 会自动发现已注册的工具，并可在无需用户配置的情况下调用它们。

客户端配置示例

以下示例展示了如何配置 Cursor 等客户端以连接到此服务。

通过 Stdio 连接（推荐用于本地开发）

此方法使用 Cursor 的 mcp.json 文件（通常位于 Linux/macOS 上的 ~/.cursor/mcp.json，或 Windows 上的 C:\Users\<username>\.cursor\mcp.json）。

1. 确保已运行 npm run build，以创建 dist/index.js 文件。

2. 在 package.json 中添加一个脚本，以显式运行编译后的 stdio 服务：

   "scripts": {
     // ... other scripts
     "start:stdio": "cross-env NODE_ENV=production node dist/index.js --stdio"
   }
   

3. 如果尚未安装 cross-env，请运行：npm install --save-dev cross-env。

4. 在 mcp.json 中配置服务（确保文件中不存在 JSON 注释 //）：

   {
     "mcpServers": {
       "mcp_minimal": {
         "displayName": "MCP Minimal",
         "command": "node",
         "args": [
           "C:\\path\\to\\your\\project\\dist\\index.js",
           "--stdio"
         ],
         "env": {
           "NODE_ENV": "production"
         },
         "enabled": true
       }
     }
   }
   

   • 重要： 将 "C:\\path\\to\\your\\project\\dist\\index.js" 替换为你项目目录中 dist/index.js 文件的正确绝对路径。在 Windows 上，请使用双反斜杠（\\）作为路径分隔符。
   • 此配置会直接使用绝对脚本路径调用 node，从而避免 Cursor 启动时可能出现的 npm 和相对路径问题。

基本安全注意事项

• 输入验证： 使用 Zod schema 进行基本验证。请确保 schema 足够严格，以满足你的需求。
• 错误处理： 避免在返回给客户端的错误消息中泄露敏感信息。当前设置会抛出错误，并由 SDK 转换；请检查 SDK 的错误格式。
• 资源访问： 如果资源/工具处理器会访问敏感数据或执行受限操作，请在其中实现授权检查（当前尚未实现）。
• 依赖项： 定期审计依赖项是否存在漏洞（npm audit）。
• 容器安全： Dockerfile 使用非 root 用户。请保持基础镜像为最新版本。

测试

• 使用 Vitest 运行测试：

  npm test
  

• 在监视模式下运行测试：

  npm run test:watch
  

• 生成覆盖率报告：

  npm run coverage
  

• 在 tests/ 目录中按照 *.test.ts 模式添加新的测试文件。

代码检查与格式化

• 检查格式：npm run format
• 应用格式：npm run format:fix
• 运行代码检查器：npm run lint
• 修复代码检查错误：npm run lint:fix

限制

MCP 是一种非常新的协议，仍在积极开发中。以下是一些需要注意的已知问题：

• AI 模型兼容性： Cursor AI Agent 自动使用或被提示使用自定义 MCP 工具的能力可能取决于模型。即使动态发现的工具已正确列在设置中，某些模型也可能难以发起调用。如果遇到 AI 工具调用问题，可能需要在 Cursor 中使用不同的 AI 模型进行测试。
• 工具数量： 某些 MCP 服务，或启用了大量 MCP 服务的用户，可能会有许多可供 Cursor 使用的工具。目前，Cursor 只会向 Agent 发送前 40 个工具。
• 远程开发： Cursor 会从本地计算机直接与 MCP 服务通信，通过 stdio 直接通信，或通过网络使用 sse 通信。因此，通过 SSH 或其他开发环境访问 Cursor 时，MCP 服务可能无法正常工作。我们希望在未来的版本中改进这一点。
• MCP 功能支持： MCP 服务提供三种主要能力：工具、资源和提示词。目前，Cursor 仅支持工具。资源和提示词已在协议中定义并在此服务中实现，但目前无法通过 Cursor 访问。我们希望未来的 Cursor 版本能够支持这些额外能力。

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。