Metadata-Version: 2.4
Name: weatherwork-consumer-mcp
Version: 0.3.2
Summary: WeatherWork Consumer MCP Server — 基于 weathercn API 的消费者天气工具集
Project-URL: Homepage, https://github.com/weatherwork/consumer-mcp
Project-URL: Repository, https://github.com/weatherwork/consumer-mcp
Project-URL: Documentation, https://github.com/weatherwork/consumer-mcp#readme
Author: WeatherWork
License: MIT
Keywords: forecast,mcp,model-context-protocol,weather,weathercn
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0.0
Requires-Dist: zhdate>=0.1
Description-Content-Type: text/markdown

# WeatherWork Consumer MCP

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

## 安装

```bash
pip install weatherwork-consumer-mcp
```

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

```bash
cd weatherwork-consumer-mcp
pip install -e .
```

## 配置密钥

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

```bash
export WEATHERCN_OPENAPI_KEY="your_openapi_key"
```

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

```bash
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）：

```bash
weatherwork-consumer-mcp
```

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

---

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

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

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

```bash
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 时单独更新文件：

```bash
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` 示例：

```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`：

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

## 接入 Cursor

`.cursor/mcp.json` 示例：

```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 `/` 菜单） |

## 本地测试

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

## 发布到 PyPI（维护者）

```bash
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`
