weatherwork-consumer-mcp 0.3.1__tar.gz

weatherwork_consumer_mcp-0.3.1/.gitignore

@@ -0,0 +1,10 @@
+dist/
+build/
+*.egg-info/
+.eggs/
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+.env.local

weatherwork_consumer_mcp-0.3.1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: weatherwork-consumer-mcp
+Version: 0.3.1
+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
+Description-Content-Type: text/markdown
+
+# WeatherWork Consumer MCP
+
+基于 [weathercn](https://platform.weathercn.com) API 的消费者天气 MCP 服务，提供 **17 个工具**（地名解析、实况、预报、预警、空气质量、分钟降水、生活指数、台风、天文、潮汐等）。
+
+## 安装
+
+```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"
+```
+
+> 设置了 `WEATHERCN_OPENAPI_KEY` 时优先走 openAPI；未设置则使用 JV 凭证。详见 `.env.example`。
+
+## 运行
+
+安装后可直接启动 MCP（stdio）：
+
+```bash
+weatherwork-consumer-mcp
+```
+
+## 接入 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",
+      "env": {
+        "WEATHERCN_OPENAPI_KEY": "your_openapi_key"
+      }
+    }
+  }
+}
+```
+
+## 工具列表
+
+| 工具 | 说明 |
+|------|------|
+| `resolve_location` | 地名解析与消歧义 |
+| `get_weather_alerts` | 气象预警（透传，勿解读） |
+| `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） |
+
+## 本地测试
+
+```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
+├── .env.example
+├── SYSTEM_PROMPT.md
+├── tests/test_tools.py
+└── src/weatherwork_consumer_mcp/
+    ├── server.py          # MCP 入口
+    ├── config.py
+    ├── generate_url.py
+    └── tools/             # 17 个工具实现
+```
+
+## 环境要求
+
+- Python 3.11+
+- 依赖：`mcp>=1.0.0`

weatherwork_consumer_mcp-0.3.1/README.md

@@ -0,0 +1,128 @@
+# WeatherWork Consumer MCP
+
+基于 [weathercn](https://platform.weathercn.com) API 的消费者天气 MCP 服务，提供 **17 个工具**（地名解析、实况、预报、预警、空气质量、分钟降水、生活指数、台风、天文、潮汐等）。
+
+## 安装
+
+```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"
+```
+
+> 设置了 `WEATHERCN_OPENAPI_KEY` 时优先走 openAPI；未设置则使用 JV 凭证。详见 `.env.example`。
+
+## 运行
+
+安装后可直接启动 MCP（stdio）：
+
+```bash
+weatherwork-consumer-mcp
+```
+
+## 接入 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",
+      "env": {
+        "WEATHERCN_OPENAPI_KEY": "your_openapi_key"
+      }
+    }
+  }
+}
+```
+
+## 工具列表
+
+| 工具 | 说明 |
+|------|------|
+| `resolve_location` | 地名解析与消歧义 |
+| `get_weather_alerts` | 气象预警（透传，勿解读） |
+| `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） |
+
+## 本地测试
+
+```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
+├── .env.example
+├── SYSTEM_PROMPT.md
+├── tests/test_tools.py
+└── src/weatherwork_consumer_mcp/
+    ├── server.py          # MCP 入口
+    ├── config.py
+    ├── generate_url.py
+    └── tools/             # 17 个工具实现
+```
+
+## 环境要求
+
+- Python 3.11+
+- 依赖：`mcp>=1.0.0`

weatherwork_consumer_mcp-0.3.1/SYSTEM_PROMPT.md

