MCP Server

MCP 服务

提供使用 Bun 搭建自有 MCP 服务项目功能的 MCP 服务。

• MCP 服务
  • 背景
  • 前置条件
  • 项目设置
  • 构建
  • 设置 Claude Desktop
  • 用法
  • 开发
    • 新增工具
    • 测试覆盖率
      • 前置条件（开发）
      • 运行测试覆盖率

背景

本项目使用 Model Context Protocol（MCP），提供标准化工具（MCP 服务），用于在预先指定的位置创建示例 MCP 项目。

在本示例中，我们集成了 Claude Desktop 来运行 MCP 服务，同时让它充当 MCP 客户端，与 MCP 服务交互。

生成的示例项目与本项目采用相同的结构，并附带一个用于计算两个数值之和的示例工具。

选择 Bun 而非 NodeJS 是有意为之，旨在展示 Bun 已取得长足进展，正逐渐成为 NodeJS 的真正替代方案。它速度极快、易于设置，并且开箱即用地提供了许多功能。它还与现有工具链（如 ESLint 等）良好集成。

前置条件

1. 必须安装 Bun。
2. 建议安装 Claude Desktop。

项目设置

1. 克隆仓库。

2. 运行：

   bun install
   

3. 根据 /env/sample.env 在根目录创建 .env 文件。按需提供相应值，具体说明见文件。

   注意： 这主要适用于希望通过 bun run start 在开发模式下运行服务的情况。

4. (可选) 运行以下命令以验证项目完整性：

   bun run verify
   

构建

1. 运行：

   bun run build
   

这会打包入口文件 build/main.js，之后即可使用该文件。

设置 Claude Desktop

本节参考了这份通用指南，并针对本用例作了具体说明。

1. 启动 Claude Desktop 并打开 Settings

2. 点击 Settings 面板左侧栏中的 Developer，然后点击 Edit Config：

3. 编辑文件 claude_desktop_config.json 并添加以下内容：

   {
     "mcpServers": {
       "create-mcp-app-bun": {
         "command": "bun",
         "args": ["run", "<path_to_project>/build/main.js"]
       }
     }
   }
   

   将 <path_to_project> 替换为项目路径，例如：/Users/username/Documents/projects/create-mcp-server-app-bun

4. 重启 Claude Desktop；这一步很重要，否则 Claude Desktop 不会应用对 claude_desktop_config.json 的更改。

5. 在主屏幕上，点击 Search and Tools 按钮，然后点击 MCP 服务名称：

   

确保已启用该服务。

用法

1. 你可以先直接要求 Claude 创建一个新的 MCP 项目：create a new mcp project

   Claude 会要求你指定名称（例如 my-test-mcp-server），然后创建项目。

   

2. 如果项目已存在，实现也会正确处理这种情况，并提示用户指定后续操作。

开发

新增工具

添加新工具时，请确保 ./src/tools 中的每个新工具模块都扩展 AbstractTool、实现 ITool，并提供显式构造函数（以确保测试覆盖率）：

...
export class NewTool extends AbstractTool implements ITool {
  // Explicit constructor definition to ensure test coverage in Bun tracks constructor.
  constructor(fetch: typeof globalThis.fetch = globalThis.fetch) {
    super(fetch);
  }
...

此外，必须实现以下方法（详情请参阅相应的 JSDoc）：

• getName
• getDescription
• getInputSchema
• validateWithDefaults
• processToolWorkflow

请参考现有工具的实现，并记得编写相应的测试。

无需进行其他配置即可注册更多工具；重启 MCP 服务后，系统会自动包含这些工具。

测试覆盖率

可以使用 lcov 报告分析测试覆盖率缺口，以便更清楚地了解已覆盖的代码行和函数。

注意：

• 类的构造函数应定义在相应的类中，因为 Bun 只会跟踪类的函数（包括构造函数）。如果继承的抽象类本身带有构造函数，而该构造函数又未被跟踪，就会产生问题。因此，只需在类中定义抽象类的构造函数并调用 super。
• 在模块顶部导入某些内容（例如 import dedent from "dedent";）可能导致 Bun 无法正确跟踪该行的覆盖情况。只需将其移到其他导入语句之后，Bun 就能正确跟踪。

前置条件（开发）

1. 安装 lcov：

   brew install lcov
   

2. 安装 VSCode 扩展 ryanluker.vscode-coverage-gutters（已在 settings.json 中定义）。

运行测试覆盖率

1. 在大多数情况下，运行以下命令即可：

   bun run test:coverage
   

   注意： 如果覆盖率低于 100，但未报告 Uncovered Line #s，你可能需要按照接下来的步骤进一步调查，并重新查看上文的注意事项。

2. 对于更复杂的情况，请运行：

   bun run test:coverage:lcov
   

   这会生成 lcov 覆盖率报告，供 VSCode 扩展 ryanluker.vscode-coverage-gutters 用于在编辑器中可视化已覆盖的代码行。

3. 如果你希望生成 HTML 报告，请在终端中运行：

   genhtml --function-coverage --branch-coverage --output-directory coverage-report coverage/lcov.info
   

   这会生成 HTML 覆盖率报告，你可以在首选的浏览器中查看。