使用说明
智慧城市MCP助理
🔗 现场演示：https://smartcity-mcp-assistant.onrender.com/
SmartCity MCP Assistant是使用模型上下文协议（MCP）构建的城市信息助手。
系统将推理（LLM）与工具执行（MCP工具）分离，而不是在聊天逻辑中对API调用进行硬编码。
LLM决定何时需要外部数据，MCP处理结构化的API调用。
这个项目是什么
该项目将大型语言模型与现实世界的公共API连接起来，例如：
- 天气
- 空气质量
- 新闻
- 附近的地方
助手不会简单地用静态文本进行回复。
它分析查询，确定是否需要实时数据，并动态调用工具。
它还实现了缓存，以避免不必要的API调用。
运作原理
该系统分为三层。
1.上下文提供者（外部API）
以下是真实世界的数据源：
- Open Meteo→ 天气+空气质量
- 新闻数据.io→ News
- Geoapify→ 附近的地方
每个提供者返回结构化的JSON数据。
2.MCP服务器（工具层）
MCP服务器：
- 使用FastMCP注册工具
- 包装外部API调用
- 应用默认参数（城市、纬度、经度）
- 将结构化输出返回给客户端
每个工具代表一种特定的功能（例如，获取天气、获取新闻、查找医院）。
3.MCP客户端+LLM（推理层）
客户：
- 将用户查询发送到LLM
- 确定是否需要工具调用
- 必要时调用相应的MCP工具
- 将工具输出反馈给LLM
- 生成最终响应
LLM用于推理和格式化，而不是用于检索原始数据。
刀具调用流程
- 用户提交查询。
- LLM分析意图。
- 如果需要实时数据：
- 系统检查缓存。
- 如果缓存过期，则调用MCP工具。
- 返回工具输出。
- LLM生成一个上下文的自然语言响应。
这使得数据检索结构化，推理分离。
缓存策略
为了减少API的使用，系统缓存特定持续时间的工具响应：
- 当前天气→ 30 分钟
- 每小时天气→ 4 hours
- 每日天气→ 24 hours
- 空气质量→ 30 分钟/4小时/24小时
- News → 30 分钟
- 附近的地方→ 3 days
缓存存储在 cache.json.
示例用例
天气建议
用户：
“现在是出去的好时机吗？”
该系统获取当前天气和空气质量，然后生成建议。
新闻检索
用户：
“最新消息是什么？”
该系统获取最近的头条新闻并对其进行格式化。
附近医院搜索
用户：
“找附近的医院。”
系统查询Geoapify并返回基于位置的结果。
技术栈
- python
- 快速API
- FastMCP（模型上下文协议）
- API米斯特拉尔
- 开放气象API
- 新闻数据.io API
- 地理位置API
- Jinja2
- HTML/CSS
项目结构
智慧城市MCP助理
│
├── App/
│ ├── 路线.py
│ ├── 对话.py
│
├── MCP/
│ ├── 服务器.py
│ ├── 客户端.py
│ ├── Nearby_Category.py
│
├── 缓存/
│ ├── cache_handler.py
│ ├── cache.json
│
├── 模板/
│ └── index.html
│
├── initial_prompt.txt
├── secondary_prompt.txt
├── main.py
├── 需求.txt
环境配置
创建一个 .env 根目录中的文件：
MISTRAL_API_KEY=your_mistral_api_key
NEWS_API_KEY=your_news_api_key
GEOPIFY_API_KEY=your_geoapify_api_key
LATITUDE=your_latitude
LONGITUDE=your_longitude
CITY=your_default_city
LANGUAGES=preferred_language
所有敏感密钥都是通过环境变量加载的。
本地运行
- 安装依赖项：
pip install -r requirements.txt
-
配置您的
.env文件。 -
运行：
python main.py
FastAPI服务器将在本地启动，助手界面将在浏览器中可用。
