README.md•7.16 kB
# Weather MCP (Model Context Protocol) 天气查询服务
## 🌤️ 服务介绍
Weather MCP 是一个基于 Model Context Protocol (MCP) 的天气查询服务，通过集成 OpenWeather API 提供全球天气信息查询功能。该服务支持自然语言交互，用户可以用中文描述需求，系统会自动调用相应的天气查询工具并返回格式化的天气信息。
## 📋 服务描述
### 主要功能
- **全球天气查询**: 支持查询全球任意城市的实时天气信息
- **多语言支持**: 支持中文查询和中文天气描述
- **智能交互**: 通过大语言模型理解用户意图，自动调用天气查询工具
- **格式化输出**: 提供美观易读的天气信息展示
### 技术特点
- 基于 MCP 协议，支持与各种 AI 客户端集成
- 异步 HTTP 请求，提高响应速度
- 完善的错误处理和容错机制
- 支持 stdio 通信方式
## 🏗️ 类型
### 服务类型
- **MCP Server**: 提供天气查询工具的 MCP 服务器
- **MCP Client**: 支持与大语言模型交互的客户端
- **API Integration**: 集成 OpenWeather API 的天气数据服务
### 架构类型
- **微服务架构**: 服务器和客户端分离，支持独立部署
- **异步架构**: 基于 asyncio 的异步处理
- **协议驱动**: 基于 MCP 协议的标准化通信
## ⚙️ 服务配置
### 服务器配置 (server.py)
```python
# MCP 服务器配置
mcp = FastMCP("WeatherServer")
# OpenWeather API 配置
OPENWEATHER_API_BASE = "https://api.openweathermap.org/data/2.5/weather"
API_KEY = "your_api_key_here"
USER_AGENT = "weather-app/1.0"
# 请求参数配置
DEFAULT_PARAMS = {
"units": "metric", # 使用摄氏度
"lang": "zh_cn" # 中文语言
}
```
### 客户端配置 (client.py)
```python
class MCPClient:
def __init__(self):
self.openai_api_key = os.getenv("OPENAI_API_KEY")
self.base_url = os.getenv("BASE_URL")
self.model = os.getenv("MODEL")
self.client = OpenAI(api_key=self.openai_api_key, base_url=self.base_url)
```
### 项目依赖配置
#### Python 依赖 (pyproject.toml)
```toml
[project]
name = "weather-mcp"
version = "0.1.0"
description = "Weather MCP Server for global weather queries"
dependencies = [
"mcp>=1.0.0",
"httpx>=0.24.0",
"openai>=1.0.0",
"python-dotenv>=1.0.0"
]
[project.optional-dependencies]
dev = [
"pytest>=7.0.0",
"black>=23.0.0",
"flake8>=6.0.0"
]
```
#### Node.js 依赖 (package.json)
```json
{
"name": "weather-mcp",
"version": "0.1.0",
"description": "Weather MCP Server",
"dependencies": {
"commander": "^11.0.0"
}
}
```
## 🔧 环境变量配置
### 必需环境变量
创建 `.env` 文件并配置以下环境变量：
```bash
# OpenAI API 配置
OPENAI_API_KEY=your_openai_api_key_here
BASE_URL=https://api.openai.com/v1
MODEL=gpt-3.5-turbo
# OpenWeather API 配置 (在 server.py 中配置)
# API_KEY=your_openweather_api_key_here
```
### 环境变量说明
| 变量名 | 描述 | 示例值 | 是否必需 |
|--------|------|--------|----------|
| `OPENAI_API_KEY` | OpenAI API 密钥 | `sk-...` | ✅ 必需 |
| `BASE_URL` | OpenAI API 基础 URL | `https://api.openai.com/v1` | ✅ 必需 |
| `MODEL` | 使用的 OpenAI 模型 | `gpt-3.5-turbo` | ✅ 必需 |
### 获取 API 密钥
#### OpenAI API Key
1. 访问 [OpenAI Platform](https://platform.openai.com/)
2. 登录或注册账号
3. 进入 API Keys 页面
4. 创建新的 API Key
5. 复制密钥到 `.env` 文件
#### OpenWeather API Key
1. 访问 [OpenWeather API](https://openweathermap.org/api)
2. 注册免费账号
3. 获取 API Key
4. 在 `server.py` 中替换 `API_KEY` 变量
## 🚀 快速开始
### 1. 安装依赖
```bash
# 使用 uv 安装 Python 依赖
uv sync
# 或使用 pip
pip install -r requirements.txt
```
### 2. 配置环境变量
```bash
# 复制环境变量模板
cp .env.example .env
# 编辑 .env 文件，填入你的 API 密钥
nano .env
```
### 3. 启动服务器
```bash
# 启动 MCP 服务器
python server.py
```
### 4. 运行客户端
```bash
# 在另一个终端中运行客户端
python client.py server.py
```
### 5. 开始使用
```
你: 查询北京的天气
🤖 OpenAI: 我来为您查询北京的天气信息。
[Calling tool query_weather with args {'city': 'Beijing'}]
🤖 OpenAI: 根据查询结果，北京今天的天气情况如下：
📍 北京, CN
🌡️ 温度: 25°C
💧 湿度: 65%
💨 风速: 3.2 m/s
☁️ 天气: 多云
```
## 📁 项目结构
```
weather_mcp/
├── server.py # MCP 服务器主文件
├── client.py # MCP 客户端主文件
├── main.py # 项目入口文件
├── config.py # 配置文件
├── pyproject.toml # Python 项目配置
├── package.json # Node.js 项目配置
├── .env # 环境变量文件
├── .gitignore # Git 忽略文件
├── README.md # 项目说明文档
└── requirements.txt # Python 依赖列表
```
## 🔍 API 文档
### 可用工具
#### query_weather
- **描述**: 查询指定城市的天气信息
- **参数**:
- `city` (string): 城市名称（英文）
- **返回**: 格式化的天气信息字符串
### 使用示例
```python
# 查询天气
result = await session.call_tool("query_weather", {"city": "Shanghai"})
print(result.content[0].text)
```
## 🛠️ 开发指南
### 添加新的天气工具
1. 在 `server.py` 中添加新的工具函数
2. 使用 `@mcp.tool()` 装饰器注册工具
3. 实现工具逻辑和错误处理
4. 更新文档和测试
### 自定义配置
可以通过修改 `config.py` 文件来自定义服务配置：
```python
# 自定义天气 API 配置
WEATHER_CONFIG = {
"api_base": "https://api.openweathermap.org/data/2.5/weather",
"timeout": 30.0,
"retry_count": 3
}
```
## 📝 许可证
本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。
## 🤝 贡献
欢迎提交 Issue 和 Pull Request 来改进这个项目！
## 📞 支持
如果你遇到问题或有建议，请：
1. 查看 [Issues](https://github.com/LiuKeTong713/Weather_mcp/issues)
2. 创建新的 Issue
3. 联系项目维护者
---
**注意**: 请确保妥善保管你的 API 密钥，不要将其提交到版本控制系统中。
## 🔧 标准服务配置
```json
{
"mcpServers": {
"weather_mcp": {
"args": [
"server.py"
],
"command": "python",
"env": {
"OPENAI_API_KEY": "your_openai_api_key_here",
"BASE_URL": "your_model_base_url",
"MODEL": "YOUR_Model_Name",
"WEATHER_API_KEY": "your_openweather_api_key_here"
}
}
}
}
```
### 字段说明
- `"args"`：传递给 MCP 服务器的参数（如 `server.py`）。
- `"command"`：启动命令（Python 项目用 `"python"`）。
- `"env"`：自动提取的环境变量，**请将 `your_openai_api_key_here` 和 `your_openweather_api_key_here` 替换为你自己的密钥**。
---
如需多个服务配置，可以用 JSON 数组格式填写多个 `mcpServers`。
如需进一步定制或有其他字段需求，请告知！