mtg-mcp

mtg-mcp

mtg-mcp 为 LLM 提供基于事实的 Magic: The Gathering 卡牌、套牌、数据提供方和统计证据。LLM 负责制定套牌构筑决策。

版本 0.9.0 是全新设计的 stdio 服务。其 remote 模式下的完整 all 配置公开 97 个工具、一个 mtg://server/capabilities 资源，且不提供提示词。精简的默认配置在 read-only 模式下公开 33 个工具，在 local 或 remote 模式下公开 55 个工具。它不会迁移 0.8.x 的数据或工具架构。

状态

以证据为先的重写已完成。0.9.0 是新服务的首个稳定版本。

功能	工具	默认启用	存储或写入
本地套牌与数据交换	29	是	本地
Scryfall 证据	18	是	本地缓存和卡牌数据
精确统计	8	是	无
Archidekt	23	否	远程
Playgroup	16	否	远程
Commander Spellbook 证据	3	否	仅本地缓存

在加入 Spellbook 之前，打包验收运行安全地调用了 88 个工具。由于没有可用的在线清理路由，两个 Scryfall 卡牌数据下载工具和两个 Playgroup 写入工具使用保存的测试数据。Scryfall 回滚需要 Scryfall 发布另一个数据版本；在此之前，检查会报告正在等待。Commander Spellbook 有单独的有限只读在线检查。 参见在线验收。

启动服务

初始化代码库，然后运行 MCP 冒烟测试：

.\bootstrap.ps1
task smoke:mcp

在 Linux 或 macOS 上：

./bootstrap.sh
task smoke:mcp

初始化会在需要时安装 Mise。Mise 会从 mise.toml 安装 Task 和 PowerShell，并从 global.json 将 .NET SDK 安装到隔离的工具目录中。初始化后，正常运行 task <command>。Taskfile 会为 .NET 调用 Mise；如果新 shell 找不到 Task，请激活 Mise，或临时使用 mise exec -- task <command>。

已提交的 Mise 和 NuGet 锁定文件可确保设置可重复。版本固定项位于 mise.toml、global.json、Directory.Packages.props 和 dotnet-tools.json 中。使用 task deps:check 检查可用更新。只有在准备审查相关固定版本和锁定文件变更时，才使用 task deps:update。

使用 mtg-mcp 作为 MCP 命令。默认调用等同于：

mtg-mcp --mode=local --toolsets=default

使用 --smoke 进行一次性配置检查。它不会启动 MCP 会话。

task install 还会启动并停止一个隔离的只读服务，并启用 Scryfall 工具集。这可以发现 --smoke 无法检测到的打包 SQLite 和 Scryfall 启动问题。

选择模式

模式用于控制权限。

模式	读取	本地写入	远程写入
read-only	是	否	否
local	是	是	否
remote	是	是	是

默认模式为 local。Scryfall 缓存未命中时，可能需要本地写入，以记录响应和速率限制时间。在 read-only 模式下，这种未命中会在任何 HTTP 请求发出前返回 local-write-required。

在这三种模式下都可以读取 Commander Spellbook 数据。这些读取不会更改套牌，也不会向数据源发送写入请求。成功的响应会使用短期本地缓存，避免重复的精确请求产生不必要的数据提供方流量。

选择工具集

工具集决定会话可以看到哪些工具，但不会授予写入权限。

值	结果
default 或省略	启用 decks、scryfall 和 stats
all	启用所有已实现的工具集
none	不公开任何工具
逗号分隔的列表	启用指定的工具集

可用工具集包括 decks、scryfall、stats、archidekt、playgroup 和 spellbook。工具集选择在 MCP 会话期间固定不变。

配置文件	read-only	local	remote
default	33	55	55
all	61	84	97
none	0	0	0

读取 mtg://server/capabilities 可查看当前激活的模式、工具集、工具数量、凭据状态、软件包版本和本地数据状态。此操作不会联系任何提供方。

配置服务

通过命令行、环境变量，或工作目录中的可选 mtg-mcp.json 传递配置。命令行值优先于环境变量值，环境变量值优先于 JSON 值。

设置	命令行	环境变量	JSON 键
操作模式	--mode	MTGMCP__MODE	MODE
工具集	--toolsets	MTGMCP__TOOLSETS	TOOLSETS
数据根目录	--data-dir	MTGMCP__DATA_DIR	DATA_DIR
Scryfall TTL	--scryfall-ttl-hours	MTGMCP__SCRYFALL_TTL_HOURS	SCRYFALL_TTL_HOURS
Commander Spellbook TTL	--spellbook-ttl-minutes	MTGMCP__SPELLBOOK__TTL_MINUTES	SPELLBOOK_TTL_MINUTES

