| Name | mcp-server-weather-cuhksz JSON |
| Version |
0.2.3
JSON |
| download |
| home_page | None |
| Summary | CUHK-SZ Weather MCP Server |
| upload_time | 2025-09-04 06:24:40 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2025 Beijing ColorfulClouds Technology Co.,Ltd.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
mcp
weather
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MCP Weather 服务器 (`mcp_server_weather_cuhksz`)
该目录包含了基于和风天气 (QWeather) API、为 MCP 提供天气相关工具的 FastMCP 服务器实现。
一个基于和风天气 (QWeather) API、为语言模型提供天气相关工具的 FastMCP 服务器。
## 📋 目录
- [✨ 项目描述](#-项目描述)
- [🎯 核心功能](#-核心功能)
- [🛠️ 可用工具](#️-可用工具)
- [⚙️ 操作模式](#️-操作模式)
- [🚀 安装与部署](#-安装与部署)
- [🏗️ 项目架构](#️-项目架构)
- [🧪 测试说明](#-测试说明)
- [🔧 故障排除](#-故障排除)
- [📄 许可证](#-许可证)
## ✨ 项目描述
本项目基于 FastMCP 框架，将多个和风天气 API 端点封装为标准的 MCP 工具，使语言模型能够轻松地查询实时天气、天气预报、灾害预警和生活指数等信息。
## 🎯 核心功能
- **丰富工具集**: 提供从城市搜索到未来15天天气预报、逐小时预报、灾害预警等多种实用工具。
- **双重操作模式**: 支持直连和风天气 API 或通过 `unified-api` 代理服务运行，灵活适应不同部署需求。
- **动态配置**: 通过环境变量在运行时动态决定连接目标，无需修改代码即可切换模式。
- **容器化设计**: 提供完整的 Docker 和 Docker Compose 配置，实现一键部署和隔离环境。
- **内置缓存**: 对 API 请求结果进行缓存，提高响应速度并减少不必要的 API 调用。
## 🛠️ 可用工具
---
### 1. `get_location_id`
调用和风天气城市搜索，返回含 Location ID 的详细地点列表。**注意⚠️: 在调用其他需要地理位置的工具前，必须先调用此工具获取 Location ID。**
- **参数说明**:
- `location` (`string`): **必须**。查询关键字，可以是城市名称、`经度,纬度`、LocationID 或 Adcode（中国行政区划代码）。例如 `"北京"` 或 `"116.41,39.92"`。
- `adm` (`string`): *可选*。上级行政区过滤，如 `"beijing"` 或 `"江西省"`。
- `search_range` (`string`): *可选*。搜索范围，ISO 3166 国家/地区代码，如 `"cn"`。
- `number` (`int`): *可选*。返回数量，取值范围 1-20，默认为 `1`。
- `lang` (`string`): *可选*。语言设置，支持 `'zh'` (默认) 或 `'en'`。
---
### 2. `get_daily_weather`
获取指定地点未来多天的逐日天气预报。
- **参数说明**:
- `days` (`string`): **必须**。预报天数，可选值为 `'3d'`, `'7d'`, `'10d'`, `'15d'`, `'30d'`。
- `location` (`string`): **必须**。地理位置参数，必须是 `get_location_id` 返回的 LocationID 或 `经度,纬度` 格式。例如 `"101010100"`。
- `lang` (`string`): *可选*。语言设置，支持 `'zh'` (默认) 或 `'en'`。
- `unit` (`string`): *可选*。单位制，支持 `'m'` (公制，默认) 或 `'i'` (英制)。
---
### 3. `get_hourly_weather`
获取指定地点未来多小时的逐小时天气预报。
- **参数说明**:
- `hours` (`string`): **必须**。预报小时数，可选值为 `'24h'`, `'72h'`, `'168h'`。
- `location` (`string`): **必须**。地理位置参数，同上。
- `lang` (`string`): *可选*。语言设置，支持 `'zh'` (默认) 或 `'en'`。
- `unit` (`string`): *可选*。单位制，支持 `'m'` (公制，默认) 或 `'i'` (英制)。
---
### 4. `get_weather_warning_now`
查询指定地点的实时气象灾害预警信息。
- **参数说明**:
- `location` (`string`): **必须**。地理位置参数，同上。
- `lang` (`string`): *可选*。语言设置，支持 `'zh'` (默认) 或 `'en'`。
---
### 5. `get_weather_indices`
查询指定地点的天气生活指数。
- **参数说明**:
- `days` (`string`): **必须**。预报天数，可选值为 `'1d'` 或 `'3d'`。
- `location` (`string`): **必须**。地理位置参数，同上。
- `lang` (`string`): *可选*。语言设置，支持 `'zh'` (默认) 或 `'en'`。
## ⚙️ 操作模式
服务器可在以下两种模式之一运行，由 `IS_UNIFIED_API` 环境变量控制。
### 1. 统一 API 代理模式 (Unified API Proxy Mode) - 推荐
- **描述**: 在此模式下，服务器作为 `unified-api` 代理服务的客户端。它将所有天气 API 请求转发到该代理，由代理负责账户选择、负载均衡和认证。这是**生产环境或多账户部署场景下的推荐模式**。
- **配置 (`IS_UNIFIED_API=true`)**:
- `IS_UNIFIED_API`: 必须设置为 `true`。
- `UNIFIED_API_HOST`: `unified-api` 服务的 URL (例如 `http://unified-api:6380` 或 `http://host.docker.internal:6380`)。
### 2. 直连 API 模式 (Direct API Mode)
- **描述**: 在此模式下，服务器直接连接到和风天气 API，并使用本地配置的凭证生成 JWT 进行认证。此模式适用于本地开发和独立测试。
- **配置 (`IS_UNIFIED_API=false`)**:
- `IS_UNIFIED_API`: 必须设置为 `false`。
- `WEATHER_API_HOST`: 和风天气 API 的 URL (例如, `https://api.qweather.com`)。
- `QWEATHER_KEY_ID`, `QWEATHER_PROJECT_ID`, `QWEATHER_PRIVATE_KEY`: 您的和风天气凭证。
## 🚀 安装与部署
本项目设计为在 Docker 环境中运行。
### 1. 集成部署 (统一 API 代理模式) - 推荐
此方法会同时启动 `mcp-server`、`unified-api` 和 `redis` 服务，是完整的生产和测试部署方案。
**a. 环境准备**
- 安装 [Docker](https://www.docker.com/get-started/) 和 [Docker Compose](https://docs.docker.com/compose/install/)。
- 确保项目根目录下的 `.env` 文件和 `unified_api/` 目录下的配置文件已准备就绪。
**b. 启动服务**
在**项目根目录**下执行：
```bash
# 构建并以守护进程模式启动所有服务
docker-compose up --build -d
# 查看 mcp-server 的实时日志
docker-compose logs -f mcp-server
# 停止所有服务
docker-compose down
```
服务启动后，将在 `http://localhost:3003` 上提供 MCP 接口。根 `docker-compose.yml` 会自动设置 `IS_UNIFIED_API=true`。
### 2. 独立部署 (直连 API 模式)
此方法仅用于单独运行和测试 `mcp-server`。
**a. 配置凭证**
在 `src/mcp_server_weather_cuhksz/` 目录下创建一个 `.env` 文件，并填入“直连 API 模式”所需的 `QWEATHER_*` 变量。
**b. 启动服务**
从 `src/mcp_server_weather_cuhksz/` 目录**内部**执行：
```bash
docker-compose up --build -d
```
## 🏗️ 项目架构
### 模块关系
本项目由两个核心服务组成：
- **`mcp-server-weather` (本项目)**: 作为 MCP 层，将业务逻辑（天气查询）封装为语言模型可调用的工具。
- **`unified-api`**: 作为代理和认证层，管理多个和风天气账户，实现负载均衡和统一的 API 访问入口。
### 关键设计：运行时动态配置
为了确保配置的灵活性和可靠性，本项目采用以下策略：
1. **集中化配置入口**: 所有配置逻辑都集中在主入口 `__main__.py` 中，由它根据环境变量决定最终的操作模式和 API Host。
2. **运行时动态解析**: 核心逻辑模块 `mcp_weather.py` 中的工具函数在被调用时，才通过 `os.getenv(...)` 动态获取配置。这确保了工具总是使用最新的、由容器编排工具注入的正确配置，避免了因 Python 模块导入时序问题导致的配置固化。
这种设计确保了由 Docker Compose 注入的配置始终拥有最高优先级，使得服务行为在不同部署环境中一致且可靠。
## 🧪 测试说明
项目提供了一个自动化测试脚本 `test/test.py`，用于验证所有 MCP 工具的基本功能。
### 运行测试
1. **启动服务**: 确保服务已通过 `docker-compose up -d` (在项目根目录) 成功启动。
2. **执行脚本**: 在您的本地 Python 环境中（需要安装 `fastmcp` 客户端库），运行测试：
```bash
# 建议在项目的虚拟环境中运行
python test/test.py
```
脚本会自动连接 `http://localhost:3003` 的服务，发现并调用所有可用工具，然后打印出结果或错误信息。
## 🔧 故障排除
### 常见问题
#### 1. 工具调用时出现 `Name or service not known` 错误
- **症状**: `test/test.py` 或其他客户端调用工具时，返回类似 `[Errno -2] Name or service not known` 的网络错误。
- **原因**: `mcp-server` 容器无法通过其配置的 `UNIFIED_API_HOST` 地址连接到 `unified-api` 服务。
- **解决方案**:
- 检查根 `docker-compose.yml` 文件中 `mcp-server` 服务的 `UNIFIED_API_HOST` 环境变量。
- 对于 Docker for Mac/Windows，推荐使用 `http://host.docker.internal:6380`，它会指向宿主机的网络。
- 如果在 Linux 上，您可能需要配置 `extra_hosts` 或确保两个服务在同一个自定义的 bridge network 中，并使用服务名 `http://unified-api:6380` 进行通信。
#### 2. `unified-api` 服务健康检查失败
- **症状**: `docker-compose up` 过程中 `mcp-server` 等待 `unified-api` 超时。
- **原因**: `unified-api` 容器未能正常启动。可能是 `accounts.yaml` 配置错误、私钥文件缺失或路径不正确。
- **解决方案**: 使用 `docker-compose logs unified-api` 查看其详细日志，定位并修复问题。
## 📄 许可证
本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-server-weather-cuhksz",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "lkcy23 <lkcydream@gmail.com>",
"keywords": "MCP, Weather",
"author": null,
"author_email": "lkcy23 <lkcydream@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b5/34/5867ee9a4cf814caf8ee5ebba0e39cee0c3d4319f5635873c2f18f110084/mcp_server_weather_cuhksz-0.2.3.tar.gz",
"platform": null,
"description": "# MCP Weather \u670d\u52a1\u5668 (`mcp_server_weather_cuhksz`)\n\n\u8be5\u76ee\u5f55\u5305\u542b\u4e86\u57fa\u4e8e\u548c\u98ce\u5929\u6c14 (QWeather) API\u3001\u4e3a MCP \u63d0\u4f9b\u5929\u6c14\u76f8\u5173\u5de5\u5177\u7684 FastMCP \u670d\u52a1\u5668\u5b9e\u73b0\u3002\n\n\u4e00\u4e2a\u57fa\u4e8e\u548c\u98ce\u5929\u6c14 (QWeather) API\u3001\u4e3a\u8bed\u8a00\u6a21\u578b\u63d0\u4f9b\u5929\u6c14\u76f8\u5173\u5de5\u5177\u7684 FastMCP \u670d\u52a1\u5668\u3002\n\n## \ud83d\udccb \u76ee\u5f55\n\n- [\u2728 \u9879\u76ee\u63cf\u8ff0](#-\u9879\u76ee\u63cf\u8ff0)\n- [\ud83c\udfaf \u6838\u5fc3\u529f\u80fd](#-\u6838\u5fc3\u529f\u80fd)\n- [\ud83d\udee0\ufe0f \u53ef\u7528\u5de5\u5177](#\ufe0f-\u53ef\u7528\u5de5\u5177)\n- [\u2699\ufe0f \u64cd\u4f5c\u6a21\u5f0f](#\ufe0f-\u64cd\u4f5c\u6a21\u5f0f)\n- [\ud83d\ude80 \u5b89\u88c5\u4e0e\u90e8\u7f72](#-\u5b89\u88c5\u4e0e\u90e8\u7f72)\n- [\ud83c\udfd7\ufe0f \u9879\u76ee\u67b6\u6784](#\ufe0f-\u9879\u76ee\u67b6\u6784)\n- [\ud83e\uddea \u6d4b\u8bd5\u8bf4\u660e](#-\u6d4b\u8bd5\u8bf4\u660e)\n- [\ud83d\udd27 \u6545\u969c\u6392\u9664](#-\u6545\u969c\u6392\u9664)\n- [\ud83d\udcc4 \u8bb8\u53ef\u8bc1](#-\u8bb8\u53ef\u8bc1)\n\n## \u2728 \u9879\u76ee\u63cf\u8ff0\n\n\u672c\u9879\u76ee\u57fa\u4e8e FastMCP \u6846\u67b6\uff0c\u5c06\u591a\u4e2a\u548c\u98ce\u5929\u6c14 API \u7aef\u70b9\u5c01\u88c5\u4e3a\u6807\u51c6\u7684 MCP \u5de5\u5177\uff0c\u4f7f\u8bed\u8a00\u6a21\u578b\u80fd\u591f\u8f7b\u677e\u5730\u67e5\u8be2\u5b9e\u65f6\u5929\u6c14\u3001\u5929\u6c14\u9884\u62a5\u3001\u707e\u5bb3\u9884\u8b66\u548c\u751f\u6d3b\u6307\u6570\u7b49\u4fe1\u606f\u3002\n\n## \ud83c\udfaf \u6838\u5fc3\u529f\u80fd\n\n- **\u4e30\u5bcc\u5de5\u5177\u96c6**: \u63d0\u4f9b\u4ece\u57ce\u5e02\u641c\u7d22\u5230\u672a\u676515\u5929\u5929\u6c14\u9884\u62a5\u3001\u9010\u5c0f\u65f6\u9884\u62a5\u3001\u707e\u5bb3\u9884\u8b66\u7b49\u591a\u79cd\u5b9e\u7528\u5de5\u5177\u3002\n- **\u53cc\u91cd\u64cd\u4f5c\u6a21\u5f0f**: \u652f\u6301\u76f4\u8fde\u548c\u98ce\u5929\u6c14 API \u6216\u901a\u8fc7 `unified-api` \u4ee3\u7406\u670d\u52a1\u8fd0\u884c\uff0c\u7075\u6d3b\u9002\u5e94\u4e0d\u540c\u90e8\u7f72\u9700\u6c42\u3002\n- **\u52a8\u6001\u914d\u7f6e**: \u901a\u8fc7\u73af\u5883\u53d8\u91cf\u5728\u8fd0\u884c\u65f6\u52a8\u6001\u51b3\u5b9a\u8fde\u63a5\u76ee\u6807\uff0c\u65e0\u9700\u4fee\u6539\u4ee3\u7801\u5373\u53ef\u5207\u6362\u6a21\u5f0f\u3002\n- **\u5bb9\u5668\u5316\u8bbe\u8ba1**: \u63d0\u4f9b\u5b8c\u6574\u7684 Docker \u548c Docker Compose \u914d\u7f6e\uff0c\u5b9e\u73b0\u4e00\u952e\u90e8\u7f72\u548c\u9694\u79bb\u73af\u5883\u3002\n- **\u5185\u7f6e\u7f13\u5b58**: \u5bf9 API \u8bf7\u6c42\u7ed3\u679c\u8fdb\u884c\u7f13\u5b58\uff0c\u63d0\u9ad8\u54cd\u5e94\u901f\u5ea6\u5e76\u51cf\u5c11\u4e0d\u5fc5\u8981\u7684 API \u8c03\u7528\u3002\n\n## \ud83d\udee0\ufe0f \u53ef\u7528\u5de5\u5177\n\n---\n\n### 1. `get_location_id`\n\u8c03\u7528\u548c\u98ce\u5929\u6c14\u57ce\u5e02\u641c\u7d22\uff0c\u8fd4\u56de\u542b Location ID \u7684\u8be6\u7ec6\u5730\u70b9\u5217\u8868\u3002**\u6ce8\u610f\u26a0\ufe0f: \u5728\u8c03\u7528\u5176\u4ed6\u9700\u8981\u5730\u7406\u4f4d\u7f6e\u7684\u5de5\u5177\u524d\uff0c\u5fc5\u987b\u5148\u8c03\u7528\u6b64\u5de5\u5177\u83b7\u53d6 Location ID\u3002**\n\n- **\u53c2\u6570\u8bf4\u660e**:\n - `location` (`string`): **\u5fc5\u987b**\u3002\u67e5\u8be2\u5173\u952e\u5b57\uff0c\u53ef\u4ee5\u662f\u57ce\u5e02\u540d\u79f0\u3001`\u7ecf\u5ea6,\u7eac\u5ea6`\u3001LocationID \u6216 Adcode\uff08\u4e2d\u56fd\u884c\u653f\u533a\u5212\u4ee3\u7801\uff09\u3002\u4f8b\u5982 `\"\u5317\u4eac\"` \u6216 `\"116.41,39.92\"`\u3002\n - `adm` (`string`): *\u53ef\u9009*\u3002\u4e0a\u7ea7\u884c\u653f\u533a\u8fc7\u6ee4\uff0c\u5982 `\"beijing\"` \u6216 `\"\u6c5f\u897f\u7701\"`\u3002\n - `search_range` (`string`): *\u53ef\u9009*\u3002\u641c\u7d22\u8303\u56f4\uff0cISO 3166 \u56fd\u5bb6/\u5730\u533a\u4ee3\u7801\uff0c\u5982 `\"cn\"`\u3002\n - `number` (`int`): *\u53ef\u9009*\u3002\u8fd4\u56de\u6570\u91cf\uff0c\u53d6\u503c\u8303\u56f4 1-20\uff0c\u9ed8\u8ba4\u4e3a `1`\u3002\n - `lang` (`string`): *\u53ef\u9009*\u3002\u8bed\u8a00\u8bbe\u7f6e\uff0c\u652f\u6301 `'zh'` (\u9ed8\u8ba4) \u6216 `'en'`\u3002\n\n---\n\n### 2. `get_daily_weather`\n\u83b7\u53d6\u6307\u5b9a\u5730\u70b9\u672a\u6765\u591a\u5929\u7684\u9010\u65e5\u5929\u6c14\u9884\u62a5\u3002\n\n- **\u53c2\u6570\u8bf4\u660e**:\n - `days` (`string`): **\u5fc5\u987b**\u3002\u9884\u62a5\u5929\u6570\uff0c\u53ef\u9009\u503c\u4e3a `'3d'`, `'7d'`, `'10d'`, `'15d'`, `'30d'`\u3002\n - `location` (`string`): **\u5fc5\u987b**\u3002\u5730\u7406\u4f4d\u7f6e\u53c2\u6570\uff0c\u5fc5\u987b\u662f `get_location_id` \u8fd4\u56de\u7684 LocationID \u6216 `\u7ecf\u5ea6,\u7eac\u5ea6` \u683c\u5f0f\u3002\u4f8b\u5982 `\"101010100\"`\u3002\n - `lang` (`string`): *\u53ef\u9009*\u3002\u8bed\u8a00\u8bbe\u7f6e\uff0c\u652f\u6301 `'zh'` (\u9ed8\u8ba4) \u6216 `'en'`\u3002\n - `unit` (`string`): *\u53ef\u9009*\u3002\u5355\u4f4d\u5236\uff0c\u652f\u6301 `'m'` (\u516c\u5236\uff0c\u9ed8\u8ba4) \u6216 `'i'` (\u82f1\u5236)\u3002\n\n---\n\n### 3. `get_hourly_weather`\n\u83b7\u53d6\u6307\u5b9a\u5730\u70b9\u672a\u6765\u591a\u5c0f\u65f6\u7684\u9010\u5c0f\u65f6\u5929\u6c14\u9884\u62a5\u3002\n\n- **\u53c2\u6570\u8bf4\u660e**:\n - `hours` (`string`): **\u5fc5\u987b**\u3002\u9884\u62a5\u5c0f\u65f6\u6570\uff0c\u53ef\u9009\u503c\u4e3a `'24h'`, `'72h'`, `'168h'`\u3002\n - `location` (`string`): **\u5fc5\u987b**\u3002\u5730\u7406\u4f4d\u7f6e\u53c2\u6570\uff0c\u540c\u4e0a\u3002\n - `lang` (`string`): *\u53ef\u9009*\u3002\u8bed\u8a00\u8bbe\u7f6e\uff0c\u652f\u6301 `'zh'` (\u9ed8\u8ba4) \u6216 `'en'`\u3002\n - `unit` (`string`): *\u53ef\u9009*\u3002\u5355\u4f4d\u5236\uff0c\u652f\u6301 `'m'` (\u516c\u5236\uff0c\u9ed8\u8ba4) \u6216 `'i'` (\u82f1\u5236)\u3002\n\n---\n\n### 4. `get_weather_warning_now`\n\u67e5\u8be2\u6307\u5b9a\u5730\u70b9\u7684\u5b9e\u65f6\u6c14\u8c61\u707e\u5bb3\u9884\u8b66\u4fe1\u606f\u3002\n\n- **\u53c2\u6570\u8bf4\u660e**:\n - `location` (`string`): **\u5fc5\u987b**\u3002\u5730\u7406\u4f4d\u7f6e\u53c2\u6570\uff0c\u540c\u4e0a\u3002\n - `lang` (`string`): *\u53ef\u9009*\u3002\u8bed\u8a00\u8bbe\u7f6e\uff0c\u652f\u6301 `'zh'` (\u9ed8\u8ba4) \u6216 `'en'`\u3002\n\n---\n\n### 5. `get_weather_indices`\n\u67e5\u8be2\u6307\u5b9a\u5730\u70b9\u7684\u5929\u6c14\u751f\u6d3b\u6307\u6570\u3002\n\n- **\u53c2\u6570\u8bf4\u660e**:\n - `days` (`string`): **\u5fc5\u987b**\u3002\u9884\u62a5\u5929\u6570\uff0c\u53ef\u9009\u503c\u4e3a `'1d'` \u6216 `'3d'`\u3002\n - `location` (`string`): **\u5fc5\u987b**\u3002\u5730\u7406\u4f4d\u7f6e\u53c2\u6570\uff0c\u540c\u4e0a\u3002\n - `lang` (`string`): *\u53ef\u9009*\u3002\u8bed\u8a00\u8bbe\u7f6e\uff0c\u652f\u6301 `'zh'` (\u9ed8\u8ba4) \u6216 `'en'`\u3002\n\n## \u2699\ufe0f \u64cd\u4f5c\u6a21\u5f0f\n\n\u670d\u52a1\u5668\u53ef\u5728\u4ee5\u4e0b\u4e24\u79cd\u6a21\u5f0f\u4e4b\u4e00\u8fd0\u884c\uff0c\u7531 `IS_UNIFIED_API` \u73af\u5883\u53d8\u91cf\u63a7\u5236\u3002\n\n### 1. \u7edf\u4e00 API \u4ee3\u7406\u6a21\u5f0f (Unified API Proxy Mode) - \u63a8\u8350\n\n- **\u63cf\u8ff0**: \u5728\u6b64\u6a21\u5f0f\u4e0b\uff0c\u670d\u52a1\u5668\u4f5c\u4e3a `unified-api` \u4ee3\u7406\u670d\u52a1\u7684\u5ba2\u6237\u7aef\u3002\u5b83\u5c06\u6240\u6709\u5929\u6c14 API \u8bf7\u6c42\u8f6c\u53d1\u5230\u8be5\u4ee3\u7406\uff0c\u7531\u4ee3\u7406\u8d1f\u8d23\u8d26\u6237\u9009\u62e9\u3001\u8d1f\u8f7d\u5747\u8861\u548c\u8ba4\u8bc1\u3002\u8fd9\u662f**\u751f\u4ea7\u73af\u5883\u6216\u591a\u8d26\u6237\u90e8\u7f72\u573a\u666f\u4e0b\u7684\u63a8\u8350\u6a21\u5f0f**\u3002\n- **\u914d\u7f6e (`IS_UNIFIED_API=true`)**:\n - `IS_UNIFIED_API`: \u5fc5\u987b\u8bbe\u7f6e\u4e3a `true`\u3002\n - `UNIFIED_API_HOST`: `unified-api` \u670d\u52a1\u7684 URL (\u4f8b\u5982 `http://unified-api:6380` \u6216 `http://host.docker.internal:6380`)\u3002\n\n### 2. \u76f4\u8fde API \u6a21\u5f0f (Direct API Mode)\n\n- **\u63cf\u8ff0**: \u5728\u6b64\u6a21\u5f0f\u4e0b\uff0c\u670d\u52a1\u5668\u76f4\u63a5\u8fde\u63a5\u5230\u548c\u98ce\u5929\u6c14 API\uff0c\u5e76\u4f7f\u7528\u672c\u5730\u914d\u7f6e\u7684\u51ed\u8bc1\u751f\u6210 JWT \u8fdb\u884c\u8ba4\u8bc1\u3002\u6b64\u6a21\u5f0f\u9002\u7528\u4e8e\u672c\u5730\u5f00\u53d1\u548c\u72ec\u7acb\u6d4b\u8bd5\u3002\n- **\u914d\u7f6e (`IS_UNIFIED_API=false`)**:\n - `IS_UNIFIED_API`: \u5fc5\u987b\u8bbe\u7f6e\u4e3a `false`\u3002\n - `WEATHER_API_HOST`: \u548c\u98ce\u5929\u6c14 API \u7684 URL (\u4f8b\u5982, `https://api.qweather.com`)\u3002\n - `QWEATHER_KEY_ID`, `QWEATHER_PROJECT_ID`, `QWEATHER_PRIVATE_KEY`: \u60a8\u7684\u548c\u98ce\u5929\u6c14\u51ed\u8bc1\u3002\n\n## \ud83d\ude80 \u5b89\u88c5\u4e0e\u90e8\u7f72\n\n\u672c\u9879\u76ee\u8bbe\u8ba1\u4e3a\u5728 Docker \u73af\u5883\u4e2d\u8fd0\u884c\u3002\n\n### 1. \u96c6\u6210\u90e8\u7f72 (\u7edf\u4e00 API \u4ee3\u7406\u6a21\u5f0f) - \u63a8\u8350\n\n\u6b64\u65b9\u6cd5\u4f1a\u540c\u65f6\u542f\u52a8 `mcp-server`\u3001`unified-api` \u548c `redis` \u670d\u52a1\uff0c\u662f\u5b8c\u6574\u7684\u751f\u4ea7\u548c\u6d4b\u8bd5\u90e8\u7f72\u65b9\u6848\u3002\n\n**a. \u73af\u5883\u51c6\u5907**\n\n- \u5b89\u88c5 [Docker](https://www.docker.com/get-started/) \u548c [Docker Compose](https://docs.docker.com/compose/install/)\u3002\n- \u786e\u4fdd\u9879\u76ee\u6839\u76ee\u5f55\u4e0b\u7684 `.env` \u6587\u4ef6\u548c `unified_api/` \u76ee\u5f55\u4e0b\u7684\u914d\u7f6e\u6587\u4ef6\u5df2\u51c6\u5907\u5c31\u7eea\u3002\n\n**b. \u542f\u52a8\u670d\u52a1**\n\n\u5728**\u9879\u76ee\u6839\u76ee\u5f55**\u4e0b\u6267\u884c\uff1a\n```bash\n# \u6784\u5efa\u5e76\u4ee5\u5b88\u62a4\u8fdb\u7a0b\u6a21\u5f0f\u542f\u52a8\u6240\u6709\u670d\u52a1\ndocker-compose up --build -d\n\n# \u67e5\u770b mcp-server \u7684\u5b9e\u65f6\u65e5\u5fd7\ndocker-compose logs -f mcp-server\n\n# \u505c\u6b62\u6240\u6709\u670d\u52a1\ndocker-compose down\n```\n\u670d\u52a1\u542f\u52a8\u540e\uff0c\u5c06\u5728 `http://localhost:3003` \u4e0a\u63d0\u4f9b MCP \u63a5\u53e3\u3002\u6839 `docker-compose.yml` \u4f1a\u81ea\u52a8\u8bbe\u7f6e `IS_UNIFIED_API=true`\u3002\n\n### 2. \u72ec\u7acb\u90e8\u7f72 (\u76f4\u8fde API \u6a21\u5f0f)\n\n\u6b64\u65b9\u6cd5\u4ec5\u7528\u4e8e\u5355\u72ec\u8fd0\u884c\u548c\u6d4b\u8bd5 `mcp-server`\u3002\n\n**a. \u914d\u7f6e\u51ed\u8bc1**\n\n\u5728 `src/mcp_server_weather_cuhksz/` \u76ee\u5f55\u4e0b\u521b\u5efa\u4e00\u4e2a `.env` \u6587\u4ef6\uff0c\u5e76\u586b\u5165\u201c\u76f4\u8fde API \u6a21\u5f0f\u201d\u6240\u9700\u7684 `QWEATHER_*` \u53d8\u91cf\u3002\n\n**b. \u542f\u52a8\u670d\u52a1**\n\n\u4ece `src/mcp_server_weather_cuhksz/` \u76ee\u5f55**\u5185\u90e8**\u6267\u884c\uff1a\n```bash\ndocker-compose up --build -d\n```\n\n## \ud83c\udfd7\ufe0f \u9879\u76ee\u67b6\u6784\n\n### \u6a21\u5757\u5173\u7cfb\n\n\u672c\u9879\u76ee\u7531\u4e24\u4e2a\u6838\u5fc3\u670d\u52a1\u7ec4\u6210\uff1a\n- **`mcp-server-weather` (\u672c\u9879\u76ee)**: \u4f5c\u4e3a MCP \u5c42\uff0c\u5c06\u4e1a\u52a1\u903b\u8f91\uff08\u5929\u6c14\u67e5\u8be2\uff09\u5c01\u88c5\u4e3a\u8bed\u8a00\u6a21\u578b\u53ef\u8c03\u7528\u7684\u5de5\u5177\u3002\n- **`unified-api`**: \u4f5c\u4e3a\u4ee3\u7406\u548c\u8ba4\u8bc1\u5c42\uff0c\u7ba1\u7406\u591a\u4e2a\u548c\u98ce\u5929\u6c14\u8d26\u6237\uff0c\u5b9e\u73b0\u8d1f\u8f7d\u5747\u8861\u548c\u7edf\u4e00\u7684 API \u8bbf\u95ee\u5165\u53e3\u3002\n\n### \u5173\u952e\u8bbe\u8ba1\uff1a\u8fd0\u884c\u65f6\u52a8\u6001\u914d\u7f6e\n\n\u4e3a\u4e86\u786e\u4fdd\u914d\u7f6e\u7684\u7075\u6d3b\u6027\u548c\u53ef\u9760\u6027\uff0c\u672c\u9879\u76ee\u91c7\u7528\u4ee5\u4e0b\u7b56\u7565\uff1a\n1. **\u96c6\u4e2d\u5316\u914d\u7f6e\u5165\u53e3**: \u6240\u6709\u914d\u7f6e\u903b\u8f91\u90fd\u96c6\u4e2d\u5728\u4e3b\u5165\u53e3 `__main__.py` \u4e2d\uff0c\u7531\u5b83\u6839\u636e\u73af\u5883\u53d8\u91cf\u51b3\u5b9a\u6700\u7ec8\u7684\u64cd\u4f5c\u6a21\u5f0f\u548c API Host\u3002\n2. **\u8fd0\u884c\u65f6\u52a8\u6001\u89e3\u6790**: \u6838\u5fc3\u903b\u8f91\u6a21\u5757 `mcp_weather.py` \u4e2d\u7684\u5de5\u5177\u51fd\u6570\u5728\u88ab\u8c03\u7528\u65f6\uff0c\u624d\u901a\u8fc7 `os.getenv(...)` \u52a8\u6001\u83b7\u53d6\u914d\u7f6e\u3002\u8fd9\u786e\u4fdd\u4e86\u5de5\u5177\u603b\u662f\u4f7f\u7528\u6700\u65b0\u7684\u3001\u7531\u5bb9\u5668\u7f16\u6392\u5de5\u5177\u6ce8\u5165\u7684\u6b63\u786e\u914d\u7f6e\uff0c\u907f\u514d\u4e86\u56e0 Python \u6a21\u5757\u5bfc\u5165\u65f6\u5e8f\u95ee\u9898\u5bfc\u81f4\u7684\u914d\u7f6e\u56fa\u5316\u3002\n\n\u8fd9\u79cd\u8bbe\u8ba1\u786e\u4fdd\u4e86\u7531 Docker Compose \u6ce8\u5165\u7684\u914d\u7f6e\u59cb\u7ec8\u62e5\u6709\u6700\u9ad8\u4f18\u5148\u7ea7\uff0c\u4f7f\u5f97\u670d\u52a1\u884c\u4e3a\u5728\u4e0d\u540c\u90e8\u7f72\u73af\u5883\u4e2d\u4e00\u81f4\u4e14\u53ef\u9760\u3002\n\n## \ud83e\uddea \u6d4b\u8bd5\u8bf4\u660e\n\n\u9879\u76ee\u63d0\u4f9b\u4e86\u4e00\u4e2a\u81ea\u52a8\u5316\u6d4b\u8bd5\u811a\u672c `test/test.py`\uff0c\u7528\u4e8e\u9a8c\u8bc1\u6240\u6709 MCP \u5de5\u5177\u7684\u57fa\u672c\u529f\u80fd\u3002\n\n### \u8fd0\u884c\u6d4b\u8bd5\n\n1. **\u542f\u52a8\u670d\u52a1**: \u786e\u4fdd\u670d\u52a1\u5df2\u901a\u8fc7 `docker-compose up -d` (\u5728\u9879\u76ee\u6839\u76ee\u5f55) \u6210\u529f\u542f\u52a8\u3002\n2. **\u6267\u884c\u811a\u672c**: \u5728\u60a8\u7684\u672c\u5730 Python \u73af\u5883\u4e2d\uff08\u9700\u8981\u5b89\u88c5 `fastmcp` \u5ba2\u6237\u7aef\u5e93\uff09\uff0c\u8fd0\u884c\u6d4b\u8bd5\uff1a\n ```bash\n # \u5efa\u8bae\u5728\u9879\u76ee\u7684\u865a\u62df\u73af\u5883\u4e2d\u8fd0\u884c\n python test/test.py\n ```\n\u811a\u672c\u4f1a\u81ea\u52a8\u8fde\u63a5 `http://localhost:3003` \u7684\u670d\u52a1\uff0c\u53d1\u73b0\u5e76\u8c03\u7528\u6240\u6709\u53ef\u7528\u5de5\u5177\uff0c\u7136\u540e\u6253\u5370\u51fa\u7ed3\u679c\u6216\u9519\u8bef\u4fe1\u606f\u3002\n\n## \ud83d\udd27 \u6545\u969c\u6392\u9664\n\n### \u5e38\u89c1\u95ee\u9898\n\n#### 1. \u5de5\u5177\u8c03\u7528\u65f6\u51fa\u73b0 `Name or service not known` \u9519\u8bef\n- **\u75c7\u72b6**: `test/test.py` \u6216\u5176\u4ed6\u5ba2\u6237\u7aef\u8c03\u7528\u5de5\u5177\u65f6\uff0c\u8fd4\u56de\u7c7b\u4f3c `[Errno -2] Name or service not known` \u7684\u7f51\u7edc\u9519\u8bef\u3002\n- **\u539f\u56e0**: `mcp-server` \u5bb9\u5668\u65e0\u6cd5\u901a\u8fc7\u5176\u914d\u7f6e\u7684 `UNIFIED_API_HOST` \u5730\u5740\u8fde\u63a5\u5230 `unified-api` \u670d\u52a1\u3002\n- **\u89e3\u51b3\u65b9\u6848**:\n - \u68c0\u67e5\u6839 `docker-compose.yml` \u6587\u4ef6\u4e2d `mcp-server` \u670d\u52a1\u7684 `UNIFIED_API_HOST` \u73af\u5883\u53d8\u91cf\u3002\n - \u5bf9\u4e8e Docker for Mac/Windows\uff0c\u63a8\u8350\u4f7f\u7528 `http://host.docker.internal:6380`\uff0c\u5b83\u4f1a\u6307\u5411\u5bbf\u4e3b\u673a\u7684\u7f51\u7edc\u3002\n - \u5982\u679c\u5728 Linux \u4e0a\uff0c\u60a8\u53ef\u80fd\u9700\u8981\u914d\u7f6e `extra_hosts` \u6216\u786e\u4fdd\u4e24\u4e2a\u670d\u52a1\u5728\u540c\u4e00\u4e2a\u81ea\u5b9a\u4e49\u7684 bridge network \u4e2d\uff0c\u5e76\u4f7f\u7528\u670d\u52a1\u540d `http://unified-api:6380` \u8fdb\u884c\u901a\u4fe1\u3002\n\n#### 2. `unified-api` \u670d\u52a1\u5065\u5eb7\u68c0\u67e5\u5931\u8d25\n- **\u75c7\u72b6**: `docker-compose up` \u8fc7\u7a0b\u4e2d `mcp-server` \u7b49\u5f85 `unified-api` \u8d85\u65f6\u3002\n- **\u539f\u56e0**: `unified-api` \u5bb9\u5668\u672a\u80fd\u6b63\u5e38\u542f\u52a8\u3002\u53ef\u80fd\u662f `accounts.yaml` \u914d\u7f6e\u9519\u8bef\u3001\u79c1\u94a5\u6587\u4ef6\u7f3a\u5931\u6216\u8def\u5f84\u4e0d\u6b63\u786e\u3002\n- **\u89e3\u51b3\u65b9\u6848**: \u4f7f\u7528 `docker-compose logs unified-api` \u67e5\u770b\u5176\u8be6\u7ec6\u65e5\u5fd7\uff0c\u5b9a\u4f4d\u5e76\u4fee\u590d\u95ee\u9898\u3002\n\n## \ud83d\udcc4 \u8bb8\u53ef\u8bc1\n\n\u672c\u9879\u76ee\u91c7\u7528 MIT \u8bb8\u53ef\u8bc1\u3002\u8be6\u89c1 [LICENSE](LICENSE) \u6587\u4ef6\u3002\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Beijing ColorfulClouds Technology Co.,Ltd.\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "CUHK-SZ Weather MCP Server",
"version": "0.2.3",
"project_urls": {
"Homepage": "https://github.com/LKCY23/mcp-server-weather-cuhksz",
"Issues": "https://github.com/LKCY23/mcp-server-weather-cuhksz/issues"
},
"split_keywords": [
"mcp",
" weather"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a2540e2efd74977182e7e1f378f2455d6b0273cd327832f71ce2fd70b38524fb",
"md5": "a30425f157abaabc6c2d8c79dbc4b8f0",
"sha256": "b3be0a1678e020ebcd5dab6a0b5a892181bb859e2b8f3c86e5a438ca59f2be80"
},
"downloads": -1,
"filename": "mcp_server_weather_cuhksz-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a30425f157abaabc6c2d8c79dbc4b8f0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19133,
"upload_time": "2025-09-04T06:24:38",
"upload_time_iso_8601": "2025-09-04T06:24:38.620594Z",
"url": "https://files.pythonhosted.org/packages/a2/54/0e2efd74977182e7e1f378f2455d6b0273cd327832f71ce2fd70b38524fb/mcp_server_weather_cuhksz-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b5345867ee9a4cf814caf8ee5ebba0e39cee0c3d4319f5635873c2f18f110084",
"md5": "2e204effbb7e9b4a0baae93879dc451e",
"sha256": "57fdacd559142e8317afdcc43d9227a4d71bb20aa61e28dfb4cfc20e415771a5"
},
"downloads": -1,
"filename": "mcp_server_weather_cuhksz-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "2e204effbb7e9b4a0baae93879dc451e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 24415,
"upload_time": "2025-09-04T06:24:40",
"upload_time_iso_8601": "2025-09-04T06:24:40.057234Z",
"url": "https://files.pythonhosted.org/packages/b5/34/5867ee9a4cf814caf8ee5ebba0e39cee0c3d4319f5635873c2f18f110084/mcp_server_weather_cuhksz-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 06:24:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LKCY23",
"github_project": "mcp-server-weather-cuhksz",
"github_not_found": true,
"lcname": "mcp-server-weather-cuhksz"
}
