Weather MCP 学习项目

一个渐进式学习项目，展示从普通 LLM 应用到通过模型上下文协议 (MCP) 暴露天气能力的完整路径。

学习进度

1. 普通 LLM 应用 — 通过 Ollama 与本地开源模型聊天

2. 传统天气 API 应用 — Open-Meteo 客户端（阶段 2A）+ 直接 LLM 编排（阶段 2B）

3. Weather MCP 服务器 — 通过 stdio 将天气暴露为 MCP 工具（阶段 3）

4. MCP 客户端/代理 — 显式工具客户端（阶段 4A）+ 模型选择工具（阶段 4B）

本仓库当前实现了 阶段 1 至 4B。

Related MCP server: MCP Weather Server Demo

环境要求

• Python 3.12 或更高版本

• Ollama（或任何兼容 OpenAI 的本地服务器）

• 一个支持工具调用的本地开源模型（默认：qwen2.5:7b）

不需要 OpenAI 或 Gemini 账号。

设置

1. 安装并启动 Ollama

从 https://ollama.com 安装，然后拉取一个模型：

ollama pull qwen2.5:7b

或者使用你已有的、支持工具调用的任何模型（ollama list 查看），然后在 .env 中将 LLM_MODEL 设置为该名称。

确认 Ollama 正在运行（macOS 安装后通常自动启动）：

ollama list

2. 创建虚拟环境

python3 -m venv .venv
source .venv/bin/activate

在 Windows 上：

python -m venv .venv
.venv\Scripts\activate

3. 安装依赖

pip install -e ".[dev]"

4. 配置环境变量

cp .env.example .env

.env 中的默认值指向本地 Ollama：

LLM_BASE_URL=http://localhost:11434/v1
LLM_API_KEY=ollama
LLM_MODEL=qwen2.5:7b

• LLM_BASE_URL — 兼容 OpenAI 的 API URL（上面显示的是 Ollama 的默认值；用于 Chat Completions 和 Responses）

• LLM_API_KEY — 客户端库需要；Ollama 会忽略它（任何非空值均可）

• LLM_MODEL — 来自 ollama list 的本地模型名称（阶段 4B 的工具调用功能与 qwen2.5:7b 配合良好）

其他选项：LM Studio、vLLM 或任何支持 OpenAI 聊天 API 的服务器——只需更改 LLM_BASE_URL 和 LLM_MODEL。

阶段 2A：Open-Meteo 天气客户端

app/weather_client.py 分两步与 Open-Meteo 通信（无 LLM，无 MCP）：

1. 地理编码 — GET https://geocoding-api.open-meteo.com/v1/search 将城市名称（以及可选的州/地区和国家）转换为纬度、经度、规范名称、行政区域、国家和时区。

2. 预报 — GET https://api.open-meteo.com/v1/forecast 使用这些坐标获取当前天气（温度、湿度、风速、WMO 天气代码）。

调用方收到的是类型化模型（Location、CurrentWeather、WeatherResult），而不是原始提供商 JSON。WMO 天气代码到文本的转换集中在一处（WMO_WEATHER_CODES / weather_condition_from_code）。

示例（异步）：

from app.weather_client import get_current_weather

result = await get_current_weather("Berlin")
print(result.location.name, result.current.temperature, result.current.condition)

阶段 2B：直接天气 + LLM 应用

app/direct_weather_app.py 是一个传统的 LLM 应用：你的代码决定何时调用天气 API，然后将结果传递给 LLM 以生成友好摘要。

User
  → direct_weather_app
      → Open-Meteo   (application-controlled)
      → LLM          (summarize only the supplied payload)
  → Response

如何运行

在虚拟环境激活、Ollama 运行且网络可访问 Open-Meteo 的情况下：

python -m app.direct_weather_app "San Francisco"

可选的消歧义参数：

python -m app.direct_weather_app "Springfield" --state Illinois --country US

或使用控制台脚本：

direct-weather "San Francisco"

在 stderr 上你会看到编排步骤：

1. 应用接收到城市名

2. 应用调用天气提供者

3. 应用接收到结构化天气数据

4. 应用将天气上下文发送给 LLM

Stdout 显示结构化天气块，然后是 LLM 摘要。

与普通 LLM 应用的区别

重要学习点：LLM 不会发现或调用天气工具。应用编排 Open-Meteo，然后要求 LLM 组织结果。提示告诉模型数据是权威的，不要编造缺失的事实。

阶段 3：Weather MCP 服务器

app/mcp_server.py 将现有的 weather_client 暴露为 MCP 工具。该服务器仅提供能力——它不与 LLM 对话或管理对话。

官方 SDK 版本及使用的 API

在本项目环境中检查：

from mcp.server import MCPServer

mcp = MCPServer("weather-learning-server")

服务器职责

• 向 MCP 客户端通告工具（工具发现）

