Weather Retriever MCP

🌤️ 天气检索器MCP

全面的 模型上下文协议（MCP） 提供实时天气数据和人工智能天气援助的实施。该项目包括多个MCP服务器、人工智能集成客户端和用于强大天气信息检索的测试工具。

📋 目录

• 特性
• 项目结构
• 安装
• 快速开始
• 使用指南
• api参考
• 集成示例
• 开发与测试
• 故障排除
• 贡献

✨ 特性

核心天气功能

• 🔴 实时天气警报：针对美国各州的主动警告、观察和建议
• 🌤️ 基于位置的预测：5天天气预报，包括温度、风和详细情况
• 📊 NWS官方数据：与美国国家气象局API（Weather.gov）直接集成
• 🌍 地区范围：美国所有50个州和地区

MCP集成

• 🔌 多种传输协议：支持Stdio和服务器发送事件（SSE）
• 🤖 AI代理集成：内置Gemini AI聊天界面，具有对话记忆功能
• 🛠️ 基于工具的体系结构：用于气象操作的可扩展MCP工具
• 📚 资源支持：用于连接测试的回声资源

开发与部署

• 🐳 Docker支持：具有优化构建的容器化部署
• 🧪 综合测试：用于验证的Stdio和SSE客户端实现
• 📦 现代Python：支持Python 3.11+的uv包管理器
• 🔧 灵活的配置：基于环境的安装，支持.env

🏗️ 项目结构

weather-retriever-mcp/
├── 📁 server/                    # Production MCP Server
│   ├── weather.py               # Main MCP server (stdio transport)
│   ├── weather.json             # MCP client configuration
│   └── client.py                # Gemini AI chat client
├── 📁 mcpserver/                # Enhanced MCP Server (Development)
│   ├── server.py                # Advanced server with SSE/stdio support
│   ├── client-stdio.py          # Stdio transport test client
│   ├── client-sse.py            # SSE transport test client
│   ├── Dockerfile               # Container deployment
│   └── requirements.txt         # Python dependencies
├── main.py                      # Alternative server entry point
├── pyproject.toml               # Project configuration & dependencies
├── uv.lock                      # Dependency lock file
├── README.md                    # This file
└── .env.example                 # Environment variables template

🚀 安装

先决条件

• Python 3.11或更高版本 （3.11推荐）
• 紫外线 包管理器（推荐）
• 谷歌人工智能API密钥 （适用于Gemini AI客户端）

分步安装

1.克隆和导航

git clone 
cd weather-retriever-mcp

2.使用紫外线进行安装（推荐）

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies
uv sync

3.替代方案：用pip安装

pip install -e .

4.环境设置

# Copy environment template
cp .env.example .env

# Edit .env and add your Google AI API key
echo "GOOGLE_API_KEY=your_google_api_key_here" > .env

🏃 快速开始

1.基础气象服务器

# Run the production weather server
uv run python server/weather.py

2.使用MCP检查员进行测试

# Inspect available tools and resources
uv run mcp-inspector python server/weather.py

3.AI聊天界面

# Interactive chat with Gemini AI
uv run python server/client.py

📖 使用指南

组件1：生产MCP服务器(server/weather.py)

目的：具有基本功能的天气警报标准MCP服务器。

运行服务器

# Method 1: Direct execution
uv run python server/weather.py

# Method 2: Using main.py
uv run python main.py

# Method 3: With MCP inspector
uv run mcp-inspector python server/weather.py

可用工具

• get_alerts(state: str)：获取美国某个州的活跃天气警报
• 资源: echo://{message} -用于测试的回声功能

示例用法

# In MCP inspector or client:
get_alerts("CA")  # Get California alerts
get_alerts("TX")  # Get Texas alerts

组件2：增强型MCP服务器(mcpserver/server.py)

目的：具有预测功能和多种传输选项的高级服务器。

使用SSE传输运行（默认）