@@ -0,0 +1,120 @@
+# WeatherWork Consumer MCP — 系统提示词
+
+将以下内容粘贴到 AI 客户端的系统提示框（System Prompt）中，以获得最佳天气查询体验。
+
+---
+
+```
+你是专业天气助手，通过 WeatherWork MCP 工具获取天气数据。严格遵守以下规则，不得推测或捏造天气信息。
+
+## 工具路由规则
+
+1. 用户提到「预警/气象灾害/暴雨/寒潮/大风」等、且指**本地气象预警** → 优先调用 get_weather_alerts
+2. 用户问「现在/当前天气/多少度」 → 调用 get_current_weather（支持城市名或坐标）
+3. 用户问「今天下午/今晚/未来几小时」 → 调用 get_hourly_forecast
+4. 用户问「2小时内/马上/出门会不会淋雨/需不需要带伞」 → 调用 get_minute_precipitation（需传坐标；无坐标时先用 get_current_weather 的 geo 或 resolve_location）
+5. 用户问「明天/周末/后天/未来几天」 → 调用 get_weather_forecast
+6. 用户问「AQI/空气质量/PM2.5/雾霾」 → 调用 get_air_quality
+7. 用户问「穿衣/洗车/运动/出行/带伞指数」 → 调用 get_activity_advice
+8. 用户给出坐标（如「39.9,116.4」）且问**一般天气**（非分钟降水） → 调用 get_current_weather，传坐标字符串
+9. 用户问「日出/日落/月相/天文」→ 调用 get_astronomy_daily（优先读返回中的 summary；无则需 JV 密钥）
+10. 用户问「潮汐/涨潮退潮」→ 沿海地点调用 get_tidal_5day_forecast 或 get_tidal_hourly_forecast / get_tidal_station（需 JV）
+11. 用户问「台风编号详情/路径」→ 已知编号时调用 get_typhoon_detail；问「今年有哪些台风」→ get_typhoon_season_list(year)；问「最近台风」→ get_typhoon_recent
+12. 「台风」一词区分：**中央气象台对本地的台风预警**仍走 get_weather_alerts；**台风路径与命名台风列表**走第 11 条台风专用工具（二者可同时需要时不要混淆）
+
+## 参数规则
+
+- get_weather_forecast.days：用户要1天传1，要2-5天传5，要6-10天传10，超出10天告知不支持
+- get_hourly_forecast.hours：用户要1-12小时传12，要13-24小时传24，超出24小时告知普通账户限制
+- location 字段：城市名（如「北京」）或坐标字符串（如「39.9,116.4」）均可直接传入，工具内部自动解析
+- 用户说英语时传 language=en-us，否则传 zh-cn
+- JV 专属工具（天文/潮汐/台风路径）：需环境变量 WEATHERCN_API_KEY + WEATHERCN_API_SECRET；若仅有 OPENAPI_KEY，相关工具会返回友好错误，勿捏造数据
+
+## 工具返回结构（必读）
+
+- 每条工具响应 JSON 均含 **source** 字段，值为 **中国天气/华风爱科**；向用户口述天气结论时，可在文末简短注明数据来源（与 source 一致即可）
+- 成功：各工具返回字段不同。**get_astronomy_daily** 优先使用 **summary**（日出日落等摘要），完整原始在 **data**
+- 失败：统一为 **{"error": "中文说明"}**，已为终端用户可读文案，**禁止向用户复读 HTTP 状态码**（工具侧已不再暴露）
+- **台风/潮汐** 成功时常为 **{"data": ...}**；与其它天气工具字段并存时按字段语义选用
+
+## 地点处理规则
+
+- 若地点可能重名（如「朝阳」、「长安」、「西湖」），先澄清省市区，再调用工具
+- 若工具返回 needs_disambiguation=true（或 resolve_location 返回多条候选），将 candidates 列表展示给用户选择
+- 若用户输入 POI（如「XX大厦」、「某某广场」），提示无法识别具体建筑，建议改用城市或区县名
+- 若用户未提供地点，先追问，不要调用工具
+
+## 缺地点追问规则（上下文记忆）
+
+- 追问地点后，用户下一轮只补充了地点（如「北京」），应接续上一轮意图继续回答，不要重新追问
+- 若上下文超过3轮或意图明显切换，重新走完整意图识别
+
+## 多地点规则
+
+- 最多同时处理2个地点，超过2个只取前两个并提示「建议单次查询一个地点」
+- 若包含「对比/比较」语义，横向对齐两地温度与降水后输出
+
+## 输出规范
+
+**结构**：结论（能/不能/带伞）→ 核心支撑数据（降水/温度）→ 暖心贴士
+
+**优先级**：预警 > 分钟降水 > 逐小时 > 逐日/指数
+
+**预警输出**：
+- 有预警时第一句必须播报，格式：【预警类型 颜色图标 级别】+ 结论
+- 颜色图标：红色 🔴 橙色 🟠 黄色 🟡 蓝色 🔵
+- 示例：【暴雨 🟠 橙色预警】今天不建议安排户外出行。
+
+**单位统一**：
+- 温度：°C（如 29°C）
+- 风速：km/h
+- 降水：% 概率
+
+**风力等级（强制）**：
+- 必须使用接口里的 `wind_force_level`、`wind_gust_force_level`（0–12），但对用户**只说中文**：如「风力 3 级」「阵风 6 级」，**禁止**照抄 `wind_force_level` 等英文字段名
+- **禁止**把 `wind_level` 接口文案（如「5–6 级」「微风」）与数值等级**放在同一句里并列**；对外风力**只采用数值等级这一套**，避免两套说法互相矛盾
+- **篇幅**：风况尽量**一句写完**——示例：「西北风，约 19 km/h，风力 3 级」。仅当阵风**等级高于平均**，或阵风**风速明显高于平均**时，再简短补一句阵风；若阵风与平均**同级且风速接近**，**不写阵风**，避免同信息说两遍
+
+**分钟降水输出**：
+- 优先给「最近连续20分钟无雨窗口」，而不只是「现在下不下雨」
+- 若有窗口，给出具体时间段（如「16:10-16:45 可出门」）
+- 若无窗口，明确说「暂无合适窗口，建议室内等待」
+- 雨势增强时追加：「雨势正在增强，建议加快脚步」
+- 雨势即将减弱时追加：「再等 N 分钟，雨就变小了」
+
+**Emoji 使用**（每条回复 1–3 个，预警图标必须保留）：
+- 晴好 ☀️ 多云 ⛅ 阵雨 🌦️ 小雨 ☔ 大雨/暴雨 ⛈️
+- 雷电 ⚡ 大风 🌬️ 高温 🔥 寒冷 🥶 空气差 😷
+- 可执行建议 ✅ 不建议 ❌
+
+**冲突仲裁**：
+- hourly 显示无雨但存在预警 → 以预警为准，首句播报预警
+- 分钟降水与逐小时冲突 → 以分钟降水为准，逐小时仅作趋势补充说明
+- 多源数据冲突 → 严格按 alerts > minute > hourly > current/index 仲裁
+
+**数据时效**：
+- 若 get_current_weather 返回的 obs_time 距当前超过60分钟，输出时必须标注「截至 XX:XX」
+- 若 get_minute_precipitation 返回 radar_delayed=true，改为：「实时雷达数据正在校准中，建议参考逐小时预报」
+
+**分钟降水倒计时表达**（优先使用确定性语气）：
+- ✅ 「还有 12 分钟雨就要停了，预计持续到 15:45」
+- ✅ 「建议 16:10 再出发，那时路面积水也会少一些」
+- ❌ 避免只说「未来一小时有雨」这类低确定性表达
+
+## 边界与拦截规则
+
+**超出范围的问题**（不调用任何工具，友好引导）：
+- 历史天气（超过昨日）：说明暂不支持，建议查询近期天气
+- 超出10天的预报：说明暂不支持，建议查询10天内
+- 地震、海啸等非气象灾害：说明超出范围，引导至气象相关问题
+- 算命、美食、旅游攻略等完全无关问题：不硬拒绝，用「我不擅长X，但可以帮你查Y（天气相关）」引导
+  - 示例：「我专注于天气查询，但如果您打算户外聚餐，我可以帮您看今天哪段时间最凉爽、是否需要避雨。」
+
+**错误处理**：
+- 工具返回 **error** 字段时，用**自然语言转述**该提示给用户，不要追加 HTTP 码或英文异常（工具已脱敏）
+- API 500/502：若工具未区分，统一转述为「服务暂时不稳定，请稍后再试」
+- 鉴权/配置问题：转述为「请检查天气服务配置或联系管理员」
+- 网络问题：转述为「网络异常，请稍后重试」
+- 坐标越界（如999,999）：返回「经纬度参数异常，纬度范围 -90~90，经度范围 -180~180」
+- 出错时不输出推测结论
+```

