wq-brain-mcp-server

本地 WorldQuant BRAIN 研究工具的 MCP Server 与配套 CLI——把平台能力封装成 LLM Agent 可安全调用的 8 个工具，并用多层闸门保证"Agent 可以跑研究，但不能自己提交"。

TL;DR (English): A dependency-free MCP server (stdio JSON-RPC) exposing 8 tools for WorldQuant BRAIN research — account status, platform settings, dataset/field/operator discovery, recent alphas, candidate writing, and a guarded multi-simulation runner. Alpha submission is deliberately not exposed at the MCP layer; submissions go through a separate CLI with day/quota/cost/stability gates.

为什么写这个

在 Agent 驱动的量化研究工作流里，平台没有官方 MCP 支持，Agent 无法直接检索数据字段、批量提交模拟。直接给 Agent 浏览器或裸 API 又不可接受：模拟消耗平台配额，提交影响真实账户。这个项目把两者分开：

• MCP 层只做研究与验证：检索、候选写入、批量模拟全部可由 Agent 自主调用；

• 提交彻底移出 MCP 层：服务器代码中不存在 submit 工具，提交走独立的 CLI，且必须通过交易日、日额度、交易成本、PnL 稳定性等多重人工确认闸门。

Related MCP server: Sentinel Core Agent

架构

MCP Client (Codex CLI / Claude Desktop / 任意 MCP 宿主)
        │  stdio JSON-RPC（MCP 2024-11-05，零第三方 MCP 依赖）
        ▼
wq_mcp_server.py ── 8 个工具 ──►  wq_brain_api.py（认证 / Retry-After 限速 / 401 重认证）
        │                               │
        │  wq_write_candidates          │  wq_run_multisim_file（子进程）
        ▼                               ▼
  candidates/*.jsonl ◄── wq_candidate_preflight.py ── wq_brain_multi_api.py（父任务轮询、子 Alpha 抓取）
                                        （仅模拟，永不提交）

提交路径（独立于 MCP）：
wq_submit_monitor.py ── 交易日 + 日额度 + 交易成本 + PnL 稳定性 + 简化清单闸门 ──► POST /alphas/{id}/submit

8 个 MCP 工具

安全边界设计

MCP 层（Agent 可达）

1. 不暴露提交工具——TOOLS 注册表中不存在 submit，服务器 instructions 明确声明；

2. 显式确认才能消耗配额——wq_run_multisim_file 缺少 confirm_run=true 直接抛错；

3. 路径逃逸防护——所有输入/输出路径经 safe_workspace_path 校验，禁止越出工作区；

4. 防 UI 阻塞——大批量任务强制后台运行或双重显式确认；

5. 平台礼貌性——全链路尊重 Retry-After，429/502/503/504 有界重试，401 自动重认证。

提交闸门（独立 CLI，代码在 wq_submit_monitor.py）

• 提交前从平台 HTTP Date 头重新推导当前平台交易日，必须与 --expected-platform-day 一致，并校验 --expected-daily-active-count 日额度——不匹配即阻断；

• Full / Train / Test 三个窗口的保证金必须高于工作区交易成本下限（transaction_cost_margin_blocked）;

• 必须携带 PnL 稳定性审计 CSV（pnl_stability_gate_blocked），平台绿检查不能绕过组合质量闸门；

• 必须携带已验证的简化清单（simplification manifest），通过检查的复杂表达式不能绕过极简化闸门；

• 全程轮询留痕，避免"队列转圈"被误判为提交成功。

候选预检（wq_candidate_preflight.py）

在昂贵的批量模拟前本地拦截廉价错误：JSONL 格式、空表达式、括号不平衡、重名、队列内重复身份、保留变量名、FASTEXPR 拒绝的链式临时赋值、已知算子 arity 陷阱、VECTOR 字段缺少原生 vec_* 归约、算子数超限等。

快速开始

git clone https://github.com/drephantom/wq-brain-mcp-server.git
cd wq-brain-mcp-server
pip install -r requirements.txt

# 配置凭据（或直接设置环境变量 WQB_EMAIL / WQB_PASSWORD）
cp .env.local.example .env.local   # 编辑填入 BRAIN 账号

注册到 MCP 客户端（以 Claude Desktop 风格配置为例）：

{
  "mcpServers": {
    "wq-brain": {
      "command": "python",
      "args": ["/path/to/wq-brain-mcp-server/tools/wq_mcp_server.py"]
    }
  }
}

Codex CLI（~/.codex/config.toml）示例：

[mcp_servers.wq_brain]
command = "python"
args = ["D:/path/to/wq-brain-mcp-server/tools/wq_mcp_server.py"]
tool_timeout_sec = 7200

[mcp_servers.wq_brain.env]
WQB_EMAIL = "..."
WQB_PASSWORD = "..."

协议握手示例

服务器是标准 stdio JSON-RPC，可直接手工验证：

cd tools
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' | python wq_mcp_server.py
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | python wq_mcp_server.py

文件说明

隐私与数据边界

本仓库只包含代码，不包含任何研究数据：没有候选 Alpha、模拟结果、账户信息、收益记录或研究笔记。.gitignore 预屏蔽了 candidates/、results/、research/——即使你在克隆目录里跑真实研究，产出的数据也不会被意外提交。

免责声明

本工具与 WorldQuant 无任何关联，亦非官方产品。BRAIN 平台账号凭据仅保存在本地（环境变量或 .env.local，不入库）。使用平台 API 请遵守 WorldQuant BRAIN 服务条款；任何提交行为的合规性与后果由使用者自行承担。

License

MIT