Weather MCP Server

Weather MCP Server

这是一个利用 Model Context Protocol (MCP) 和 Bun 为大模型提供一组天气报告工具的项目。

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

背景

本项目演示了如何设置一个能够处理工具请求并执行工具的基本 MCP 服务。输入邮政编码后，它可以提供当前天气和未来天气预报（逐小时和逐日）。多个工具协同工作，大模型会根据工具配置来协调它们的使用。 此实现还提供了一个简单的框架，便于以集中且结构化的方式添加其他工具。更多信息请参阅开发部分中的新增工具一节。

前提条件

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（不是 Account setting）。

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

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

   {
     "mcpServers": {
       "weather-mcp-server": {
         "command": "bun",
         "args": ["run", "<path_to_project>/build/main.js"],
         "env": {
           "APP_NAME": "weather-mcp-server",
           "APP_EMAIL": "<app-email>"
         }
       }
     }
   }
   

   • 将 <path_to_project> 替换为项目路径，例如：/Users/username/Documents/projects/create-mcp-server-app-bun
   • 将 <app-email> 替换为用于识别部分 API 请求的电子邮件地址，例如：[email protected]

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

5. 在主屏幕上，点击 Search and Tools 按钮，然后点击你的 MCP 服务名称。确保已启用该服务。

使用方法

以下是与 Claude 和此 MCP 服务交互的一些提示。

1. 可以先直接询问 Claude 你所在邮政编码的当前天气，例如 current weather for 90210，它会输出相应结果。你可能会发现，Claude 会动态、独立地依次使用多个工具来提供所需结果。
2. 你也可以询问 Claude 接下来几天的天气预报，例如：what's the weather this weekend?。这会触发后续请求（除非先前的问题已在上下文中提供邮政编码），以获取所需的邮政编码。提供邮政编码后，回复将包含相应结果。
   1. 请注意，如果适用，Claude 会自动重用先前工具调用的结果来回答此问题。

开发

新增工具

添加新工具时，请确保 ./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 覆盖率报告，你可以在首选的浏览器中查看。