使用说明

市场情报MCP服务器 🚀

利用MCP（模型上下文协议）集成的AI驱动后端服务，用于市场情报和金融新闻分析。

📋 概述

这个项目实施了一个 仅后端 运行在MCP服务器架构上的服务，将人工智能功能与实时市场数据工具相结合。它通过RESTful API提供针对市场和金融问题的上下文感知响应。

主要特点

✅ MCP服务器架构 - 基于模型上下文协议进行工具集成
✅ AI驱动的响应 - 使用Google Gemini 2.0 Flash获取智能答案
✅ 实时市场数据 - 股价、公司信息请通过雅虎财经获取
✅ 财经新闻 - 来自多个来源的最新新闻（NewsAPI + RSS订阅）
✅ 上下文管理 - 基于会话的对话记忆
✅ 流媒体支持 - 实时流式响应（附加功能）
✅ 异步架构 - 高性能的异步/等待（async/await）实现

🏗️ 建筑学

┌─────────────┐
│   Client    │
│  (curl/API) │
└──────┬──────┘
       │ HTTP Request
       ▼
┌─────────────────────────────────┐
│      FastAPI Server             │
│  ┌──────────────────────────┐  │
│  │   MCP Integration Layer  │  │
│  └────────┬─────────────────┘  │
│           │                     │
│  ┌────────▼─────────┐          │
│  │  AI Model        │          │
│  │  (Gemini 2.0)    │          │
│  └──────────────────┘          │
└───────────┬─────────────────────┘
            │
    ┌───────┴───────┐
    ▼               ▼
┌─────────┐   ┌──────────┐
│ MCP     │   │ MCP News │
│ Stock   │   │ Fetcher  │
│ Tool    │   │ Tool     │
└────┬────┘   └────┬─────┘
     │             │
     ▼             ▼
┌─────────┐   ┌──────────┐
│ Yahoo   │   │ NewsAPI/ │
│ Finance │   │ RSS Feeds│
└─────────┘   └──────────┘

🚀 快速入门

先决条件

Python 3.9及以上版本
pip（通常指Python的包管理工具，用于安装和管理Python包）
谷歌Gemini API密钥（免费）

安装

克隆并设置：

git clone <your-repo>
cd market-intel-mcp

安装依赖项：

pip install -r requirements.txt

配置环境：

cp .env.example .env
# Edit .env and add your API keys

验证设置：

python setup_checker.py

启动服务器：

python main.py

服务器将在 http://localhost:8000

🔑 API密钥设置

所需密钥：

谷歌Gemini API （免费）
- 从以下网址获取：https://aistudio.google.com/app/apikey
- 添加到 .env： GOOGLE_API_KEY=your-key
服务API密钥 （您自己的密码）
- 生成： python -c "import secrets; print(secrets.token_hex(32))"
- 添加到 .env: SERVICE_API_KEY=your-secure-key

可选键：

NewsAPI（新闻应用程序编程接口） （免费 - 每天100次请求）
- 从以下网址获取：https://newsapi.org/register
- 添加到 .env： NEWS_API_KEY=your-key
- 如未提供，则自动使用RSS订阅源

看 API_KEYS_GUIDE.md 以获取详细说明。

📡 API 接口端点

基本URL

http://localhost:8000

1. 健康检查

curl http://localhost:8000/health

2. 查询终端（主）

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-service-api-key" \
  -d '{
    "message": "What is the current price of Apple stock?"
  }'

回答：

{
  "session_id": "abc123...",
  "answer": "Based on real-time data, Apple (AAPL) is currently trading at $185.50...",
  "tool_data_used": ["stock_data"],
  "timestamp": 1728738000.0
}

3. 流媒体终端（额外奖励）

curl -X POST http://localhost:8000/query/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-service-api-key" \
  -d '{
    "message": "Give me latest stock market news"
  }' \
  --no-buffer

4. 对话历史

curl http://localhost:8000/sessions/{session_id}/history \
  -H "X-API-Key: your-service-api-key"

