npm package: @lakphy-tools/caiyun-mcp
Description: 彩云天气API的MCP server，提供天气查询功能
Author: lakphy
Latest version: 0.1.1

# 彩云天气 MCP Server

🌤️ 一个基于[彩云天气 API v2.6](https://docs.caiyunapp.com/weather-api/v2/v2.6/)的专业天气数据 MCP (Model Context Protocol) 服务器

**彩云天气**是中国领先的精准天气服务提供商，为用户提供高精度、多时效的专业气象数据服务。本MCP Server将彩云天气强大的API能力封装为标准化的MCP工具，让AI助手能够轻松获取和分析天气信息。

## 🎯 功能特性

### 核心能力
- 🌡️ **高精度数据**: 基于多源气象数据融合，提供精准的天气信息
- 🕐 **多时效预报**: 从分钟级到15天的全时效天气预报覆盖
- 🌍 **全域覆盖**: 支持中国大陆任意经纬度位置的天气查询
- 🌐 **多语言支持**: 支持15种语言，包括中英日韩德法等主要语言
- 📏 **灵活单位**: 支持公制和英制单位制自由切换
- 🚨 **官方预警**: 基于中国气象局发布的权威气象灾害预警

### 🛠️ MCP工具清单

#### 1️⃣ **实时天气** (`get_realtime_weather`)
获取当前精准天气状况，包含完整的气象要素：
- 🌡️ 温度、体感温度、湿度、云量
- 💨 风速、风向、气压、能见度  
- 🌧️ 降水状况、降水强度
- 🫁 PM2.5/PM10/O3等空气质量指数
- 🌞 紫外线指数、舒适度指数

#### 2️⃣ **分钟级降水预报** (`get_minutely_precipitation`) 
精确到分钟的短临降水预测：
- ⏰ 未来120分钟逐分钟降水强度
- 📊 降水概率分析
- 🎯 基于雷达回波的高精度预测

#### 3️⃣ **小时级预报** (`get_hourly_forecast`)
详细的逐小时天气演变：
- ⏳ 支持1-360小时(最长15天)预报
- 📈 逐小时温度、湿度、降水等要素变化
- 🌬️ 风力风向、气压、能见度趋势

#### 4️⃣ **天级预报** (`get_daily_forecast`)
中长期天气趋势分析：
- 📅 支持1-15天预报范围  
- 🌅 白天/夜晚天气现象区分
- 📊 每日最高/最低/平均值统计
- 🏃 生活指数：洗车、穿衣、感冒、紫外线等

#### 5️⃣ **官方预警** (`get_weather_alerts`)  
权威气象灾害预警信息：
- 🚨 台风、暴雨、暴雪、大风等预警
- 📍 精确到县级行政区划
- ⏰ 预警发布时间、更新时间
- 📝 详细预警描述和防护建议

#### 6️⃣ **综合天气** (`get_comprehensive_weather`)
一站式完整天气信息：
- 🔄 整合实时、预报、预警于一体
- ⚡ 减少API调用次数，提升效率
- 🎛️ 支持所有参数自定义配置

## 安装

1. 克隆项目并安装依赖：

```bash
git clone <repository-url>
cd caiyun-mcp
npm install
```

2. 构建项目：

```bash
npm run build
```

3. 获取彩云天气 API 密钥：
   - 访问[彩云科技开放平台](https://caiyunapp.com/api)
   - 注册账号并申请彩云天气 API 访问令牌
   - 完成开发者信息申请，等待审核通过

## 使用方法

### 环境变量配置

设置彩云天气 API 令牌：

```bash
export CAIYUN_API_TOKEN="your_api_token_here"
```

### 启动 MCP Server

```bash
npm start
# 或者直接运行
node dist/index.js
```

### 在 MCP 客户端中使用

配置你的 MCP 客户端连接到此 server。以下是各工具的使用示例：

#### 1. 获取实时天气

```json
{
  "tool": "get_realtime_weather",
  "arguments": {
    "longitude": 116.3176,
    "latitude": 39.976,
    "lang": "zh_CN",
    "unit": "metric:v2"
  }
}
```

#### 2. 获取分钟级降水预报

```json
{
  "tool": "get_minutely_precipitation",
  "arguments": {
    "longitude": 116.3176,
    "latitude": 39.976
  }
}
```

#### 3. 获取小时级预报

```json
{
  "tool": "get_hourly_forecast",
  "arguments": {
    "longitude": 116.3176,
    "latitude": 39.976,
    "hourlysteps": 48
  }
}
```

#### 4. 获取天级预报

```json
{
  "tool": "get_daily_forecast",
  "arguments": {
    "longitude": 116.3176,
    "latitude": 39.976,
    "dailysteps": 5
  }
}
```

#### 5. 获取天气预警

```json
{
  "tool": "get_weather_alerts",
  "arguments": {
    "longitude": 116.3176,
    "latitude": 39.976
  }
}
```

#### 6. 获取综合天气信息

```json
{
  "tool": "get_comprehensive_weather",
  "arguments": {
    "longitude": 116.3176,
    "latitude": 39.976,
    "hourlysteps": 48,
    "dailysteps": 5,
    "alert": true
  }
}
```

## 📋 参数详细说明

### 🎯 必需参数

#### 📍 地理坐标 (基于WGS84坐标系)
- **`longitude`** (经度): `-180°` ~ `+180°`
  - 东经为正值，西经为负值
  - 中国范围：73°E ~ 135°E
  - 示例：北京 116.3176°E，上海 121.4737°E，广州 113.2644°E
  - 💡 建议精确到小数点后4位以获得最佳定位精度

- **`latitude`** (纬度): `-90°` ~ `+90°`  
  - 北纬为正值，南纬为负值
  - 中国范围：18°N ~ 54°N
  - 示例：北京 39.9760°N，上海 31.2304°N，广州 23.1291°N
  - 💡 推荐使用GPS获取的高精度坐标

### ⚙️ 可选参数

#### 🌐 语言设置 (`lang`)
支持15种语言，影响天气描述、地名、预警信息等的语言显示：
- `zh_CN` - 🇨🇳 简体中文 (默认)
- `zh_TW` - 🇭🇰 繁体中文  
- `en_US` - 🇺🇸 美式英语
- `en_GB` - 🇬🇧 英式英语
- `ja` - 🇯🇵 日语
- `de` - 🇩🇪 德语
- `fr` - 🇫🇷 法语  
- `es` - 🇪🇸 西班牙语
- `it` - 🇮🇹 意大利语
- `ko` - 🇰🇷 韩语
- `ru` - 🇷🇺 俄语
- `hi` - 🇮🇳 印地语
- `th` - 🇹🇭 泰语
- `vi` - 🇻🇳 越南语
- `ar` - 🇸🇦 阿拉伯语

#### 📏 单位制设置 (`unit`)
- **`metric:v2`** - 公制单位 (默认，推荐)
  - 温度: °C | 风速: km/h | 距离: km | 气压: Pa | 降水: mm/h
- **`imperial`** - 英制单位
  - 温度: °F | 风速: mph | 距离: mile | 气压: inHg | 降水: in/h
- **`metric`** - 旧版公制单位 (部分单位与v2不同)

#### ⏰ 预报时长设置
- **`hourlysteps`** - 小时级预报步数 (1-360小时，默认48)
  - 24 = 1天 | 48 = 2天 | 72 = 3天 | 120 = 5天 | 240 = 10天 | 360 = 15天(最大)
  - 💡 较小值适合短期精准预报，较大值适合长期趋势分析

- **`dailysteps`** - 天级预报步数 (1-15天，默认5)
  - 1 = 今天 | 3 = 未来3天 | 5 = 未来5天 | 7 = 一周 | 15 = 最长预报
  - ⚠️ 预报时间越长，不确定性越大

#### 🚨 预警开关 (`alert`)
- **`true`** (默认) - 包含气象预警信息
  - 返回当前生效的所有预警：台风、暴雨、暴雪、寒潮、大风、沙尘、高温、干旱等
  - 数据来源：中国气象局官方发布
- **`false`** - 不返回预警信息，减少数据量

## 📊 数据说明

### 🌤️ 天气现象代码 (Skycon)
彩云天气采用国际标准的天气现象分类，支持白天/夜晚区分：

#### 🌞 晴朗天气
- `CLEAR_DAY` / `CLEAR_NIGHT` - 晴天/晴夜 (云量<10%)

#### ☁️ 云量天气  
- `PARTLY_CLOUDY_DAY` / `PARTLY_CLOUDY_NIGHT` - 多云 (云量10%-90%)
- `CLOUDY` - 阴天 (云量>90%)

#### 🌧️ 降水天气
**雨类** (按强度分级)：
- `LIGHT_RAIN` - 小雨 (0.1-2.5mm/h)
- `MODERATE_RAIN` - 中雨 (2.6-8.0mm/h)  
- `HEAVY_RAIN` - 大雨 (8.1-15.9mm/h)
- `STORM_RAIN` - 暴雨 (≥16mm/h)

**雪类** (按强度分级)：
- `LIGHT_SNOW` - 小雪 (0.1-2.5mm/h水当量)
- `MODERATE_SNOW` - 中雪 (2.6-5.0mm/h)
- `HEAVY_SNOW` - 大雪 (5.1-10mm/h)
- `STORM_SNOW` - 暴雪 (>10mm/h)

#### 🌫️ 低能见度天气
- `FOG` - 雾 (水汽凝结，能见度<1km)
- `LIGHT_HAZE` - 轻雾霾 (能见度1-3km)
- `MODERATE_HAZE` - 中雾霾 (能见度0.5-1km)
- `HEAVY_HAZE` - 重雾霾 (能见度<0.5km)

#### 🌪️ 特殊天气
- `DUST` - 浮尘 (远距离输送的细颗粒物)
- `SAND` - 沙尘暴 (强风卷起大量沙尘)  
- `WIND` - 大风 (风力显著但无其他突出现象)

### 🫁 空气质量指数 (AQI)
提供双重标准的空气质量评估：

#### 🇨🇳 中国标准 (CHN AQI)
- 0-50: 优 🟢 (空气质量令人满意)
- 51-100: 良 🟡 (可接受，敏感人群需注意)
- 101-150: 轻度污染 🟠 (敏感人群有症状)
- 151-200: 中度污染 🔴 (所有人群开始出现症状)
- 201-300: 重度污染 🟣 (健康警告)
- 300+: 严重污染 🟤 (紧急状况)

#### 🇺🇸 美国标准 (USA AQI)
- 同样的6级分类，但计算方法和阈值略有不同
- 提供双语环境下的空气质量对比参考

#### 🔬 污染物浓度
- **PM2.5** - 细颗粒物 (μg/m³)
- **PM10** - 可吸入颗粒物 (μg/m³)  
- **O3** - 臭氧浓度 (μg/m³)
- **SO2** - 二氧化硫浓度 (μg/m³)
- **NO2** - 二氧化氮浓度 (μg/m³)
- **CO** - 一氧化碳浓度 (mg/m³)

### 🏃 生活指数
基于气象条件计算的实用生活建议：

- **🌞 紫外线指数** - UV强度等级 (1-15级)，防晒建议
- **🚗 洗车指数** - 洗车时机建议，考虑降水概率
- **👔 穿衣指数** - 着装厚薄建议，基于体感温度
- **😌 舒适度指数** - 人体舒适感，综合温湿度评估
- **🤧 感冒指数** - 感冒易感性，基于温差湿度变化

### 💨 风力风向
- **风向**: 16方位制 (N/NNE/NE/.../NNW)
- **风速**: 支持km/h, mph等多种单位
- **风向角度**: 0-360°，北为0°，顺时针增加

## 错误处理

Server 会自动处理以下错误情况：

- API 令牌未设置或无效
- 经纬度参数超出有效范围
- 网络连接失败
- 彩云天气 API 返回错误

所有错误都会以 MCP 标准错误格式返回，包含详细的错误描述。

## 📁 项目结构

本项目采用模块化架构，将功能按类型分为不同的模块：

```
src/
├── index.ts                    # MCP Server主入口
├── types.ts                    # TypeScript类型定义
├── tools/                      # 🛠️ 天气查询工具模块
│   ├── base.ts                 # 基础配置和接口
│   ├── index.ts                # 工具汇总导出
│   ├── realtime-weather.ts     # 实时天气
│   ├── minutely-precipitation.ts # 分钟级降水
│   ├── hourly-forecast.ts      # 小时级预报
│   ├── daily-forecast.ts       # 天级预报
│   ├── weather-alerts.ts       # 天气预警
│   └── comprehensive-weather.ts # 综合天气
├── prompts/                    # 💬 智能提示词系统
│   ├── index.ts                # 提示词系统入口
│   ├── base.ts                 # 基础架构和工具类
│   ├── knowledge.ts            # 知识类prompts(气象学、空气质量、预报)
│   ├── analysis.ts             # 分析类prompts(数据分析、生活指导)
│   ├── professional.ts         # 专业类prompts(行业服务、教育科普)  
│   ├── dynamic.ts              # 动态生成系统
│   ├── mcp-integration.ts      # MCP协议集成
│   └── README.md               # 系统详细说明
└── resources/                  # 📦 资源模块（预留）
    ├── index.ts                # 资源配置
    └── README.md               # 模块说明
```

### 🎯 模块化优势

- **🔧 易于维护**: 每个工具独立文件，修改不互相影响
- **📈 可扩展性**: 新增工具只需添加对应文件
- **👥 团队协作**: 不同开发者可并行开发不同工具
- **🔄 代码复用**: 公共配置统一管理，避免重复
- **📚 文档清晰**: 每个模块都有明确的职责和说明
- **🧠 智能化**: 完整的prompt系统，为AI提供丰富的气象知识

## 🧠 MCP Prompt 系统

本项目包含了完整的MCP Prompt系统，为AI提供专业的天气知识服务:

### 📚 知识体系
- **🌤️ 气象学专家**: 深度解析天气现象和物理机制
- **🌫️ 空气质量专家**: 专业的AQI分析和健康指导  
- **🔮 预报技术专家**: 天气预报原理和精度评估
- **📊 数据分析师**: 专业的天气数据分析和解读
- **🏠 生活顾问**: 个性化的生活天气指导
- **🏢 行业专家**: 面向各行业的专业气象服务
- **🎓 教育专家**: 生动的气象科普和教育内容

### 🤖 智能特色
- **动态生成**: 基于实时天气数据自动生成分析内容
- **个性化**: 根据用户特征和需求定制服务
- **多层次**: 支持基础到专家级的不同深度服务
- **本土化**: 专门针对彩云天气API和中国气象特点优化

详细信息请参考:
- 项目架构: [ARCHITECTURE.md](./ARCHITECTURE.md)
- Prompt系统: [MCP-PROMPTS.md](./MCP-PROMPTS.md)

## 🔧 开发

### 开发模式

```bash
npm run dev
```

### 运行测试

```bash
npm test
```

### 类型检查

```bash
npm run typecheck
```

### 添加新工具

1. 在 `src/tools/` 目录下创建新工具文件
2. 实现工具配置（参考现有工具文件）
3. 在 `src/tools/index.ts` 中导出新工具
4. 更新类型定义（如需要）

## License

MIT License

## 🚀 应用场景

### 🏢 企业级应用
- **智慧城市管理**: 城市气象监测、应急预案制定
- **农业生产**: 农作物生长监测、灌溉决策支持  
- **物流运输**: 路线规划、运输安全评估
- **能源管理**: 风电光伏发电预测、负荷预测
- **建筑工程**: 施工天气窗口、安全风险评估

### 🏠 个人应用
- **出行规划**: 旅游天气查询、通勤路线建议
- **健康生活**: 运动时机选择、疾病预防提醒
- **日常决策**: 穿衣搭配、洗车时机、户外活动安排

### 🤖 AI助手增强
- **智能问答**: 为AI助手提供实时准确的天气数据支持
- **上下文感知**: 基于天气情况提供个性化建议
- **多模态交互**: 结合语音、文本、图像的天气信息服务

## 🎖️ 技术优势

### 🎯 数据精准度
- **多源数据融合**: 结合气象观测站、卫星、雷达、数值预报模型
- **本土化优势**: 专注中国天气特点，预报精度优于国外产品
- **实时更新**: 数据更新频率高，保证信息时效性

### ⚡ 性能表现  
- **低延迟响应**: 平均响应时间<500ms
- **高并发支持**: 稳定服务，支持大规模并发访问
- **可靠性保证**: 99.9%+服务可用性，企业级稳定性

### 🔧 集成便利
- **标准化接口**: 完全符合MCP协议规范
- **丰富文档**: 详尽的API文档和示例代码  
- **灵活配置**: 支持多种参数组合，满足不同需求

## ⚠️ 使用限制与建议

### 📍 地理覆盖
- **主要支持**: 中国大陆地区 (18°N-54°N, 73°E-135°E)
- **数据精度**: 城市级精度最高，偏远地区精度略低
- **海外支持**: 海外地区数据有限，建议使用其他气象服务

### 🔑 API配额
- 请访问[彩云科技开放平台](https://caiyunapp.com/api)了解配额限制
- 建议根据使用频率选择合适的套餐方案  
- 合理使用缓存机制，避免不必要的重复请求

### 💡 最佳实践
- **位置精度**: 使用GPS坐标，精确到小数点后4位
- **缓存策略**: 相同位置的数据可缓存5-10分钟
- **错误处理**: 实现超时重试和降级机制
- **参数优化**: 根据实际需求选择合适的预报步数

## 🤝 社区与支持

### 📚 学习资源
- [彩云天气 API 文档](https://docs.caiyunapp.com/weather-api/v2/v2.6/) - 官方API详细文档
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP协议规范
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - MCP开发工具包

### 🆘 技术支持
- **API问题**: 访问彩云科技开放平台获取技术支持
- **MCP相关**: 查阅MCP官方文档或社区论坛
- **项目Issues**: 通过GitHub Issues报告问题和建议

### 🌟 贡献指南
欢迎为项目贡献代码、文档或建议：
1. Fork项目并创建特性分支
2. 提交代码并添加相应测试
3. 更新文档说明  
4. 提交Pull Request

---

<div align="center">

### 🌈 让AI助手拥有感知天气的能力

**基于彩云天气API v2.6 | 遵循MCP标准 | 开源免费使用**

*为您的AI应用注入专业的天气数据服务能力* ☀️🌧️❄️

</div>