MTG指挥官甲板分析仪-MCP

🎉 当前状态： v0.4.0-GPT-4.1 LLM甲板构建器，SQLite数据库，EDHREC集成，自定义banlist

开源TypeScript库和MCP服务器，用于分析和构建Magic:The Gathering Commander（EDH）平台。

🎯 项目目标

提供自动化工具以：

分析现有甲板：格式验证、卡片分类、括号分析、黑名单验证
从头开始建造甲板：基于指挥官的生成，具有EDHREC自动填充功能（无预算限制）
建议优化：基于EDHREC数据和第3级规则的建议
强制执行自定义禁止列表：使用 data/Banlist.txt 阻止被禁止的牌进入牌组

🏗️ 建筑

mtg-commander-analyzer-mcp/
├── src/
│   ├── core/                    # Business logic
│   │   ├── deckParser.ts        # Decklist parser
│   │   ├── analyzer.ts          # Advanced deck analysis
│   │   ├── deckBuilder.ts       # Deck builder
│   │   ├── scryfall.ts          # Scryfall integration (auto-uses DB or JSON)
│   │   ├── cardDatabase.ts      # SQLite database queries
│   │   ├── banlist.ts           # Custom banlist enforcement
│   │   ├── edhrec.ts            # EDHREC integration
│   │   ├── roles.ts             # Role classification
│   │   ├── templates.ts         # Deck templates
│   │   ├── brackets.ts          # Bracket rules
│   │   ├── bracketCards.ts      # Card lists by bracket
│   │   ├── categoryUtils.ts     # Category utilities
│   │   ├── types.ts             # TypeScript interfaces
│   │   └── schemas.ts           # Zod schemas for MCP
│   ├── scripts/                 # Database management scripts
│   │   ├── createDatabase.ts    # Create SQLite schema
│   │   └── importCards.ts       # Stream-import from JSON
│   ├── mcp/                     # MCP server implementation
│   │   ├── server.ts            # MCP server (stdio transport)
│   │   ├── analyzeDeckTool.ts   # analyze_deck tool
│   │   ├── buildDeckFromCommanderTool.ts  # build_deck_from_commander
│   │   └── buildDeckWithLLMTool.ts        # build_deck_with_llm
│   ├── testLocal.ts             # Analysis testing
│   ├── testBuildLocal.ts        # Build testing
│   └── testEndToEnd.ts          # End-to-end testing
├── data/                        # Card data, rules, templates
│   ├── cards.db                 # SQLite database (primary card source)
│   ├── rulings.json             # Card rulings from Scryfall (by oracle_id)
│   ├── MagicCompRules.txt       # Official MTG Comprehensive Rules
│   ├── Banlist.txt              # Custom banlist (one card per line)
│   ├── deck-template-*.json     # Deck templates (Bracket 3)
│   ├── bracket-rules.json       # Bracket rules
│   ├── bracket3-*.json          # Bracket 3 card lists
│   └── edhrec_structures/       # EDHREC JSON data
└── package.json

🚀 快速安装

📖 详细指南：参见安装.md 获取完整的说明和故障排除。

1.克隆和安装依赖项

# Clone the repository
git clone https://github.com/kscius/mtg-commander-analyzer-mcp.git
cd mtg-commander-analyzer-mcp

# Install dependencies
npm install

2.设置卡数据库（必填）

该项目使用SQLite高效地查询卡片数据。这支持任何大小的文件，包括完整的Scryfall“All Cards”数据库（2GB以上）。

选项A-使用预先存在的oracle-cards.json：

如果你已经有了 data/oracle-cards.json:

# Create the database schema
npm run db:create

# Import cards (supports streaming, handles 2GB+ files)
npm run db:import

导入脚本：

✅ 使用流式JSON解析（从不在内存中加载完整文件）
✅ 每秒处理约2800张卡
✅ 创建索引以实现快速查找
✅ 全文搜索支持

选项B-下载新的Scryfall数据：

# Linux/macOS
chmod +x setup.sh
./setup.sh

# Windows PowerShell
.\setup.ps1

然后运行数据库安装程序：

npm run db:create
npm run db:import

选项C-手动下载：

访问 Scryfall批量数据
下载“Oracle卡”（唯一卡）或“所有卡”（所有打印）
另存为 data/oracle-cards.json
跑 npm run db:create && npm run db:import

数据库命令：

命令	描述
`npm run db:create`	使用模式创建空SQLite数据库
`npm run db:import`	从以下位置导入卡片 `data/oracle-cards.json`
`npm run db:import /path/to/file.json`	从自定义路径导入

2.5自定义禁止列表（可选）

编辑 data/Banlist.txt 自定义哪些卡被禁止。每行一个卡名：

