bizonquant-mcp

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

能力

当前源码提供 58 个工具：行情与因子、异步选股诊断、三类回测、批量试参、结果分档与对比、回测另存策略，以及交易面的盯盘复盘只读查询。组合/轮动可内联试参，子策略仍需本人已保存 ID。

先调 get_usage_guide_tool 读随包指南，或读取只读 resource bizonquant://guide；无需访问私仓。写配置前调 get_config_template_tool(section=...)，按需取 config、engine_config、rotation、portfolio、formula、caliber_changes（默认 all）。

账号与日历（3）

行情与个股（10）

因子与选股（7）

策略与模板（7）

回测提交与批量（5）

回测结果与对比（8）

组合与轮动（5）

盯盘与复盘（13）

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

状态与边界

• 本地测试覆盖协议握手、工具调用和模板契约；测试结果以当前 CI/本次执行为准。本地通过不等于真实凭证与线上链路可用。
• 托管 Streamable HTTP、QuantBot/Python MCP 工具单源化、真实凭证 E2E、工具调用审计与更完整用户级限流仍需分别验证或建设。

三类回测共用每用户提交闸，排队+执行上限默认 3 个，与桌面端共享。提交429且提示并发上限时先等已有任务。degraded 是可取结果的终态，解读时保留质量标志。

日 K 仅查本地数据，不触发外部补数。研究池的特征写入链尚不完整，未接空壳工具。QuantBot 内置工具另有实现。

四条 MCP prompts 提供研究步骤：design_multifactor_strategy、diagnose_backtest、design_composite_strategy、review_trading_account；均引用现有工具，交易面只读。

批量回测与盯盘复盘

submit_backtest_batch_tool 以公共 config/preset_id/base_backtest_id 加1~30个带唯一 label 的补丁项试参；组合/轮动可用 kind+config 内联，子策略仍需已保存 ID。补丁对象深合并，null 删键、数组整体替换。默认 max_parallel=2，给桌面端留一个名额；账户总上限默认3，各宿主共享。单次提交遇429返回 submitted=false 与活跃任务；批次遇429退避后自动补位。

保存 batch_id，用 get_backtest_batch_tool 等待并取榜单；已有多个 ID 用 wait_backtests_tool。榜单不代表口径可比，先用 compare_backtests_tool 核对，再读五档结果与质量标记。满意后 save_strategy_from_backtest_tool 按当次配置另存，同名409不覆盖。cancel_backtest_batch_tool 默认仅停未提交队列，cancel_submitted=true 才取消已提交未终态回测。

批次仅在本地进程内存中。宿主重启会丢未提交项与批次状态；已提交任务仍在后端运行，按 list_backtests_tool 返回名称匹配 name_prefix 找回（需自行翻页匹配，无名称过滤参数）。

“今天调了吗／为何没调”从运行状态查托管任务与日志；“为什么卖了这只”查任务计划、信号 run、委托备注和实际成交；“分红到账了吗”查模拟盘现金账本。get_simulation_review_tool 还支持调仓计划、持仓变化、指定日回放和成交统计；各有历史窗口，空页不等于从未发生。批量快照可看自选/持仓新鲜度。部署、启动、停止托管必须由用户在桌面端操作。

安装与运行

0.9.0 需先上线 P1 后端，再由协调者发布包。本次源码升级不执行发版。

0.9.0 变更

• 三类回测及三个保存入口自动使用随机幂等键，批量每项持续复用同一键。ConnectError / ConnectTimeout / PoolTimeout / ProxyError 表示请求未发出，返回 accepted=no/retryable=true，单发可同键退避重试两次、批量继续排队，不依赖能力探测。
• ReadError / ReadTimeout / WriteError / WriteTimeout / RemoteProtocolError，以及无语义字段的网关 502/504 表示结果不确定；仅当 research_writes.idempotency_key 严格为 true 时，单次调用内同键重试一次。语义不确定错误（入队/保存结局未知、仍在处理、已换代）不在单次调用内重发；最终 accepted=unknown/retryable=false 时先查状态或历史，勿再次调用提交/保存工具。成功回放输出 replayed:true。
• 批量不确定项保持 pending 并占名额，退避后确认能力才同键重试；能力暂不可读时只重新探测，不盲目重发，最多 20 次后标 unknown。候选 ID 跟随最新不确定回执，取消只针对当前候选。IDEMPOTENCY_STORE_UNAVAILABLE 在单次预算内同键按 1、2、4 秒退避（服务端等待下限超过4秒时直接返回可重试错误，交给队列退避），最多重试 3 次；配额禁用不重试。
• 错误输出保留 isError 和结构化 reason/accepted/retryable/context；retryable=false 时不提示等待秒数，retry_after 为 null。批量行的 error 仍是人读字符串（无错误时省略），结构化字段放 error_info（dict 或 null），失败终态的 message 给最终失败原因；区分并发限制、配额禁用、保存结果不确定及选股 expired。
• 保存映射 overwrite 到 on_conflict，确认后端能力后使用原子 reject；旧后端保留先查后写和执行参数继承。
• 包重构为传输、身份与 ClientState 分层；测试与锁文件为 2.3.0，依赖范围 mcp>=2.1,<3。BIZONQUANT_TOOLSETS 可选择工具组，默认仍为 58 个工具；批量仍由客户端调度。