• 接受 get_current_weather 工具调用

• 委托给 app.weather_client（不重复 Open-Meteo 代码）

• 返回结构化天气数据（或安全的工具错误）

• 通过 stdio 进行 MCP 通信（针对此本地学习 POC）

暴露的工具契约：get_current_weather

参数

结构化结果字段

resolved_location、region、country、latitude、longitude、temperature、apparent_temperature（如可用）、condition、wind_speed、observation_time、timezone、units

如何启动服务器

python -m app.mcp_server

或者：

weather-mcp-server

对于 stdio，进程会等待 MCP 主机在 stdin/stdout 上。单独在终端中运行它会看起来“卡住”——这是预期的。

stdio 传输的工作原理（概念上）

MCP host / Inspector
   ├── spawns: python -m app.mcp_server
   ├── writes JSON-RPC MCP messages → server stdin
   └── reads JSON-RPC MCP messages  ← server stdout

• 此 POC 不使用端口和 HTTP

• stdout 是协议线路（不要在那里 print() 普通应用输出）

• 日志应放在 stderr 上

使用官方 MCP Inspector 独立测试

已验证：

• 官方 mcp 2.0.0（MCPServer）

• 官方 Inspector 包 @modelcontextprotocol/inspector

• Node.js 22.19+（当前 Inspector 文档需要）

• 可访问 Open-Meteo 的网络

前提条件

cd weather-mcp-learning
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"   # includes mcp[cli]

确认 Node/npx：

node --version   # need 22.19.0 or newer
npx --version

如果你的系统 node/npx 损坏或太旧，请使用 nvm（或等效工具）安装当前 Node，然后确保 npx 在 PATH 的最前面。

选项 A — 通过 mcp dev 的 Web UI（官方 SDK 辅助工具）

从项目根目录，在虚拟环境激活状态下（还需要 uv，因为 mcp dev 通过 uv run 启动服务器）：

mcp dev app/mcp_server.py --with-editable .

预期：

1. 终端输出类似 MCP Inspector Web is up and running at: http://localhost:6274?MCP_INSPECTOR_API_TOKEN=...

2. 浏览器打开 Inspector

3. Inspector 启动/连接到本地 stdio 服务器（weather-learning-server）

4. 会话初始化（显示服务器名称/说明）

5. 打开 Tools → 列表显示 get_current_weather

6. 选择工具 → UI 显示来自模式的文档字符串/描述和输入字段（city 必需；state_or_region / country 可选）

7. 设置 city = San Francisco → Run Tool

8. 结果面板显示结构化内容，如 resolved_location、region、temperature、condition、units 等

--with-editable . 将此项目安装到 mcp dev 构建的临时环境中，以便 import app... 正常工作。

选项 B — 通过 Inspector + 项目配置的 Web UI

仓库根目录中的 mcp-inspector.json 将 Inspector 指向本地 stdio 服务器：

npx -y @modelcontextprotocol/inspector --config ./mcp-inspector.json --server weather-learning-server

打开打印的 http://localhost:6274?... URL，确认会话已连接，然后像选项 A 一样使用 Tools 选项卡。

选项 C — 可脚本化的 CLI 检查（无浏览器）

这些用于从终端证明相同的协议步骤。从项目根目录运行，虚拟环境激活，且 PATH 上有可用的 Node 22.19+ npx：

# 1–2. Start/connect over stdio + initialize session
npx -y @modelcontextprotocol/inspector --cli \
  --config ./mcp-inspector.json \
  --server weather-learning-server \
  --method initialize \
  --format json

预期的 JSON 包含 "name": "weather-learning-server" 在 result.serverInfo 下。

# 3–4. List tools; confirm description + input schema
npx -y @modelcontextprotocol/inspector --cli \
  --config ./mcp-inspector.json \
  --server weather-learning-server \
  --method tools/list \
  --format json

预期：一个名为 get_current_weather 的工具，其 inputSchema.required 包含 city，以及一个实时/当前天气描述。

# 5–6. Invoke with city = San Francisco; display structured result
npx -y @modelcontextprotocol/inspector --cli \
  --config ./mcp-inspector.json \
  --server weather-learning-server \
  --method tools/call \
  --tool-name get_current_weather \
  --tool-arg 'city=San Francisco' \
  --format json

预期："isError": false 和包含以下字段的 structuredContent：

{
  "resolved_location": "San Francisco",
  "region": "California",
  "country": "United States",
  "latitude": 37.77493,
  "longitude": -122.41942,
  "temperature": 13.8,
  "apparent_temperature": 12.1,
  "condition": "Fog",
  "wind_speed": 19.1,
  "observation_time": "2026-08-12T22:45",
  "timezone": "America/Los_Angeles",
  "units": {
    "temperature": "°C",
    "wind_speed": "km/h",
    "apparent_temperature": "°C"
  }
}

