🌤 Weather MCP Server

一个最小化但完整的 MCP (Model Context Protocol) 服务端实现，为 AI Agent 提供实时天气查询能力。

为什么做这个项目

这是 从零学 AI Agent 架构 的实战项目 #1。MCP 协议是 AI Agent 与外部世界交互的标准接口——理解 MCP 是理解整个 Agent 架构的第一步。本项目用最小的代码量（~200 行）展示 MCP Server 的完整生命周期。

快速开始

# 1. 安装
cd weather-mcp-server
pip install -e .

# 2. 测试
pytest tests/ -v

# 3. 运行（stdio transport）
weather-mcp

接入 Claude Code

在 claude_desktop_config.json 或 .claude/settings.json 中添加：

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "D:\\AI_Space\\ClaudeCode-DeepSeek\\weather-mcp-server",
        "weather-mcp"
      ]
    }
  }
}

重启 Claude Code 后，你就能看到 mcp__weather__get_current_weather 和 mcp__weather__get_forecast 两个工具。

提供的工具

工具名	用途	参数
get_current_weather	实时天气（温度/体感/风速/湿度/紫外线）	city (string)
get_forecast	未来 N 天预报	city (string), days (int, 1-3)

架构

┌──────────────────────────────────────────┐
│           Claude Code (Host)             │
│  ┌────────────────────────────────────┐  │
│  │   MCP Client (weather)             │  │
│  │   JSON-RPC over stdio              │  │
│  └──────────────┬─────────────────────┘  │
└─────────────────┼────────────────────────┘
                  │ stdin/stdout
┌─────────────────▼────────────────────────┐
│         Weather MCP Server               │
│  ┌────────────────────────────────────┐  │
│  │  handle_list_tools()              │  │
│  │  handle_call_tool()               │  │
│  └──────────┬─────────────────────────┘  │
│             │                            │
│  ┌──────────▼─────────────────────────┐  │
│  │  fetch_weather() (wttr.in)        │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘

项目结构

weather-mcp-server/
├── pyproject.toml          # 项目配置和依赖
├── README.md               # 本文件
├── src/
│   └── weather_mcp/
│       ├── __init__.py
│       └── server.py       # MCP Server 核心（~200行）
└── tests/
    └── test_server.py      # 单元测试 + 集成测试

学会了什么

通过这个项目你可以理解：

1. MCP 协议三层模型: Host → Client → Server
2. JSON-RPC 2.0: MCP 的底层传输格式
3. stdio transport: 进程间通过标准输入输出通信
4. Tool 定义: name + description + input_schema，AI 如何匹配工具
5. 业务逻辑与协议解耦: fetch_weather() 不知道 MCP 的存在
6. 错误处理: MCP 协议要求返回 is_error 而非抛异常

License

MIT