Mana Crypt
Dockside Extortionist
Black Lotus
Jeweled Lotus

特征：

✅ 被禁止的卡片会自动从牌组构建自动填充中排除
✅ 被禁止的种子卡会被过滤并发出警告
✅ 甲板分析显示违反禁令
✅ 没有预算限制（只有禁令控制卡的合法性）
✅ 不区分大小写的匹配
✅ 支持数量前缀（例如“1马纳密码”）

默认的banlist包括74张卡片，通常被认为对随意的指挥官游戏有问题。

2.6 LLM/AI代理的参考文件

当将此MCP与AI代理（Cursor、Claude Desktop等）一起使用时，代理应始终参考这些资源以进行准确的甲板构建：

资源	目的
`data/cards.db`	包含所有卡数据的SQLite数据库（使用MCP工具查询）
`data/rulings.json`	Scryfall的特定卡规则（由索引 `oracle_id`)
`data/MagicCompRules.txt`	官方魔术：收集综合规则
`data/Banlist.txt`	自定义禁用卡列表

⚠️ 重要提示：甲板验证规则

AI代理必须始终验证：

正好100张卡 （99+1指挥官）
指挥官彩色身份证内的所有卡片
没有禁用卡 （从 data/Banlist.txt)
辛格尔顿规则 （每张卡仅1份，基本土地除外）
指挥官合法性 （指挥官必须是传说中的生物，或者“可以成为你的指挥官”）

用于卡片查找，代理人应：

使用MCP analyze_deck 或 build_deck_from_commander 工具（他们查询 cards.db 自动）
SQLite数据库包含所有支持全文搜索的Scryfall卡数据

用于复杂的卡交互，代理人应：

检查 data/rulings.json 针对特定卡片的官方裁决
参考 data/MagicCompRules.txt 对于规则问题（例如，层次、优先级、替换效果）

3.构建（可选）

npm run build

4.单元测试（Vitest）

npm test
npm run test:watch   # watch mode during development

拉取请求并推送至 main / master 跑 npm ci, npm run build，以及 npm test 在Node 18和20上通过GitHub操作（参见 .github/workflows/ci.yml).

📖 用法

MCP服务器（推荐）

MCP服务器为兼容的客户端（Cursor、Claude Desktop等）提供了三个工具： analyze_deck, build_deck_from_commander，以及 build_deck_with_llm （要求 OPENAI_API_KEY).

启动服务器：

npm run mcp

服务器通过stdio（stdin/stdout）监听MCP消息，并保持活动状态等待请求。

可用的MCP工具

1. `analyze_deck`

使用支架3验证分析现有的指挥官甲板清单。

输入：

{
  "deckText": "1 Sol Ring\n1 Arcane Signet\n1 Rhystic Study\n37 Island\n...",
  "templateId": "bracket3",
  "bracketId": "bracket3"
}

输出：

{
  "input": { "deckText": "...", "templateId": "bracket3" },
  "analysis": {
    "commanderName": "Atraxa, Praetors' Voice",
    "totalCards": 99,
    "uniqueCards": 99,
    "categories": [
      { "name": "lands", "count": 37, "min": 35, "max": 38, "status": "within" },
      { "name": "ramp", "count": 9, "min": 8, "max": 10, "status": "within" },
      { "name": "card_draw", "count": 8, "min": 8, "max": 10, "status": "within" },
      { "name": "target_removal", "count": 6, "min": 6, "max": 8, "status": "within" },
      { "name": "board_wipes", "count": 3, "min": 3, "max": 4, "status": "within" }
    ],
    "bracketWarnings": [
      "This deck uses 2 Game Changers (max allowed for Bracket bracket3: 3)."
    ],
    "notes": ["..."]
  },
  "bracketId": "bracket3",
  "bracketLabel": "Bracket 3 (Upgraded)"
}

特征：

✅ 指挥官格式验证（99+1指挥官）
✅ 自动分类（土地、斜坡、绘制、移除、擦拭）
✅ 使用Scryfall oracle文本进行角色检测
✅ 支架3验证（游戏改变者、大规模土地拒绝、额外回合）
✅ 基于类别的建议

2. `build_deck_from_commander`

使用可选的EDHREC自动填充功能，从指挥官姓名构建指挥官甲板。

输入：

{
  "commanderName": "Atraxa, Praetors' Voice",
  "templateId": "bracket3",
  "bracketId": "bracket3",
  "seedCards": ["Sol Ring", "Arcane Signet"],
  "useEdhrec": true,
  "useEdhrecAutofill": true
}

输出：

