Scryfall MCP

🚀 Scryfall MCP服务器

Scryfall MCP服务器是一个全面的模型上下文协议（MCP）服务器，它与Scryfall API集成，为Claude等AI助手提供《万智牌》的卡牌数据和功能。

✨ 主要特性

🔧 MCP工具

• search_cards：使用Scryfall强大的搜索语法搜索卡牌。
• get_card：获取特定卡牌的详细信息。
• get_card_prices：检索卡牌的当前价格数据。
• random_card：获取随机卡牌，可选择添加过滤器。
• search_sets：搜索和筛选《万智牌》系列。

📚 MCP资源

• card-database://bulk：完整的Scryfall批量卡牌数据库，每日更新。
• set-database://all：包含所有《万智牌》系列的元数据和图标。

💡 MCP提示

• analyze_card：生成全面的卡牌分析，包括竞技可行性、协同效应和环境定位。
• build_deck：围绕特定卡牌创建套牌构建指南。

⚡ 性能特性

• 速率限制：遵守Scryfall的API限制，最小间隔为75毫秒。
• 智能缓存：通过可配置的TTL（存活时间）将API调用减少70%以上。
• 错误处理：优雅处理所有API错误情况。
• 断路器：在API中断时防止级联故障。

📦 安装指南

前提条件

• Node.js 18+
• npm或yarn

安装步骤

1. 克隆仓库

   git clone https://github.com/bmurdock/scryfall-mcp.git
   cd scryfall-mcp
   

2. 安装依赖

   npm install
   

3. 配置环境（可选）

   cp .env.example .env
   # 根据个人喜好编辑.env文件
   

4. 构建项目

   npm run build
   

💻 使用示例

基础用法

开发模式

npm run dev

生产模式

npm start

测试

# 运行所有测试
npm test

# 以监听模式运行测试
npm run test:watch

# 以UI模式运行测试
npm run test:ui

MCP检查器

npm run inspector

高级用法

与Claude Desktop集成

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

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "scryfall": {
      "command": "node",
      "args": ["/absolute/path/to/scryfall-mcp/dist/index.js"]
    }
  }
}

请将/absolute/path/to/scryfall-mcp替换为实际的安装路径。

工具使用示例

搜索卡牌

// 基本搜索
{
  "query": "lightning bolt"
}

// 使用Scryfall语法进行高级搜索
{
  "query": "c:red type:instant cmc:1",
  "limit": 10,
  "format": "json"
}

// 特定格式搜索
{
  "query": "legal:modern type:creature power>=4",
  "order": "cmc"
}

获取卡牌详情

// 按名称获取
{
  "identifier": "Lightning Bolt"
}

// 按系列和收藏编号获取
{
  "identifier": "dom/123"
}

// 按Scryfall ID获取
{
  "identifier": "f7a99cc1-2b73-4c9c-8de2-9b6c4c1d8f2a"
}

// 指定系列获取
{
  "identifier": "Lightning Bolt",
  "set": "m21"
}

获取卡牌价格

{
  "card_id": "f7a99cc1-2b73-4c9c-8de2-9b6c4c1d8f2a",
  "currency": "usd"
}

随机卡牌

// 完全随机
{}

// 过滤后的随机卡牌
{
  "query": "type:creature",
  "format": "modern"
}

搜索系列

// 所有系列
{}

// 按类型和日期过滤
{
  "type": "expansion",
  "released_after": "2020-01-01"
}

📚 详细文档

Scryfall搜索语法

服务器支持Scryfall的完整搜索语法：

基本运算符

• c:red - 颜色
• type:creature - 类型行
• set:dom - 系列代码
• cmc:3 - 法术力费用
• power>=4 - 力量/防御力比较
• legal:modern - 格式合法性

高级运算符

• is:commander - 卡牌属性
• year:2023 - 发行年份
• rarity:mythic - 稀有度
• artist:"john avon" - 艺术家姓名
• flavor:"text" - 背景文本搜索

布尔逻辑

• red OR blue - 满足任一条件
• creature AND red - 同时满足两个条件
• NOT black - 排除某个条件
• (red OR blue) type:instant - 分组

错误处理

服务器为常见问题提供详细的错误消息：

• 404：未找到卡牌/资源
• 422：无效的搜索语法
• 429：超出速率限制（自动重试）
• 验证错误：参数验证失败

性能监控

缓存统计

// 获取缓存性能
server.getCacheStats()

速率限制器状态

// 检查速率限制状态
server.getRateLimiterStatus()

健康检查

// 系统整体健康状况
server.healthCheck()

配置

环境变量

SCRYFALL_USER_AGENT=ScryfallMCPServer/1.0
CACHE_TTL_HOURS=24
RATE_LIMIT_MS=75
LOG_LEVEL=info
NODE_ENV=development

缓存时长

• 卡牌搜索：30分钟
• 卡牌详情：24小时
• 卡牌价格：6小时
• 系列数据：1周
• 批量数据：24小时

🔧 技术细节

故障排除

常见问题

“超出速率限制”

• 服务器会自动处理速率限制。
• 稍等片刻后重试。
• 检查是否发起了过多的并发请求。

“网络错误：意外的标记”或与gzip相关的错误

• 此问题在v1.0.2版本中通过禁用gzip压缩修复。
• 确保使用的是最新版本：npm run build。
• 重新构建后重启Claude Desktop。
• 服务器现在请求未压缩的响应以避免解析问题。

“未找到卡牌”

• 验证卡牌名称的拼写。
• 尝试使用系列代码 + 收藏编号的格式。
• 检查卡牌是否存在于Scryfall中。

“无效的搜索语法”

• 查看Scryfall搜索语法文档。
• 检查是否有未匹配的括号。
• 避免以布尔运算符开头进行查询。

Claude Desktop集成失败

• 验证配置文件中的绝对路径。
• 确保服务器成功构建。
• 检查Claude Desktop日志中的错误信息。

调试模式

LOG_LEVEL=debug npm run dev

清除缓存

# 编程方式清除
server.clearCaches()

# 或重启服务器

贡献代码

1. 分叉仓库。
2. 创建功能分支。
3. 进行更改。
4. 为新功能添加测试。
5. 确保所有测试通过。
6. 提交拉取请求。

开发指南

• 遵循TypeScript最佳实践。
• 保持测试覆盖率超过80%。
• 使用常规的提交消息。
• 为新功能更新文档。

API速率限制与合规性

本服务器完全遵守Scryfall的API指南：

• 速率限制：请求之间的最小间隔为100毫秒（最大每秒10个请求）。
• 必需的请求头：正确的User-Agent和Accept请求头。
• 缓存：卡牌数据缓存24小时以上，价格缓存6小时。
• 批量数据：使用每日批量下载，不计入限制。
• 错误处理：遵守429响应，采用指数退避策略。
• 断路器：在API出现问题时防止过载。

完整的合规细节请参阅 SCRYFALL_COMPLIANCE.md。

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

致谢

• Scryfall 提供了出色的《万智牌》API。
• 模型上下文协议 提供了MCP规范。
• 《万智牌》社区提供了灵感和反馈。