cd mcpserver
uv run python server.py
# Server starts on http://localhost:8001

使用Stdio Transport运行

# Edit server.py line 100:
transport = "stdio"  # Change from "sse"

# Then run:
uv run python server.py

可用工具

• get_alerts(state: str)：天气警报（与基本服务器相同）
• get_forecast(latitude: float, longitude: float)：5天天气预报

示例用法

# Weather alerts
get_alerts("FL")

# Location forecast (Miami, FL coordinates)
get_forecast(25.7617, -80.1918)

组件3:Gemini AI聊天客户端(server/client.py)

目的：配备对话记忆功能的交互式人工智能天气助手。

先决条件

• 谷歌人工智能API密钥 .env 文件
• MCP服务器正在运行（请参阅组件1）

运行客户端

cd server
uv run python client.py

特性

• 🤖 Gemini AI集成：由谷歌Gemini 2.5 Pro提供技术支持
• 💬 对话记忆：记住会话间的聊天历史记录
• 🔄 自动MCP连接：自动连接到天气服务器
• 🎯 智能命令：聊天管理的特殊命令

交互式使用

===== Interactive MCP Chat =====
Type 'exit' or 'quit' to end the conversation
Type 'clear' to clear conversation history
==================================

You: What are the current weather alerts for California?
Assistant: [Gemini AI processes request and queries weather server]

You: clear
Conversation history cleared.

You: exit
Ending conversation...

组件4：测试客户端

标准测试客户端(mcpserver/client-stdio.py)

cd mcpserver
uv run python client-stdio.py

目的：通过将服务器作为子进程启动来测试stdio传输。

SSE测试客户端(mcpserver/client-sse.py)

# First, start the SSE server in another terminal:
cd mcpserver
uv run python server.py

# Then run the client:
uv run python client-sse.py

目的：通过连接到正在运行的HTTP服务器来测试SSE传输。

🔌 集成示例

游标IDE集成

1. 查找MCP配置:

- 窗户： %APPDATA%\Cursor\User\globalStorage\cursor.mcp.json - macOS： ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp.json - Linux： ~/.config/Cursor/User/globalStorage/cursor.mcp.json

1. 添加天气服务器配置:

   {
     "mcpServers": {
       "weather": {
         "command": "uv",
         "args": ["run", "python", "server/weather.py"],
         "cwd": "E:\\MCP\\weather-retriever-mcp"
       }
     }
   }

1. 重新启动游标 并使用代理模式：

   "Get weather alerts for California"
   "What are the current warnings in Texas?"
   "Are there any active alerts in Florida?"

Claude桌面集成

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["run", "--project", "E:\\MCP\\weather-retriever-mcp", "python", "server/weather.py"]
    }
  }
}

其他MCP客户端

服务器通过将其配置为运行以下命令与任何MCP兼容的客户端一起工作：

uv run python server/weather.py

🧪 开发与测试

运行测试

1.测试标准运输

cd mcpserver
uv run python client-stdio.py

2.测试SSE传输

# Terminal 1: Start server
cd mcpserver
uv run python server.py

# Terminal 2: Run client
cd mcpserver
uv run python client-sse.py

3.测试MCP检查员

uv run mcp-inspector python server/weather.py

开发工作流程

添加新的天气工具

1. 编辑 server/weather.py 或 mcpserver/server.py
2. 添加新的 @mcp.tool() 装饰功能
3. 与MCP检查员一起测试
4. 如果需要，更新客户端配置

修改AI客户端

1. 编辑 server/client.py
2. 更改LLM模型或参数
3. 更新环境变量
4. 测试交互功能

🐳 Docker部署

建立和运行

1.构建Docker镜像

cd mcpserver
docker build -t weather-mcp .

2.运行容器

# Run with SSE transport (default)
docker run -p 8001:8001 weather-mcp

# Access server at http://localhost:8001

3.测试容器化服务器

# In another terminal
cd mcpserver
uv run python client-sse.py