5. 清除会话

curl -X POST http://localhost:8000/sessions/{session_id}/clear \
  -H "X-API-Key: your-service-api-key"

6. 列出MCP工具

curl http://localhost:8000/mcp/tools \
  -H "X-API-Key: your-service-api-key"

🧠 上下文是如何被保留的

基于会话的内存

每次对话都会获得一个唯一的（标识） session_id
存储在内存中的消息，带有时间戳
最后6次交换记录保留在上下文中（可通过配置调整） MAX_HISTORY）
30分钟无操作后自动清理

上下文流程：

User Query 1 → AI Response 1 → Stored in session
User Query 2 → [Previous context + Query 2] → AI Response 2

实施：

内存存储： CONTEXTS 以 session_id 为索引的字典
线程安全每个会话的异步锁
坚持不懈的在同一个会话中的多个查询间保持上下文

🛠️ MCP 服务器配置

什么是MCP？

MCP（模型上下文协议）是Anthropic用于将AI模型连接到外部工具和数据源的标准。

我们的MCP（可能指某种系统、协议或方法的缩写，具体需根据上下文确定）实施：

工具曝光：

股票数据工具
- get_stock_price() - 当前价格及指标
- get_historical_data() - 历史价格
- get_company_info() - 公司详情
新闻抓取工具
- get_latest_news() - 搜索财经新闻
- get_market_news() - 一般市场动态更新
- get_company_news() - 公司特定新闻
- get_economic_news() - 经济指标

MCP服务器配置：

# Located in mcp_server.py
Server Name: market-intelligence-mcp
Version: 1.0.0
Protocol: stdio-based MCP
Tools: 2 (Stock Data, News Fetcher)

工具集成：

FastAPI 层根据查询分析自动调用 MCP 工具：

像“价格”、“库存”这样的关键词 → 触发库存工具
关键词如“新闻”、“最新” → 触发新闻工具
将结果传递给AI进行智能合成

📚 技术栈与库

核心框架：

FastAPI（快速API） - 现代异步网络框架
Uvicorn（注：Uvicorn是一个用于构建异步ASGI服务器的Python库，直接翻译为中文可能无直接对应词汇，但通常保持原名以指代其特定功能或项目。） - ASGI服务器
Pydantic - 数据验证

人工智能与大型语言模型：

LangChain - 大语言模型（LLM）编排
谷歌生成式人工智能 - Gemini 2.0 闪存模型

MCP协议：

mcp可以翻译为“最小化兼容包”或“微控制器协议（在特定上下文中）”，但具体含义需根据上下文确定。在计算机科学或软件开发领域，“mcp”通常指的是“最小化兼容包”，即一种旨在保持兼容性的同时尽可能减少资源占用的软件包或系统组件。在其他领域，如电子工程，它可能指的是与微控制器相关的协议或标准。因此，翻译时需结合具体语境 - 模型上下文协议实现
“anthropic-mcp” 可以翻译为“人类（或类人）多智能体协作平台”或“类人多智能体控制系统”，具体翻译取决于该术语在上下文中的具体含义和用途。在这里，我给出了一个较为通用的翻译，以涵盖可能的多种解释 - Anthropic的MCP实用工具

市场数据：

yfinance（注：这是一个Python库的名称，用于从Yahoo Finance获取金融数据，直接翻译为中文可能无具体含义，故保留原英文名称） - 雅虎财经API（股票数据）
newsapi-python（可翻译为“新闻API Python客户端”或“用于新闻API的Python库”，具体翻译取决于上下文和该库的具体用途） - NewsAPI 客户端
feedparser（用于解析RSS/Atom订阅源的Python库） - RSS订阅源解析

公用设施：

