内容
# MTG Commander Deck Analyzer - MCP
> **当前状态：** v0.7.0 — 模板 + EDHREC牌组构建工具，适用于Cursor和其他MCP客户端（参见 **[AGENTS.md](./AGENTS.md)**）。 **无需API密钥** — 主机代理是LLM；MCP提供数据和验证。 **代理聊天设置：** [docs/agent-chat-setup.md](./docs/agent-chat-setup.md)。
开源TypeScript库和MCP服务器，用于分析和构建Magic: The Gathering Commander（EDH）牌组。
## 🎯 项目目标
提供自动化工具来：
- **分析现有牌组**：格式验证、卡片分类、括号分析、禁牌验证
- **从头构建牌组**：基于指挥官的生成，带有EDHREC自动填充（无预算限制）
- **建议优化**：基于EDHREC数据和Bracket 3规则的建议
- **强制自定义禁牌列表**：使用`data/Banlist.txt`阻止禁牌进入牌组构建
## 🏗️ 架构
```
mtg-commander-analyzer-mcp/
├── src/
│ ├── core/ # 业务逻辑
│ │ ├── deckParser.ts # 牌组列表解析器
│ │ ├── analyzer.ts # 高级牌组分析
│ │ ├── deckBuilder.ts # 牌组构建器
│ │ ├── scryfall.ts # Scryfall集成（自动使用数据库或JSON）
│ │ ├── cardDatabase.ts # SQLite数据库查询
│ │ ├── banlist.ts # 自定义禁牌列表强制执行
│ │ ├── edhrec.ts # EDHREC集成
│ │ ├── autoTags.ts # 主要类别标签（roles.ts弃用占位符）
│ │ ├── templates.ts # 牌组模板
│ │ ├── brackets.ts # 括号规则
│ │ ├── bracketCards.ts # 按括号分类的卡片列表
│ │ ├── categoryUtils.ts # 类别实用工具
│ │ ├── types.ts # TypeScript接口
│ │ └── schemas.ts # MCP的Zod模式
│ ├── scripts/ # 数据库管理脚本
│ │ ├── createDatabase.ts # 创建SQLite模式
│ │ └── importCards.ts # 从JSON导入
│ ├── mcp/ # MCP服务器实现
│ │ ├── server.ts # MCP服务器（stdio传输）
│ │ ├── analyzeDeckTool.ts # analyze_deck工具
│ │ ├── buildDeckFromCommanderTool.ts # build_deck_from_commander
│ │ ├── searchCardsTool.ts # search_cards
│ │ └── ... # analyze, optimize, synergies, etc.
│ ├── testLocal.ts # 分析测试
│ ├── testBuildLocal.ts # 构建测试
│ └── testEndToEnd.ts # 端到端测试
├── data/ # 卡片数据、规则、模板
│ ├── cards.db # SQLite数据库（主要卡片来源）
│ ├── rulings.json # 来自Scryfall的卡片裁决（按oracle_id索引）
│ ├── MagicCompRules.txt # 官方MTG综合规则
│ ├── Banlist.txt # 自定义禁牌列表（一行一个卡片）
│ ├── deck-template-*.json # 牌组模板（括号3）
│ ├── bracket-rules.json # 括号规则
│ ├── bracket3-*.json # 括号3卡片列表
│ └── edhrec_structures/ # EDHREC JSON数据
└── package.json
```
## 🚀 快速安装
> 📖 **详细指南：** 查看 [INSTALLATION.md](./INSTALLATION.md) 了解完整说明和故障排除。
### 1. 克隆和安装依赖
```bash
# 克隆仓库
git clone https://github.com/kscius/mtg-commander-analyzer-mcp.git
cd mtg-commander-analyzer-mcp
# 安装依赖
npm install
```
### 2. 设置卡片数据库（必需）
该项目使用SQLite高效查询卡片数据。此功能支持任意大小的文件，包括完整的Scryfall“所有卡片”数据库（2GB+）。
**选项A - 使用预先存在的oracle-cards.json：**
如果您已经拥有`data/oracle-cards.json`:
```bash
# 创建数据库模式
npm run db:create
# 导入卡片（支持流式处理，处理2GB+文件）
npm run db:import
```
导入脚本：
- ✅ 使用流式JSON解析（从不加载完整文件到内存）
- ✅ 处理约2800张卡片/秒
- ✅ 为快速查找创建索引
- ✅ 支持全文搜索
**选项B - 下载新鲜的Scryfall数据：**
```bash
# Linux/macOS
chmod +x setup.sh
./setup.sh
# Windows PowerShell
.\setup.ps1
```
然后运行数据库设置：
```bash
npm run db:create
npm run db:import
```
**选项C - 手动下载：**
1. 访问 [Scryfall Bulk Data](https://scryfall.com/docs/api/bulk-data)
2. 下载“Oracle Cards”（唯一卡片）或“All Cards”（所有印刷）
3. 保存为`data/oracle-cards.json`
4. 运行`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 Mana Crypt”）
默认禁牌列表包括74张通常被认为对休闲Commander游戏有问题的卡片。
### 2.6 参考文件用于LLM/AI代理
当与AI代理（Cursor, Claude Desktop等）一起使用此MCP时，代理应始终参考这些资源以确保准确的牌组构建：
| 资源 | 目的 |
|----------|---------|
| `data/cards.db` | 带有所有卡片数据的SQLite数据库（使用MCP工具查询） |
| `data/rulings.json` | 来自Scryfall的卡片特定裁决（按`oracle_id`索引） |
| `data/MagicCompRules.txt` | 官方Magic: The Gathering综合规则 |
| `data/Banlist.txt` | 自定义禁止卡片列表 |
**⚠️ 重要：牌组验证规则**
AI代理必须始终验证：
1. **恰好100张卡片** （99 + 1指挥官）
2. **所有卡片都在指挥官的颜色身份之内**
3. **没有禁止的卡片** （来自`data/Banlist.txt`）
4. **单一规则** （每张卡片只有一个副本，除基本土地外）
5. **指挥官合法性** （指挥官必须是传奇生物或具有“可以作为你的指挥官”）
**用于卡片查找**，代理应：
- 使用MCP的`analyze_deck`或`build_deck_from_commander`工具（它们自动查询`cards.db`）
- SQLite数据库包含所有Scryfall卡片数据，支持全文搜索
**用于复杂的卡片交互**，代理应：
- 检查`data/rulings.json`以获取特定卡片的官方裁决
- 参考`data/MagicCompRules.txt`以获取规则问题（例如，层，优先级，替换效果）
### 3. 构建（可选）
```bash
npm run build
```
### 4. 单元测试（Vitest）
```bash
npm test
npm run test:watch # 开发过程中的监视模式
```
拉取请求和推送到`main` / `master`会在Node 20上运行：`npm ci` → 数据库设置（`scripts/ci-setup-db.sh`）→ `npm run build` → `npm run test:mcp-smoke` → `npm test` → `npm run test:golden` → `npm run benchmark:decks`。参见`.github/workflows/ci.yml`和[docs/testing.md](docs/testing.md)。
## 📖 使用方法
### MCP服务器（推荐）
MCP服务器为兼容的客户端（Cursor, Claude Desktop等）公开了**十一项工具：**
| 工具 | 目的 |
|------|---------|
| `get_synergies` | 为指挥官列出EDHREC主题 |
| `get_user_deck_style` | 从导入的牌组（`data/my_decks`）聚合基 mana 基地/类别统计 |
| `get_strategy_guide` | 用于协同作用slug的Markdown构建指南 |
| `build_deck_from_commander` | 从指挥官名称构建99张主牌（模板+EDHREC；**首选**；默认为`data/my_decks`偏置） |
| `get_category_candidates` | 用于模板类别的排名数据库候选（无需猜测名称的填充） |
| `analyze_deck` | 验证牌组列表、类别、Bracket 3、`qualityGate`、`agentBrief` |
| `optimize_deck` | 迭代分析→剪切/添加→EDHREC自动填充 |
| `apply_deck_changes` | 在不重新粘贴99行`deckText`的情况下应用剪切/添加交换 |
| `evaluate_card_swap` | 预览一张卡片交换的影响 |
| `search_cards` | 查询`cards.db`并带有协同作用相关的排序 |
| `resolve_card` | 解析一个卡片名称+合法性/颜色拟合 |
参见 **[AGENTS.md](./AGENTS.md)** 以获取推荐的代理工作流。
**MCP资源**（通过`resources/list`和`resources/read`读取只读文档/数据）：
| URI | 内容 |
|-----|---------|
| `mtg-commander:///template/bracket3` | Bracket 3牌组模板JSON |
| `mtg-commander:///banlist` | 项目禁牌列表 |
| `mtg-commander:///agents` | AGENTS.md |
| `mtg-commander:///strategy-guide/{slug}` | 架构markdown指南 |
| `mtg-commander:///user-decks/index` | 导入的牌组清单 |
| `mtg-commander:///user-decks/style-profile` | 聚合的用户基 mana 基地配置文件 |
| `mtg-commander:///docs/user-deck-style-reference` | 代理指南，用于个人牌组库 |
**用户牌组库：** 将您的Moxfield列表导入`data/my_decks`（`npm run decks:download-moxfield`）。构建使用`useUserStyleReference: true`（默认）偏置土地数量和 staple - 生成的牌组**永远不会**保存到那里。参见 [docs/user-deck-style-reference.md](./docs/user-deck-style-reference.md)。
EDHREC响应在`data/cache/edhrec/`处缓存24小时（TTL）以加速重复构建。
**MCP提示**（通过`prompts/list`和`prompts/get`的工作流模板）：
| 提示 | 参数 | 目的 |
|--------|-----------|---------|
| `build-commander-deck` | `commanderName`（必需），`preferredStrategy`（可选） | 完整的构建工作流 + Bracket 3检查清单 |
| `optimize-decklist` | `commanderName`，`preferredStrategy`（必需），`deckText`（可选） | 优化循环 + 质量门控 |
**启动服务器：**
```bash
npm run mcp
```
服务器通过stdio（stdin/stdout）监听MCP消息，并保持活动状态以等待请求。
### 可用的MCP工具
#### 1. `analyze_deck`
分析现有的Commander牌组清单，带有Bracket 3验证。
**输入：**
```json
{
"deckText": "1 Sol Ring\n1 Arcane Signet\n1 Rhystic Study\n37 Island\n...",
"templateId": "bracket3",
"bracketId": "bracket3"
}
```
**输出：**
```json
{
"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": 9, "max": 12, "status": "within" },
{ "name": "card_draw", "count": 8, "min": 8, "max": 11, "status": "within" },
{ "name": "within" },
{ "name": "spot_removal", "count": 6, "min": 4, "max": 7, "status": "within" },
{ "name": "board_wipes", "count": 3, "min": 2, "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神谕文本的角色检测
- ✅ Bracket 3验证（游戏改变者，土地剥夺，额外回合）
- ✅ 基于类别的建议
#### 2. `build_deck_from_commander`
从指挥官名称构建Commander牌组，带有可选的EDHREC自动填充。
**输入：**
```json
{
"commanderName": "Atraxa, Praetors' Voice",
"templateId": "bracket3",
"bracketId": "bracket3",
"seedCards": ["Sol Ring", "Arcane Signet"],
"useEdhrec": true,
"useEdhrecAutofill": true
}
```
**输出：**
```json
{
"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集成（颜色分类卡片）
- ✅ 类别赤字智能填充
- ✅ Bracket 3约束强制执行
- ✅ 颜色身份验证
- ✅ 所有卡片的角色分类
### 本地测试
**牌组分析：**
```bash
npm run test:local
```
**牌组构建：**
```bash
npm run test:build
```
两个脚本都在控制台中显示详细的输出结果。
## 🤖 代理/LLM（无需MCP API密钥）
牌组构建和卡片选择由**主机代理**（例如Cursor）进行。MCP服务器为构建、验证、填充空白（`get_category_candidates`）、增量编辑（`apply_deck_changes`）和优化提供了**十一项工具**。 **无需OpenAI API密钥** - 可选的`OPENAI_API_KEY`启用叙事`get_user_deck_style`和构建类别增强（`useOpenAIEnhancement`，默认为true）。
模板生成用**EDHREC** + **本地SQLite**查找填充类别空白（`searchCardsFiltered`，与`search_cards`使用相同的数据库）。构建/分析/优化默认为 **`responseMode: "brief"`** (`agentBrief`, `qualityGate`)；如果需要完整的`analysis`对象，请传递`responseMode: "full"`。使用`get_category_candidates`, `search_cards`, `apply_deck_changes`, 或`optimize_deck`当构建后仍有空白时。
## 🔧 MCP客户端配置
### Cursor
在Cursor的MCP配置中添加以下内容：
```json
{
"mcpServers": {
"mtg-commander-analyzer": {
"command": "npm",
"args": ["run", "mcp"],
"cwd": "/path/to/mtg-commander-analyzer-mcp"
}
}
}
```
### Claude Desktop
在`claude_desktop_config.json`中：
```json
{
"mcpServers": {
"mtg-commander-analyzer": {
"command": "npm",
"args": ["run", "mcp"],
"cwd": "/path/to/mtg-commander-analyzer-mcp"
}
}
}
```
## 🛠️ 当前功能（v0.7.0）
### ✅ 已实现
**核心：**
- ✅ 牌组清单解析器，用于`<quantity> <name>`格式
- ✅ **SQLite数据库**用于高效的卡片查找（支持2GB+数据集）
- ✅ **流式JSON导入** - 绝不将完整文件加载到内存中
- ✅ 如果数据库不可用，自动回落到JSON文件
- ✅ 基于类型和神谕文本的角色分类（ramp, draw, removal, wipes）
- ✅ 模板系统（Bracket 3）
- ✅ Bracket 3规则，带有卡片列表
- ✅ **始终开启的EDHREC集成**（默认启用）
- ✅ EDHREC请求的内存缓存
- ✅ **自定义禁牌列表** (`data/Banlist.txt`) - 74张禁牌
- ✅ **模板牌组生成器** - EDHREC + SQLite填充完整的99张牌组
**数据库：**
- ✅ 完整的Scryfall模式，包含60多个列
- ✅ 为常见查询优化的索引
- ✅ 卡片名称和神谕文本的全文本搜索（FTS5）
- ✅ 用于复杂数据的JSON列（合法性，价格，图像）
- ✅ 来自`data/oracle-cards.json`的~38,000个神谕唯一卡片（默认`npm run db:import`路径）
**分析：**
- ✅ 牌组大小验证（99 + 指挥官）
- ✅ 自动分类（土地，冲锋，抽卡，移除，清除）
- ✅ 游戏改变者，土地剥夺和额外回合检测
- ✅ 与Bracket 3模板比较
- ✅ 详细的警告和建议
**构建：**
- ✅ 从指挥官生成骨架
- ✅ 根据颜色身份自动基本土地分布
- ✅ **EDHREC始终启用（默认）** （可以禁用）
- ✅ EDHREC建议（前50张卡片+前50张土地）
- ✅ 类别赤字智能填充
- ✅ 颜色身份验证
- ✅ 构建过程中的Bracket 3约束强制执行
- ✅ 自动填充后重新分析
**MCP服务器：**
- ✅ 完整的MCP服务器，带有@modelcontextprotocol/sdk
- ✅ 通用的stdio传输
- ✅ 十一项MCP工具：`get_synergies`, `get_user_deck_style`, `get_strategy_guide`, `get_category_candidates`, `search_cards`, `resolve_card`, `build_deck_from_commander`, `analyze_deck`, `optimize_deck`, `apply_deck_changes`, `evaluate_card_swap`. 代理入口：**AGENTS.md**
- ✅ 用户牌组样式参考 (`data/my_decks`, `useUserStyleReference`, 可选OpenAI叙事)
- ✅ 使用zod模式的输入验证
- ✅ 宽容的错误处理
### 🔜 下一步（v0.4.0+）
- [ ] 指挥官特定的EDHREC端点 (`commanders/atraxa.json`)
- [ ] 主题检测和主题填充
- [ ] Mana曲线分析
- [ ] 无限组合检测
- [ ] 支持其他括号（1, 2, 4）
- [x] MCP工具：`optimize_deck` - 已发布
- [x] MCP工具：`evaluate_card_swap` - 已发布
- [x] MCP工具：`get_strategy_guide` - 已发布
- [x] MCP工具：`search_cards` （基于SQL的搜索+协同作用相关性）- 已发布
- [x] MCP工具：`get_synergies` - 已发布
- [x] MCP资源：模板，禁牌列表，策略指南，AGENTS.md (`mtg-commander:///` URIs)
- [x] MCP提示：`build-commander-deck`, `optimize-decklist` （AGENTS检查清单嵌入）
- [x] 黄金牌组CI工件：`data/golden/shadrix-group-slug-analyze.expected.json` + `npm run test:golden`
- [ ] MCP资源：Scryfall数据直接访问
## 📋 Commander（EDH）格式规则
- **牌组大小：** 恰好100张卡片（1张指挥官 + 99张牌组卡片）
- **单一规则：** 每张卡片最多复制1次（基本土地除外）
- **颜色身份：** 所有卡片必须与指挥官的颜色身份相符
- **Bracket 3（升级）：**
- 最多3张游戏改变者
- 没有大规模土地破坏
- 有限的额外回合卡片
## 🤝 贡献
这是一个开源项目。欢迎贡献：
1. 分叉仓库
2. 创建一个功能分支：`git checkout -b feature/new-feature`
3. 提交并带有清晰的消息：`git commit -m "feat: add mana curve detection"`
4. 推送：`git push origin feature/new-feature`
5. 打开拉取请求
## 📝 代码约定
- **TypeScript严格模式** 启用
- **纯函数** 尽可能
- **JSDoc注释** 用于公共API
- **关注点分离：** 核心（逻辑）与mcp（协议）
- **测试：** 每次提交前运行本地脚本
## 📄 许可证
MIT许可证 - 详见LICENSE文件了解详情
## 🔗 参考资料
- [Scryfall API](https://scryfall.com/docs/api)
- [EDHREC](https://edhrec.com/)
- [模型上下文协议](https://modelcontextprotocol.io/)
- [Commander格式规则](https://mtgcommander.net/index.php/rules/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
---
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器