Metadata-Version: 2.5
Name: bizonquant-mcp
Version: 0.2.0
Summary: BizonQuant MCP server —— 把量化能力面（行情/多因子选股/回测）开放给外部 agent
License: MIT
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.9
Description-Content-Type: text/markdown

# bizonquant-mcp

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

## 能力（31 工具）

| 组 | 工具 | 说明 |
|---|---|---|
| 锚点 | `get_me_tool` | 当前用户；凭证探针 |
| 锚点 | `get_trading_day_info_tool` | 交易日判断 + 上/下一交易日 |
| 锚点 | `get_data_coverage_tool` | 数据覆盖/因子数/股票池——回测日期边界来源 |
| 锚点 | `get_config_template_tool` | 选股/回测 config 模板 + formula 语法 |
| 行情 | `search_stocks_tool` | 模糊名 → 规范代码 |
| 行情 | `get_daily_klines_tool` | K 线 + 区间摘要（涨跌/高低/MA20/MA60/站上均线） |
| 行情 | `get_market_overview_tool` | 大盘全貌：主要指数 + 全市场涨跌家数 |
| 选股 | `list_factors_tool` | 因子目录 + 取值语义（防条件翻译错） |
| 选股 | `screen_stocks_tool` | 即时截面选股，附因子值 |
| 选股 | `validate_strategy_config_tool` | 提交前配置校验（valid/errors/warnings） |
| 选股 | `list_presets_tool` / `save_preset_tool` | 方案列表 / 存方案 |
| 策略 | `list_my_strategies_tool` | 全部策略与运行状态 |
| 策略 | `get_strategy_detail_tool` | 单条策略完整配置 |
| 策略 | `list_composite_strategies_tool` | 组合（PORTFOLIO）/轮动（ROTATION）策略与配置 |
| 回测 | `submit_backtest_tool` | 提交多因子回测（异步） |
| 回测 | `wait_backtest_tool` | 有界等待（≤50s），done:false 续调 |
| 回测 | `get_backtest_status_tool` / `get_backtest_result_tool` / `list_backtests_tool` | 状态 / 结果（曲线抽样）/ 历史 |
| 回测 | `get_backtest_logs_tool` | 运行日志尾窗（TTL 1h），诊断失败 |
| 回测 | `compare_backtests_tool` | 两条正式回测并排指标对比 |
| 基准 | `get_benchmark_curve_tool` | 基准指数收盘序列（与净值对比） |
| 交易（只读） | `get_simulation_account_tool` / `get_real_account_tool` | 模拟盘 / 实盘账户与持仓（PTrade 用户自动回退脚本快照） |
| 交易（只读） | `get_ptrade_overview_tool` | PTrade 通道状态 / 订阅 / 当日信号 |
| 交易（只读） | `list_orders_tool` / `list_trades_tool` | 委托 / 成交（simulation、real/shadow） |
| 交易（只读） | `get_trading_status_tool` / `get_equity_curve_tool` | 实盘运行状态 / 逐日资金曲线 |
| 其他 | `list_notifications_tool` | 通知历史（策略信号/订单/回测完成，近 30 天） |
| 其他 | `list_watchlist_tool` | 自选股清单（只读，增删在桌面端） |

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

## 安装与运行

```bash
# 从仓库根
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）

```jsonc
// ~/.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

## 开发

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

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