Arbitrage Suite

基于 MCP (Model Context Protocol) 的 QDII/LOF 溢价套利和微信通知服务套件。

📖 项目简介

本项目提供了一个基于 SSE 传输的 MCP 服务器，集成了以下功能：

• QDII/LOF 溢价套利：从集思录抓取 QDII 和 LOF 基金数据，筛选满足溢价条件的套利机会
• 微信通知：通过 Server 酱发送微信消息通知
• A股行情：获取A股实时和历史行情数据
• 期货行情：获取国内期货实时行情和主力合约列表
• Docker 部署：支持 Docker Compose 一键部署
• 生产级日志：环境变量控制的日志系统

🚀 快速开始

环境要求

• Python 3.8+
• pip

安装依赖

pip install -r requirements.txt

配置文件

创建 config.json 文件，填入必要的配置信息：

{
  "deepseek_base_url": "https://api.deepseek.com",
  "deepseek_api_key": "你的DeepSeek API Key",
  "qwen_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "qwen_api_key": "你的Qwen API Key",
  "SCT_KEY": "你的Server酱Key"
}

配置说明：

• SCT_KEY: Server 酱的推送 Key，用于发送微信通知（在 Server 酱官网 获取）
• deepseek_api_key: DeepSeek API 密钥（如需使用 AI 功能）
• deepseek_base_url: DeepSeek API 服务地址
• qwen_api_key: 通义千问 API 密钥（可选）
• qwen_base_url: 通义千问 API 服务地址（可选）

环境变量（可选）

可以通过环境变量覆盖配置文件中的设置：

• ENV: 运行环境，可选值 prod（生产）或 dev（开发）
  • prod: 日志同时输出到文件（/app/logs/）和控制台
  • dev: 日志仅输出到控制台（默认）
• PORT: 服务端口，默认 4567
• SCT_KEY: Server 酱推送密钥，优先级高于配置文件

# 生产环境启动（启用文件日志）
ENV=prod python server/mcp_server.py

# 开发环境启动（仅控制台日志）
ENV=dev python server/mcp_server.py

启动 MCP 服务器

python server/mcp_server.py
# 或者从项目根目录
python .\server\mcp_server.py

服务器将在 http://127.0.0.1:4567 启动，使用 SSE 传输方式。

🔧 可用工具

1. fetch_qdii_candidates

获取 QDII/LOF 溢价套利候选列表。

参数：

• threshold (float, optional): 溢价率阈值，默认为 2.0%

数据来源：

• QDII 基金数据（集思录 QDII API）
• LOF 基金数据（集思录 LOF API）

返回： 返回满足以下条件的基金列表：

• T-1 溢价率 > threshold
• 申购状态不是"暂停申购"或"开放申购"（通常是"限额申购"）

示例：

# 获取溢价率大于2%的基金
candidates = fetch_qdii_candidates(threshold=2.0)

返回数据格式：

[
  {
    "代码": "159920",
    "名称": "恒生ETF",
    "T-1溢价率": 2.5,
    "申购状态": "限额申购"
  }
]

2. send_wechat

发送微信通知消息。

参数：

• title (str, required): 通知的标题
• desp (str, required): 通知的详细内容

示例：

send_wechat(
    title="QDII套利提醒",
    desp="发现3只满足条件的套利基金"
)

3. get_stock_realtime

获取A股单只股票的实时行情数据。

参数：

• symbol (str, required): 股票代码，6位数字，如 "000001" 或 "600000"

返回数据格式：

{
  "success": true,
  "symbol": "000001",
  "data": {
    "代码": "000001",
    "名称": "平安银行",
    "最新价": 12.34,
    "涨跌幅": 1.23,
    "涨跌额": 0.15,
    "成交量": 1234567,
    "成交额": 15234567890,
    "振幅": 2.5,
    "最高": 12.5,
    "最低": 12.2,
    "今开": 12.25,
    "昨收": 12.19
  }
}

4. get_stock_hist

获取A股单只股票的历史行情数据（最近10条记录）。

参数：

• symbol (str, required): 股票代码，6位数字，如 "000001" 或 "600000"
• period (str, optional): 周期，可选 "daily"(日K), "weekly"(周K), "monthly"(月K)，默认为 "daily"
• adjust (str, optional): 复权类型，可选 ""(不复权), "qfq"(前复权), "hfq"(后复权)，默认为 ""

返回数据格式：

