bizonquant-mcp

BizonQuant 量化平台的 MCP server（客户端形态）：跑在你本机，把平台能力面开放给外部 agent（Claude Code / Cursor / Codex / 自写 agent），服务器零常驻进程、不开前端。

能力（31 工具）

交易面全部只读：下单/撤单/启停实盘/删方案/删回测不在能力面内，永远不会开放给 agent。

安装与运行

# 从仓库根
cd mcp-server && uv sync
uv run bizonquant-mcp init     # 录入 key 并自检（写入 ~/.config/bizonquant-mcp/config.json，0600）
uv run bizonquant-mcp doctor   # 探链路：health / token / whoami / 数据面

接入 Claude Code（stdio）

// ~/.claude.json 的 mcpServers
"bizonquant": {
  "command": "uv",
  "args": ["--directory", "<仓库路径>/mcp-server", "run", "bizonquant-mcp"],
  "env": {
    "BIZONQUANT_ACCESS_KEY": "bq_live_xxx",
    "BIZONQUANT_SECRET_KEY": "sk_yyy",
    "BIZONQUANT_BASE_URL": "https://bizon.naiyu.xyz:8443"
  }
}

也支持单变量 BIZONQUANT_API_KEY=access_key.secret_key。

拿凭证（三选一）

1. 桌面端：API 密钥页建 key，permissions 勾 mcp.read（只读）或 mcp.*（含 save_preset / submit_backtest 写点）
2. 过渡 curl：登录（注意 device_type）→ POST /api/v1/api-keys（{"name":"mcp","permissions":["mcp.*"]}，secret 只显示一次）
3. 桌面端「Agent 接入」UI（待建，阶段 2）

客户端纪律（内置，无需配置）

• 默认拒绝 http:// 明文网关（BIZONQUANT_ALLOW_INSECURE=1 可解锁内网场景）
• token 只走 Authorization 头；401 自动换发一次，仍 401 即停（key 撤销后不打风暴）
• UA 带 bizonquant-mcp/{version}，服务端可审计

安全模型

• 凭证是 API Key（access_key + bcrypt secret），不是账号密码——泄漏面仅限该 key 的能力面
• 服务端对 agent token 施加 scope 硬闸：GET 全放，非 GET 只放白名单（选股/存方案/校验/回测提交/回测对比），/admin 与 /api-keys 一律 403
• 交易/资金类写端点不在能力面内；删 key / 停用 / 轮换 secret 即时全链失效
• revoke 命令 = 同 key 再换发一次（互踢规则下旧会话全灭）；永久吊销请在桌面端删 key

开发

uv run pytest -q        # 全量测试（含与网关 scope 闸、TS 工具表的 (method,path) 对拍）
uv run bizonquant-mcp --version

对拍闸：tests/test_conformance.py 断言本包工具的 (method, path) ⊆ 网关 AGENT_WRITE_ALLOWLIST ∪ GET——网关收窄或工具新增写路径而网关未放行时，测试立即红。