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 用户。

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 库：

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 工具：

# 安装 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 格式的工具调用：

# 首先设置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 等），可以使用以下配置：

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

示例代码

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

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，实时更新。