mtg-mcp

mtg-mcp

mtg-mcp は、Magic: The Gathering のカード、デッキ、プロバイダー、統計的な根拠を LLM に提供します。デッキ構築の判断は LLM が行います。

バージョン 0.9.0 は、新しい stdio サーバー設計です。remote モードの完全な all プロファイルでは、97 個のツール、1 つの mtg://server/capabilities リソース、プロンプトなしを提供します。絞り込まれたデフォルトプロファイルでは、read-only モードで 33 個、local または remote モードで 55 個のツールを提供します。0.8.x のデータやツールスキーマは移行しません。

ステータス

根拠を優先した書き換えは完了しました。0.9.0 は新しいサーバーの最初の安定版リリースです。

機能	ツール	デフォルト	ストレージまたは書き込み
ローカルデッキとデータ交換	29	はい	ローカル
Scryfall の根拠	18	はい	ローカルキャッシュとカードデータ
正確な統計	8	はい	なし
Archidekt	23	いいえ	リモート
プレイグループ	16	いいえ	リモート
Commander Spellbook の根拠	3	いいえ	ローカルキャッシュのみ

Spellbook の追加前に実施したパッケージ済みの受け入れテストでは、安全なツール呼び出しを 88 回行いました。Scryfall のカードデータダウンロードツール 2 つと Playgroup の書き込みツール 2 つには、ライブのクリーンアップ用ルートを利用できないため、保存済みのテストデータを使用します。Scryfall のロールバックには、Scryfall が別のデータバージョンを公開する必要があります。それまでは、チェックは待機中と報告します。Commander Spellbook には、独自の限定的な読み取り専用ライブチェックがあります。 ライブ受け入れテストを参照してください。

サーバーを起動する

リポジトリをブートストラップしてから、MCP のスモークテストを実行します。

.\bootstrap.ps1
task smoke:mcp

Linux または macOS の場合：

./bootstrap.sh
task smoke:mcp

ブートストラップでは、必要に応じて Mise をインストールします。Mise は、分離されたツールディレクトリに mise.toml から Task と PowerShell を、global.json から .NET SDK をインストールします。ブートストラップ後は、通常どおり task <command> を実行します。Taskfile は .NET のために Mise を呼び出します。新しいシェルで Task が見つからない場合は、Mise を有効にするか、一時的に mise exec -- task <command> を使用します。

コミット済みの Mise と NuGet のロックファイルにより、セットアップを再現可能にしています。バージョンの固定設定は mise.toml、global.json、Directory.Packages.props、dotnet-tools.json にあります。利用可能な更新を確認するには task deps:check を使用してください。関連するバージョン固定設定とロックファイルの変更を確認する場合に限り、task deps:update を使用してください。

MCP コマンドとして mtg-mcp を使用します。デフォルトの呼び出しは、次と同等です。

mtg-mcp --mode=local --toolsets=default

一度だけ設定を確認するには --smoke を使用します。MCP セッションは開始されません。

task install は、Scryfall ツールセットを有効にした分離された読み取り専用サーバーも起動して停止します。これにより、--smoke では検出できない、パッケージ済み SQLite と Scryfall の起動に関する問題を検出できます。

モードを選択する

モードによって権限が制御されます。

モード	読み取り	ローカルへの書き込み	リモートへの書き込み
read-only	はい	いいえ	いいえ
local	はい	はい	いいえ
remote	はい	はい	はい

デフォルトは local です。Scryfall のキャッシュが見つからない場合、応答とレート制限のタイミングを記録するために、ローカルへの書き込みが必要になることがあります。read-only では、HTTP リクエストを送信する前に、そのキャッシュミスは local-write-required を返します。

Commander Spellbook の読み取りは、3 つすべてのモードで利用できます。デッキを変更したり、ソースに書き込みリクエストを送信したりすることはありません。成功した応答は有効期間の短いローカルキャッシュを使用するため、同じリクエストを繰り返しても、プロバイダーへの不要なトラフィックは発生しません。

ツールセットを選択する

ツールセットによって、セッションから参照できるツールが決まります。書き込み権限が付与されるわけではありません。

