# wq-brain-mcp-server

[![CI](https://github.com/drephantom/wq-brain-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/drephantom/wq-brain-mcp-server/actions/workflows/ci.yml)

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

> **公开脱敏说明：** 本仓库是量化研究 Agent 的公开脱敏版本，仅包含 MCP 工具、确定性执行器与提交安全边界；不包含账号凭据、真实研究 Alpha 表达式、候选/模拟结果、跨日 Campaign State、回归用例或完整私有 Agent Harness。

**TL;DR (English):** A lightweight MCP server implemented without a third-party MCP SDK. Its stdio JSON-RPC interface exposes 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 稳定性等多重人工确认闸门。

## 架构

```
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 工具

| 工具 | 作用 | 安全约束 |
|---|---|---|
| `wq_auth_status` | 认证并返回脱敏账户摘要 | 仅返回白名单字段 |
| `wq_get_platform_setting_options` | 读取平台模拟设置选项 | 只读 |
| `wq_list_datasets` | 按区域/宇宙/延迟列出数据集 | 分页上限 100 |
| `wq_search_datafields` | 检索数据字段（数据集/类别/类型/文本） | 分页上限 50，短超时防阻塞 |
| `wq_get_operators` | 列出算子（可按类别/关键词过滤） | 分页上限 500 |
| `wq_recent_alphas` | 读取最近 Alpha 列表与详情 | 只读 |
| `wq_write_candidates` | 将候选写入工作区 JSONL | 路径限制在工作区内 |
| `wq_run_multisim_file` | 批量多模拟 | **必须显式 `confirm_run=true`**；批量 2–10；并发 1–8；大批量需 `background=true` 或显式放行 |

## 安全边界设计

**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_*` 归约、算子数超限等。

## 快速开始

```bash
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 风格配置为例）：

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

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

```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，可直接手工验证：

```bash
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
```

### 离线验证

```bash
python -m compileall -q tools
python -m unittest discover -s tests -v
```

这些检查只验证公开工具契约、路径边界、显式确认闸门与候选预检，不读取账号凭据，
也不会向平台发起请求。

## 文件说明

| 文件 | 职责 |
|---|---|
| `tools/wq_mcp_server.py` | MCP 服务器：8 个工具、JSON-RPC 分发、安全包装 |
| `tools/wq_brain_api.py` | BRAIN API 客户端：认证、限速重试、模拟作业、质量摘要 |
| `tools/wq_brain_multi_api.py` | 批量多模拟 runner：父任务轮询、子 Alpha 抓取、断点续跑 |
| `tools/wq_candidate_preflight.py` | 候选文件本地预检（语法/重复/算子陷阱/类型元数据） |
| `tools/wq_submit_monitor.py` | 提交闸门：交易日/额度校验、成本下限、状态轮询留痕 |
| `tools/wq_pnl_stability_audit.py` | PnL 平滑度与状态稳定性审计（提交前诊断） |
| `tools/wq_datafields.py` | 数据字段分页发现（大数据集遍历） |
| `tools/wq_launch_coordinator.py` | 平台认证请求槽协调 |
| `tools/wq_platform_timezone.py` | 美东时区（含离线 Windows 夏令时回退） |
| `tools/wq_requests_compat.py` | requests 兼容 shim（完整/精简运行时） |
| `tests/test_public_contract.py` | 8 项工具契约、隐私白名单与安全闸门的离线测试 |

## 隐私与数据边界

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

## 免责声明

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

## License

[MIT](LICENSE)