{
  "success": true,
  "symbol": "000001",
  "period": "daily",
  "adjust": "qfq",
  "count": 10,
  "data": [
    {
      "日期": "2024-01-15",
      "开盘": 12.25,
      "收盘": 12.34,
      "最高": 12.5,
      "最低": 12.2,
      "成交量": 1234567,
      "成交额": 15234567890
    }
  ]
}

5. get_futures_realtime

获取国内期货单只合约的实时行情数据。

参数：

• symbol (str, required): 期货代码，如 "RB2505" 或 "AG2604"

返回数据格式：

{
  "success": true,
  "symbol": "RB2505",
  "name": "螺纹钢2505",
  "price": 3850.0,
  "open": 3840.0,
  "high": 3860.0,
  "low": 3835.0,
  "volume": 123456,
  "position": 234567,
  "time": "15:00:00"
}

6. get_futures_main_list

获取国内期货主力合约行情列表（全部数据）。

参数： 无

返回数据格式：

{
  "success": true,
  "count": 50,
  "data": [
    {
      "代码": "RB2505",
      "名称": "螺纹钢2505",
      "最新价": 3850.0,
      "涨跌": 15.0,
      "成交量": 123456
    }
  ]
}

📁 项目结构

mcp/
├── README.md                          # 项目说明文档
├── DOCKER.md                          # Docker 部署文档
├── LOGGING.md                         # 日志配置文档
├── requirements.txt                   # Python 依赖列表
├── config.json                        # 配置文件（需自行创建）
├── Dockerfile                         # Docker 镜像构建文件
├── docker-compose.yml                 # Docker Compose 配置
├── .dockerignore                      # Docker 构建排除文件
├── deploy.sh                          # 自动部署脚本
├── config/                            # 配置模块目录
│   ├── __init__.py                    # Python 包初始化文件
│   └── logging_config.py              # 日志配置模块
├── server/                            # 服务器模块目录
│   ├── mcp_server.py                  # MCP 服务器主程序（SSE 传输）
│   └── modules/                       # 业务逻辑模块
│       ├── __init__.py                # Python 包初始化文件
│       ├── jisilu_mcp_server.py       # 集思录数据抓取模块（QDII + LOF）
│       ├── wechat_server.py           # 微信通知模块
│       ├── stock_server.py            # A股行情数据模块
│       └── futures_server.py          # 期货行情数据模块
├── client/                            # 客户端脚本目录
│   ├── __init__.py                    # Python 包初始化文件
│   ├── notify_arbitrage_mcp_client.py # AI Agent 模式客户端
│   └── deepseek_client.py             # DeepSeek API 客户端
└── tests/                             # 测试脚本目录
    ├── __init__.py                    # Python 包初始化文件
    ├── test_mcp_server.py             # MCP 服务器测试脚本
    ├── test_mcp_server_demo.py        # MCP 服务器演示测试
    ├── test_stock_server.py           # A股行情模块测试脚本
    ├── test_deepseek.py               # DeepSeek 客户端测试脚本
    └── test_deepseek_reasoner.py      # DeepSeek Reasoner 测试脚本

💻 使用示例

基本调用示例

import requests

MCP_BASE = "http://127.0.0.1:4096"

# 调用QDII候选工具
def call_mcp_tool(tool_name: str, params: dict = None):
    payload = {"tool": tool_name, "params": params or {}}
    res = requests.post(f"{MCP_BASE}/call", json=payload, timeout=10)
    res.raise_for_status()
    return res.json()

# 获取溢价率≥3%的基金
candidates = call_mcp_tool("fetch_qdii_candidates", {"threshold": 3.0})
print(candidates)

# 发送微信通知
result = call_mcp_tool("send_wechat", {
    "title": "套利提醒",
    "desp": f"发现 {len(candidates)} 只满足条件的基金"
})
print(result)

使用配置文件

项目提供了 mcp_http_config.json 配置文件示例，您可以在支持 MCP 协议的客户端中使用：

{
  "mcpServers": {
    "arbitrage-suite": {
      "type": "http",
      "url": "http://127.0.0.1:4096",
      "description": "QDII溢价套利和微信通知服务"
    }
  }
}

🔍 数据来源

基金数据从以下来源抓取（按优先级）：

QDII 和 LOF 数据

1. 集思录 QDII API：https://www.jisilu.cn/data/qdii/qdii_list/
2. 集思录 LOF API：https://www.jisilu.cn/data/lof/index_lof_list/
3. AKShare 数据接口（备用）：当 API 失败时自动切换

⚙️ 技术栈

