MCP 天气助手

一个基于 Model Context Protocol (MCP) 构建的交互式天气助手。主机连接两个本地 MCP 服务器，将其工具发布到兼容 OpenRouter 的语言模型，并让模型自行决定何时获取天气信息。

功能特性

• 通过 National Weather Service API 获取美国各地的天气预报。

• 获取美国某个州的活跃天气警报。

• 通过 weather2day.co.il 网站和由 Playwright 控制的可视 Chromium 浏览器获取以色列天气预报。

• 一个交互式终端聊天界面。

• 通过 stdio 连接多个 MCP 服务器。

• 自动工具发现和命名空间隔离，避免服务器之间的冲突。

Related MCP server: MCP Weather Assistant

项目结构

环境要求

• Windows、macOS 或 Linux。

• Python 3.13 或更高版本。

• 一个 OpenRouter API 密钥。

• 可访问 OpenRouter、api.weather.gov 和 weather2day.co.il 的互联网连接。

• 通过 Playwright 安装的 Chromium，用于以色列天气查询。

• 建议使用虚拟环境。

安装

使用 uv

在项目目录中：

uv sync
uv run playwright install chromium

项目当前直接导入 httpx。如果锁定环境中尚未包含它，请使用以下命令安装：

uv add httpx

使用标准 Python 工具

py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install anthropic mcp python-dotenv playwright openai google-genai httpx
python -m playwright install chromium

在 macOS 或 Linux 上，使用以下命令激活环境：

source .venv/bin/activate

声明的依赖项包含多个当前未被 host.py 使用的提供商 SDK；为了与模板兼容，它们仍然是项目元数据的一部分。

配置

在项目根目录创建 .env 文件：

OPENROUTER_API_KEY=your_openrouter_api_key

host.py 使用 python-dotenv 加载此文件，并将密钥作为 Bearer 令牌发送给 OpenRouter。请勿提交 .env 文件，也不要在源代码管理、日志、截图或错误报告中暴露该密钥。

当前模型在 host.py 中配置：

MODEL = "nvidia/nemotron-3-super-120b-a12b:free"

如果您想使用另一个支持工具调用的 OpenRouter 模型，请更改此常量。

运行助手

使用 uv：

uv run python host.py

使用已激活的虚拟环境：

python host.py

您应该会看到一条启动消息，随后是 Query: 提示符。输入问题并按 Enter 键。输入 quit 可停止应用程序。

示例问题：

What is the forecast for 34.05, -118.25?
Are there any active weather alerts in California?
What is the weather forecast in Tel Aviv?

主机会在工具调用发生时打印它们，随后打印模型的最终响应。

MCP 服务器与工具

美国服务器

weather_USA.py 启动一个名为 weather-USA 的 MCP 服务器，并提供：

• get_alerts_in_USA(state)

  • state：两位字母州代码，例如 CA 或 NY。

  • 使用 NWS 活跃警报端点。

• get_forecast_in_USA(latitude, longitude)

  • latitude：十进制度纬度。

  • longitude：十进制度经度。

  • 通过 NWS points 端点解析位置，然后返回前五个预报时段。

NWS API 请求使用 Accept: application/geo+json 和自定义 User-Agent。

以色列服务器

weather_Israel.py 启动一个名为 weather-Israel 的 MCP 服务器，并提供：

1. open_weather_forecast_israel()

   • 打开非无头 Chromium 浏览器并导航到以色列天气预报网站。

2. enter_weather_forecast_city_israel(city)

   • 输入城市名称并等待自动补全建议。

3. select_weather_forecast_city_israel()

   • 选择第一个自动补全建议并等待预报页面加载。

4. get_forecast_content_israel()

   • 从已加载页面提取可见文本，清理空行，并将结果限制为 4,000 个字符。

以色列工具是有状态的，必须按顺序调用。必须先打开浏览器才能输入城市，必须先选择城市才能提取预报。

架构

User terminal
    |
    v
host.py (ChatHost)
    |-- OpenRouter chat-completions API
    |
    |-- client.py -> weather_USA.py -> api.weather.gov
    |
    `-- client.py -> weather_Israel.py -> Playwright -> weather2day.co.il

启动时，ChatHost 为每个天气服务器创建一个 MCPClient。每个客户端使用与主机相同的 Python 解释器将服务器作为子进程启动。主机发现所有 MCP 工具，并使用函数调用模式将它们暴露给 OpenRouter。

为防止名称重复，工具以以下形式暴露给模型：

<server_script_name>__<tool_name>

例如，美国警报工具以 weather_USA__get_alerts_in_USA 的形式暴露。当 OpenRouter 请求某个工具时，主机将该公共名称映射回所属的 MCP 客户端和原始工具名称，执行它，并将结果发送回模型对话中。

运行单个 MCP 服务器

每个服务器都可以直接启动，供兼容 MCP 的客户端使用或进行基本冒烟测试：

python weather_USA.py
python weather_Israel.py

这些程序使用 MCP stdio 传输，因此它们旨在与 MCP 客户端通信，而不是显示普通网页或命令提示符。

故障排除

ModuleNotFoundError: No module named 'httpx'

安装缺失的依赖项：

uv add httpx

或：

python -m pip install httpx

Chromium 无法启动

安装 Playwright 浏览器二进制文件：

python -m playwright install chromium

以色列服务器有意使用 headless=False 启动 Chromium，因此该提供商需要桌面会话。

OpenRouter 身份验证失败

检查 .env 是否与 host.py 位于同一目录，变量是否恰好命名为 OPENROUTER_API_KEY，以及密钥是否有效。更改文件后重新启动主机。

没有可用工具

确认两个服务器脚本都存在于项目根目录中，并且主机是从该目录启动的。主机当前使用相对路径 ./weather_USA.py 和 ./weather_Israel.py。

天气请求失败

应用程序依赖外部服务。请检查互联网连接、NWS 对请求坐标或州的响应，以及以色列网站的 HTML 选择器是否已更改。

安全与运维说明

• host.py 和 NWS 客户端使用 verify=False 禁用 TLS 证书验证。这在当前网络环境中可能是必要的，但它会降低传输安全性，在生产环境中应替换为正常的证书验证。

• OpenRouter 会收到用户的查询以及天气工具返回的结果。

• 以色列提供商打开可见浏览器并抓取页面的正文文本。网站布局更改可能会破坏选择器或改变提取的内容。

• 应用程序没有持久化的对话历史；每次终端查询都会启动一个新的模型消息列表。

• 错误会打印到终端，而不会写入日志服务。

开发说明

MCP 服务器脚本通过 FastMCP 装饰器暴露工具，并使用异步函数进行网络和浏览器操作。修改服务器时，请将 stdio 通道保留给 MCP 协议流量；应谨慎处理诊断输出，以免破坏协议通信。

仓库中目前没有自动化测试。一个有用的下一步测试层是模拟 NWS 响应、OpenRouter 工具调用响应和 Playwright 页面交互，以便在没有网络访问或浏览器的情况下验证编排逻辑。

许可证

此仓库目前未包含许可证文件。