python-dotenv - 环境管理
httpx（注：httpx 是一个用于发送 HTTP 请求的工具，常用于安全测试等领域，但在此处仅作为词汇翻译，不涉及具体功能说明） / aiohttp（一个用于异步网络请求的Python库） - 异步HTTP客户端
`asyncio` 是 Python 中用于编写异步网络代码的库，全称是 "Asynchronous IO"（异步输入/输出）。它允许开发者编写并发代码，使用 `async` 和 `await` 关键字来定义协程（coroutine），从而实现非阻塞的异步操作。 - 支持异步/等待（Async/await）

📁 项目结构

market-intel-mcp/
├── main.py                    # FastAPI application + MCP integration
├── mcp_server.py             # Standalone MCP server implementation
├── tools/
│   ├── __init__.py           # Tools package
│   ├── stock_data.py         # Stock market data tools
│   └── news_fetcher.py       # Financial news tools
├── requirements.txt          # Python dependencies
├── .env                      # Environment variables (you create this)
├── .env.example             # Environment template
├── setup_checker.py         # Setup verification script
├── README.md                # This file
├── API_KEYS_GUIDE.md       # Detailed API key instructions
└── market_intel.log        # Application logs

🧪 测试

运行安装检查器：

python setup_checker.py

测试终端点：

基本查询：

# Replace YOUR_API_KEY with your SERVICE_API_KEY from .env
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"message": "What is the price of Microsoft stock?"}'

股票+新闻查询：

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"message": "Tell me about Tesla stock and recent news"}'

流媒体测试：

curl -X POST http://localhost:8000/query/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"message": "Latest market news"}' \
  --no-buffer

带有会话上下文：

# First query
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"message": "What is Apple stock price?"}' \
  | jq -r '.session_id' > session.txt

# Follow-up (uses context)
SESSION_ID=$(cat session.txt)
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d "{\"message\": \"How has it changed this week?\", \"session_id\": \"$SESSION_ID\"}"

🚢 部署

选项1：铁路（推荐）

# Install Railway CLI
npm install -g @railway/cli

# Login
railway login

# Deploy
railway up

选项2：渲染

连接GitHub仓库
选择“Web 服务”
构建命令： pip install -r requirements.txt
启动命令： uvicorn main:app --host 0.0.0.0 --port $PORT
添加来自（指定位置的）环境变量 .env

选项3：DigitalOcean应用平台

从GitHub创建新应用
配置构建： pip install -r requirements.txt
配置运行： python main.py
添加环境变量

部署环境变量：

确保在您的托管平台上设置了以下内容：

GOOGLE_API_KEY
SERVICE_API_KEY
NEWS_API_KEY （可选）
PORT （通常由平台自动设置）

📊 性能与扩展

异步架构所有输入/输出操作均为非阻塞的
会话管理自动清理防止内存泄漏
速率限制尊重API提供者的限制
缓存考虑在生产环境中添加使用Redis
水平扩展无状态设计允许存在多个实例

🐞 故障排除

“无效的API密钥”错误：

检查 .env 文件包含正确的密钥
确保没有多余的空格 .env
跑 python setup_checker.py

“模型未初始化”错误：

验证GOOGLE_API_KEY是否有效
检查网络连接
尝试重新生成API密钥

未返回库存数据：

Yahoo Finance 可能暂时无法访问
检查股票代码是否正确（大写）
尝试使用不同的股票代码

新闻加载失败：

如果未提供NewsAPI密钥，则使用RSS订阅源（可能会较慢）
检查是否已设置NEWS_API_KEY
RSS订阅源可能有速率限制

📄 许可证

MIT 许可证 - 详见 LICENSE 文件

🤝 贡献（或：参与贡献）

这是一个实习项目，但欢迎提出建议！

为仓库创建分支（或“克隆仓库”）
创建特性分支
做出改变
提交拉取请求

📞 支持

对于问题或疑问：

检查 API_KEYS_GUIDE.md 用于设置帮助
跑步 python setup_checker.py 诊断问题
查看登录日志 market_intel.log

🎯 项目需求已满足

✅ Python 后端服务
✅ MCP服务器实现
✅ 集成AI聊天机器人（Google Gemini）
✅ 上下文保持（基于会话的记忆）
✅ 市场数据