• MCP 框架: FastMCP 2.14+ - 快速构建 MCP 服务器
• 传输协议: SSE (Server-Sent Events)
• HTTP 客户端: httpx - 异步 HTTP 请求
• 数据解析: BeautifulSoup4 + lxml
• 金融数据: AKShare（集思录 API + AKShare 备用）
• 容器化: Docker + Docker Compose
• Web 服务器: Uvicorn（FastMCP 内置）

📝 依赖说明

httpx>=0.28.1           # HTTP 客户端
beautifulsoup4>=4.14.2  # HTML 解析
lxml>=6.0.2             # XML/HTML 处理
akshare>=1.17.87        # 金融数据接口
mcp>=1.21.2             # MCP 协议框架
fastmcp                 # FastMCP 服务器框架

🐳 Docker 部署

快速开始

# 使用 Docker Compose（推荐）
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

更新 Docker 服务

方式一：使用自动更新脚本（推荐）

# Linux/Mac
chmod +x update_docker.sh
./update_docker.sh

# Windows PowerShell
.\update_docker.ps1

方式二：手动更新

# 停止并删除旧容器
docker-compose down

# 重新构建镜像
docker-compose build --no-cache

# 启动新容器
docker-compose up -d

详细的更新步骤和故障排查请查看项目中的 update_docker.sh 或 update_docker.ps1 脚本。

部署文档

详细部署说明请查看 DOCKER.md

端口配置

• 服务端口: 4567（可通过环境变量 PORT 修改）
• SSE 端点: http://localhost:4567/sse

🔬 测试

运行测试脚本

# 确保服务器正在运行
python server/mcp_server.py

# 在另一个终端运行测试
python tests/test_mcp_server.py

AI Agent 客户端示例

项目提供了一个完整的 AI Agent 客户端示例，它结合了 DeepSeek 大模型和 MCP 工具调用：

# 运行 AI Agent 客户端
python client/notify_arbitrage_mcp_client.py

该客户端会：

1. 连接到 MCP 服务器获取可用工具
2. 使用 DeepSeek 分析用户需求并决策调用哪些工具
3. 自动执行工具调用并生成分析报告
4. 通过微信发送通知

测试输出示例

✅ 已成功建立连接并初始化。
[可用工具]: ['fetch_qdii_candidates', 'send_wechat', 'get_stock_realtime', 'get_stock_hist', 'get_futures_realtime', 'get_futures_main_list']

共 7 只基金:
  1. 国投白银LOF (161226)
     溢价率: 50.86%
     申购状态: 限100
  2. 黄金主题LOF (161116)
     溢价率: 13.82%
     申购状态: 限10
  ...

🛠️ 开发说明

MCP 传输方式

本项目使用 SSE (Server-Sent Events) 传输方式：

# mcp_server.py
mcp.run(transport="sse", host="0.0.0.0", port=4567)

扩展新工具

在 mcp_server.py 中添加新的 MCP 工具：

@mcp.tool(description="工具描述")
def your_tool_name(param1: str, param2: int) -> dict:
    """
    工具说明文档

    Args:
        param1: 参数1说明
        param2: 参数2说明
    """
    # 实现逻辑
    return {"result": "success"}

📄 许可证

本项目遵循 MIT 许可证。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

⚠️ 注意事项

1. 配置安全：请勿将 config.json 提交到版本控制系统，注意保护 API 密钥
2. 频率限制：抓取集思录数据时请注意访问频率，避免被封 IP
3. Server 酱额度：免费版 Server 酱有推送次数限制，请合理使用
4. 网络连接：首次运行需要下载数据，请确保网络连接稳定
5. 反向代理：如使用 Nginx/Apache 代理，需特殊配置 SSE 支持（参见 SSE_TROUBLESHOOTING.md）
6. 日志文件：生产环境（ENV=prod）会在 /app/logs/ 生成日志文件

📚 相关文档

项目文档

• Docker 部署指南
• 日志配置说明
• SSE 故障排查

外部资源

• MCP 官方文档
• FastMCP 文档
• Server 酱文档
• 集思录 QDII 页面
• 集思录 LOF 页面
• AKShare 文档

🌟 特性亮点

• ✅ 多数据源：同时支持 QDII 和 LOF 基金数据
• ✅ 行情数据：提供 A股实时/历史行情和期货主力合约数据
• ✅ 自动切换：API 失败时自动切换到备用数据源
• ✅ 生产就绪：Docker 部署 + 环境变量配置 + 日志管理
• ✅ 实时通知：Server 酱微信推送
• ✅ 易于扩展：基于 FastMCP 框架，轻松添加新工具
• ✅ 完整测试：提供完整的测试脚本和示例