MCP 服务器样板 (TypeScript)

一个结构良好、可维护且可扩展的样板项目，用于使用 TypeScript 构建模型上下文协议 (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 用于创建优化的生产镜像。
• Linting/格式化: 配置了 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。
   • 只有有效的 JSON-RPC 消息才应在 stdio 模式下发送到 stdout。

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": {
     // ... 其他脚本
     "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 模式用于基本验证。确保模式对于您的需求来说足够严格。
• 错误处理: 避免在发送回客户端的错误消息中泄漏敏感信息。当前设置会抛出错误，SDK 会转换这些错误；查看 SDK 的错误格式。
• 资源访问: 如果资源/工具处理程序访问敏感数据或执行受限操作，请在其中实现授权检查（当前未实现）。
• 依赖项: 定期审核依赖项是否存在漏洞 (npm audit)。
• 容器安全: Dockerfile 使用非 root 用户。保持基础镜像更新。

测试

• 使用 Vitest 运行测试:

  npm test
  

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

  npm run test:watch
  

• 生成覆盖率报告:

  npm run coverage
  

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

Linting 和格式化

• 检查格式: npm run format
• 应用格式: npm run format:fix
• 运行 linter: npm run lint
• 修复 linter 错误: npm run lint:fix

局限性

MCP 是一种非常新的协议，并且仍在积极开发中。 有一些已知的注意事项需要注意：

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

许可证

此项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。