bizonquant-mcp 0.1.0__tar.gz

bizonquant_mcp-0.1.0/.gitignore

@@ -0,0 +1,178 @@
+# ==============================================================================
+# 1. Environment & Packages
+# ==============================================================================
+.venv/
+env/
+venv/
+ENV/
+.python-version
+node_modules/
+.npm/
+*.local
+/__pycache__/
+# ==============================================================================
+# 2. Caches, Build & OS
+# ==============================================================================
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.eslintcache
+.parcel-cache
+.vite/
+.npm-global/
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+*.bak
+*.bak_*
+.project
+.pydevproject
+.settings/
+build/
+dist/
+out/
+electron/dist/
+electron/out/
+.deploy_tmp/
+.deploy_fix/
+*.docker-build-lock
+.docker/
+.qwen
+# ==============================================================================
+# 3. AI, IDE & Local Tools
+# ==============================================================================
+.vscode/
+.idea/
+.trae/
+.codex/
+.codex_logs/
+.copilot/
+.gemini/
+.geminiignore
+.hintrc
+.traeignore
+.antigravityignore
+.workbuddy/
+.claude/
+.omo/
+.playwright-mcp/
+.codegraph/
+
+# ==============================================================================
+# 4. Data, ML & Results
+# ==============================================================================
+logs/
+*.log
+# Databases
+*.duckdb
+*.duckdb.tmp/
+*.sqlite
+*.sqlite3
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Qlib & Large Data Files
+db/qlib_data/**/*.bin
+db/qlib_data/**/*.data
+!db/qlib_data/
+!db/qlib_data/**/
+!db/qlib_data/**/*.txt
+db/qlib_bin/
+db/qlib_csv/
+db/*.tar.gz
+db.tar.gz
+*.bin
+*.parquet
+# 测试夹具是代码的一部分，必须入库——否则干净克隆上读取测试直接失败
+!electron/electron/services/__tests__/fixtures/*.parquet
+*.csv
+!backend/services/trade/data/corporate_actions.csv
+!backend/tests/**/*.csv
+!data/examples/**/*.csv
+data/backtest_results/
+userdata/
+
+# Test Coverage Artifacts
+.coverage
+coverage.xml
+htmlcov/
+
+# Runtime user data
+user_pools_local/
+data/user_strategies/
+
+# Temp files
+tmp/
+temp/
+.temp/
+run/*.pid
+
+# ==============================================================================
+# 5. Secrets & Config
+# ==============================================================================
+.env
+.env.local
+.env.*.local
+!.env.example
+*.pem
+*.key
+.ssh/
+/db/*.sql
+/redis
+/data/ai_ide/tmp_run
+/electron/icon.iconset
+# ==============================================================================
+# 5. Marketing Files
+# ==============================================================================
+marketing/
+
+# ==============================================================================
+# 6. Repository Specific Exceptions
+# ==============================================================================
+!.github/
+redis/data/appendonlydir/appendonly.aof.2.incr.aof
+# Windows specific build artifacts
+*.exe
+*.msi
+electron/public/fonts/AlibabaPuHuiTi-Bold.ttf
+electron/public/fonts/AlibabaPuHuiTi-Regular.ttf
+data/ai_ide/config.json
+db/diagram/postgresql_schema.dot
+db/backups/*.gz
+!db/feature_snapshots/*.json
+website/download-config.json
+
+# Ignore db subdirectories
+/db/backups/
+/db/custom/
+/db/feature_snapshots/
+/db/qlib_data/
+/models/users/
+data/user_10000001
+db/csmar
+/website/
+/db/
+/sync_to_gitee.sh
+
+# 运行时产物（同步暂存/审计报告/临时检查输出），不入库
+/audit/
+/data/sync_staging/
+data/backups/
+data/uploads/
+
+# 生产 PG 备份产物（scripts/ops/db/pg_backup.sh），不入库
+/backups/
+*.sql.gz
+
+# 外部 agent skills（npx skills add 可重装的依赖，不是源码；软链在 .claude/ 下，已被第 60 行覆盖）
+/.agents/
+
+# Orca 工作树与本地工具产物,不入库
+/.orca/
+/.reasonix/

bizonquant_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: bizonquant-mcp
+Version: 0.1.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），**服务器零常驻进程、不开前端**。
+
+## 能力（首期 15 工具）
+
+| 组 | 工具 | 说明 |
+|---|---|---|
+| 锚点 | `get_me_tool` | 当前用户；凭证探针 |
+| 锚点 | `get_trading_day_info_tool` | 交易日判断 + 上/下一交易日 |
+| 锚点 | `get_data_coverage_tool` | 数据覆盖/因子数/股票池——回测日期边界来源 |
+| 行情 | `search_stocks_tool` | 模糊名 → 规范代码 |
+| 行情 | `get_daily_klines_tool` | K 线 + 区间摘要（涨跌/高低/MA20/MA60/站上均线） |
+| 选股 | `list_factors_tool` | 因子目录 + 取值语义（防条件翻译错） |
+| 选股 | `screen_stocks_tool` | 即时截面选股，附因子值 |
+| 选股 | `list_presets_tool` / `save_preset_tool` | 方案列表 / 存方案 |
+| 回测 | `submit_backtest_tool` | 提交多因子回测（异步） |
+| 回测 | `wait_backtest_tool` | 有界等待（≤50s），done:false 续调 |
+| 回测 | `get_backtest_status_tool` / `get_backtest_result_tool` / `list_backtests_tool` | 状态 / 结果（曲线抽样）/ 历史 |
+| 总览 | `list_my_strategies_tool` | 全部策略与运行状态 |
+
+## 安装与运行
+
+```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": "qm_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 只放 5 条写白名单（选股/存方案/回测提交），`/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——网关收窄或工具新增写路径而网关未放行时，测试立即红。

bizonquant_mcp-0.1.0/README.md

@@ -0,0 +1,74 @@
+# bizonquant-mcp
+
+BizonQuant 量化平台的 MCP server（客户端形态）：跑在你本机，把平台能力面开放给外部 agent（Claude Code / Cursor / Codex / 自写 agent），**服务器零常驻进程、不开前端**。
+
+## 能力（首期 15 工具）
+
+| 组 | 工具 | 说明 |
+|---|---|---|
+| 锚点 | `get_me_tool` | 当前用户；凭证探针 |
+| 锚点 | `get_trading_day_info_tool` | 交易日判断 + 上/下一交易日 |
+| 锚点 | `get_data_coverage_tool` | 数据覆盖/因子数/股票池——回测日期边界来源 |
+| 行情 | `search_stocks_tool` | 模糊名 → 规范代码 |
+| 行情 | `get_daily_klines_tool` | K 线 + 区间摘要（涨跌/高低/MA20/MA60/站上均线） |
+| 选股 | `list_factors_tool` | 因子目录 + 取值语义（防条件翻译错） |
+| 选股 | `screen_stocks_tool` | 即时截面选股，附因子值 |
+| 选股 | `list_presets_tool` / `save_preset_tool` | 方案列表 / 存方案 |
+| 回测 | `submit_backtest_tool` | 提交多因子回测（异步） |
+| 回测 | `wait_backtest_tool` | 有界等待（≤50s），done:false 续调 |
+| 回测 | `get_backtest_status_tool` / `get_backtest_result_tool` / `list_backtests_tool` | 状态 / 结果（曲线抽样）/ 历史 |
+| 总览 | `list_my_strategies_tool` | 全部策略与运行状态 |
+
+## 安装与运行
+
+```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": "qm_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 只放 5 条写白名单（选股/存方案/回测提交），`/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——网关收窄或工具新增写路径而网关未放行时，测试立即红。

bizonquant_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "bizonquant-mcp"
+version = "0.1.0"
+description = "BizonQuant MCP server —— 把量化能力面（行情/多因子选股/回测）开放给外部 agent"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = [
+    "mcp>=1.9",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+bizonquant-mcp = "bizonquant_mcp.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bizonquant_mcp"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "respx>=0.22",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

bizonquant_mcp-0.1.0/src/bizonquant_mcp/__init__.py

@@ -0,0 +1,19 @@
+"""BizonQuant MCP server：把平台能力面（行情/多因子选股/回测）开放给外部 agent。
+
+客户端形态（调研报告 C 方案）：本包是 stdio MCP server，跑在用户本机，
+所有工具都是对公网网关 REST 的薄封装——服务器零常驻进程。
+"""
+
+from bizonquant_mcp.gateway import (
+    BizonQuantError,
+    CredentialError,
+    GatewayClient,
+)
+from bizonquant_mcp.version import __version__
+
+__all__ = [
+    "BizonQuantError",
+    "CredentialError",
+    "GatewayClient",
+    "__version__",
+]

bizonquant_mcp-0.1.0/src/bizonquant_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""python -m bizonquant_mcp → stdio MCP server。"""
+
+from bizonquant_mcp.server import main
+
+main()

bizonquant_mcp-0.1.0/src/bizonquant_mcp/cli.py

@@ -0,0 +1,168 @@
+"""CLI：init / doctor / revoke——从零到可用全程不开前端。
+
+init    交互式录入 access_key/secret_key/base_url，写配置文件（0600），
+        并跑一遍 doctor 验证
+doctor  探链路：health → 换发 token → whoami → 数据覆盖摘要
+revoke  用同 key 再换发一次：互踢规则下同 key 旧会话全部失效
+        （key 本体的删除/停用需在桌面端或 API 管理）
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+from bizonquant_mcp import __version__
+from bizonquant_mcp.gateway import DEFAULT_BASE_URL, BizonQuantError, GatewayClient
+
+CONFIG_PATH = (
+    Path(os.environ.get("BIZONQUANT_CONFIG", ""))
+    or Path.home() / ".config" / "bizonquant-mcp" / "config.json"
+)
+
+
+def _load_or_prompt(access: str | None, secret: str | None, base_url: str | None) -> tuple[str, str, str]:
+    env_access = os.environ.get("BIZONQUANT_ACCESS_KEY")
+    env_secret = os.environ.get("BIZONQUANT_SECRET_KEY")
+    access = access or env_access
+    secret = secret or env_secret
+    base_url = base_url or os.environ.get("BIZONQUANT_BASE_URL") or DEFAULT_BASE_URL
+
+    if not (access and secret) and CONFIG_PATH.exists():
+        cfg = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+        access = access or cfg.get("access_key")
+        secret = secret or cfg.get("secret_key")
+        base_url = base_url or cfg.get("base_url") or DEFAULT_BASE_URL
+
+    if not (access and secret):
+        if not sys.stdin.isatty():
+            raise BizonQuantError("非交互环境且未提供凭证（--access-key/--secret-key 或环境变量）")
+        print("BizonQuant MCP 凭证初始化")
+        print("（access_key/secret_key 在桌面端「API 密钥」页创建，permissions 勾选 mcp.read / mcp.write）")
+        access = access or input("access_key: ").strip()
+        secret = secret or input("secret_key: ").strip()
+        custom = input(f"base_url [{DEFAULT_BASE_URL}]: ").strip()
+        base_url = custom or base_url
+    return access, secret, base_url
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    access, secret, base_url = _load_or_prompt(args.access_key, args.secret_key, args.base_url)
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(
+        json.dumps(
+            {"access_key": access, "secret_key": secret, "base_url": base_url},
+            ensure_ascii=False,
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+    CONFIG_PATH.chmod(stat.S_IRUSR | stat.S_IWUSR)  # 0600：secret 落盘仅本人可读
+    print(f"配置已写入 {CONFIG_PATH}")
+    return cmd_doctor(args)
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    access, secret, base_url = _load_or_prompt(args.access_key, args.secret_key, args.base_url)
+    gw = GatewayClient(access_key=access, secret_key=secret, base_url=base_url)
+    ok = True
+
+    async def _run() -> None:
+        nonlocal ok
+
+        try:
+            resp = await gw._http.get("/health")
+            print(f"1) 网关可达：{base_url} → HTTP {resp.status_code}")
+        except Exception as exc:  # noqa: BLE001 - doctor 要把任何异常转成人话
+            print(f"1) 网关不可达：{exc}")
+            ok = False
+            return
+        try:
+            await gw._fetch_token()
+            print("2) agent-token 换发：成功（scope=agent）")
+        except Exception as exc:  # noqa: BLE001
+            print(f"2) agent-token 换发失败：{exc}")
+            ok = False
+            return
+        try:
+            me = await gw.get("/api/v1/users/me")
+            user = me
+            if isinstance(me, dict):
+                user = me.get("user") or me.get("data", {}).get("user") or me.get("data") or me
+            print(
+                f"3) whoami：{user.get('username', '?')}（tenant={user.get('tenant_id', '?')}）"
+                if isinstance(user, dict)
+                else f"3) whoami：{me}"
+            )
+        except Exception as exc:  # noqa: BLE001
+            print(f"3) whoami 失败：{exc}")
+            ok = False
+        try:
+            cov = await gw.get("/api/v1/selection/multi-factor/metadata")
+            keys = sorted(cov.keys()) if isinstance(cov, dict) else type(cov).__name__
+            print(f"4) 数据面 metadata：{keys}")
+        except Exception as exc:  # noqa: BLE001
+            print(f"4) 数据面不可用：{exc}")
+
+    import asyncio
+
+    asyncio.run(_run())
+    print("doctor: PASS" if ok else "doctor: FAIL")
+    return 0 if ok else 1
+
+
+def cmd_revoke(args: argparse.Namespace) -> int:
+    access, secret, base_url = _load_or_prompt(args.access_key, args.secret_key, args.base_url)
+    gw = GatewayClient(access_key=access, secret_key=secret, base_url=base_url)
+
+    async def _run() -> None:
+        # 同 key 再换发一次 → 互踢规则下该 key 的全部旧会话立即失效
+        await gw._fetch_token()
+        print("已换发新会话：同 key 的旧 agent token 全部 401。")
+        print("如需永久吊销，请在桌面端删除该 API Key。")
+
+    import asyncio
+
+    asyncio.run(_run())
+    return 0
+
+
+def main() -> None:
+    if len(sys.argv) == 1:
+        # 无参数（console script 默认）= 启动 MCP stdio server
+        from bizonquant_mcp.server import main as server_main
+
+        server_main()
+        return
+
+    parser = argparse.ArgumentParser(prog="bizonquant-mcp", description=__doc__)
+    parser.add_argument("--version", action="version", version=f"bizonquant-mcp {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    def _common(p: argparse.ArgumentParser) -> None:
+        p.add_argument("--access-key", help="覆盖配置/环境变量")
+        p.add_argument("--secret-key", help="覆盖配置/环境变量")
+        p.add_argument("--base-url", help="覆盖配置/环境变量")
+
+    p_init = sub.add_parser("init", help="录入凭证写配置文件并自检")
+    _common(p_init)
+    p_init.set_defaults(func=cmd_init)
+
+    p_doc = sub.add_parser("doctor", help="探链路：health/token/whoami/数据面")
+    _common(p_doc)
+    p_doc.set_defaults(func=cmd_doctor)
+
+    p_rev = sub.add_parser("revoke", help="踢掉同 key 全部旧会话")
+    _common(p_rev)
+    p_rev.set_defaults(func=cmd_revoke)
+
+    args = parser.parse_args()
+    try:
+        sys.exit(args.func(args))
+    except BizonQuantError as exc:
+        print(f"错误：{exc}", file=sys.stderr)
+        sys.exit(2)

bizonquant_mcp-0.1.0/src/bizonquant_mcp/common.py

@@ -0,0 +1,38 @@
+"""工具公共件：响应解包与输出裁剪（移植 QuantBot TS 工具语义）。"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+
+def unwrap(data: Any) -> Any:
+    """网关两种响应包装：{code,message,data:{...}} 与顶层平铺——统一取载荷。"""
+    if isinstance(data, dict) and "data" in data and isinstance(data["data"], dict):
+        inner = data["data"]
+        # 防误伤：business payload 里也可能有 data 键（如 klines bars），
+        # 仅当外层像标准包装（有 code/message 或唯一 data 键）时才解包
+        if "code" in data or "message" in data or set(data) == {"data"}:
+            return inner
+    return data
+
+
+def trim_curve(points: list[Any], max_points: int = 120) -> list[Any]:
+    """曲线抽样：≤max_points 原样返回，超过等距抽 max_points 点（保首尾）。"""
+    if len(points) <= max_points:
+        return points
+    step = (len(points) - 1) / (max_points - 1)
+    return [points[round(i * step)] for i in range(max_points)]
+
+
+def sma(values: list[float], window: int) -> float | None:
+    """简单均线；样本不足返回 None。"""
+    if len(values) < window:
+        return None
+    return sum(values[-window:]) / window
+
+
+def safe_round(value: float | None, digits: int = 4) -> float | None:
+    if value is None or (isinstance(value, float) and math.isnan(value)):
+        return None
+    return round(value, digits)