0.8.0 的分档权限与停用原因提示需配套 P0-b 后端，先升级后端，再按 P0-c 发布 MCP 与 PWA，之后切换新建 key 默认为研究档。旧后端 whoami 返回 404 时自动回落旧身份接口并剔除邮箱；403 不回落。权限隔离由后端执行。

# PyPI 安装，无需 clone；新增接口需要配套后端更新
uvx bizonquant-mcp@latest init     # 录入 key 并自检（写入 ~/.config/bizonquant-mcp/config.json，0600）
uvx bizonquant-mcp@latest 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@latest"],
  "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。

环境变量凭证缺失时，服务端会读取 init 写入的配置文件：默认 ~/.config/bizonquant-mcp/config.json，可用 BIZONQUANT_CONFIG 指定路径（空字符串仍用默认路径）。环境变量优先，缺项从配置文件补齐；base_url 也优先取环境变量，再取文件，最后取内置地址。不要把 secret 放进命令行或提交进仓库。

宿主超时与网络环境

宿主可能在工具返回前超时，MCP 的 HTTP 超时和宿主工具超时是两层限制。单条/多条等待默认总预算50秒，BIZONQUANT_WAIT_BUDGET_S 可调整默认值（最大600秒），显式 max_wait_s 优先；批次查询的 wait_s 默认50秒，实际取 wait_s、环境预算、600秒三者最小值，0为立即返回。放宽前也要调整宿主允许的工具时长，或保持短等待并续调。

选股提交后台任务，一次工具调用最多等待50秒；未完成返回 job_id，用 get_screen_job_tool 续查。同账号、同数据版本、相同请求会复用任务；终态最多保存15分钟：单账号超过16条记录或全局容量满时可能提前回收，engine重启也会丢失；返回404后原参数重新提交。旧同步 /screen 的55秒预算与 BIZONQUANT_SCREEN_TIMEOUT_S 仅供兼容路径使用。回测提交超时先按名称查历史，不能据超时断言未提交。指标预览 HTTP 超时120秒，宿主可能更早结束。

默认沿用系统代理环境；BIZONQUANT_TRUST_ENV=0 让 httpx 不读取环境代理等配置，适用于系统代理不可用或协议不支持的情况。它不改变网关地址、凭证权限或 HTTPS 校验要求。

拿凭证

在桌面端设置 → 账号安全 → Agent 接入创建 key；默认研究档 mcp.research，按需勾选账户读取 mcp.account 或策略写入 mcp.strategy_write。secret 只展示一次，可复制配置片段。平台分阶段切换新建 key 的默认值，过渡期间以设置页与 get_me_tool 返回为准。

存量 mcp.* / mcp.read / mcp.write 为 legacy 档，保留既有能力；可以收紧为分档权限，不能回升为 legacy。doctor 会显示权限档位并提示 legacy key 可收紧；连旧后端时提示先升级后端。平台暂停接入和本账号停用分别提示管理员联系路径与设置页启用路径，不要因此轮换 key。

一个宿主一把 key：即使在同一台电脑，不同宿主进程也应分配独立 Key。

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

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

安全模型

• 凭证是 API Key（access_key + secret），不是账号密码；按需授权并妥善保管。
• 研究档：行情、因子、选股、校验、策略研究配置、回测提交/取消/读取/对比；不包含账户读取或保存策略。账户读取另行开放账户、持仓、委托、成交、通知、托管任务和信号；策略写入另行开放方案/组合/轮动保存与回测另存。两项可选权限相互独立，业务归属鉴权仍生效。
• 不可读：LLM 配置与凭证、API Key 管理、后台管理。
• 不可做：任何交易与资金写（含下单、撤单、部署/启停托管）及删除。研究写操作仅限网关白名单，如保存多因子/组合/轮动策略、回测单次或批量提交与取消、完成回测另存策略。已部署策略（托管或实盘运行中、被 PTrade 订阅（含暂停中）、被已部署的组合引用）服务端拒绝 agent 覆盖（409），只能另存新名；覆盖其它同名策略前须征得用户明确同意。
• 删除 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——网关收窄或工具新增写路径而网关未放行时，测试立即红。

tests/test_templates.py 以 AST 双向对拍后端字段与枚举，无需安装后端依赖；tests/test_guide.py 断言包内指南与仓库指南逐字节一致，并验证 resource/prompts。