内容
# ⛅️ 天气智慧 — 集成 MCP 和 Google ADK 的 AI 代理
> 一个使用 **模型上下文协议（MCP）** 连接到实时天气数据源的 AI 代理，获取结构化的气象数据，并使用 **Google ADK** （代理开发工具包）+ **Gemini 2.0 Flash** 生成人性化的天气报告。
---
## 🏗️ 架构
```
用户请求
│
▼
FastAPI 服务器 (main.py)
│
▼
Google ADK LlmAgent ←──── Gemini 2.0 Flash (LLM)
│
│ MCP 标准输入输出传输
▼
天气 MCP 服务器 (mcp_server/weather_mcp_server.py)
│
│ HTTP (httpx)
▼
Open-Meteo API ──→ 地理编码 API
──→ 预报 API （当前 + 5 天）
```
### 组件
| 组件 | 角色 |
|-----------|------|
| **Google ADK** | 协调代理循环，管理工具调用 |
| **MCP 服务器** | 通过标准输入输出传输暴露 `get_weather` 工具 |
| **Open-Meteo** | 免费，无需 API 密钥的天气数据（全球覆盖） |
| **FastAPI** | REST API + 网页 UI 服务器 |
| **Cloud Run** | 无服务器 Google Cloud 部署 |
---
## 📁 项目结构
```
weather-mcp-agent/
├── main.py # FastAPI 服务器 + API 端点
├── agent/
│ └── weather_agent.py # Google ADK 代理定义
├── mcp_server/
│ └── weather_mcp_server.py # MCP 服务器暴露 get_weather 工具
├── static/
│ └── index.html # 前端网页 UI
├── requirements.txt
├── Dockerfile
├── deploy.sh # 一键 Cloud Run 部署
├── .env.example # 环境变量模板
└── .gitignore
```
---
## 🖥️ 在 VS Code 中本地运行
### 前提条件
- Python 3.11 或 3.12
- 带有 Python 扩展的 VS Code
- **Google API 密钥** （用于 Gemini / ADK）
### 步骤 1 — 克隆 / 打开项目
在 VS Code 中打开 `weather-mcp-agent/` 文件夹：
```
文件 → 打开文件夹 → weather-mcp-agent/
```
### 步骤 2 — 创建虚拟环境
打开 VS Code 终端（`Ctrl+`` ` ``）并运行：
```bash
python -m venv .venv
```
激活它：
- **Windows：** `.venv\Scripts\activate`
- **Mac/Linux：** `source .venv/bin/activate`
VS Code 应自动检测虚拟环境。如果出现提示，请点击 **"是"** 以将其用作工作区解释器。
### 步骤 3 — 安装依赖项
```bash
pip install -r requirements.txt
```
### 步骤 4 — 配置环境
```bash
cp .env.example .env
```
编辑 `.env` 并设置您的密钥：
```env
GOOGLE_API_KEY=AIza...your-key-here
```
在 https://aistudio.google.com/app/apikey 获取密钥（免费层可用）
### 步骤 5 — 运行服务器
```bash
python main.py
```
或使用 VS Code 运行按钮（如果您有启动配置）。服务器启动在 **http://localhost:8080**
### 步骤 6 — 打开 UI
在浏览器中访问 **http://localhost:8080** — 您将看到 WeatherWise UI。
或使用 curl 测试：
```bash
curl -X POST http://localhost:8080/api/weather \
-H "Content-Type: application/json" \
-d '{"city": "Bengaluru"}'
```
### VS Code launch.json（可选）
创建 `.vscode/launch.json`：
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "运行 WeatherWise",
"type": "python",
"request": "launch",
"program": "${workspaceFolder}/main.py",
"envFile": "${workspaceFolder}/.env",
"console": "integratedTerminal"
}
]
}
```
---
## 🧪 直接测试 MCP 服务器
从 CLI 运行代理（绕过 FastAPI）：
```bash
python agent/weather_agent.py "Tokyo"
python agent/weather_agent.py "London"
```
测试原始天气数据（无需 LLM）：
```bash
curl http://localhost:8080/api/raw-weather/Mumbai
```
---
## ☁️ 部署到 Google Cloud Run
### 前提条件
- 具有项目的 Google Cloud 账户
- 已安装 `gcloud` CLI：https://cloud.google.com/sdk/docs/install
- 已安装 Docker（用于本地构建）或启用 Cloud Build
### 步骤 1 — 设置环境变量
```bash
export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_API_KEY=your-google-api-key
export GOOGLE_CLOUD_REGION=us-central1 # 或 asia-south1 for India
```
### 步骤 2 — 身份验证
```bash
gcloud auth login
gcloud config set project $GOOGLE_CLOUD_PROJECT
```
### 步骤 3 — 部署（一键）
```bash
chmod +x deploy.sh
./deploy.sh
```
此脚本自动：
1. 启用所需的 Google Cloud API
2. 通过 Cloud Build 构建 Docker 镜像
3. 推送到 Google Container Registry
4. 部署到 Cloud Run，并使用您的 API 密钥
5. 打印实时 Cloud Run URL
### 步骤 4 — 测试部署
```bash
# 替换为实际的 Cloud Run URL
curl -X POST https://weatherwise-agent-xxxx-uc.a.run.app/api/weather \
-H "Content-Type: application/json" \
-d '{"city": "Bengaluru"}'
```
### 手动 Cloud Run 部署（替代）
```bash
# 构建镜像
gcloud builds submit --tag gcr.io/$GOOGLE_CLOUD_PROJECT/weatherwise-agent .
# 部署
gcloud run deploy weatherwise-agent \
--image gcr.io/$GOOGLE_CLOUD_PROJECT/weatherwise-agent \
--platform managed \
--region us-central1 \
--allow-unauthenticated \
--memory 512Mi \
--set-env-vars "GOOGLE_API_KEY=$GOOGLE_API_KEY"
```
---
## 🔌 MCP 工具参考
MCP 服务器暴露一个工具：
### `get_weather`
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `city` | 字符串 | ✅ | 城市名称（例如 "Bengaluru", "Tokyo"） |
**返回：**
```json
{
"location": { "city": "Bengaluru", "country": "India", "latitude": 12.97, "longitude": 77.59 },
"current": {
"temperature_c": 24.5,
"feels_like_c": 25.1,
"humidity_pct": 68,
"wind_speed_kmh": 12.4,
"wind_direction_deg": 270,
"precipitation_mm": 0.0,
"pressure_hpa": 1013.2,
"uv_index": 6,
"condition": "Partly cloudy"
},
"forecast_5_days": [...]
}
```
---
## 📡 API 端点
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `GET` | `/` | 网页 UI |
| `GET` | `/health` | 健康检查 |
| `POST` | `/api/weather` | AI 生成的天气报告 |
| `GET` | `/api/raw-weather/{city}` | 原始天气数据（无 LLM） |
---
## 🛠️ MCP 集成工作原理
1. **代理启动**：`MCPToolset` 通过标准输入输出启动 MCP 服务器作为子进程
2. **工具发现**：ADK 查询 MCP 服务器以获取可用的工具（`list_tools`）
3. **LLM 决定**：Gemini 看到工具模式并决定调用 `get_weather`
4. **工具调用**：ADK 通过 MCP 协议发送调用 → 服务器从 Open-Meteo 获取数据
5. **响应**：结构化 JSON 天气数据流回代理
6. **报告**：Gemini 使用数据生成详细的、友好的天气报告
---
## 📝 提交检查清单
- [x] 使用 Google ADK 实现
- [x] 使用 MCP 连接到一个工具（通过 Open-Meteo 获取天气）
- [x] 检索结构化数据（当前条件 + 5 天预报）
- [x] 使用检索的数据生成最终响应
- [x] 可部署到 Google Cloud Run
- [x] 可在 VS Code 中本地运行
---
## 🔑 获取免费 Google API 密钥
1. 前往 https://aistudio.google.com/app/apikey
2. 点击 **"创建 API 密钥"**
3. 复制密钥并粘贴到 `.env`
免费层包括慷慨的 Gemini 2.0 Flash 用量。
---
## 📄 许可证
MIT — 欢迎使用和扩展。
