MCP_README.md

# 天气 MCP 服务使用指南

这个文档介绍如何使用部署在 Hugging Face Space 上的天气 MCP 服务。该服务提供了基于高德地图 API 的天气查询功能，可以通过 MCP (Model Context Protocol) 协议进行访问。

## 服务地址

MCP 服务已部署在 Hugging Face Space 上，访问地址为：

```
https://a1c-weather-mcp.hf.space/gradio_api/mcp/sse
```

## 可用工具

该 MCP 服务提供以下工具：

1. **weather_mcp_update_api_key** - 更新API密钥并返回状态信息
   - 参数：`api_key` (字符串) - 高德地图API密钥

2. **weather_mcp_weather_ui** - 简单的Gradio界面函数，用于测试天气查询
   - 参数：`city` (字符串) - 要查询的城市名称
   - 参数：`api_key_status` (字符串) - API密钥状态信息，默认值："⚠️ 未设置API密钥，请先设置API密钥后才能使用天气查询功能"

3. **weather_mcp_forecast_ui** - 简单的Gradio界面函数，用于测试天气预报查询
   - 参数：`city` (字符串) - 要查询的城市名称
   - 参数：`api_key_status` (字符串) - API密钥状态信息，默认值："⚠️ 未设置API密钥，请先设置API密钥后才能使用天气查询功能"

4. **weather_mcp_search_ui** - 简单的Gradio界面函数，用于测试城市搜索
   - 参数：`keyword` (字符串) - 城市名称关键词
   - 参数：`api_key_status` (字符串) - API密钥状态信息，默认值："⚠️ 未设置API密钥，请先设置API密钥后才能使用天气查询功能"

## 调用方式

### 1. 使用 Hugging Face InferenceClient (推荐)

这是最简单的调用方式，适合大多数 Python 用户。

```python
from huggingface_hub import InferenceClient

# 创建客户端
client = InferenceClient(model="a1c/weather-mcp")

# 首先设置API密钥
api_key = "您的高德地图API密钥"
response = client.chat(messages=[
    {"role": "user", "content": {"type": "tool_call", "name": "weather_mcp_update_api_key", "parameters": {"api_key": api_key}}}
])
api_key_status = response  # 保存API密钥状态

# 获取实时天气
response = client.chat(messages=[
    {"role": "user", "content": {"type": "tool_call", "name": "weather_mcp_weather_ui", "parameters": {"city": "北京", "api_key_status": api_key_status}}}
])
print(response)

# 获取天气预报
response = client.chat(messages=[
    {"role": "user", "content": {"type": "tool_call", "name": "weather_mcp_forecast_ui", "parameters": {"city": "上海", "api_key_status": api_key_status}}}
])
print(response)

# 搜索城市
response = client.chat(messages=[
    {"role": "user", "content": {"type": "tool_call", "name": "weather_mcp_search_ui", "parameters": {"keyword": "广", "api_key_status": api_key_status}}}
])
print(response)
```

### 2. 使用 Python MCP 客户端库

如果你需要更多控制或想使用原生 MCP 客户端，可以使用 MCP 库：

```python
import asyncio
from mcp import ClientSession
from mcp.client.sse import sse_client

async def main():
    server_url = "https://a1c-weather-mcp.hf.space/gradio_api/mcp/sse"
    
    # 创建 SSE 连接
    async with sse_client(url=server_url) as streams:
        # 创建客户端会话
        async with ClientSession(*streams) as session:
            # 初始化会话
            await session.initialize()
            
            # 列出可用工具
            response = await session.list_tools()
            print("可用工具:", [tool.name for tool in response.tools])
            
            # 首先设置API密钥
            api_key = "您的高德地图API密钥"
            result = await session.call_tool("weather_mcp_update_api_key", {"api_key": api_key})
            api_key_status = result.content  # 保存API密钥状态
            
            # 调用工具示例
            result = await session.call_tool("weather_mcp_weather_ui", {"city": "北京", "api_key_status": api_key_status})
            print(result.content)

asyncio.run(main())
```

### 3. 使用 mcp-remote 命令行工具

对于喜欢命令行操作的用户，可以使用 mcp-remote 工具：

```bash
# 安装 mcp-remote
npm install -g mcp-remote

# 连接到 MCP 服务
npx mcp-remote https://a1c-weather-mcp.hf.space/gradio_api/mcp/sse --transport sse-only
```

连接后，可以在交互式界面中输入 JSON 格式的工具调用：

```json
# 首先设置API密钥
{"type": "tool_call", "name": "weather_mcp_update_api_key", "parameters": {"api_key": "您的高德地图API密钥"}}

# 然后查询天气
{"type": "tool_call", "name": "weather_mcp_weather_ui", "parameters": {"city": "北京", "api_key_status": "✅ API密钥已设置"}}
```

### 4. 在 AI 应用中配置 MCP 服务

如果你正在使用支持 MCP 的 AI 应用（如 Cursor、Claude 等），可以使用以下配置：

```json
{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://a1c-weather-mcp.hf.space/gradio_api/mcp/sse",
        "--transport",
        "sse-only"
      ]
    }
  }
}
```

## 示例代码

我们提供了一个完整的示例脚本 `usage_mcp.py`，它演示了上述所有调用方式。运行该脚本：

```bash
python usage_mcp.py
```

然后按照提示选择不同的调用方式进行测试。

## 使用流程

1. 首先调用 `weather_mcp_update_api_key` 设置高德地图 API 密钥
2. 获取 API 密钥状态信息
3. 使用获取到的 API 密钥状态信息作为参数调用其他工具

## 注意事项

1. 服务使用高德地图 API，确保查询的是中国城市
2. 部分城市可能需要添加"市"或"省"后缀，如"北京市"
3. 必须先设置有效的 API 密钥才能使用天气查询功能
4. 如果遇到连接问题，请检查网络连接和服务状态

## 常见问题

**Q: 为什么我无法连接到 MCP 服务？**  
A: 请确保你的网络可以访问 Hugging Face 服务，并且服务正常运行。

**Q: 为什么设置了 API 密钥但仍然无法查询天气？**  
A: 确保使用了正确的 API 密钥状态参数，并且 API 密钥是有效的高德地图 API 密钥。

**Q: 如何查找更多城市？**  
A: 使用 `weather_mcp_search_ui` 工具，输入关键词即可搜索匹配的城市。

**Q: 天气数据多久更新一次？**  
A: 天气数据来自高德地图 API，实时更新。