金大哥 - scryfall-mcp MCP 详情

article

README

🚀 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

安装步骤

克隆仓库

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

安装依赖
```
npm install
```

配置环境（可选）

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

构建项目
```
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()

# 或重启服务器

贡献代码

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

开发指南

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

API速率限制与合规性

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

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

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

📄 许可证

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

致谢

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