値	結果
default または省略	decks、scryfall、stats を有効にします
all	実装済みのすべてのツールセットを有効にします
none	ツールを公開しません
カンマ区切りのリスト	名前を指定したツールセットだけを有効にします

利用可能なツールセットは decks、scryfall、stats、archidekt、playgroup、spellbook です。選択内容は MCP セッション中固定されます。

プロファイル	read-only	local	remote
default	33	55	55
all	61	84	97
none	0	0	0

mtg://server/capabilities を読み込むと、アクティブなモード、ツールセット、ツール数、認証情報の状態、パッケージのバージョン、ローカルデータの状態を確認できます。プロバイダーには接続しません。

サーバーを設定する

コマンドライン、環境変数、または作業ディレクトリ内の任意の mtg-mcp.json で設定を指定します。コマンドラインの値は環境変数の値より優先されます。環境変数の値は JSON の値より優先されます。

設定	コマンドライン	環境変数	JSON キー
動作モード	--mode	MTGMCP__MODE	MODE
ツールセット	--toolsets	MTGMCP__TOOLSETS	TOOLSETS
データルート	--data-dir	MTGMCP__DATA_DIR	DATA_DIR
Scryfall TTL	--scryfall-ttl-hours	MTGMCP__SCRYFALL_TTL_HOURS	SCRYFALL_TTL_HOURS
Commander Spellbook TTL	--spellbook-ttl-minutes	MTGMCP__SPELLBOOK__TTL_MINUTES	SPELLBOOK_TTL_MINUTES

デフォルトのデータルートは、プラットフォームのアプリケーションデータディレクトリ内にある mtg-mcp/v0.9 です。同じルートを使用するすべての MCP プロセスで、decks.db と scryfall.db を共有します。読み取りによってルートが作成されることはありません。

Archidekt を設定する

MTGMCP__ARCHIDEKT__USERNAME と MTGMCP__ARCHIDEKT__PASSWORD を使用するか、次のファイルを作成します。

~/.mtg-mcp/archidekt.json

プロバイダーのオリジンは固定されています。認証出力に認証情報、アカウント情報、認証情報のパスが含まれることはありません。

Playgroup を設定する

MTGMCP__PLAYGROUP__API_KEY を使用するか、次のファイルを作成します。

~/.mtg-mcp/playgroup.json

このファイルには apiKey プロパティが 1 つ含まれます。プロバイダーのオリジンは、公式の公開 API に固定されています。

ローカルデッキを操作する

decks ツールセットは、次の機能をサポートします。

• リビジョン管理されたデッキ、エントリー、ゾーン、カテゴリ、プロバイダー連携の変更
• アトミックな順序付きバッチ処理
• 保護機能付きのバックアップ、復元、削除
• ネイティブ JSON と汎用テキストのインポートおよびエクスポート
• Archidekt と Moxfield 用の手動インポートおよびエクスポートファイル
• Scryfall の正確な識別情報との照合
• 繰り返し可能な結果が得られる、タグルールによるグループ化
• カードデータと呼び出し元が指定する土地ルールに基づく、マナカーブ達成確率の推定

既存のデッキを変更する場合は、毎回 expectedRevision が必要です。ローカルストアは、特定のインポート形式に依存しません。検証では構造を確認しますが、Commander の適法性、カードの質、戦略への適合性は確認しません。

適用する前に deck_identity_reconcile_preview を使用してください。照合には、印刷 ID、セットとコレクター番号、Oracle ID、正確な名前の順で使用します。あいまい検索を使用したり、任意の印刷版を選択したりすることはありません。

呼び出し元が管理するタグルールを評価するには、deck_category_rules_validate、deck_category_rules_preview、deck_category_rules_apply を使用してください。ルールはインラインで指定するか、透明性の高い common-v1 プリセットを使用できます。カテゴリの意味を MCP が決めることはありません。

マナカーブの達成確率を推定する

deck_on_curve_estimate を使用すると、メインボードのカード 1 枚を指定したターンまでに唱えられる頻度をサンプリングできます。保存済みデッキ ID と現在のリビジョン、対象エントリー ID、対象となる各土地のルール、ターン上限を指定し、任意でシードとサンプル数を指定します。結果には、使用したインストール済み Scryfall データの正確な内容、呼び出し元のルール、再現用シード、95% Wilson 信頼区間、失敗回数、最大 2 件のサンプルトレースが含まれます。

