Metadata-Version: 2.5
Name: bizonquant-mcp
Version: 0.3.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），**服务器零常驻进程、不开前端**。

## 能力（0.3.0，40 工具）

0.3.0 的 stdio 子进程实际注册 40 个工具，较原 32 项新增 8 项。新增市场快照、IC 异步任务及组合回测/取消权限需要部署配套后端更新；仅升级 PyPI 客户端不会更新服务器。旧后端缺少新路由或权限时，相应调用会失败。

| 组 | 工具 | 说明 |
|---|---|---|
| 锚点 | `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` | 大盘全貌：主要指数 + 全市场涨跌家数 |
| 行情 | `get_minute_trend_tool` | 分时走势、有效价格摘要与有界抽样；成交量单位为手 |
| 行情 | `get_fund_flow_tool` | 个股资金流，金额单位元、比例为百分数，缺值不补零 |
| 行情 | `get_market_snapshot_tool` | 实时名义价、量额、买卖一档、来源时间与陈旧标志 |
| 研究 | `get_stock_factor_values_tool` | 1–20 只指定股票、最多 12 个因子的实际值，缺失显式返回 |
| 研究 | `submit_factor_ic_tool` / `get_factor_ic_result_tool` | 异步提交 IC/分层分析，再按任务 ID 查询 |
| 选股 | `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` | 提交多因子回测（异步） |
| 回测 | `submit_composite_backtest_tool` | 按本人已保存的组合/轮动策略配置提交回测 |
| 回测 | `cancel_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。

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

日 K 仅查本地数据，不触发外部补数。研究池的特征写入链尚不完整，未接空壳工具。QuantBot 内置工具另有实现；托管 HTTP 与工具单源化未在本次范围内。进度与验证记录见 [MCP 化调研报告](../docs/MCP化调研报告.md)。

## 安装与运行

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

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

## 开发

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

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