🚀 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文件。