Commander Workshop MCP

Commander Workshop 是一个本地优先的 MCP 服务器，用于构建、检查、比较和完成万智牌：指挥官套牌。它结合了固定的规则和卡牌数据与您明确导入的收藏，将套牌意图与所有权分离，并将完整的计划转化为抽取、交换、替代、代牌或购买。

该服务器适用于无约束的构筑、以库存优先的构组、Bracket 3 规划以及固定预算的预组升级。它评估有边界的完整候选方案，并给出在此约束下的最佳发现，而非声称拥有通用的力量分数或数学上完美的套牌。

功能

Related MCP server: MTG-MCP

隐私承诺

默认情况下，您的收藏、活页夹名称、位置和物理套牌分配保持本地。本地导入仅限于配置的根目录。服务器不会推送套牌、修改收藏、预留卡牌、将市场物品添加到购物车或完成购买。可选的市场价格查询仅发送最低限度的印刷要求，并从环境或 MCP 主机密钥存储中读取凭据。

安装

Commander Workshop 需要 Python 3.11 或更新版本。从仓库签出后：

python -m venv .venv
. .venv/bin/activate
python -m pip install -e .

V1 目前仅支持 POSIX 文件系统。其不可变的发布路径需要目录文件描述符、O_DIRECTORY、O_NOFOLLOW、硬链接、fsync 和咨询锁；不支持 Windows。stdio 服务器还期望准备好接下来要验证的本地输入。

目录和规则设置

V1 在服务器启动时故意不发出网络请求。通过 Scryfall 文档化的批量数据 API 下载 Scryfall Default Cards JSONL gzip，准备 docs/rules-bundle.md 中指定的五文件规则包，然后运行经过测试的离线引导命令：

.venv/bin/commander-workshop-bootstrap \
  --data-dir /absolute/path/to/commander-workshop-data \
  --catalog-jsonl-gz /absolute/path/to/default-cards.jsonl.gz \
  --catalog-url https://data.scryfall.io/default-cards.jsonl.gz \
  --catalog-retrieved-at 2026-08-15T12:00:00+00:00 \
  --rules-bundle /absolute/path/to/rules-bundle

使用实际的下载 URL 和检索时间。--data-dir 是一个安全的安装根目录；它可能已经包含无关文件，引导程序不会删除或覆盖这些文件。该命令验证 gzip 和规则，在 environments/<sha256> 下构建一个内容寻址的环境，并且仅在完整表示持久化后发布原子性的 READY 标记。重试会恢复精确的不完整环境并返回相同版本。已发布的目录和规则文件是独占的字节副本，没有保留的阶段别名。符号链接的输入、硬链接别名、意外的侧载文件和冲突的现有内容会安全失败。

在构建之前，引导程序通过其版本化输入标识发现一个完全验证的 READY 环境，因此正常的相同输入重试不会创建新阶段。失败的阶段是惰性的，可能会保留以供手动检查；引导程序永远不会递归删除它无法证明属于它的阶段内容。

打印的数据目录仍然是可变的安装根目录，MCP 记录在 records/ 下写入。打印的目录和规则路径指向经过验证的就绪版本。请同时使用这三个值；没有有效 READY 标记的目录是不完整的引导状态，并且永远不会被返回。

引导后，将 COMMANDER_WORKSHOP_IMPORT_ROOTS 设置为一个或多个现有的绝对目录，并对其他变量使用打印的值。缺失、过期或无效的关键源会安全失败。有关数据流，请参阅架构指南。

Claude、Codex 和通用 stdio 配置

对于 Claude Desktop 或使用通用 JSON 形状的其他主机，复制 examples/mcp-config.json 并替换其中的绝对占位路径。

Codex 可以从 config.toml 使用相同的可执行文件：

[mcp_servers.commander_workshop]
command = "/absolute/path/to/commander-workshop-mcp/.venv/bin/commander-workshop-mcp"
args = []