Docker配置

这 Dockerfile 包括：

• Python 3.11精简基础镜像
• uv包管理器安装
• 虚拟环境设置
• SSE运输的8001端口暴露
• 针对生产部署进行了优化

🔧 api参考

天气工具

get_alerts(state: str)

描述：检索美国某个州的活动天气警报。

参数:

• state （string）：两个字母的美国州代码（例如，“CA”、“NY”、“TX”）

退货：带有活动警报的格式化字符串，包括：

• 事件类型（警告、观察、咨询）
• 受影响区域
• 严重程度级别
• 说明和说明

示例:

result = get_alerts("CA")
# Returns formatted alert information

get_forecast(latitude: float, longitude: float)

描述：获取特定坐标的5天天气预报。

参数:

• latitude （浮动）：纬度坐标（-90到90）
• longitude （浮动）：经度坐标（-180到180）

退货：格式化预测，包括：

• 日期/时间段
• 温度（华氏）
• 风速与风向
• 详细的天气状况

示例:

result = get_forecast(40.7128, -74.0060)  # New York City
# Returns 5-day forecast

资源

echo://{message}

描述：用于测试MCP连接的简单回声资源。

示例:

echo://hello world → "Resource echo: hello world"

🐛 故障排除

常见问题

1.“连接已关闭”错误

问题：Stdio客户端无法连接到服务器。 解决方案:

# Ensure client uses uv command:
server_params = StdioServerParameters(
    command="uv",
    args=["run", "mcpserver/server.py"]
)

2.“找不到模块”错误

问题：未安装依赖项。 解决方案:

uv sync  # Install all dependencies

3.SSE连接失败

问题：SSE客户端无法连接到服务器。 解决方案:

• 确保服务器正在运行： uv run python mcpserver/server.py
• 检查端口8001是否可用
• 验证服务器是否使用SSE传输（默认）

4.Gemini AI不工作

问题：聊天客户端因API错误而失败。 解决方案:

• 检查 .env 文件有效 GOOGLE_API_KEY
• 验证API密钥是否具有Gemini API访问权限
• 确保Google AI API的网络连接

5.天气数据未加载

问题：天气API请求失败。 解决方案:

• 检查互联网连接
• 验证NWS API是否可访问
• 有效的州代码：CA、NY、TX、FL等。

调试命令

直接测试服务器

# Test basic server
uv run python server/weather.py

# Test enhanced server
cd mcpserver && uv run python server.py

检查MCP工具

# Inspect available tools
uv run mcp-inspector python server/weather.py

检查相关性

# Verify uv installation
uv --version

# Check Python version
python --version

# List installed packages
uv pip list

🤝 贡献

开发设置

1. 分叉和克隆:

   git clone https://github.com/your-username/weather-retriever-mcp.git
   cd weather-retriever-mcp

1. 再进行:

   uv sync

1. 创建特征分支:

   git checkout -b feature/your-feature-name

1. 运行测试:

   # Test all components
   uv run python mcpserver/client-stdio.py
   uv run python mcpserver/client-sse.py
   uv run python server/client.py

代码指南

• Python版本：使用Python 3.11+功能
• 类型提示：向函数参数添加类型注释
• 文档：包括所有函数的文档字符串
• 错误处理：实施适当的异常处理
• 测试：测试stdio和SSE传输

添加新功能

1. 天气工具：添加新 @mcp.tool() 函数
2. 资源：实施 @mcp.resource() 处理器
3. 人工智能集成：扩展Gemini客户端功能
4. 运输支持：添加新的传输协议

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 国家气象局 用于提供天气数据API
• 谷歌人工智能 用于Gemini语言模型集成
• MCP社区 用于模型上下文协议规范
• FastMCP 用于简化MCP服务器实现的库

______________________________________________________________________

由...制作❤️ 作者：SIV RAAM KRISHNAN。K.V

*如有疑问或支持，请在GitHub上发布问题。*