🌦️ MCP Weather Scraper

🌦️ MCP 天气抓取器

本项目是 Model Context Protocol (MCP) 的一项实验性实现，使用 ** OpenAI** 提供的轻量级大模型和 FastAPI，从开放的网络来源获取实时天气信息并进行结构化处理。项目旨在探索大模型如何与工具交互，并作为智能 Agent 检索和推理非结构化网络数据。

---

---

🚀 功能

• ✅ 符合 MCP 规范的服务，可通过浏览器搜索抓取天气信息
• ✅ 集成 OpenAI 大模型（例如 gpt-3.5-turbo）
• ✅ FastAPI 服务将天气信息作为可调用的 MCP 工具提供
• ✅ 使用 selectolax 自动解析 HTML，提升性能
• ✅ 大模型将非结构化网络内容提取为结构化数据
• ✅ 提供用于用户交互的 Streamlit 应用前端
• ✅ 使用 functools.lru_cache 缓存响应

---

🧠 开始之前，先回顾一下

本项目值得温习的 5 个核心概念

🧩 概念	🔍 含义	⚙️ 重要性
Model Context Protocol (MCP)	一种用于大模型工具调用的新协议	支持结构化的 AI Agent 通信
Uvicorn	用于 Python Web 应用的快速 ASGI 服务	承载基于 FastAPI 的 MCP 服务
Selectolax	高速 HTML 解析器	高效抓取并提取天气数据
functools.lru_cache	用于缓存函数调用的 Python 内置装饰器	避免重复获取数据，提升性能
Token Usage Metrics (OpenAI)	大模型调用中使用的 Token 数量信息	有助于跟踪成本并优化提示词设计

💡 即使你熟悉 Python 和 API，这些工具也代表着前沿的 AI 技术栈工程实践，值得花点时间了解！

---

📊 Token 使用量与性能指标

Streamlit 界面现在包含：

• ⏱️ 响应时间
  获取并处理天气信息所用的时间

• 🧠 提示词 Token 数
  大模型提示词中使用的 Token 数量

• 💬 补全 Token 数
  大模型响应生成的 Token 数量

• 🔢 Token 总数
  每次请求的 Token 总数，可用于跟踪成本

这些指标会以清晰的视觉布局显示在每张结果卡片下方。

---

🖥️ Streamlit 应用预览

---

运行要求

• Python 3.9 或更高版本
• requirements.txt 中列出的依赖项

---

🛠️ 安装

1. 克隆代码库

   git clone https://github.com/your-username/mcp_weather_scraper.git
   cd mcp_weather_scraper
   

2. 创建并激活虚拟环境

   python -m venv .venv
   .venv\Scripts\activate  # On Windows
   

3. 安装依赖项

   pip install -r requirements.txt
   

4. 设置环境变量 在根目录中创建一个 .env 文件，并添加你的 OpenAI API 密钥

   OPENAI_API_KEY=your_openai_api_key
   

5. 运行服务

   uvicorn server:app --reload
   

   服务将在 http://localhost:8000 上运行。 你可以通过以下地址访问 API 文档：
   • Swagger UI：http://localhost:8000/docs
   • ReDoc：http://localhost:8000/redoc
6. 发送请求

   python client.py
   

   或者

   curl -X POST http://localhost:8000/weather -H "Content-Type: application/json" -d '{"location": "Seattle"}'
   

   该脚本会发送一个包含以下负载的 POST 请求：

   {
     "location": "Seattle"
   }
   

   服务将以 JSON 格式返回天气数据，例如：

   {
     "location": "Seattle",
     "temperature": "15°C",
     "humidity": "80%",
     "air_quality": "Good",
     "condition": "Cloudy"
   }
   

📦 文件夹结构

.
📁 mcp_weather_scraper/
│
├── assets/
│   └── streamlit_screenshot.png
├── server.py          # MCP-compatible tool server
├── client.py          # MCP client that interacts with model + tools
├── data_models.py     # Pydantic schemas for request/response
├── utils.py           # HTML cleaning, scraping, etc.
├── requirements.txt
└── .env

📄 许可证

This project is licensed under the MIT License.