默认数据根目录是平台应用数据目录下的 mtg-mcp/v0.9。所有使用同一根目录的 MCP 进程都会复用 decks.db 和 scryfall.db。读取操作不会创建根目录。

配置 Archidekt

使用 MTGMCP__ARCHIDEKT__USERNAME 和 MTGMCP__ARCHIDEKT__PASSWORD，或创建：

~/.mtg-mcp/archidekt.json

提供方源地址固定不变。身份验证输出绝不会包含凭据、账户身份或凭据路径。

配置 Playgroup

使用 MTGMCP__PLAYGROUP__API_KEY，或创建：

~/.mtg-mcp/playgroup.json

该文件包含一个 apiKey 属性。提供方源地址固定为官方公共 API。

使用本地牌组

decks 工具集支持：

• 对牌组、牌目、区域、类别和提供方绑定进行带修订版本的变更；
• 原子化的有序批处理；
• 受保护的备份、恢复和删除；
• 原生 JSON 和通用文本的导入与导出；
• 用于 Archidekt 和 Moxfield 的手动导入与导出文件；
• 精确的 Scryfall 身份核对；
• 产生可重复结果的标签规则分组；以及
• 基于卡牌数据和调用方提供的地牌规则进行曲线估算。

对现有牌组的每项变更都必须提供 expectedRevision。本地存储不绑定于某一种导入格式。验证会检查结构，而不会判断 Commander 合法性、卡牌质量或策略适配度。

应用前请使用 deck_identity_reconcile_preview。解析时依次使用印刷版本 ID、系列和收藏编号、Oracle ID，然后是精确名称。它绝不会使用模糊匹配或随意选择某个印刷版本。

使用 deck_category_rules_validate、deck_category_rules_preview 和 deck_category_rules_apply 来评估调用方自有的标签规则。规则可以内联提供，也可以使用透明的 common-v1 预设。MCP 不会决定类别的含义。

估算按曲线施放法术的概率

使用 deck_on_curve_estimate 可采样估算一张主牌区卡牌在指定回合前能否施放。请提供已保存的牌组 ID 和当前修订版本、目标牌目 ID、每个符合条件的地牌各一条规则、回合上限，以及可选的种子和采样次数。结果包括所用已安装 Scryfall 数据的确切内容、调用方规则、可重放的种子、95% Wilson 区间、未命中次数，以及最多两条采样轨迹。

版本 1 仅对简单的印刷费用和调用方描述的单面地牌建模。它不会读取卡牌文字、推断地牌行为、模拟其他法术力来源、选择出牌、评价牌组或预测真实对局。

导入和导出牌组

使用 deck_interchange_formats 检查保留限制。

格式	说明
mtg-mcp-json-v1	无损原生格式
generic-text-v1	数量、名称、区域标题和印刷版本提示
archidekt-text-v1	手动导入，并附带原生格式／类别文件
moxfield-bulk-edit-v1	批量编辑文本，并附带原生格式／标签文件

这些服务商导出文件不会联系服务商。排除的条目会保留在原生格式附带文件中，并从服务商文本中省略。

查询 Scryfall

scryfall 工具集支持搜索、精确卡牌查询、卡牌集合查询、印刷版本、裁定、系列、目录、自动补全、批量元数据、标签证据、不可变快照和显式卡牌数据下载操作。

本地卡牌数据存储包含 All Cards、Rulings、Oracle Tags 和 Art Tags。卡牌数据下载需要显式启动，不会在启动时或后台运行。

可选：安装完整的 Scryfall 卡牌数据

完整安装包含卡牌记录、裁定、Oracle 标签和艺术标签，但不包含卡牌图像。它适用于本地标签和卡牌数据工作流；普通卡牌查询无需安装即可通过服务商和小型本地缓存完成。

下载需要数 GB 空间，更新时还需要临时工作空间。仅通过 local 或 remote 模式下的显式完整数据工具启动下载。公开名称 scryfall_corpus_status、scryfall_corpus_sync、scryfall_corpus_rollback 和 scryfall_corpus_delete 是用于检查和管理已安装卡牌数据的现有 API 名称。

新鲜度策略有 default、cache-only 和 refresh。默认 TTL 为 24 小时。不可变快照不会过期。

scryfall_card_collection 接受 150 条有序查询行。它会优先使用本地卡牌数据命中结果，对未命中项去重，并以最多 75 条为一批发送给服务商。结果使用稳定的游标分页。