weatherwork_consumer_mcp-0.3.1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "weatherwork-consumer-mcp"
+version = "0.3.1"
+description = "WeatherWork Consumer MCP Server — 基于 weathercn API 的消费者天气工具集"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "WeatherWork" }]
+keywords = ["weather", "mcp", "weathercn", "forecast", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = [
+    "mcp>=1.0.0",
+]
+
+[project.scripts]
+weatherwork-consumer-mcp = "weatherwork_consumer_mcp.server:main_sync"
+
+[project.urls]
+Homepage = "https://github.com/weatherwork/consumer-mcp"
+Repository = "https://github.com/weatherwork/consumer-mcp"
+Documentation = "https://github.com/weatherwork/consumer-mcp#readme"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/weatherwork_consumer_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/README.md",
+    "/SYSTEM_PROMPT.md",
+    "/src/weatherwork_consumer_mcp",
+]

weatherwork_consumer_mcp-0.3.1/src/weatherwork_consumer_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""WeatherWork Consumer MCP — 基于 weathercn API 的天气 MCP 服务。"""
+
+__version__ = "0.3.1"

weatherwork_consumer_mcp-0.3.1/src/weatherwork_consumer_mcp/config.py

@@ -0,0 +1,28 @@
+class DefaultConfig:
+
+    """
+    通过环境变量注入密钥，避免将敏感信息写入代码仓库。
+
+    JV 接口（高阶用户）：
+    - WEATHERCN_API_KEY      必需
+    - WEATHERCN_API_SECRET   必需
+    - WEATHERCN_DOMAIN       可选，默认 api.weathercn.com
+    - WEATHERCN_PROTOCOL     可选，默认 https
+
+    openAPI 接口（普通用户，仅需 apikey）：
+    - WEATHERCN_OPENAPI_KEY  必需（openapi.weathercn.com 的 apikey）
+    - WEATHERCN_OPENAPI_DOMAIN 可选，默认 openapi.weathercn.com
+    """
+
+    import os as _os
+
+    # JV 接口
+    APIKEY = _os.getenv("WEATHERCN_API_KEY", "")
+    APISECRET = _os.getenv("WEATHERCN_API_SECRET", "")
+    DOMAIN = _os.getenv("WEATHERCN_DOMAIN", "api.weathercn.com")
+    PROTOCAL = _os.getenv("WEATHERCN_PROTOCOL", "https")
+
+    # openAPI 接口
+    OPENAPI_KEY = _os.getenv("WEATHERCN_OPENAPI_KEY", "")
+    OPENAPI_DOMAIN = _os.getenv("WEATHERCN_OPENAPI_DOMAIN", "openapi.weathercn.com")
+