bizonquant-mcp

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

能力（源码 0.4.0，41 工具）

源码 0.4.0 注册 41 个工具，比 PyPI 上的 0.3.0（40 个）多一个 save_composite_strategy_tool。0.4.0 尚未发布 PyPI，配套后端（网关放行组合保存、组合缺省归一化修复）也需要部署后才可用；仅升级客户端不会更新服务器，旧后端缺少新路由或权限时，相应调用会失败。

先读 MCP 使用指南：因子单位、buy_priority、组合级参数、轮动条件口径等易错点都集中在那里。

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

状态与边界（2026-09-08）

• 已批准的 0.3.0 范围已完成；原候选“必选+推荐”按语义能力覆盖 36/42≈85.7%（合并工具算覆盖）。
• 验证边界：本地 MCP 全量 107 passed（2026-09-23，含组合保存与因子单位对拍）；尚未用真实用户 MCP Key 完成端到端 tools/call，本地通过不等于线上可用。
• 长期缺口（托管 Streamable HTTP、QuantBot/Python MCP 工具单源化、真实凭证 E2E、工具调用审计/更完整用户级限流）见 MCP 化调研报告，这里不报长期架构百分比。

IC 使用进程内异步任务：同用户同参数复用在跑任务，全局最多 2 个实际计算、每用户 1 个。完成结果保留 15 分钟，最多缓存 32 项；服务重启或结果过期需重新提交。三类回测共用每用户提交闸。状态/结果查询支持三类回测，degraded 是可取结果的终态，解读时保留质量标志。

日 K 仅查本地数据，不触发外部补数。研究池的特征写入链尚不完整，未接空壳工具。QuantBot 内置工具另有实现；托管 Streamable HTTP 与 QuantBot/Python MCP 工具单源化仍未交付，详见调研报告。进度与验证记录见 MCP 化调研报告。

安装与运行

# PyPI 安装，无需 clone；新增接口需要配套后端更新
uvx bizonquant-mcp@0.3.0 init     # 录入 key 并自检（写入 ~/.config/bizonquant-mcp/config.json，0600）
uvx bizonquant-mcp@0.3.0 doctor   # 探链路：health / token / whoami / 数据面

# 从源码运行
cd mcp-server && uv sync
uv run bizonquant-mcp doctor

接入 Claude Code（stdio）

// ~/.claude.json 的 mcpServers —— uvx 形态（推荐，无需本机有仓库）
"bizonquant": {
  "command": "uvx",
  "args": ["bizonquant-mcp@0.3.0"],
  "env": {
    "BIZONQUANT_ACCESS_KEY": "bq_live_xxx",
    "BIZONQUANT_SECRET_KEY": "sk_yyy",
    "BIZONQUANT_BASE_URL": "https://bizon.naiyu.xyz:8443"
  }
}

// 仓库形态（开发调试用）
// "command": "uv", "args": ["--directory", "<仓库路径>/mcp-server", "run", "bizonquant-mcp"]

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

拿凭证

1. 推荐：Agent 接入设置：设置 → 账号安全 →「Agent 接入 (MCP)」→ 生成新 Key；权限固定为 mcp.*，secret 一次性展示，可复制配置片段并管理已有 key。
2. 过渡 curl：登录（注意 device_type）→ POST /api/v1/api-keys（{"name":"mcp","permissions":["mcp.*"]}，secret 只显示一次）

当前网关按 scope=agent 统一限制操作，不能将 key 名称或 mcp.read 标签当成已经实现独立只读权限档位的保证。

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

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

安全模型

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

开发

uv run python -m pytest -q  # 全量测试（含网关 scope 与工具路径对拍、真实 stdio）
uv run bizonquant-mcp --version

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