Scryfall MCP 服务器

一个全面的模型上下文协议 (MCP) 服务器，它与 Scryfall API 集成，为 AI 助手提供万智牌 (Magic: The Gathering) 卡牌数据和功能。

本仓库目前支持：

• stdio 作为本地 MCP 客户端稳定的默认传输方式

• 实验性的 Streamable HTTP 作为本地优先 HTTP 工作流的附加传输方式

核心产品在两种模式下保持一致：为万智牌提供基于 Scryfall 的搜索、规则查询和套牌构建工作流。

功能

🔧 MCP 工具

查询构建

• build_scryfall_query: 将自然语言请求转换为优化的 Scryfall 搜索查询

  • 输入：自然语言描述、格式偏好、优化策略

  • 输出：带有解释和替代方案的优化 Scryfall 查询

  • 示例："red creatures under $5 for aggressive decks" → "c:r t:creature usd<=5 pow>=2 cmc<=3"

核心搜索工具

• search_cards: 使用 Scryfall 强大的搜索语法搜索卡牌

• get_card: 获取特定卡牌的详细信息

• get_card_prices: 获取卡牌的当前价格数据

• random_card: 获取随机卡牌，支持可选过滤器

• search_sets: 搜索并筛选万智牌系列

发现与分析工具

• query_rules: 在上下文中搜索万智牌综合规则

• search_format_staples: 查找特定赛制的必备卡、核心组件和环境主流卡

• search_alternatives: 查找预算替代品、升级版或类似卡牌

• find_synergistic_cards: 为某张卡牌、主题或原型发现协同组件

• batch_card_analysis: 分析多张卡牌的合法性、价格、协同效应或构成

套牌构建工具

• validate_brawl_commander: 检查某张卡牌是否为合法的 Brawl 或标准 Brawl 指挥官

• analyze_deck_composition: 从套牌列表中评估法术力曲线、卡牌组合、颜色和建议

• suggest_mana_base: 根据颜色需求推荐地牌数量和法术力调色方案

📚 MCP 资源

• card-database://bulk: 完整的 Scryfall 批量卡牌数据库，每日更新

• set-database://all: 所有带有元数据和图标的万智牌系列

💡 MCP 提示词

• analyze_card: 生成全面的卡牌分析，包括竞技可行性、协同效应和环境定位

• build_deck: 创建围绕特定卡牌的套牌构建指南

⚡ 性能特性

• 速率限制: 遵守 Scryfall 的 API 限制，最小间隔为 100ms

• 智能缓存: 通过可配置的 TTL 将 API 调用减少 >70%

• 错误处理: 优雅地处理所有 API 错误情况

• 断路器: 防止 API 中断期间的级联故障

🔍 简单验证系统

• 轻量级验证: 带有有用错误消息的基本查询语法验证

• 基本检查: 括号匹配、引号和常见语法错误

• 运算符识别: 验证已知的 Scryfall 运算符并提供拼写错误建议

• 性能优化: 快速验证，开销极小

Related MCP server: API Tester MCP Server

安装

先决条件

• 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
   # Edit .env with your preferences

4. 构建项目

   npm run build

使用方法

传输模式

STDIO (稳定默认)

对于 Claude Desktop、Codex 和 MCP Inspector 等本地 MCP 客户端，请使用 stdio。这是主要且支持最好的传输方式。

npm run dev

npm start

Streamable HTTP (实验性)

提供了一个附加的 HTTP 入口点，用于本地优先的 Streamable HTTP 使用。

npm run dev:http

npm run start:http

测试

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

MCP Inspector

npm run inspector

HTTP 传输状态

HTTP 支持目前处于 实验性 阶段。

这意味着：

• stdio 仍然是推荐的默认设置

• HTTP 是附加功能，而非替代品

• 实现遵循官方 MCP Streamable HTTP 传输路径

• 首次实现有意采用本地优先且范围保守的策略

当前的 HTTP 行为：

• 默认绑定到 127.0.0.1

• 暴露 POST|GET|DELETE /mcp

• 暴露 GET /health

• 默认拒绝非回环浏览器风格的 Origin 标头

• 当有意需要不同的来源策略时，可以通过 HTTP_ALLOWED_ORIGINS 进行配置

当前非目标：

• 公共互联网部署指南

• 身份验证中间件或托管生产环境加固

• 替换整个仓库中的 stdio 示例

如果您需要面向公众的部署模型，请将当前的 HTTP 支持视为基础，而非成品托管方案。

项目文档

• CONTRIBUTING.md

• SECURITY.md

• SCRYFALL_COMPLIANCE.md

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 替换为您安装的实际路径。

HTTP 配置

可选的 HTTP 环境变量：

• HTTP_HOST 默认 127.0.0.1

• HTTP_PORT 默认 3000

• HTTP_MCP_PATH 默认 /mcp

• HTTP_HEALTH_PATH 默认 /health

• HTTP_ALLOWED_ORIGINS 可选的逗号分隔来源白名单

本地 HTTP 启动示例：

HTTP_HOST=127.0.0.1 HTTP_PORT=3000 npm run start:http

