Tushare MCP (Cwjcw)

TushareMCP

一个面向量化开发者的「元数据驱动（Metadata-Driven）」Tushare 万能 MCP 工具：

• 离线层：用 Playwright 抓取 Tushare 文档，生成 tushare_api_specs.json
• 服务层：FastMCP + 反射转发器（getattr(pro, api_name)(**params)）
• 客户端：在 Cherry Studio / Codex 里先查字典再执行，避免“幻觉参数”

设计理念

• 解耦：接口定义（Schema）与代码实现（Implementation）完全分离，Tushare 文档变化只需更新 specs 文件。
• 反射：通过动态转发 getattr(pro, api_name)(**params) 替代上百个静态函数。
• 认知闭环：在客户端 SOP 中强制“先查字典再执行”，避免幻觉参数。

架构概览

1) 离线层（Cartographer）：抓取 Tushare 文档，生成 tushare_api_specs.json 2) 服务层（Universal Gateway）：FastMCP + 反射 + 风控（限流/截断/异常处理） 3) 客户端（Cognitive Agent）：严格按“查字典 -> 构参 -> 执行 -> 解释”流程

1) 安装

建议使用虚拟环境：

python -m venv .venv
. .venv/bin/activate
pip install -U pip
pip install -e ".[scrape]"
playwright install chromium

需要设置 Tushare Token：

export TUSHARE_TOKEN="your_token"

2) 离线构建数据字典（Scraper）

生成 data/tushare_api_specs.json：

tushare-mcp-scrape --base-url https://tushare.pro/document/2 --output data/tushare_api_specs.json

如果需要登录态（可选），先用 Playwright 导出 storage state，然后：

python scripts/capture_storage_state.py
tushare-mcp-scrape --storage-state storage_state.json

3) 运行万能 MCP Server（Stdio）

tushare-mcp-server --specs data/tushare_api_specs.json

Docker 运行

方式 A：直接 Docker

docker build -t tushare-mcp .
docker run --rm -i --env-file .env -v "$PWD/data:/app/data" tushare-mcp

MCP 使用 stdio，务必加 -i 保持标准输入。

方式 B：Docker Compose

docker compose up --build

MCP 客户端配置示例（通过 docker）：

{
  "mcpServers": {
    "tushare": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", ".env", "-v", "./data:/app/data", "tushare-mcp"]
    }
  }
}

Scraper（Docker）

构建并运行离线文档爬虫（生成 data/tushare_api_specs.json）：

docker build -f Dockerfile.scraper -t tushare-mcp-scraper .
docker run --rm -v "$PWD/data:/app/data" tushare-mcp-scraper

使用 Compose：

docker compose run --rm tushare-scraper

代码更新后如何同步到容器

修改代码后需要重建镜像并重启容器：

docker compose up --build -d tushare-mcp

或分两步：

docker compose build tushare-mcp
docker compose up -d tushare-mcp

HTTP / WS 网关

如果需要远程调用 MCP，可启动 HTTP/WS 网关（默认端口 8787）。

本机启动

tushare-mcp-gateway --specs data/tushare_api_specs.json --host 0.0.0.0 --port 8787

Docker 启动

docker compose up -d tushare-gateway

HTTP 端点

• MCP HTTP 端点：/mcp（streamable-http）
• 健康检查：/healthz

WebSocket 端点（MCP 标准）

/ws 使用 MCP WebSocket 传输（子协议 mcp），可用于支持 WS 的 MCP 客户端直连。

该 Server 仅暴露 2 个核心工具：

• search_api_docs(keyword, limit=10)：查字典（模糊搜索 + 返回参数/字段）
• execute_tushare_query(api_name, params)：万能执行（反射调用 + 限流 + 自动截断）

MCP 客户端配置示例

见 examples/mcp_config.json。

4) 风控参数（可选）

• TUSHARE_MCP_MAX_ROWS：返回行数截断（默认无限制； min_interval_seconds = 60 / 每分钟频次，已在档位文件中预计算。

推荐 SOP（客户端）

1) search_api_docs 搜索接口与参数 2) 根据 required 构造参数 3) execute_tushare_query 执行 4) 若报错或缺参，回到第 1 步修正

限流配置文件

• 正式配置：config/tushare_rate_limits.json
• 示例模板：config/tushare_rate_limits.example.json

该文件包含：

• tiers：不同积分的频次限制（含 min_interval_seconds）
• independent_permissions：独立权限项的“每次返回行数/每次可请求股票数”，避免混淆常规接口

storage_state.json（登录态）

storage_state.json 是 Playwright 保存的登录态快照（cookies / localStorage），用于抓取需要登录权限的文档。

• 不要提交到 Git（已在 .gitignore 中忽略）
• 如果需要在 Docker 中使用，可通过挂载文件传入