数值天气值随时间变化；字段名和 "isError": false 才是关键。

官方 Inspector 文档：MCP Inspector · SDK 运行文档：Running your server

阶段 4A：基础 MCP 客户端（显式工具调用）

app/basic_mcp_client.py 是一个非 LLM 的 MCP 客户端。它通过 stdio 启动本地天气 MCP 服务器，发现工具，然后显式地调用 get_current_weather。

basic_mcp_client
    → list_tools
    → get_current_weather   (hardcoded by this app — not chosen by an LLM)
    → MCP server (app.mcp_server via stdio)
    → Open-Meteo

重要：此客户端仍然显式地调用天气工具。LLM 尚未选择工具。这将在后续阶段实现。

如何运行

在虚拟环境激活状态下（无需自己启动 MCP 服务器——此客户端会生成它）：

python -m app.basic_mcp_client "San Francisco"

可选过滤器：

python -m app.basic_mcp_client "Springfield" --state Illinois --country US

或者：

basic-mcp-client "San Francisco"

你应该看到：

1. weather-learning-server 的连接/协议信息

2. 每个已发现工具的名称、描述和输入模式

3. 对 get_current_weather 的显式调用

4. 结构化的 MCP 工具结果 JSON

退出进程会清理 MCP 会话和子服务器进程。

阶段 4B：OpenAI Responses 代理（模型选择的 MCP 工具）

app/mcp_agent.py 连接到天气 MCP 服务器，在运行时发现工具，通过官方 OpenAI Responses API 将这些工具定义提供给模型，执行模型请求的任何工具调用（通过 MCP），将工具结果返回给模型，并打印最终答案。

user question
  → mcp_agent
      → MCP list_tools          (discovery)
      → OpenAI Responses API    (question + tool schemas)
      → model may request tool(s)
      → MCP tools/call          (only discovered names)
      → Responses function_call_output
      → final natural-language answer

没有 if "weather" in question，没有城市正则表达式，也没有硬编码的 get_current_weather 调用。模型选择是否使用工具。

代理循环（详细）

1. 启动 MCP 会话 — 通过 stdio 生成 python -m app.mcp_server；初始化客户端

2. 工具发现 — list_tools；记录每个工具的名称/描述

3. 模式转换 — MCP 工具 → Responses type: "function" 工具

4. 模型轮次 — client.responses.create(..., tools=..., tool_choice="auto")

5. 检查输出 — 如果存在 function_call 项：

   • 验证工具名称是否在已发现集合中

   • 解析/验证 JSON 参数

   • 调用 MCP；保留结构化结果

   • 使用 previous_response_id 提交 function_call_output

6. 重复直到模型返回最终文本消息（或达到最大迭代次数）

7. 打印最终答案并关闭 MCP 会话/子进程

如何运行

ollama pull qwen2.5:7b   # once, if needed
source .venv/bin/activate
python -m app.mcp_agent "What is the current weather in San Francisco?"
python -m app.mcp_agent "Explain what dependency injection is."

预期：

• 天气问题 → 日志显示 model_requested_tools / get_current_weather 的 tool_call，然后是天气答案

• 依赖注入问题 → 日志显示最终响应，没有工具调用

观察 stderr 上的 [mcp-agent] 行：发现、模型输出类型、工具名称/参数/持续时间/结果。API 密钥从不记录。

运行普通应用

在虚拟环境激活且 Ollama 运行的情况下：

python -m app.plain_llm_app

或使用自定义提示：

python -m app.plain_llm_app "What is the Model Context Protocol in one sentence?"

你也可以使用已安装的控制台脚本：

plain-llm "Hello!"

运行测试

pytest

项目布局

weather-mcp-learning/
  README.md
  .env.example
  .gitignore
  pyproject.toml
  mcp-inspector.json
  app/
    __init__.py
    config.py
    llm_client.py
    plain_llm_app.py
    weather_client.py
    direct_weather_app.py
    mcp_server.py
    basic_mcp_client.py
    mcp_agent.py
  tests/

备注

• 官方 openai Python 包被用作兼容 OpenAI 的客户端（早期使用 Chat Completions；在 Stage 4B 中使用 Responses API）。请求会发送到你配置的 LLM_BASE_URL（默认为 Ollama）。

• 天气查询通过 httpx 使用 Open-Meteo（app/weather_client.py）。

• Stage 2B（direct_weather_app.py）显式编排天气 → LLM 的流程；不涉及 MCP 和工具调用。

• Stage 3 使用官方 mcp 2.0.0 SDK（mcp.server 中的 MCPServer）通过 stdio 运行。请勿使用第三方 fastmcp 包。

• Stage 4A（basic_mcp_client.py）仍然显式调用天气工具（不涉及 LLM 工具选择）。

• Stage 4B（mcp_agent.py）在通过 Responses API 完成 MCP 发现后，让模型自行选择工具。