此模式旨在用于本地或明确受控的环境。在未添加身份验证和部署加固之前，请勿将当前的 HTTP 入口点视为生产就绪的公共暴露接口。

工具使用示例

自然语言查询构建

将自然语言转换为 Scryfall 语法：

// Convert natural language to optimized Scryfall query
{
  "tool": "build_scryfall_query",
  "arguments": {
    "natural_query": "blue counterspells in modern under $20",
    "optimize_for": "precision"
  }
}

生成预算友好型查询：

// Budget-focused query generation
{
  "tool": "build_scryfall_query",
  "arguments": {
    "natural_query": "aggressive red creatures for standard",
    "optimize_for": "budget",
    "price_budget": {
      "max": 5,
      "currency": "usd"
    }
  }
}

发现有趣的卡牌：

// Discovery-optimized search
{
  "tool": "build_scryfall_query",
  "arguments": {
    "natural_query": "legendary artifacts that produce mana",
    "format": "commander",
    "optimize_for": "discovery"
  }
}

查询规则

{
  "tool": "query_rules",
  "arguments": {
    "query": "state-based actions",
    "context_lines": 2
  }
}

搜索赛制必备卡

{
  "tool": "search_format_staples",
  "arguments": {
    "format": "commander",
    "role": "ramp",
    "tier": "competitive",
    "limit": 10
  }
}

搜索替代品

{
  "tool": "search_alternatives",
  "arguments": {
    "target_card": "Rhystic Study",
    "direction": "cheaper",
    "format": "commander",
    "max_price": 10
  }
}

查找协同卡牌

{
  "tool": "find_synergistic_cards",
  "arguments": {
    "focus_card": "Obeka, Splitter of Seconds",
    "synergy_type": "theme",
    "format": "commander",
    "limit": 12
  }
}

批量卡牌分析

{
  "tool": "batch_card_analysis",
  "arguments": {
    "card_list": ["Sol Ring", "Arcane Signet", "Command Tower"],
    "analysis_type": "prices",
    "currency": "usd",
    "include_suggestions": true
  }
}

验证 Brawl 指挥官

{
  "tool": "validate_brawl_commander",
  "arguments": {
    "card_identifier": "Ashiok, Nightmare Muse",
    "format": "brawl"
  }
}

分析套牌构成

{
  "tool": "analyze_deck_composition",
  "arguments": {
    "deck_list": "4 Lightning Bolt\n4 Monastery Swiftspear\n20 Mountain",
    "format": "modern",
    "strategy": "aggro"
  }
}

建议法术力基础

{
  "tool": "suggest_mana_base",
  "arguments": {
    "color_requirements": "WUG",
    "format": "commander",
    "strategy": "midrange",
    "budget": "moderate"
  }
}

搜索卡牌

// Basic search
{
  "query": "lightning bolt"
}

// Advanced search with Scryfall syntax
{
  "query": "c:red type:instant cmc:1",
  "limit": 10,
  "format": "json"
}

// Format-specific search
{
  "query": "legal:modern type:creature power>=4",
  "order": "cmc"
}

获取卡牌详情

// By name
{
  "identifier": "Lightning Bolt"
}

// By set and collector number
{
  "identifier": "dom/123"
}

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

// With specific set
{
  "identifier": "Lightning Bolt",
  "set": "m21"
}

获取卡牌价格

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

随机卡牌

// Completely random
{}

// Filtered random card
{
  "query": "type:creature",
  "format": "modern"
}

搜索系列

// All sets
{}

