AI导哈

卡牌数据检索服务

一个基于Scryfall API和EDHREC资源的Magic: The Gathering卡牌数据检索和搜索服务，提供智能缓存、速率限制和全面的卡牌数据。

  • by rpg2014
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 rpg2014/scryfall-mcp

使用说明

Scryfall MCP服务器

一个模型上下文协议（MCP）服务器，使用Scryfall API和EDHREC资源提供高级Magic:The Gathering卡数据检索和搜索功能。

概述

此MCP服务器充当MCP兼容客户端（如Claude Desktop、Cline或其他AI助手）和Magic:The Gathering卡数据库之间的桥梁。它提供智能缓存、速率限制和全面的卡数据，包括EDHREC的裁决和类似的卡建议。

特性

  • 🃏 卡片数据检索：使用模糊名称匹配获取有关魔法：收集卡的全面信息
  • 🔍 高级卡片搜索：使用Scryfall强大的搜索语法查找具有复杂查询的卡片
  • 🏗️ 甲板进口：从Archidekt导入并分析完整的魔法：收集牌组，其中包含详细的卡片信息
  • 💾 智能高速缓存：本地缓存系统，以减少API调用并提高性能
  • 📋 裁决整合：可选择包含Scryfall的官方卡规则
  • 🎯 类似卡推荐：与EDHREC集成，为甲板建造提供类似的卡片
  • ⚡ 速率限制：尊重API使用，内置速率限制（请求之间75毫秒）

先决条件

系统要求

  • Deno运行时：1.40+版本（含 --unstable-temporal 支持）
  • 操作系统：Linux、macOS或Windows
  • 网络接入：对Scryfall和EDHREC的API调用是必需的

安装Deno

如果您没有安装Deno：

Linux/macOS：

curl -fsSL https://deno.land/install.sh | sh

Windows（PowerShell）： 艾生成；谨慎行事。

irm https://deno.land/install.ps1 | iex

包装经理：

# macOS with Homebrew
brew install deno

# Ubuntu/Debian
sudo snap install deno

# Arch Linux
pacman -S deno

验证安装：

deno --version

安装

1.克隆存储库

git clone <repository-url>
cd scryfall-mcp-server

2.测试服务器

验证服务器是否正常工作：

deno run --allow-net --allow-read --allow-write --allow-env --unstable-temporal main.ts

服务器应启动并显示：

Scryfall MCP server running on stdio

按 Ctrl+C 停止测试。

3.设置缓存目录

服务器会自动在以下位置创建缓存目录 ~/.scryfall-mcp-cache 第一次跑步。您可以验证这一点：

ls -la ~/.scryfall-mcp-cache

MCP客户端配置

你应该查一下，这可能不准确

克劳德桌面

将以下内容添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "scryfall": {
      "command": "deno",
      "args": [
        "run",
        "--allow-net",
        "--allow-read",
        "--allow-write",
        "--allow-env",
        "--unstable-temporal",
        "/absolute/path/to/scryfall-mcp-server/main.ts"
      ]
    }
  }
}

Cline（VSCode扩展）

添加到您的Cline MCP设置或 .vscode/mcp.json:

{
  "mcpServers": {
    "scryfall": {
      "command": "deno",
      "args": [
        "run",
        "--allow-net",
        "--allow-read",
        "--allow-write",
        "--allow-env",
        "--unstable-temporal",
        "/absolute/path/to/scryfall-mcp/main.ts"
      ]
    }
  }
}

其他MCP客户端

对于任何兼容MCP的客户端，请使用以下连接参数：

  • 命令: deno
  • 参数:
    • run
    • --allow-net （用于API调用）
    • --allow-read （用于缓存读取）
    • --allow-write （用于缓存写入）
    • --allow-env （适用于HOME等环境变量）
    • --unstable-temporal （用于现代日期/时间处理）
    • /absolute/path/to/main.ts

⚠️ 重要：替换 /absolute/path/to/scryfall-mcp/main.ts 与您的实际绝对路径 main.ts 文件。

工具参考

1.获取卡片数据

检索有关特定魔法：收集卡的详细信息。

参数

  • card_names （必填）：要获取的卡名数组
  • include_rulings （可选，默认：false）：包括官方卡规则
  • include_similar_cards （可选，默认值：false）：包括EDHREC类似的卡推荐

示例用法

{
  "card_names": ["Lightning Bolt", "Counterspell"],
  "include_rulings": true,
  "include_similar_cards": true
}

响应格式

[
  {
    "name": "Lightning Bolt",
    "mana_cost": "{R}",
    "type_line": "Instant",
    "oracle_text": "Lightning Bolt deals 3 damage to any target.",
    "cmc": 1,
    "colors": ["R"],
    "legalities": {
      "standard": "not_legal",
      "modern": "legal",
      "commander": "legal"
    },
    "rulings": [...],
    "similar_cards": [...]
  }
]

2.搜索卡

使用Scryfall的高级搜索语法搜索魔法：收集卡片。