对于任意查询，Scryfall 仍是事实来源。缓存仅会复用完全相同的请求。卡牌事实和社区标签属于不同类型的信息。

查看 Commander Spellbook 证据

启用 spellbook 工具集，即可使用三个返回 Commander Spellbook 数据的工具：

• spellbook_variant_search 针对精确的 Commander Spellbook 查询返回一页有界结果。
• spellbook_variant_get 按 ID 返回一个精确的源变体。
• spellbook_deck_combos_find 仅发送一个精确已保存牌组版本中的 commander 和 main 条目，然后报告跳过的条目。

这些工具会保留 Commander Spellbook JSON，并注明来源、请求、检索时间、缓存状态、校验和及限制。它们不会对结果排序、推断卡牌角色，也不会推荐连招或卡牌更改。缓存默认持续 15 分钟；可将其配置为 1 至 1,440 之间的整数分钟数。

计算精确统计数据

stats 工具集提供八个只读工具，用于：

• 单变量和多变量超几何概率；
• 按回合划分的概率表；
• 调用方定义的法术力来源可用性；
• 套件和连招组装；
• 显式调度的调度；
• 最少副本数和最少来源数求解；以及
• 确定性的牌组构成摘要。

每项概率都会返回精确的最简分数和稳定的小数。调用方提供总体、分组、抽牌回合、法术力能力和留牌规则。MCP 不会推断合法性、角色，也不会判断结果是否理想。

基于牌组的统计可按条目 ID、区域名称或类别 ID 选择条目。这样，LLM 就能使用现有的 Archidekt 分组或确定性类别，同时明确显示所选卡牌。

同步 Archidekt

启用 archidekt 工具集。进行远程写入时使用 remote 模式。

该适配器支持列出、获取、创建和删除自有套牌，以及拉取、推送、差异比较、文件夹和命名快照。应用操作需要当前版本、指纹和预览证据。MCP 不会选择冲突解决方案。

针对每个已配置账户，请求的启动间隔至少为 2 秒。该适配器每 60 秒最多允许启动 30 次，每次工具调用最多允许发出 150 个请求。遇到 403 和 429 时会停止。对于结果不明确的变更，不会重试。

Archidekt 可能会重新排列类别位置。因此，内容相等性比较的是类别标识、成员关系、标志和主类别分配，而非由服务提供方控制的数值排名。

阅读 Playgroup 证据

启用 playgroup 工具集。它提供适用于固定版本 Public API 1.0.0 的工具。所有模式都包含 14 个安全的只读工具。remote 模式会额外提供两个写入工具。

结果保留服务提供方的 JSON，并包含操作、API 版本、获取时间、校验和及限制。该适配器不会对套牌排名，也不会推断质量。

请求启动间隔至少为 250 毫秒。读取操作会进行有限次数的重试。写入操作只尝试一次。实时验收不会调用写入操作，因为公共 API 没有提供清理操作。

证据与安全

服务器会分别标记以下结果类型：

• 服务提供方事实；
• 服务提供方证据；
• 精确推导；
• 解析器分类；
• 启发式结果；以及
• 抽样估算。

稳定版 0.9.0 不包含顾问提示词、意图推断、弱牌判断、替换建议、综合质量评分或策略模拟。延期工作列于潜在功能。

开发与验证

使用 Task 作为命令菜单：

task --list
task lint
task test
task benchmark:oncurve
task surface:report
task coverage
task pack
task smoke:process
task smoke:mcp
task release:tool-smoke

常规测试具有确定性且无需联网。实时测试需要明确启用。 task benchmark:oncurve 会运行单独的固定 99 张牌 Release 测量。 每个生产程序集的行覆盖率都必须至少达到 90%。

架构

项目	负责内容
MtgMcp.Core	与服务提供方无关的契约和证据
MtgMcp.Decks	本地 SQLite 套牌和数据交换
MtgMcp.Scryfall	官方传输、卡牌数据、快照和请求限速
MtgMcp.Archidekt	观测到的服务提供方契约和同步
MtgMcp.Playgroup	固定版本的官方 API 证据
MtgMcp.Spellbook	范围受限的 Commander Spellbook 来源证据和缓存
MtgMcp.Statistics	仅使用 BCL 的精确计算
MtgMcp.OnCurve	纯函数、可重复的抽样施放回合计算
MtgMcp.App	MCP 主机、配置、组合和架构

如需了解需长期遵守的约束，请阅读 North Star、Design Goals 和重写指南。

许可证

根据 GNU Affero General Public License v3.0 or later 授权。