バージョン 1 がモデル化するのは、単純な印刷コストと、呼び出し元が説明する単面カードの土地のみです。カードテキストを読み取ったり、土地の挙動を推測したり、ほかのマナソースをモデル化したり、プレイを選択したり、デッキを評価したり、実際のゲームを予測したりすることはありません。

デッキのインポートとエクスポート

保存される内容の制限を確認するには、deck_interchange_formats を使用します。

形式	備考
mtg-mcp-json-v1	損失のないネイティブ形式
generic-text-v1	枚数、名前、ゾーン見出し、印刷版のヒント
archidekt-text-v1	手動インポートとネイティブ形式／カテゴリの補助ファイル
moxfield-bulk-edit-v1	一括編集テキストとネイティブ形式／タグの補助ファイル

これらのプロバイダー向けエクスポートファイルは、プロバイダーに接続しません。除外されたエントリはネイティブ形式の補助ファイルに残り、プロバイダー向けテキストからは省略されます。

Scryfall をクエリする

scryfall ツールセットは、検索、カードの完全一致検索、コレクション検索、印刷版、裁定、セット、カタログ、オートコンプリート、一括メタデータ、タグの根拠、不変スナップショット、明示的なカードデータのダウンロード操作に対応しています。

ローカルのカードデータストアには、すべてのカード、裁定、Oracle タグ、アートタグが含まれます。カードデータのダウンロードは明示的に実行します。起動時やバックグラウンドでは実行されません。

任意：Scryfall の全カードデータをインストールする

完全インストールには、カードレコード、裁定、Oracle タグ、アートタグが含まれます。カード画像は含まれません。ローカルのタグやカードデータを扱うワークフローに便利です。通常のカード検索は、全データがなくてもプロバイダーと小規模なローカルキャッシュを利用できます。

ダウンロードのサイズは数ギガバイトに及び、更新には一時的な作業領域が必要です。local または remote モードの完全データ用ツールを明示的に呼び出した場合にのみ開始してください。公開名の scryfall_corpus_status、scryfall_corpus_sync、scryfall_corpus_rollback、scryfall_corpus_delete は、インストール済みのカードデータを確認・管理する既存の API 名です。

鮮度ポリシーは default、cache-only、refresh です。デフォルトの TTL は 24 時間です。不変スナップショットには有効期限がありません。

scryfall_card_collection は、順序付きの検索行を 150 件受け付けます。まずローカルのカードデータを検索し、プロバイダーへの問い合わせが必要な項目を重複排除してから、最大 75 件ずつプロバイダーに送信します。結果は安定したカーソルページネーションを使用します。

任意のクエリでは、Scryfall が引き続き信頼できる情報源となります。キャッシュが再利用するのは、完全に同じリクエストに限られます。カードの事実情報とコミュニティタグは、別々の種類の情報として扱われます。

Commander Spellbook の根拠を読む

spellbook ツールセットを有効にすると、Commander Spellbook のデータを返す次の 3 つのツールを利用できます。

• spellbook_variant_search は、指定した Commander Spellbook クエリに一致する、件数を制限した 1 ページ分の結果を返します。
• spellbook_variant_get は、ID で指定したソースバリアントを 1 件返します。
• spellbook_deck_combos_find は、保存済みデッキの特定リビジョンから commander と main のエントリのみを送信し、スキップしたエントリを報告します。

各ツールは Commander Spellbook の JSON をそのまま保持し、ソース、リクエスト、取得時刻、キャッシュの状態、チェックサム、制限を明示します。結果の順位付け、カードの役割の推測、コンボやカード変更の推奨は行いません。キャッシュのデフォルトの有効期間は 15 分です。1～1,440 の整数を設定して変更できます。

正確な統計を計算する

stats ツールセットは、次の処理を行う 8 つの読み取り専用ツールを提供します。

• 単変量および多変量の超幾何確率
• ターンごとの確率表
• 呼び出し元が定義するマナソースの利用可能性
• パッケージおよびコンボの完成
• 明示的なマリガンスケジュール
• 最小枚数および最小ソース数の算出
• 決定論的なデッキ構成の要約