参数

  • query （必填）：Scryfall搜索查询
  • max_results （可选，默认值：25，最大值：175）：最大结果数
  • unique （可选，默认：“卡片”）：如何处理重复（“卡片”、“艺术品”、“印刷品”）
  • order （可选，默认：“name”）：排序顺序
  • include_extras （可选，默认值：false）：包括标记和平面

搜索查询示例

查询 描述
o:"create" o:"token" 创建令牌的卡
t:equipment 所有设备卡片
c:red pow>=4 具有力量的红色生物4+
o:flying t:creature 飞行生物
f:commander 指挥官法律卡
s:dom Dominaria牌组
r:mythic 神话般的稀有卡片
cmc=3 转换法力值的卡牌消耗3

高级搜索语法

  • Oracle文本: o:"text" 或 oracle:"text"
  • 类型行: t:creature 或 type:artifact
  • 颜色: c:red 或 color:blue
  • 魔法力费用: m:{2}{R} 或 mana:{U}{U}
  • 力量/韧性: pow>=4, tou<=2
  • 稀有度: r:common, r:uncommon, r:rare, r:mythic
  • 集: s:dom （设置代码）或 set:"Dominaria"
  • 格式合法性: f:standard, f:modern, f:commander
  • 总法术力费用: cmc=3, cmc>=5

有关完整的语法参考，请参阅：https://scryfall.com/docs/syntax

3.获取存档

从Archidekt导入并分析完整的魔法：收集牌组，包括牌组中每张牌的详细卡信息。

参数

  • deck_id （必填）：甲板URL中的Archidekt甲板ID

示例用法

{
  "deck_id": "12954377"
}

响应格式

{
  "deck": {...}, // deck info
  "cards": [...] // scryfall get_card_data response structure
}

查找甲板ID

Archidekt甲板ID可以在甲板URL中找到：

  • 网址： https://archidekt.com/decks/123456789
  • 甲板ID： 123456789

缓存管理

缓存位置

  • Linux/macOS: ~/.scryfall-mcp-cache/
  • 视窗: %USERPROFILE%\.scryfall-mcp-cache\

缓存结构

~/.scryfall-mcp-cache/
├── similar/                    # EDHREC similar cards cache
│   └── card-name.json         # Cached for 1 year
└── card-name.json             # Individual card cache

缓存维护

查看缓存大小：

du -sh ~/.scryfall-mcp-cache

清除所有缓存：

rm -rf ~/.scryfall-mcp-cache

仅清除类似卡缓存：

rm -rf ~/.scryfall-mcp-cache/similar

发展

运行测试

deno test --allow-net --allow-read --allow-write --allow-env --unstable-temporal

编码结构

  • main.ts -主入口点和MCP服务器初始化
  • src/server.ts -使用工具处理程序实现MCP服务器
  • src/scryfall_client.ts -具有速率限制的Scryfall API客户端
  • src/archidekt_client.ts -用于甲板进口的Archidekt API客户端
  • src/cache.ts -基于文件的缓存实用程序
  • src/rate_limited_fetcher.ts -具有速率限制的HTTP客户端
  • model.ts -EDHREC API响应的TypeScript接口
  • deno.json -Deno配置和依赖关系

关键组件

  1. ScryfallClient：处理带有速率限制的API通信
  2. ArchidektClient：处理从Archidekt平台导入的甲板
  3. 缓存管理：类似卡的TTL基于文件的缓存
  4. MCP服务器：使用工具处理程序实现协议
  5. 速率限制：API请求之间的延迟为75毫秒

故障排除

常见问题

“权限被拒绝”错误：

  • 确保授予所有必需的Deno权限
  • 检查缓存目录是否可写

“找不到模块”错误：

  • 验证Deno版本是否支持所需功能
  • 跑 deno cache main.ts 预下载依赖项

API速率限制：

  • 服务器自动处理速率限制
  • 如果您看到429个错误，则可能需要调整内置延迟

缓存问题：

  • 如果遇到过时数据，请清除缓存目录
  • 如果缓存操作失败，请检查磁盘空间

调试模式

运行附加日志：

DENO_LOG=debug deno run --allow-net --allow-read --allow-write --allow-env --unstable-temporal main.ts

网络问题

测试API连接：

curl -H "User-Agent: MCP-Scryfall-Client/1.0" "https://api.scryfall.com/cards/named?fuzzy=lightning%20bolt"

业绩说明

  • 首次运行：由于缓存构建而变慢
  • 后续运行：缓存数据更快
  • 速率限制：API调用之间的75毫秒（尊重Scryfall）
  • 缓存过期：类似卡缓存1年，普通卡无限期

API限制和合理使用

此服务器遵守以下限制：

  • API公司：没有官方的速率限制，但我们使用75毫秒的延迟
  • API公司：非官方API，主动缓存（1年生存时间）
  • 用户代理：将请求正确标识为“MCP Scryfall Client/1.0”

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

许可证

[插入许可证信息]

致谢

支持

对于问题、疑问或贡献：

  • 在GitHub上打开一个问题
  • 检查现有问题的解决方案
  • 查看上面的故障排除部分

此MCP服务器不隶属于海岸奇才队、Scryfall、Archidekt或EDHREC。

相关 MCP