{
  "input": { "commanderName": "Atraxa, Praetors' Voice", ... },
  "deck": {
    "commanderName": "Atraxa, Praetors' Voice",
    "cards": [
      { "name": "Sol Ring", "quantity": 1, "roles": ["ramp"] },
      { "name": "Island", "quantity": 9, "roles": ["land"] },
      { "name": "Talisman of Dominance", "quantity": 1, "roles": ["ramp"] },
      ...
    ]
  },
  "analysis": {
    "totalCards": 99,
    "categories": [ ... ],
    "bracketWarnings": [ ... ]
  },
  "edhrecContext": {
    "sourcesUsed": ["top/multicolor.json", "lands/mono-blue.json", ...],
    "suggestions": [
      { "name": "Assassin's Trophy", "rank": 467886, "category": "top/multicolor" },
      ...
    ]
  },
  "notes": [
    "Commander: Atraxa, Praetors' Voice (Color Identity: BGUW)",
    "✓ EDHREC: Fetched 50 top cards and 50 lands (100 total suggestions).",
    "EDHREC Autofill enabled. Attempting to fill category deficits...",
    "✓ EDHREC Autofill complete: added 16 cards (6 ramp, 4 draw, 5 removal, 1 wipes)",
    ...
  ]
}

特征：

✅ 来自Scryfall的自动指挥官分辨率
✅ 基于颜色识别的土地基准生成
✅ EDHREC集成（顶部卡片+按颜色排列的土地）
✅ 智能自动填充赤字类别
✅ 支架3约束执行
✅ 颜色身份验证
✅ 所有卡片的角色分类

3. `build_deck_with_llm` ⭐ 新

完全自主的 甲板建造商使用GPT-4.1。无需人工干预即可构建完整的99张牌组。

⚠️ 需要OpenAI API密钥。 看 LLM配置在......下面

输入：

{
  "commanderName": "Atraxa, Praetors' Voice",
  "seedCards": ["Doubling Season", "Deepglow Skate"]
}

输出：

{
  "deck": {
    "commanderName": "Atraxa, Praetors' Voice",
    "cards": [
      { "name": "Sol Ring", "quantity": 1, "roles": ["ramp"] },
      { "name": "Breeding Pool", "quantity": 1, "roles": ["land"] },
      ... // EXACTLY 99 cards
    ]
  },
  "analysis": {
    "totalCards": 99,
    "banlistValid": true,
    "categories": [ ... ]
  },
  "notes": [
    "[LLM] Using gpt-4.1 for deck building",
    "Commander: Atraxa, Praetors' Voice (Color Identity: BGUW)",
    "✓ EDHREC: Fetched 100 card suggestions",
    "✓ LLM response received (2847 in, 1923 out)",
    "Strategy: Superfriends/Planeswalker deck focusing on proliferate..."
  ]
}

特征：

✅ 完成99张牌组 （不是骷髅）
✅ 基于指挥官协同的人工智能选卡
✅ 使用EDHREC数据做出明智的选择
✅ 尊重自定义禁止列表
✅ 验证颜色标识和单例规则
✅ 支架3功率等级
✅ 成本：每层约0.002-0.01美元

本地测试

甲板分析：

npm run test:local

甲板建筑：

npm run test:build

这两个脚本都在控制台中显示详细的结果。

🤖 LLM配置（OpenAI）

要使用 build_deck_with_llm 工具，您需要配置一个OpenAI API密钥。

1.获取API密钥

首选 OpenAI平台
创建新的API密钥
复制密钥（以开头 sk-)

2.配置密钥

复制示例环境文件并添加密钥：

cp .env.example .env

编辑 .env:

# Required
OPENAI_API_KEY=sk-your-actual-api-key-here

# Optional (defaults shown)
OPENAI_MODEL=gpt-4.1
OPENAI_TEMPERATURE=0.7
OPENAI_MAX_TOKENS=4096
# OPENAI_BASE_URL=https://api.openai.com/v1

3.可用型号

型号	速度	成本	建议
`gpt-4.1`	快速	~0.005美元/甲板	⭐ 默认 -最佳平衡
`gpt-4o`	快速	~0.01美元/套	更有创意
`gpt-4o-mini`	最快	~0.00/甲板	最经济
`o3-mini`	缓慢	~0.02美元/台	深入推理

4.验证配置

npm run build
npm run mcp

如果配置正确 build_deck_with_llm 工具将可用。

🔧 MCP客户端配置

光标

将此添加到Cursor中的MCP配置中：

{
  "mcpServers": {
    "mtg-commander-analyzer": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/path/to/mtg-commander-analyzer-mcp"
    }
  }
}

克劳德桌面版

在 claude_desktop_config.json:

{
  "mcpServers": {
    "mtg-commander-analyzer": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/path/to/mtg-commander-analyzer-mcp"
    }
  }
}

