Weather MCP Server

Weather MCP 服务

概述

本项目实现了一个 Model Context Protocol（MCP）服务，可提供天气信息服务。它利用 National Weather Service（NWS）API 获取天气警报和预报，并将其作为工具提供给 Claude 等 MCP 客户端使用。

该服务采用模块化架构，并遵循 Python 项目的最佳实践，易于维护和扩展。

功能

• 天气工具：获取各州的天气警报，以及指定坐标的天气预报
• 系统工具：运行 shell 命令并查看系统进程信息
• MCP 集成：与 Claude Desktop 等 MCP 客户端无缝集成

安装

前置条件

• Python 3.11 或更高版本
• uv 包管理器

设置

1. 克隆仓库：

   git clone https://github.com/yourusername/weather.git
   cd weather
   

2. 使用 uv 安装依赖项：

   make install
   

3. 开发时，安装其他依赖项：

   make dev
   

用法

运行服务

启动 MCP 服务：

make run

也可以直接使用 uv 启动：

uv run python -m main

连接到 Claude Desktop

1. 更新 Claude Desktop 配置，加入天气服务：

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["-m", "main"],
      "cwd": "/path/to/weather"
    }
  }
}

2. 重启 Claude Desktop 以应用更改

3. 在 Claude Desktop 中，现在可以从 MCP 服务下拉菜单中选择“weather” MCP 服务

Claude Desktop 将能够使用天气 MCP 服务，让你在对话中直接查询天气数据。

示例查询

连接后，你可以向 Claude 提问：

• “CA 当前有哪些天气警报？”
• “纬度 37.7749、经度 -122.4194 处的天气预报是什么？”
• “我的系统中哪些进程占用的 CPU 最多？”

项目结构

weather/
├── src/
│   └── weather/
│       ├── __init__.py          # Package initialization
│       ├── server.py            # Main server setup
│       ├── tools/               # Tool implementations
│       │   ├── __init__.py
│       │   ├── weather_tools.py
│       │   └── system_tools.py
│       ├── resources/           # Resource implementations
│       │   ├── __init__.py
│       │   └── system_resources.py
│       ├── services/            # External service integrations
│       │   ├── __init__.py
│       │   ├── weather_service.py
│       │   └── system_service.py
│       └── utils/               # Helper functions
│           ├── __init__.py
│           ├── http.py
│           └── formatting.py
├── tests/                       # Test suite
├── main.py                      # Entry point
├── pyproject.toml               # Dependencies and metadata
├── Makefile                     # Build commands
└── README.md                    # This file

Make 目标

项目包含多个 make 目标，可简化开发流程：

目标	描述
install	使用 uv 安装项目依赖项
lint	使用 uv 运行 ruff 检查器并自动修复
format	使用 uv 运行 black 格式化工具
format-check	检查 black 是否会重新格式化文件
lint-format	同时运行检查器和格式化工具
test	使用 uv 运行 pytest 测试
clean	删除构建产物和缓存文件
outdated	使用 uv 检查过时的依赖项
upgrade-deps	使用 uv 升级所有过时的依赖项
run	使用 uv 启动 MCP 服务
inspector	启动 MCP Inspector 进行测试
hooks	安装 git hooks
dev-server	以开发模式启动 MCP 服务
stop-server	停止 MCP 服务和 Inspector
claude-install	在 Claude Desktop 中安装服务
claude-uninstall	从 Claude Desktop 中卸载服务

运行 make help 查看所有可用目标。

在 Claude Desktop 中使用

若要在 Claude Desktop 中使用天气 MCP 服务：

1. 在 Claude Desktop 中安装该服务：

make claude-install

此操作将：

• 使用 MCP CLI 在 Claude Desktop 中安装服务
• 以可编辑模式安装项目（-e .）
• 将服务注册为“weather”
• 将服务配置为从项目目录运行

2. 重启 Claude Desktop 以应用更改

3. 在 Claude Desktop 中，现在可以从 MCP 服务下拉菜单中选择“weather” MCP 服务

Claude Desktop 将能够使用天气 MCP 服务，让你在对话中直接查询天气数据。

若要从 Claude Desktop 中卸载该服务：

make claude-uninstall

这将从 Claude Desktop 中移除天气 MCP 服务配置。你需要重启 Claude 以应用更改。

开发模式

在主动开发时，可在代码更改后自动重新加载：

# Start the server in development mode with the MCP Inspector
make dev-server

这将：

1. 使用 mcp dev 命令启动 MCP 服务
2. 以可编辑模式（-e .）安装项目
3. 自动启动 MCP Inspector
4. 在代码更改后启用自动重新加载

MCP Inspector 可在浏览器中通过 http://localhost:5173 访问。

停止服务和 Inspector：

make stop-server

这种设置非常适合迭代开发，因为代码更改后服务会自动重新加载。

Inspector 功能

MCP Inspector 可用于：

1. 探索工具：查看所有可用工具、其参数和文档。
2. 调用工具：使用自定义参数执行工具并查看结果。
3. 浏览资源：查看所有可用资源及其当前值。
4. 测试提示词：如果服务提供提示词模板，可使用不同输入进行测试。
5. 查看日志：查看 Inspector 与服务之间所有交互的详细日志。

测试天气工具

使用 Inspector，可以轻松测试天气工具：

1. 在 Inspector 界面中找到 get_weather_alerts 工具
2. 在参数栏中输入州代码（例如，“CA”、“NY”、“FL”）
3. 执行工具并查看结果

同样，也可以通过提供纬度和经度坐标来测试 get_forecast 工具。

测试系统工具

Inspector 也让测试系统工具变得简单：

1. 找到 run_shell_command 工具
2. 在参数栏中输入安全的命令（例如，“ls -la”、“echo hello”）
3. 执行工具并查看结果

使用 Inspector 调试

Inspector 对调试尤其有用：

1. 工具调用失败时，它会显示详细的错误消息
2. 可以查看准确的请求和响应载荷
3. 它有助于找出参数验证或工具实现方面的问题

有关 MCP Inspector 的更多信息，请访问 Model Context Protocol 文档。

本地测试

可以使用 mcp[cli] 包附带的 MCP CLI 工具在本地测试 MCP 服务：

1. 启动服务：

   make run
   

2. 在另一个终端中，使用 MCP CLI 与服务交互：

   # List all available tools
   make inspector
   
   # Call a specific weather tool
   mcp call-tool http://localhost:8000 get_weather_alerts --args '{"state": "CA"}'
   
   # Get a weather forecast
   mcp call-tool http://localhost:8000 get_forecast --args '{"latitude": 37.7749, "longitude": -122.4194}'
   
   # List system resources
   mcp list-resources http://localhost:8000
   
   # Get system processes
   mcp get-resource http://localhost:8000 top_processes
   

如果直接使用 uv，可以通过以下命令运行 MCP CLI：

uv run mcp list-tools http://localhost:8000

开发

添加新工具

向服务添加新工具：

1. 在相应的工具模块中创建一个函数
2. 使用 @server.tool() 装饰器注册该函数
3. 更新 tools/__init__.py 中的工具注册

示例：

@server.tool()
async def my_new_tool(param1: str, param2: int) -> str:
    """
    Tool description.
    
    Args:
        param1: Description of param1
        param2: Description of param2
        
    Returns:
        Description of return value
    """
    # Implementation
    return result

添加新资源

添加新资源：

1. 在相应的资源模块中创建一个函数
2. 使用 @server.resource() 装饰器注册该函数
3. 更新 resources/__init__.py 中的资源注册

许可证

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

致谢

• Model Context Protocol 提供 MCP 规范
• National Weather Service API 提供天气数据