// Filter by type and date
{
  "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: 超过速率限制（自动重试）

• 验证错误: 参数验证失败

性能监控

缓存统计

// Get cache performance
server.getCacheStats()

速率限制器状态

// Check rate limiting status
server.getRateLimiterStatus()

健康检查

// Overall system health
server.healthCheck()

配置

环境变量

SCRYFALL_USER_AGENT=ScryfallMCPServer/1.0
RATE_LIMIT_MS=100
LOG_LEVEL=info
NODE_ENV=development
# Optional timeouts and health/deep checks
SCRYFALL_TIMEOUT_MS=15000
HEALTHCHECK_DEEP=false
# Bound the internal rate limiter queue
RATE_LIMIT_QUEUE_MAX=500

缓存时长

• 卡牌搜索: 30 分钟

• 卡牌详情: 24 小时

• 卡牌价格: 6 小时

• 系列数据: 1 周

• 批量数据: 24 小时

日志配置

服务器使用 Pino 进行高性能结构化日志记录，并具有全面的错误跟踪和监控功能。

日志级别

# Available log levels (default: info)
LOG_LEVEL=trace    # Most verbose - all operations
LOG_LEVEL=debug    # Debug information and performance metrics
LOG_LEVEL=info     # General information (default)
LOG_LEVEL=warn     # Warnings and degraded performance
LOG_LEVEL=error    # Errors only
LOG_LEVEL=fatal    # Critical errors only

开发与生产日志记录

开发模式 (NODE_ENV=development):

• 美化打印、彩色输出

• 人类可读的时间戳

• 请求 ID 和工具名称高亮

• 自动日志格式化以提高可读性

生产模式 (NODE_ENV=production):

• 用于机器处理的 JSON 结构化日志

• 针对日志聚合系统进行了优化

• 高性能场景下的最小开销

• 兼容 ELK Stack、Grafana 和监控工具

结构化日志格式

所有日志都包含用于调试和监控的结构化上下文：

{
  "level": "info",
  "time": "2025-01-17T19:32:53.123Z",
  "pid": 12345,
  "hostname": "server-01",
  "service": "scryfall-mcp",
  "version": "1.0.0",
  "requestId": "req_1737145973123_abc123def",
  "toolName": "search_cards",
  "operation": "tool_execution",
  "duration": 245,
  "msg": "Tool execution completed"
}

请求关联

每个请求都有一个唯一的关联 ID，用于跨操作跟踪：

• 格式: req_{timestamp}_{random}

• 跟踪工具执行、API 调用和错误

• 实现端到端请求跟踪

• 自动清理旧的关联数据

错误处理与监控

错误分类

服务器通过结构化错误类实现了全面的错误处理：

基础错误类型：

• MCPError - 具有结构化日志支持的基类

• ToolExecutionError - 工具特定的执行失败

• ResourceError - 资源访问失败

• PromptError - 提示词生成失败

领域特定错误：

• ScryfallAPIError - 与 Scryfall API 相关的错误

• RateLimitError - 速率限制和节流

• ValidationError - 输入验证失败

错误监控功能

自动错误跟踪：

• 按类型统计错误频率

• 性能指标收集

• 请求关联跟踪

• API 故障的断路器模式

监控数据访问：

// Get comprehensive monitoring report
const status = server.getStatus();
console.log(status.monitoring);

// Output includes:
// - Error counts by type
// - Performance metrics (avg response times)
// - Request correlation data
// - Health check status

健康检查监控

增强的健康检查，提供详细的服务状态：

# Health check includes:
# - Cache service status
# - Rate limiter status
# - Scryfall API connectivity
# - Error monitoring metrics
# - Performance statistics

生产监控设置

推荐的监控栈：

1. 日志聚合: ELK Stack (Elasticsearch, Logstash, Kibana)

2. 指标: Grafana + Prometheus

3. 错误跟踪: Sentry (带有结构化错误上下文)

4. 警报: 基于错误率和响应时间

关键监控指标：

• 工具执行成功/失败率

• API 响应时间分布

• 错误类型频率

• 缓存命中/未命中率

• 速率限制器状态

错误恢复策略

自动恢复：

• API 故障的指数退避

• 断路器防止级联故障

• 带有抖动的智能重试逻辑

• 中断期间的优雅降级

手动恢复：

// Reset error monitoring
server.resetRateLimiter();
server.clearCaches();

// Check system health
const health = await server.healthCheck();

故障排除

常见问题

"Rate limit exceeded" (超过速率限制)

• 服务器会自动处理速率限制

• 请稍候片刻再试

• 检查是否发起了过多的并发请求

"Network error: Unexpected token" 或与 gzip 相关的错误

• 此问题已在 v1.0.2 中通过禁用 gzip 压缩修复

• 确保使用最新构建：npm run build

• 重建后重启 Claude Desktop

• 服务器现在请求未压缩的响应以避免解析问题

"Card not found" (未找到卡牌)

• 验证卡牌名称拼写

• 尝试使用“系列代码 + 收藏编号”格式

• 检查卡牌是否存在于 Scryfall 中

"Invalid search syntax" (无效的搜索语法)

• 查看 Scryfall 搜索语法文档

• 检查括号是否匹配

• 避免以布尔运算符开头查询

Claude Desktop 集成不工作

• 验证配置中的绝对路径

• 确保服务器构建成功

• 检查 Claude Desktop 日志以获取错误信息

调试模式

LOG_LEVEL=debug npm run dev

清除缓存

# Programmatically
server.clearCaches()

# Or restart the server

贡献

1. Fork 本仓库

2. 创建功能分支

3. 进行更改

4. 为新功能添加测试

5. 确保所有测试通过

6. 提交 Pull Request

开发指南

• 遵循 TypeScript 最佳实践

• 保持 >80% 的测试覆盖率

• 使用约定式提交信息

• 为新功能更新文档

API 速率限制与合规性

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

• 速率限制: 请求之间至少间隔 100ms（最高 10 次请求/秒）

• 必需标头: 正确的 User-Agent 和 Accept 标头

• 缓存: 卡牌数据缓存 24 小时以上，价格缓存 6 小时

• 批量数据: 使用不计入限制的每日批量下载

• 错误处理: 遵守 429 响应并进行指数退避

• 断路器: 防止 API 问题期间过载

有关完整的合规性详细信息，请参阅 SCRYFALL_COMPLIANCE.md。

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

• Scryfall 提供出色的万智牌 API

• Model Context Protocol 提供 MCP 规范

• 万智牌社区提供灵感和反馈

HTTP 行为与标头

• 根据 Scryfall 指南，服务器在所有 Scryfall API 调用上发送描述性的 User-Agent 和 `Accept: application/json