[mcp_servers.commander_workshop.env]
COMMANDER_WORKSHOP_DATA_DIR = "/absolute/install-root"
COMMANDER_WORKSHOP_CATALOG_CURRENT = "/absolute/install-root/environments/<printed-sha256>/catalog/current.json"
COMMANDER_WORKSHOP_RULESET = "/absolute/install-root/environments/<printed-sha256>/rules/current.json"
COMMANDER_WORKSHOP_IMPORT_ROOTS = "/absolute/path/to/imports"

任何 MCP v2 客户端都可以使用这些环境变量将绝对虚拟环境可执行文件作为本地 stdio 子进程启动。V1 中没有 HTTP 服务或账户设置。pipx 安装也可行：使用 pipx environment --value PIPX_BIN_DIR 返回的绝对路径，加上 commander-workshop-mcp。

端到端示例：无约束构筑

1. 使用 search_cards 检查固定的目录，并使用 load_deck 检查构筑过程中产生的每个完整候选套牌。

2. 调用 plan_deck，操作为 build，卡池为 all_legal，设置所需的 bracket/theme/proxy 维度，并提交一至八个完整候选方案。读取返回的 commander://plans/... 资源。

3. （可选）加载收藏，为获胜计划调用 resolve_availability，然后调用 create_fulfillment_plan。可用性仍然是假设性的；完成操作仅在该不可变结果内分配一个副本。

在构筑过程中，此流程不受库存约束，但仍然可以在用户决定行动之前显示手头有什么以及缺少什么。完整的 plan_deck 请求模板 已通过验收套件的模式验证。

端到端示例：仅拥有的构筑

1. 将物理收藏导出为 ManaBox CSV 或带有显式列映射的 CSV，然后在严格模式下调用 load_collection_snapshot。

2. 使用 search_library 按名称、印刷、活页夹或已组套牌分配查找候选卡牌。

3. 调用 plan_deck，卡池为 owned_only，并设置收藏快照 ID。包含未拥有的非基本卡牌的候选方案会违反硬约束。

4. 读取计划和可用性资源，查看活页夹抽取和冲突。已分配给套牌的副本会被报告，而不会默认视为空闲。

使用完整的 仅拥有请求模板，将其中的套牌和收藏 ID 替换为先前工具的结果。

端到端示例：Bracket 3 USD/EUR 50 预组升级

1. 导出或粘贴预组套牌并调用 load_deck；它仍然是套牌意图，而非所有权声明。

2. 加载完整的升级候选方案，并调用 plan_deck，操作为 upgrade，预组套牌作为 starting_deck_id，Bracket 3，以及 precon-upgrade-50-usd 或 precon-upgrade-50-eur 场景预设语义。

3. 检查精确的添加/删除、带日期的 bracket 证据、Game Changers、主题事实以及有保证的本币获取上限。缺少必需的价格证据无法以零通过上限。

4. （可选）解决库存问题，使用 create_fulfillment_plan 选择抽取/交换/替代/代牌，然后为剩余的购买行调用 price_purchases。定价仅供参考，且永远不会下订单。

USD 50 请求模板 包含完整的场景、候选证据、分数定义、bracket 策略和起始套牌字段。对于 EUR 预设，请更改货币和总预算策略。

支持的导入

• ManaBox 收藏 CSV，将物理活页夹和已注册套牌与愿望清单或其他非拥有列表分开。

• 通用收藏 CSV，带有数量和精确卡牌身份的显式映射，以及可选的印刷和位置字段。

• 竞技场风格和常见的数量/名称/系列/编号套牌文本。

• 用户从 Moxfield、Archidekt、Deckbox、Deckstats、TopDecked 及类似主机导出的套牌文本，前提是符合支持的文本格式。

粘贴或选择您有权使用的导出。V1 不会抓取账户页面、重用浏览器 cookie 或调用未文档化的套牌主机端点。直接托管 URL 返回 unsupported_source；请导出套牌并导入其文本。

工具

公开的界面正好是十一个工具：

