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規範。
• 《萬智牌》社區提供了靈感和反饋。