Weather Assistant

天气助理

天气助手应用程序，使用MCP（模型上下文协议）与Google Gemini AI和OpenWeatherMap One Call API 3.0。

重要信息：API要求

此应用程序现在使用 OpenWeatherMap一次调用API 3.0 其提供全面的天气数据，包括：

• 当前天气状况
• 48小时小时预报
• 8天每日预报
• 天气警报
• 紫外线指数和空气质量数据

⚠️ 需要订阅：One Call API 3.0需要单独的“One Call by Call”订阅（包括每天1000个免费呼叫）。

项目结构

• mcp_server/ -包含提供天气数据工具的MCP服务器
• weather_agent_langchain/ -基于LangChain的客户端实现（功能齐全）
• weather_agent_Llamaindex/ -基于LlamaIdex的客户端实现（简化）
• weather_agent/ -旧客户端目录（已弃用）
• .env -环境变量文件（创建自 .env.example)
• .env.example -环境变量模板

客户端选项

该项目提供 两种不同的AI代理实现 演示MCP客户端开发的不同方法：

1.LangChain实现(weather_agent_langchain/)

• 全功能 具有综合能力的实施
• 基于LangGraph 复杂会话流的体系结构
• 高级功能：结构化提示、资源管理、交互式命令
• 文件: weather_agent_langchain/main.py
• 最适合：需要丰富会话AI的生产应用程序

2.LlamaIdex的实现(weather_agent_Llamaindex/)

• 简体 以核心功能为重点的实现
• 基于ReActAgent 用于直接交互的架构
• 流线型：基本天气查询和工具使用
• 文件: weather_agent_Llamaindex/main.py
• 最适合：学习MCP概念和快速原型制作

这两种实现都连接到同一个MCP服务器并提供天气功能，但提供不同级别的复杂度和功能集。

功能对比

设置

1. Python要求：

- 需要Python 3.10或更高版本 - 这个项目已经用Python 3.11.14进行了测试

1. 创建虚拟环境（推荐）：

   python3.11 -m venv .venv
   source .venv/bin/activate  # On macOS/Linux
   # or
   .venv\Scripts\activate     # On Windows

1. 安装依赖项：

   pip install -r requirements.txt

1. 配置环境变量：

   # Copy the example environment file
   cp .env.example .env

   # Edit .env and add your actual API keys

1. 获取API密钥：

- OpenWeatherMap一次调用API 3.0: - 注册地址：https://openweathermap.org/api - 重要：订阅“一次通话”计划（包括每天1000次免费通话） - 这是从基本的当前天气API单独订阅的 - 从API密钥部分获取API密钥 - Google Gemini API：从以下位置获取钥匙https://makersuite.google.com/app/apikey

1. 更新.env文件：

   OPENWEATHERMAP_API_KEY=your_actual_openweathermap_key
   GOOGLE_GEMINI_API_KEY=your_actual_gemini_key

运行应用程序

1. 启动MCP服务器：

   cd mcp_server
   python main.py

1. 选择并启动Weather Agent（在单独的终端中）：

选项A：LangChain实施（推荐）

   cd weather_agent_langchain
   python main.py

选项B:LlamaIdex实现（简化）

   cd weather_agent_Llamaindex
   python main.py

遗留选项：原始实现

   cd weather_agent
   python main.py

用法

两个组件都运行后，您可以通过键入有关不同地点天气信息的自然语言查询与天气助手进行交互。

交互式命令

天气助手现在支持交互式命令以增强功能：

• /prompts -列出所有可用的结构化提示及其用法
• **`/prompt

"arg1" "arg2"`** -使用参数执行特定提示

• /resources -列出MCP服务器上的所有可用资源
• /resource -加载并使用特定资源
• exit, quit，或 q -干净地退出应用程序

可用提示

• 天气比较: /prompt compare_weather_prompt "London" "Paris"

- 生成两个城市之间的结构化比较 - 提供温度、条件和风的并排分析 - 以易于阅读的表格或要点呈现结果

资源管理

助手可以加载和使用外部资源：

