WeatherWork Consumer MCP

基于 weathercn API 的消费者天气 MCP 服务，提供 18 个工具（地名解析、实况、预报、预警、空气质量、分钟降水、生活指数、台风、天文、潮汐等）。

安装

pip install weatherwork-consumer-mcp

从本目录源码安装（开发）：

cd weatherwork-consumer-mcp
pip install -e .

配置密钥

openAPI 标准模式（推荐普通用户）：

export WEATHERCN_OPENAPI_KEY="your_openapi_key"

JV 高阶模式（商务授权）：

export WEATHERCN_API_KEY="your_api_key"
export WEATHERCN_API_SECRET="your_api_secret"

JV 与 openAPI 密钥可并存：两者都配置时，实况/预报/预警等共用接口默认走 JV；仅配置 WEATHERCN_OPENAPI_KEY 时走 openAPI。台风/天文/潮汐仅 JV。详见 .env.example。

运行

安装后可直接启动 MCP（stdio）：

weatherwork-consumer-mcp

启动时会通过 MCP instructions 下发 SYSTEM_PROMPT.md 中的助手规则。Cursor 一般无需额外配置。

---

接入 VS Code / GitHub Copilot（推荐流程）

Copilot 不会稳定使用 MCP initialize.instructions，请按下面三步适配（与 Cursor 行为对齐）。

0. 检查是否已适配（推荐先跑）

pip install -e .
weatherwork-consumer-mcp --check-vscode-setup
# 或独立命令：
weatherwork-check-vscode --workspace /你的项目路径

• 退出码 0：.github/copilot-instructions.md 等已就绪
• 退出码 1：缺少必要文件（会打印修复命令）
• 退出码 2：仅有警告（如规则版本过期、缺 .env.mcp.local）

安装后也可查看说明：weatherwork-consumer-mcp --install-hint

VS Code 启动 MCP 时自动同步：首次在 VS Code 中连接本 MCP（或规则版本与包版本不一致）时，会自动写入/更新 .github/copilot-instructions.md 与 .github/agents/weather.agent.md（日志仅输出到 stderr，不影响 MCP stdio）。请新开一条 Agent 对话后 Copilot 才会读到最新规则。禁用自动同步：WEATHERWORK_SKIP_VSCODE_AUTO_SYNC=1。

1. 一键生成 Copilot 规则与配置（可选，与自动同步相同）

在要使用天气助手的仓库根目录执行（开发时可在本包目录与上层工作区各执行一次）；通常不必再手动执行，除非要在未启动 MCP 时单独更新文件：

weatherwork-sync-vscode
# 若 MCP 工作区在上一级目录，例如：
weatherwork-sync-vscode --workspace ..
# 或：weatherwork-check-vscode --workspace .. --sync

将生成（已存在 .vscode/mcp.json 时不会覆盖）：

文件	作用
.github/copilot-instructions.md	每次对话自动注入的路由与输出规范（与 SYSTEM_PROMPT.md 同步）
.github/agents/weather.agent.md	可选：在 Agent 列表选择 weather 专用助手
.vscode/mcp.json	MCP 服务器配置（weatherwork + envFile）

修改 SYSTEM_PROMPT.md 后：重启 MCP 即可自动更新 Copilot 规则；或手动运行 weatherwork-sync-vscode。

2. 配置密钥与 MCP

复制 .env.mcp.local.example 为仓库根目录的 .env.mcp.local 并填写 WEATHERCN_OPENAPI_KEY。

VS Code：MCP: Restart Servers → 使用 Agent 模式 → 在工具列表启用 weatherwork（含 get_today_weather）。

.vscode/mcp.json 示例：

{
  "servers": {
    "weatherwork": {
      "type": "stdio",
      "command": "weatherwork-consumer-mcp",
      "envFile": "${workspaceFolder}/.env.mcp.local"
    }
  }
}

3. MCP Prompt（可选兜底）

在聊天输入框输入 /，选择 mcp.weatherwork.weather-assistant（或类似名称），可手动注入完整规则。

VS Code 工具路由要点

用户问题	优先工具
今天天气 / 今天热吗	get_today_weather
两小时内有没有雨 / 带伞	默认 get_hourly_forecast（可补 get_current_weather）；仅用户明确给出经纬度时可用 get_minute_precipitation
仅此刻多少度	get_current_weather

---

接入 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "weatherwork": {
      "command": "weatherwork-consumer-mcp",
      "env": {
        "WEATHERCN_OPENAPI_KEY": "your_openapi_key"
      }
    }
  }
}

接入 Cursor

.cursor/mcp.json 示例：

{
  "mcpServers": {
    "weatherwork": {
      "command": "weatherwork-consumer-mcp",
      "envFile": "${workspaceFolder}/.env.mcp.local"
    }
  }
}

工具列表

工具	说明
resolve_location	地名解析与消歧义
get_weather_alerts	气象预警（透传，勿解读）
get_today_weather	今日天气聚合（实况 + 逐日 + 24h，VS Code 首选）
get_current_weather	当前实况
get_weather_forecast	逐日预报
get_hourly_forecast	逐小时预报
get_activity_advice	生活指数与活动建议
get_air_quality	空气质量
get_minute_precipitation	分钟级降水（GCJ-02 坐标）
get_typhoon_*	台风（JV）
get_astronomy_*	天文（JV）
get_tidal_*	潮汐（JV）

MCP Prompt	说明
weather-assistant	注入完整 SYSTEM_PROMPT 规则（VS Code / 菜单）

本地测试

pip install -e .
export WEATHERCN_OPENAPI_KEY="..."
python tests/test_tools.py

发布到 PyPI（维护者）

pip install build twine
python -m build
twine upload dist/*

目录结构

weatherwork-consumer-mcp/
├── pyproject.toml
├── README.md
├── SYSTEM_PROMPT.md
├── vscode/agents/weather.agent.md   # Custom Agent 模板
├── scripts/                         # （可选）维护脚本
├── tests/test_tools.py
└── src/weatherwork_consumer_mcp/
    ├── server.py
    ├── vscode_sync.py               # weatherwork-sync-vscode
    ├── prompts.py
    └── tools/

环境要求

• Python 3.11+
• 依赖：mcp>=1.0.0,<2（本包仍用 MCP Python SDK 1.x 装饰器 API）