すべての確率は、約分済みの正確な分数と、安定した小数値を返します。母集団、グループ、ターンごとのドロー、マナ能力、キープルールは呼び出し元が指定します。MCP が適法性や役割、結果の良し悪しを推測することはありません。

デッキに基づく統計では、エントリ ID、ゾーン名、カテゴリ ID でエントリを選択できます。これにより、LLM は選択したカードを隠すことなく、既存の Archidekt グループや決定論的なカテゴリを利用できます。

Archidekt を同期する

archidekt ツールセットを有効にします。リモートへの書き込みには remote モードを使用します。

アダプターは、所有デッキの一覧取得／取得／作成／削除、プル、プッシュ、差分、フォルダー、名前付きスナップショットに対応しています。適用操作には、最新のリビジョン、フィンガープリント、プレビューの証拠が必要です。MCP が競合の勝者を選ぶことはありません。

リクエストの開始間隔は、設定済みアカウントごとに 2 秒以上です。アダプターは 60 秒間に最大 30 回の開始、ツール呼び出し 1 回あたり最大 150 件のリクエストを許可します。403 と 429 で停止します。結果が不明な変更操作は再試行しません。

Archidekt ではカテゴリーの位置番号が振り直される場合があります。そのため、内容の同一性は、プロバイダーが管理する数値の順位ではなく、カテゴリーの識別情報、所属、フラグ、プライマリー指定を比較して判定します。

Playgroup の証拠を読み取る

playgroup ツールセットを有効にします。ピン留めされた Public API 1.0.0 向けのツールを提供します。すべてのモードに、安全な読み取り専用ツールが 14 個含まれます。remote モードでは、書き込みツールが 2 個追加されます。

結果はプロバイダーの JSON を保持し、操作、API バージョン、取得時刻、チェックサム、制限事項が含まれます。アダプターがデッキを順位付けしたり、品質を推測したりすることはありません。

リクエストの開始間隔は 250 ミリ秒以上です。読み取りには上限付きの再試行があります。書き込みは 1 回のみ試行されます。公開 API にクリーンアップ操作がないため、ライブ受け入れテストでは書き込みを実行しません。

証拠と安全性

サーバーは、次の種類の結果を個別にラベル付けします。

• プロバイダーの事実
• プロバイダーの証拠
• 厳密な導出結果
• パーサーによる分類
• ヒューリスティック
• サンプリングによる推定

安定版 0.9.0 には、アドバイザープロンプト、意図の推測、弱いカードの判定、入れ替えの推奨、複合品質スコア、戦略シミュレーションは含まれていません。延期された作業については、今後の機能 を参照してください。

開発と検証

コマンドメニューには Task を使用します。

task --list
task lint
task test
task benchmark:oncurve
task surface:report
task coverage
task pack
task smoke:process
task smoke:mcp
task release:tool-smoke

通常のテストは決定的で、オフラインで実行されます。ライブテストには明示的なオプトインが必要です。task benchmark:oncurve は、固定の 99 枚デッキを使った個別の Release 測定を実行します。各本番アセンブリでは、行カバレッジを 90 パーセント以上に維持する必要があります。

アーキテクチャ

プロジェクト	担当
MtgMcp.Core	プロバイダーに依存しない契約と証拠
MtgMcp.Decks	ローカルの SQLite デッキと相互運用
MtgMcp.Scryfall	公式の通信処理、カードデータ、スナップショット、リクエスト間隔制御
MtgMcp.Archidekt	確認されたプロバイダー契約と同期
MtgMcp.Playgroup	ピン留めされた公式 API の証拠
MtgMcp.Spellbook	範囲を限定した Commander Spellbook の情報源の証拠とキャッシュ
MtgMcp.Statistics	BCL のみを使った厳密な計算
MtgMcp.OnCurve	純粋で再現可能な、サンプリングによるターンごとのキャスト計算
MtgMcp.App	MCP ホスト、構成、組み立て、スキーマ

長期的に適用される制約については、North Star、設計目標、書き換えガイド をお読みください。

ライセンス

GNU Affero General Public License v3.0 以降 の下でライセンスされています。