Scryfall MCP

🚀 スクライフォールMCPサーバー

Scryfall APIと統合された包括的なモデルコンテキストプロトコル（MCP）サーバーです。ClaudeのようなAIアシスタントに、マジック・ザ・ギャザリングのカードデータと機能を提供します。

🚀 クイックスタート

このサーバーは、Scryfall APIと連携して、マジック・ザ・ギャザリングのカードデータを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：特定のカードを中心としたデッキ構築ガイドを作成します。

⚡ パフォーマンス機能

• レート制限：75msの最小間隔でScryfallのAPI制限を尊重します。
• インテリジェントキャッシュ：設定可能な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デスクトップとの統合

Claudeデスクトップの設定ファイルに以下を追加します。

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の完全な検索構文をサポートしています。

基本演算子

• 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デスクトップを再起動してください。
• サーバーは現在、解析問題を回避するために非圧縮のレスポンスを要求しています。

「カードが見つかりません」

• カード名のスペルを確認してください。
• セットコード + 収集番号の形式を使用してみてください。
• カードがScryfallに存在するか確認してください。

「無効な検索構文」

• Scryfall検索構文のドキュメントを確認してください。
• 一致しない括弧がないか確認してください。
• クエリを論理演算子で始めないようにしてください。

Claudeデスクトップとの統合が機能しない

• 設定ファイルの絶対パスを確認してください。
• サーバーが正常にビルドされていることを確認してください。
• Claudeデスクトップのログを確認してエラーを確認してください。

デバッグモード

LOG_LEVEL=debug npm run dev

キャッシュをクリアする

# プログラム的に
server.clearCaches()

# またはサーバーを再起動する

コントリビューション

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. 変更を加える
4. 新機能に対するテストを追加する
5. すべてのテストが通過することを確認する
6. プルリクエストを送信する

開発ガイドライン

• TypeScriptのベストプラクティスに従ってください。
• 80％以上のテストカバレッジを維持してください。
• 従来のコミットメッセージを使用してください。
• 新機能に対するドキュメントを更新してください。

APIレート制限とコンプライアンス

このサーバーはScryfallのAPIガイドラインに完全に準拠しています。

• レート制限: リクエスト間の最小間隔は100ms (最大10リクエスト/秒)
• 必要なヘッダー: 適切なUser-AgentとAcceptヘッダー
• キャッシュ: カードデータは24時間以上、価格は6時間キャッシュ
• バルクデータ: 制限にカウントされない毎日のバルクダウンロードを使用
• エラーハンドリング: 429レスポンスを指数バックオフで尊重
• サーキットブレーカー: API問題時の過負荷を防止

完全なコンプライアンスの詳細については、SCRYFALL_COMPLIANCE.md を参照してください。

📄 ライセンス

MITライセンス - 詳細についてはLICENSEファイルを参照してください。

謝辞

• Scryfall が優れたマジック・ザ・ギャザリングAPIを提供してくれたことに感謝します。
• モデルコンテキストプロトコル がMCP仕様を提供してくれたことに感謝します。
• マジック・ザ・ギャザリングのコミュニティがインスピレーションとフィードバックを提供してくれたことに感謝します。