用途
backtrader-mcp 是一个独立的、本地优先的 MCP 服务器，用于构建和运行可复现的 Backtrader 策略。它的目标是把受限的 CSV 文件变成不可变数据集，把类型化的策略意图变成私有草稿，再把经过审核的草稿变成有界的子进程回测，并保留持久化状态和报告。该产品在 P0 阶段刻意保持离线且仅用于回测，不暴露经纪商、存储、凭据、实盘订单、任意 Python 执行或网络传输。
主要能力
- 将受限 CSV 文件注册为不可变数据集，支持规范化列映射、内容寻址存储、去重和流式注册。
- 支持派生表格数据集，仅允许 identity、dropna、returns 或 sma 四种操作，并带类型化参数和精确源清单哈希。
- 提供策略目录搜索，可选择七种原型；支持 single_test 或 python_bundle 两种输出配置。
- 草稿创建、更新、校验均基于修订版本和文件哈希；校验阶段仅解析和编译 AST，不在服务器内导入候选策略。
- 变更审批与运行审批分离，支持签名令牌、幂等键、私有本地数据库审批记录以及日志式重命名事务。
- 提供五种固定运行配置：runonce、runnext、runonce_runnext_compare、fixed_tests、parameter_sweep；其中 parameter_sweep 支持类型化参数网格（最多 64 个组合）并按 return_rate 排名。
- 提供可观测性工具：list_jobs、get_run_logs、list_target_tree；get_run_status 会报告 log_uri、elapsed_seconds 和 eta_bound。
- 提供 get_catalog_snapshot、search_strategy_catalog、list_strategy_templates 等目录与模板工具。
- 作业状态机包括 QUEUED、RUNNING、CANCEL_REQUESTED、CANCELLED、SUCCEEDED、FAILED、TIMED_OUT、ORPHANED；每个状态转换都是比较并交换写入，终态一旦持久化不会被覆盖。
- 服务器自有看门狗会消费工作进程心跳、执行墙钟超时宽限、孤立死亡工作进程并清理分离的候选进程组。
- 作业报告结构化 error_kind，区分用户策略、资源限制、超时、校验、基础设施、取消和孤立等错误。
使用方式
- 要求 Python 3.10 或更高版本，MCP Python SDK 版本需满足 >=2.0.0,<2.1，并使用 MCPServer 和本地 stdio。
- 安装方式：创建并激活专用虚拟环境后安装软件包；从源码检出或依赖被跳过时，运行显式安装器。安装器仅在缺少 Backtrader 时安装；若已安装其他 Backtrader 发行版则保持不变并返回 installed_backtrader_untrusted 警告。
- 运行时根目录必须包含 backtrader/init.py，且 Git origin 解析到 github.com/cloudquant/backtrader；其他 fork 或公共 PyPI 包会在策略运行前被拒绝。
- 主机注册支持 Claude Desktop / Claude Code、Codex、OpenCode、OpenClaw，提供对应示例配置文件或命令。所有适配器启动相同的 stdio 服务器。
- 首次主机验证会执行 MCP initialize，然后发现 tools/list、resources/list、prompts/list，并提交非变更请求；期望 doctor.status=passed、module_file 位于注册运行时下、Backtrader 版本/提交符合预期、catalog entry_count=1155。
- 闭环工作流：inspect_dataset → register_dataset → preview_dataset → derive_tabular_dataset → search_strategy_catalog → create_strategy_draft → update_strategy_draft → validate_strategy_draft → list_target_tree → prepare_strategy_changes → 本地批准 → apply_strategy_changes → prepare_strategy_run → 本地运行批准 → start_strategy_run → 轮询 get_run_status → 可选 cancel_strategy_run → get_run_result。
- 审批必须通过本地 CLI 命令执行，不存在 MCP 审批工具，也没有 approved=true 参数。变更审批与运行审批不能混用。
- 作业启动时并发上限会直接拒绝而非排队；达到 max_concurrent_jobs 时返回可操作建议。
- 保留策略：backtrader-mcp clean --kind jobs|cas|drafts|approvals|nonces --before YYYY-MM-DD 可分别清理已结束作业记录、未被引用的 CAS 对象、未引用草稿、已消费或过期审批以及已消费令牌 nonce。
- 升级到兼容的 0.2.x 版本时，需停止所有连接主机、备份私有状态根、激活专用环境并重新安装；不兼容版本间不得复用草稿校验令牌、变更/运行令牌或审批。
- 卸载：先从各主机移除 backtrader MCP 注册（或删除匹配配置项），停止活动运行，再卸载。卸载 wheel 会保留已配置状态、数据集、生成策略和源文件。
适用场景
适用于需要在本地、离线、仅回测环境下，借助 AI 辅助进行 Backtrader 策略开发、审核和可复现运行的量化研究场景。适合对数据不可变性、审批链路、运行可追溯性和安全性有要求的用户。
限制
- 刻意离线且仅用于回测：没有经纪商、存储、凭据、实盘订单、任意 Python 执行或网络传输。
- 不提供 MCP 审批工具；审批必须在本地通过 CLI 完成。
- 策略运行仅接受已注册的 CloudQuant Backtrader 运行时，其他 fork 或 PyPI 包会被拒绝。
- 数据集派生仅限 identity、dropna、returns、sma 四种操作；参数网格最多 64 个组合。
- 并发达到上限时直接拒绝，不排队。
- 产品不迁移 P0 之前的状态。
- 文档指出 MCP SDK v2.0.0 不提供 Tasks 扩展，因此产品不声称支持该扩展。
更多完整文档（英文/中文）见 https://cloudquant.github.io/backtrader-mcp/ ，也可在 Read the Docs 构建，源文件位于 docs/ 。