每个工具都返回一个版本化的信封，包含稳定的结果 ID、状态、简明摘要、问题、来源标记，并且通常还有一个资源 URI。

资源

commander://cards/{oracle_id}
commander://searches/{result_id}
commander://collections/{snapshot_id}
commander://decks/{deck_id}
commander://plans/{plan_id}
commander://availability/{resolution_id}
commander://prices/{snapshot_id}
commander://fulfillment/{plan_id}
commander://rules/current
commander://presets

记录是不可变的，且是内容寻址的。收藏和广泛搜索是有界且分页的；工具摘要避免重复收藏内容。

场景维度

规划场景由以下独立选择组成：

• 操作：构建、升级或分析；

• bracket：1 到 5，带有带日期的回合和 Game Changer 证据；

• 卡池：all_legal、prefer_owned 或 owned_only；

• 预算：本币总额和可选的单卡上限，包括 USD/EUR 50 预组升级预设；

• 代牌政策：无、拥有一张或无限制（如果游戏组允许）；

• 主题政策：严格契约、灵活偏好或强度导向；

• 受保护的已组套牌、固定的规则集和确定性种子。

套牌适配度和战略强度不会合并为一个分数。官方指挥官规则仍然具有权威性，且规则零的覆盖必须明确声明。

定价语义

price_purchases 将商品小计、供应商小计、运费和预估到岸总价分开。未知商品或运费保持 null，绝不设为 0。只有在所选策略下，每个必需购买都有符合条件的已知证据时，才能通过有保障的预算。

Scryfall 目录价格是指示性的 PriceEstimate 观察数据，而非结账报价。CardTrader 列表是只读的 PurchaseQuote 观察数据。规划估算使用声明的时效窗口，最长不超过 24 小时；CardTrader 可能使用更短的列表有效期。部分过时的观察数据会明确标注 unknown_price、认证问题、中断或速率限制问题。

供应商限制

• Scryfall 估算来自已验证的本地目录，可能缺少货币、版本、品相、语言、数量或运费信息，且不可购买。

• CardTrader 为可选，需要 CARDTRADER_API_TOKEN，仅使用固定的文档化 GET 端点，不跟踪重定向，也不优化多卖家购物篮。

• Cardmarket 和 TCGplayer 默认未启用；任何未来适配器必须尊重访问限制和供应商条款。

• 任何供应商都不能更改套牌合法性、收藏所有权、代牌政策或预留库存。任何供应商都不提供购物车或购买操作。

正常测试和持续集成不发出实时市场或套牌托管请求。

开发

python -m pip install -e '.[test]'
python scripts/check_public_tree.py
ruff check src tests scripts
pytest -q
python -m build

隐私扫描器会检查追踪树中的私有路径、凭据、数据库、不安全的数据导出、符号链接以及未记录/过大的夹具。所有测试数据均为合成且确定性的。

架构

参见 docs/architecture.md 了解组件边界、不可变存储、信任边界、规划/执行流程以及扩展点。

安全报告

遵循 SECURITY.md。使用私有安全通告和最小合成复现；切勿附带收藏导出、卡册库存、令牌或其他个人数据。

致谢

卡牌名称、规则文本和目录元数据可能源自 Scryfall，其数据和致谢要求适用。万智牌规则和指挥官套牌分级政策由 威世智 发布。供应商名称和市场数据归其各自所有者所有。

非关联声明

Commander Workshop MCP 是非官方的粉丝软件。它与威世智、Scryfall、CardTrader 或任何其他套牌托管商或市场无关联，也未获得其认可、赞助或批准。万智牌、指挥官及相关商标归威世智及其各自所有者所有。

Commander Workshop MCP 是根据粉丝内容政策允许的非官方粉丝内容。未经威世智批准/认可。所使用的材料部分归威世智所有。©威世智有限责任公司。

许可证

本软件根据 MIT 许可证 发布。第三方卡牌、规则和市场数据仍受其自身条款和许可证约束。