cloudQuant/backtrader-mcp

**English** | **中文**
Backtrader MCP is an independent, local-first MCP server for building and
running reproducible Backtrader strategies. It turns confined CSV files into
immutable datasets, typed strategy intent into private drafts, and reviewed
drafts into bounded subprocess runs with durable status and reports.
P0 is deliberately offline and backtest-only. It does not expose brokers,
stores, credentials, live orders, arbitrary Python execution, or network
transports.
Full documentation (English / 中文):
(also buildable on Read the
Docs; sources under docs/).
Distribution contract
- Python 3.10 or newer.
- MCP Python SDK >=2.0.0, （亦可在 Read the Docs 构建；
源文件位于 docs/）。
分发契约
- Python 3.10 及以上。
- MCP Python SDK >=2.0.0,<2.1（以 2.0.0 验证），使用 MCPServer 与本地
stdio。
- 独立的 wheel / 源码分发；唯一可接受的 Backtrader 运行时是
cloudQuant/backtrader，包元数据固定到
commit 3c967ed61be184c0099ba5bef55d4bed09ad0b4a。
- SQLite/WAL 状态、内容寻址的 CSV 数据、私有草稿文件、HMAC 能力令牌、文件系统
锁、幂等性记录以及启动恢复。
- 产品自有的 prepare_strategy_run、start_strategy_run、
get_run_status、cancel_strategy_run 和 get_run_result 工具。MCP SDK
v2.0.0 不提供 Tasks 扩展，因此本产品也不声称支持。
- 可观测性工具：list_jobs（按状态过滤的作业枚举）、get_run_logs（有界、
绝对路径脱敏的作业日志尾部）与 list_target_tree（只读目标树原像，用于
精确变更评审）；get_run_status 返回 log_uri、elapsed_seconds 和
eta_bound。
- 全部 30 个工具都带有 readOnlyHint/destructiveHint/idempotentHint/
openWorldHint 注解。工具错误以结构化 [code] 消息 文本跨越 MCP 边界，可选
附带 Suggestion: 下一步建议；错误文本与作业日志中的绝对文件系统路径会被脱敏。
wheel 在 backtrader_mcp/schemas/ 下包含七个 JSON Schema 契约，在
backtrader_mcp/policies/ 下包含确定性比较策略。它还内置自己的不可变完整元数据
快照：1,155 条唯一记录，覆盖 1,152 个功能测试、1,035 个三文件策略包和 1,032 个
已验证映射。当前 fork 的十四条模板条目（七个 archetype × 两种输出 profile）与
这些语料记录分开存放。
不改动基础环境的安装
在本目录下创建并激活一个专用虚拟环境，然后安装本包。python 可以是任意受支持的
Python 3.10+ 解释器：
包依赖会安装该固定的 CloudQuant 源码。若从源码检出运行或此前跳过了依赖安装，可改用
显式安装入口：
它只会在 Backtrader 缺失时安装；若已存在其他 Backtrader 发行版，会保持原环境不变并
返回机器可读的 installed_backtrader_untrusted 警告。
只在宿主环境中注册绝对、可信的 root：
Root 映射是 JSON 对象。MCP 调用方只能拿到 root ID 和相对路径，不能提交绝对路径或
可执行路径。运行时 root 必须包含 backtrader/__init__.py，且 Git origin 必须解析为
github.com/cloudquant/backtrader；其他 fork 或公开 PyPI 包会在启动策略前被拒绝。若未
设置 BACKTRADER_MCP_RUNTIMES，已验证的已安装 CloudQuant 分发会自动注册为
default。
新增宿主之前，先在安装 shell 中导出同样的值并运行只读诊断。给 JSON 值加引号可以
避免被 shell 解释：
doctor.status 必须为 passed。报告是稳定的 JSON，包含已安装产品及依赖版本、已安装
Backtrader 的溯源、已配置的 root 检查、支持的 adapter / run profile，以及实际的
Backtrader module_file、版本、Git commit、分支、溯源和运行时能力。已有的非
CloudQuant 已安装包会显示 warning；已配置的非 CloudQuant 运行时则是 error。CLI 诊断
本身不会创建 state root，也不会写入 source / target root；正常 MCP 服务器启动时才会
在工具可用之前初始化自己的私有 state root。
Catalog 模式
get_catalog_snapshot 默认只返回精简 header：计数、哈希、溯源以及
extensions.entry_count，不含 1,155 条记录列表。设置 include_entries=true 可
以用 limit（1-100）与 offset 分页获取条目；响应会报告
pagination.total/has_more/truncated。全部记录的
source_available=false：搜索和溯源可用，但 inspect_strategy 不会假装原始源
码字节随包分发。list_strategy_templates（工具与资源两种形态）独立返回当前
fork 的全部 14 条 archetype / profile 模板。search_strategy_catalog 返回
total/has_more/offset 分页元数据以及可操作的空结果建议。
若要显式重建带源码的快照，把 functional 和 package 两个语料以两个只读 ID 注册到
BACKTRADER_MCP_SOURCE_ROOTS，然后调用：
服务器只扫描元数据和哈希，绝不导入、执行或修改任何语料文件。结果会报告最新的
functional_tests/strategy_packages/mapped 计数、内容哈希，以及与已验证的
1,152/1,035/1,032 基线不一致时的诊断信息。带源码的记录使用
source_available=true，后续 inspect_strategy 可检测 functional 或 package 字节
是否变化。只提供 source_root_id 时，则保留针对已注册策略 target root 的更小
AST-only 刷新。
宿主配置
请替换对应文件中每一个 /ABSOLUTE/PATH 占位符。
Claude Desktop / Claude Code
把 examples/hosts/claude-desktop.json 复制进宿主的 MCP 配置，或替换全部占位符后
运行下面这条完整的 Claude Code 命令：
编辑 Claude Desktop 的 JSON 后需重启。Claude Code 可用 claude mcp list 及其交互
式 /mcp 视图验证项目级服务器。
Codex
把 examples/hosts/codex-config.toml 合并到 ~/.codex/config.toml 或可信项目的
.codex/config.toml，然后重启 Codex 客户端。Codex App、Codex CLI 和 Codex IDE
扩展共用这份配置。Codex 自身的 approval_policy 管理宿主，但不替代本产品的任一
可信本地审批记录。
等价的 CLI 注册命令：
OpenCode
把 examples/hosts/opencode.json 合并到全局或项目级 OpenCode 配置。当前配置把每个
具名的本地服务器直接放在 mcp 下；command 是参数向量，enabled 为 true。运行