天机气象API工具集
基于天机气象API的完整解决方案，提供CLI命令行工具和MCP协议服务器，支持JSON和NetCDF格式的气象数据获取。
🚀 快速开始
安装
# 克隆仓库
git clone https://github.com/yourusername/tjweather.git
cd tjweather
# 运行安装脚本
./install.sh基本使用
# 初始化配置
tjweather init
# 查询天气数据
tjweather query -l "116.23128,40.22077" -f t2m -d 3
# 下载NetCDF文件
tjweather download -l "116.23128,40.22077" -f t2m -d 3 -o weather.nc📁 项目结构
tjweather/
├── docs/ # 📚 文档中心
│ ├── README.md # 项目主文档 (本文件)
│ ├── index.md # 文档导航中心
│ ├── QUICK_START.md # 5分钟快速上手
│ ├── api/ # API 文档
│ │ └── api_readme # 天机气象API文档
│ ├── user-guide/ # 用户指南
│ │ ├── 多要素查询指南.md # 多要素查询说明
│ │ └── NetCDF数据下载指南.md # NetCDF下载说明
│ ├── development/ # 开发文档
│ │ ├── 命令格式重构报告.md # CLI架构演进
│ │ └── CLI工具调试报告.md # 功能测试报告
│ ├── deployment/ # 部署文档
│ │ ├── GITHUB.md # GitHub设置指南
│ │ └── 仓库初始化报告.md # 项目结构记录
│ ├── INSTALL.md # 安装指南
│ └── LICENSE # MIT许可证
├── tjweather-cli/ # 🔧 CLI 命令行工具
│ ├── src/ # TypeScript 源码
│ ├── dist/ # 编译输出
│ ├── package.json # 包配置
│ ├── install.sh # 📦 安装脚本
│ ├── uninstall.sh # 🗑️ 卸载脚本
│ └── README.md # CLI使用文档
├── tjweather-mcp/ # 🔌 MCP 协议服务器
│ ├── src/ # TypeScript 源码
│ ├── dist/ # 编译输出
│ ├── package.json # 包配置
│ └── README.md # MCP使用文档
├── .env.example # 🔑 配置模板
├── .gitignore # Git 忽略文件
├── .gitattributes # Git 属性配置
└── README.md # 项目主文档 (本文件)📚 文档中心
🚀 快速开始
📖 用户指南
- 多要素查询指南 - 一次获取多个气象要素
- NetCDF数据下载指南 - 下载科学数据格式
🛠️ 开发文档
🚀 部署文档
- - 仓库配置和发布
- 仓库初始化报告 - 项目结构记录
🔌 API文档
- 天机气象API文档 - 完整API接口说明
🎯 功能特性
CLI工具 (tjweather)
- 天气查询: 支持表格、JSON、CSV格式输出
- NetCDF下载: 科学数据格式，支持多要素
- 多要素查询: 一次请求获取多个气象要素
- 全局配置: 多层级配置管理系统
- 错误处理: 友好的错误提示和参数验证
MCP服务器 (tjweather-mcp)
- 标准协议: 基于Model Context Protocol
- AI集成: 支持Claude Code等AI工具
- 工具集: weather_query、weather_fields_info等
- 配置共享: 与CLI工具统一的配置管理
核心特性
- ✅ 160+气象要素: 风速、温度、湿度、气压等
- ✅ 全球覆盖: 支持全球任意经纬度查询
- ✅ 高分辨率: 15分钟和1小时时间分辨率
- ✅ 灵活预报: 支持45天内预报数据
- ✅ 多格式输出: JSON、表格、CSV、NetCDF
🛠️ 安装和部署
方法1: 使用安装脚本（推荐）
./install.sh方法2: 手动安装
# CLI工具
cd tjweather-cli
npm install
npm run build
npm link
# MCP服务器
cd ../tjweather-mcp
npm install
npm run build方法3: 全局安装
npm install -g ./tjweather-cli
npm install -g ./tjweather-mcp🔧 配置
初始化配置
tjweather init配置文件位置
- 当前目录:
./.env - 用户配置:
~/.config/tjweather/.env - 环境变量: 系统环境变量
配置格式
# 天机气象API配置
API_KEY=YOUR_API_KEY_HERE
NC_ENDPOINT=https://api.tjweather.com/nc/beta
JSON_ENDPOINT=https://api.tjweather.com/beta🌟 使用示例
基本查询
# 查询温度
tjweather query -l "116.23128,40.22077" -f t2m -d 3
# 多要素查询
tjweather query -l "116.23128,40.22077" -f "t2m,rh2m" -d 7
# 高分辨率预报
tjweather query -l "116.23128,40.22077" -f t2m -d 0 -h 24 -r 15min数据下载
# 下载NetCDF文件
tjweather download -l "116.23128,40.22077" -f t2m -d 7 -o weather.nc
# 多要素高分辨率下载
tjweather download -l "116.23128,40.22077" -f "t2m,rh2m,tp" -d 0 -h 24 -r 15min配置管理
# 查看配置
tjweather config
# 显示API密钥
tjweather config --show-secret
# 详细模式
tjweather --verbose query -l "116.23128,40.22077" -f t2m🔌 MCP集成
配置MCP服务器
在Claude Code中添加：
{
"mcpServers": {
"tjweather": {
"command": "/path/to/tjweather-mcp/dist/index.js"
}
}
}可用工具
weather_query- 查询天气数据weather_fields_info- 获取气象要素信息
🌐 支持的气象要素
常用要素
t2m: 2米温度 (°C) ✅rh2m: 2米相对湿度 (%) ✅ws100m: 100米风速 (m/s) ⚠️ 需要订阅ssrd: 辐照度 (W/㎡) ⚠️ 需要订阅
更多要素
- 160+ 气象要素支持
- 全球和中国特有要素
- 多高度层数据
- 降水和云量信息
📦 技术栈
- 语言: TypeScript + Node.js
- CLI框架: Commander.js
- HTTP客户端: Axios
- MCP协议: @modelcontextprotocol/sdk
- 配置管理: dotenv
- 输出格式: 彩色表格、JSON、CSV、NetCDF
🤝 贡献指南
开发环境
# 安装依赖
cd tjweather-cli && npm install
cd ../tjweather-mcp && npm install
# 开发模式
npm run dev
# 构建
npm run build代码规范
- TypeScript严格模式
- ESLint代码检查
- 语义化提交信息
- 完整的文档更新
📄 许可证
本项目采用 MIT 许可证。
🆘 支持
- 📧 邮箱: popfrog@gmail.com
- 🐛 问题反馈: GitHub Issues
- 📖 文档: docs/
- 💬 讨论: GitHub Discussions
天机气象API工具集 - 让气象数据获取变得简单高效！ 🌤️