🛠️ 当前功能（v0.4.0）

✅ 实现

核心：

✅ Decklist解析器格式
✅ SQLite数据库 用于高效的卡查找（支持2GB以上的数据集）
✅ 流式JSON导入 -从不在内存中加载完整文件
✅ 如果数据库不可用，则自动回退到JSON文件
✅ 按类型和oracle文本（斜坡、绘制、删除、擦除）进行角色分类
✅ 模板系统（支架3）
✅ 带卡片列表的括号3规则
✅ 始终处于EDHREC集成状态 （默认启用）
✅ EDHREC请求的内存缓存
✅ 自定义banlist (data/Banlist.txt)-74张禁用卡
✅ LLM动力甲板建造机 （GPT-4.1）-构建完整的99副牌组

数据库：

✅ 具有60多个列的完整Scryfall模式
✅ 针对常见查询优化索引
✅ 卡片名称和甲骨文文本的全文搜索（FTS5）
✅ 用于复杂数据（合法性、价格、图像）的JSON列
✅ ~来自“所有卡”批量数据的520000+张卡

分析：

✅ 甲板尺寸验证（99+指挥官）
✅ 自动分类（土地、坡道、卡片清理、移除、木板管道）
✅ 游戏规则改变者、大规模陆地拒绝和额外转弯检测
✅ 与支架3模板的比较
✅ 详细警告和建议

建筑：

✅ 指挥官的骨骼生成
✅ 基于颜色标识的自动基本土地分配
✅ 默认情况下，EDHREC始终处于启用状态 （可以禁用）
✅ EDHREC建议（前50张牌+前50张落地牌）
✅ 智能自动填充赤字类别
✅ 颜色身份验证
✅ 自动填充中的括号3约束执行
✅ 自动填充后重新分析

MCP服务器：

✅ 使用@modelcontextprotocol/sdk完成MCP服务器
✅ 通用兼容性标准传输
✅ 三个工具： analyze_deck, build_deck_from_commander, build_deck_with_llm （可选OpenAI）
✅ 使用zod模式进行输入验证
✅ 优雅的错误处理

🔜 下一步（v0.4.0+）

\[\]指挥官特定的EDHREC端点(commanders/atraxa.json)
\[\]主题检测和主题自动填充
\[\]马纳曲线分析
\[\]无限组合检测
\[\]支持其他括号（1、2、4）
\[\]附加MCP工具： optimize_deck
\[\]附加MCP工具： search_cards （基于SQL的搜索）
\[\]MCP资源：直接访问Scryfall数据
\[\]MCP提示：上下文建议

📋 指挥官（EDH）格式规则

甲板尺寸： 正好100张牌（1个指挥官+99副牌）
辛格尔顿： 每张卡最多1份（基本土地除外）
颜色标识： 所有卡片必须与指挥官的颜色标识相匹配
支架3（升级版）：

- 最多3个游戏改变者 - 没有大规模的土地破坏 - 有限的额外回合卡

🤝 贡献

这是一个开源项目。欢迎捐款：

分叉存储库
创建要素分支： git checkout -b feature/new-feature
以明确的信息承诺： git commit -m "feat: add mana curve detection"
推： git push origin feature/new-feature
打开拉取请求

📝 代码规范

TypeScript 严格模式 启用
纯函数 在可能的情况下
JSDoc评论 公共API
关注点分离： 核心（逻辑）与mcp（协议）
测试： 每次提交前的本地脚本

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🔗 参考文献

______________________________________________________________________

注：该项目功能齐全，随时可用。MCP服务器已完全实现，并与任何MCP客户端兼容。

Mtg Commander Analyzer MCP

快速接入

详细介绍

MTG指挥官甲板分析仪-MCP

🎯 项目目标

🏗️ 建筑

🚀 快速安装

1.克隆和安装依赖项

2.设置卡数据库（必填）

2.5自定义禁止列表（可选）

2.6 LLM/AI代理的参考文件

3.构建（可选）

4.单元测试（Vitest）

📖 用法

MCP服务器（推荐）

可用的MCP工具

1. analyze_deck

2. build_deck_from_commander

3. build_deck_with_llm ⭐ 新

本地测试

🤖 LLM配置（OpenAI）

1.获取API密钥

2.配置密钥

3.可用型号

4.验证配置

🔧 MCP客户端配置

光标

克劳德桌面版

🛠️ 当前功能（v0.4.0）

✅ 实现

🔜 下一步（v0.4.0+）

📋 指挥官（EDH）格式规则

🤝 贡献

📝 代码规范

📄 许可证

🔗 参考文献

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `analyze_deck`

2. `build_deck_from_commander`

3. `build_deck_with_llm` ⭐ 新