• /resources -显示可用资源，如：

- file://delivery_log -访问交付日志数据 - file://index -访问索引文件数据

• /resource file://delivery_log -加载交付日志内容

- 加载后，您可以指定“分析此数据”或“汇总订单”等操作 - 或者按Enter键将内容添加到对话记忆中

资源使用示例

You: /resources
# Lists: file://delivery_log, file://index

You: /resource file://delivery_log
Resource loaded. What should I do with this content? 
> analyze the delivery patterns

# The assistant will analyze the loaded delivery data and provide insights

自然语言查询

使用One Call API 3.0增强功能：

• “纽约的天气怎么样？”-了解当前情况
• “伦敦的每小时天气预报是什么？”-获取详细的每小时数据
• “东京本周会下雨吗？”-获取8天天气预报
• “迈阿密有天气警报吗？”-获取天气警报
• “悉尼的紫外线指数是多少？”-获取紫外线和空气质量数据
• “比较西雅图和波特兰的天气”-获取人工智能生成的比较结果

示例用法

You: /prompts
# Lists all available prompts

You: /prompt compare_weather_prompt "New York" "Los Angeles"
# Generates structured weather comparison between NYC and LA

You: /resources
# Lists available resources: file://delivery_log, file://index

You: /resource file://delivery_log
Resource loaded. What should I do with this content? 
> find the most common delivery cities
# Assistant analyzes the delivery data and identifies patterns

You: What's the weather like in London?
# Natural language query for current London weather

You: exit
# Clean exit without errors

特性

天气能力

• 当前状况：具有详细指标的实时天气数据
• 48小时预报：每小时天气预报
• 8天预测：延长每日天气预报
• 天气警报：恶劣天气警告和公告
• 紫外线指数和空气质量：综合大气数据
• 聪明的比较：人工智能生成的城市间天气比较

交互系统

• 结构化提示：用于一致结果的预定义提示模板
• 资源管理：加载和分析外部数据文件
• 上下文记忆：维护对话历史记录和加载的资源内容
• 清洁出口：正确的错误处理，实现优雅的关机
• 命令发现：可用命令的内置帮助系统

该助手提供全面的天气信息，包括预报、警报、详细的大气条件和位置之间的结构化比较。它还具有用于加载和分析外部数据文件的资源管理功能。

技术细节

建筑

• MCP服务器：处理天气API调用和资源管理
• 气象代理：多种实施方案：

- LangChain：基于LangGraph的对话式人工智能与谷歌Gemini - Llama索引：ReActAgent与BasicMCPClient集成 - 遗产：最初的全面实施

• 协议：结构化工具和资源访问的模型上下文协议
• 应用程序编程接口：用于天气数据的OpenWeatherMap One Call API 3.0

实现细节

LangChain实施：

• 用途 LangGraph 用于状态管理和会话流
• 整合 BasicMCPClient 从 mcp 包裹
• 为MCP工具实施自定义工具包装
• 先进的快速工程和资源管理

LlamaIdex实现：

• 用途 ReActAgent 用于推理和动作循环
• 直接集成 BasicMCPClient
• 简化工具注册和使用
• 最小的配置开销

资源系统

• 交货日志：测试资源能力的样本交付数据
• 索引文件：资源管理示例的其他数据源
• 可扩展：易于添加新的资源类型和数据源

示例数据文件

此存储库包括示例数据文件，用于演示资源管理系统：

• weather_agent/delivery_log.txt -包含带有订单号和城市的示例交货订单数据

- 格式：“订单#XXXXX：交付至\[城市名称\]” - 访问方式： /resource file://delivery_log - 用例：数据分析、模式识别、城市频率分析

• 样品内容：订单配送至美国多个城市，包括圣地亚哥、奥斯汀、罗利等。

这些文件包含在存储库中，可用于测试资源管理功能。

安全说明

• 永远不要承诺你的 .env 文件到版本控制
• 保持API密钥的安全，不要共享它们
• 这 .gitignore 文件被配置为排除 .env 文件