isco-tec

scorezilla-mcp

Claude Code や Cursor に頼むだけで、ゲームにグローバルリーダーボードを追加できます。 組み込まれる SDK は gzip 圧縮後で約 5 KB、実行時依存関係はありません。

Scorezilla の公式 Model Context Protocol（MCP）サーバーです。AI コーディングアシスタント（Claude Code、Cursor、Continue.dev など）に接続すれば、エディターを離れずに動作するリーダーボードを公開できます。

AI に依頼できること

• 「ゲームにリーダーボードを追加して」→ ゲームとボードをセットアップし、すぐに実行できる TypeScript SDK コードをプロジェクトに貼り付けます
• 「最後のテストスコアは何位だった？」→ ライブのリーダーボードを読み取ります
• 「ゲームを一覧表示して」／「X のボードを見せて」→ すでにあるものを確認します

ツールは全部で 11 個です。読み取り専用が 5 個、書き込みが 6 個あります。書き込みツールのうち 4 個はリソースを作成し（bootstrap_leaderboard、create_game、create_board、mint_key）、残りの 2 個は設定を更新します（update_board_config — スコアの範囲と保持設定。たとえば不正防止用の maxScore、update_game_config — ブラウザーからの送信を許可するオリジンの許可リスト）。

インストールと設定

アクセス — すべての Scorezilla アカウントで利用できます。 dashboard.scorezilla.dev で無料登録してトークンを作成すれば、すぐに使えます。ゲームとボードの作成数はプランの上限に含まれます（Free：ゲーム 2 個 × 各 3 ボード）。上限に達すると、ツールのエラーにアップグレードへの直接リンクが表示されます。料金をご覧ください。

1. トークンを取得する

dashboard.scorezilla.dev にサインインし、MCP tokens を開いて Create token をクリックします。mcp_live_* の値を一度だけコピーしてください。再表示されません。

2. MCP サーバーを AI コーディングアシスタントに追加する

Claude Code — 次のコマンドを 1 つ実行します（--scope user を指定すると、すべてのプロジェクトで使えるようになります）。

claude mcp add scorezilla --scope user -e SCOREZILLA_TOKEN=mcp_live_… -- npx -y @scorezilla/mcp

Cursor — ~/.cursor/mcp.json に次の内容を追加します（または「Settings → MCP → Add new MCP server」から追加します）。

{
  "mcpServers": {
    "scorezilla": {
      "command": "npx",
      "args": ["-y", "@scorezilla/mcp"],
      "env": {
        "SCOREZILLA_TOKEN": "mcp_live_…"
      }
    }
  }
}

🔒 MCP の設定は非公開にしてください。 どちらのクライアントもトークンを平文で保存します（Claude Code は ~/.claude.json、Cursor は ~/.cursor/mcp.json）。Git にコミットしたり、公開 dotfiles リポジトリと同期したり、共有場所にバックアップしたりしないでください。macOS/Linux では、ファイルを chmod 600 にして、自分だけが読み取れるようにしてください。トークンが漏えいした場合は、dashboard.scorezilla.dev/account/tokens で無効化してください。

Claude Desktop — ワンクリックで設定できます。最新リリースから scorezilla-mcp.mcpb をダウンロードしてダブルクリックし、Claude Desktop に求められたら mcp_live_… トークンを貼り付けてください。トークンはシステムの安全な認証情報ストアに保存されます。

その他の MCP 対応クライアント — 環境変数に SCOREZILLA_TOKEN を設定し、クライアントから npx -y @scorezilla/mcp を指定してください。

3. 依頼する

Claude Code または Cursor で、「このゲームに Scorezilla のリーダーボードを追加して」 と依頼します。

ツール

ツール	機能
list_games	ゲームの一覧を表示します。まずこれを使って状況を確認してください。
list_boards	ゲーム内のリーダーボードを一覧表示します。
get_keys	公開キー（埋め込みに使用しても安全です）とシークレットキーのプレフィックスを返します。シークレットキー全体がダッシュボードから外部に出ることはありません。
get_board_top_n	リーダーボードの上位エントリーを返します。「連携が機能しているか」を確認するためのツールです。
get_sdk_snippet	リーダーボード用のすぐに貼り付けられる連携コードを返します。オプションの軸引数で、匿名／OAuth ID、クライアントのみかサーバー検証付きのチート対策か、サーバー言語（TS／Python／Go／C#）を指定できます。
bootstrap_leaderboard	新しいゲームと最初のリーダーボードを1回の呼び出しで作成し、ウィジェット埋め込みコード、SDK スニペット、平易な英語での推奨事項を返します。オプションの軸引数（チート対策、OAuth、サーバー言語）も同様に指定できます。90秒デモ向けの手順です。
create_game	空の新しいゲームを作成します。すでにゲームが存在する場合（そのため bootstrap_leaderboard が競合する場合）や、別のゲームを作成したい場合に使用します。
create_board	既存のゲーム（gameId で指定）に、すべてのオプション（sortDir、scoreKind、retention、bounds）を設定してリーダーボードを追加します。
mint_key	既存のゲーム用に新しい公開キー／シークレットキーのペアを発行します。シークレットキーは一度だけ表示されます。
update_board_config	リーダーボードのスコア範囲（チート対策の maxScore など）と保持期間を変更します。一部の項目のみ更新できます。null を指定すると範囲の上限または下限を解除します。
update_game_config	ゲームのブラウザー送信元許可リスト（https://yourgame.com、*.yourgame.com など）を設定します。リストが空の場合、すべての送信元が許可されます。

再試行

作成ツール（bootstrap_leaderboard、create_game、create_board、mint_key）は、引数から生成した Idempotency-Key を送信します。呼び出しがタイムアウトし、5分以内に同じ引数でアシスタントが再試行すると、API は重複を作成せず、元の結果を返します。bootstrap_leaderboard では同じゲームとリーダーボードが、mint_key では同じキーのペアが返されます。

その期間を過ぎた場合、または bootstrap_leaderboard が partial_failure や slug_taken_active を返した場合は、再度ブートストラップしないでください。list_games（および list_boards）を呼び出して既存の内容を確認し、その後 create_board または mint_key で完了してください。

プランの上限

ゲームとリーダーボードの作成は、Scorezilla プランの上限（Free：ゲーム2個 × 各3ボード）にカウントされます。料金をご覧ください。書き込みによって上限を超える場合、ツールは上限とアップグレードへの直接リンクを含む plan_limit エラーを返します。アシスタントはその情報を伝えることができます。自動的に請求されることはありません。リクエストにはトークン単位およびアカウント単位のレート制限も適用されます。rate_limited エラーには再試行可能な時刻が示されます。

フラグ

scorezilla-mcp [--read-only] [--base-url=<url>] [--version] [--help]

• --read-only — 書き込みツール（bootstrap_leaderboard、create_game、create_board、mint_key、update_board_config、update_game_config）の登録を拒否します。共有設定やCI設定で使用すると、AIがリソースを作成または変更できないようにできます。
• --base-url=<url> — API のオリジンを上書きします。デフォルトは https://api.scorezilla.dev です。セルフホスト環境やステージング環境で便利です。

環境変数

• SCOREZILLA_TOKEN — 必須。dashboard.scorezilla.dev/account/tokensで発行されるベアラートークンです。
• SCOREZILLA_BASE_URL — --base-url と同じ設定ですが、環境変数で指定します。両方が設定されている場合はCLIフラグが優先されます。
• SCOREZILLA_BETA_TOKEN — 不要になりました。MCP はすべてのアカウントで利用できます。互換性のために残されており、設定されている場合は X-MCP-Beta として送信されます。

トークンの仕組み

• トークンは発行した開発者に紐づけられており、そのアカウントに関連付けられたすべてのゲームにアクセスできます。
• MCP サーバーがゲームのシークレットキーの平文を返すことはありません。必要な場合は、ダッシュボードからコピーしてください。
• トークンはいつでもdashboard.scorezilla.dev/account/tokensで取り消せます。取り消しは数秒以内に反映されます。
• トークンはベアラー認証情報です。値を知っている人は誰でも、あなたになり代わって API を呼び出せます。ソースコードにコミットしたり、共有チャットに貼り付けたりしないでください。env ブロック、パスワードマネージャー、またはシークレットストアで管理してください。

ランタイム要件

• Node ≥ 20
• https://api.scorezilla.dev へのネットワーク接続

リリース

リリースは CI によって実行され、npm-publish GitHub Environment での承認クリックが必要です。全体の流れは次のとおりです。

1. ローカルで変更セットを作成します。 pnpm changeset を実行し、変更内容とバージョンの更新種別を記述します。ファイルを .changeset/ の下にコミットします。
2. main にマージします。 .github/workflows/release.yml が実行され、package.json のバージョンを更新し、scripts/sync-server-json-version.mjs で server.json（MCP Registry マニフェスト）を同期し、CHANGELOG.md を更新する「chore(release): version @scorezilla/mcp」PR が作成されます。
3. バージョン更新 PR をマージします。 その後、同じワークフローが次の処理を公開します。
   • --provenance を付けた npm tarball（GH OIDC と sigstore による検証可能なビルドアテステーション）、および @scorezilla/mcp@<version> git タグと GitHub リリース（CHANGELOG.md のリリースノート）
   • 公開済み tarball をインストールしてバイナリを実行する公開後のスモークテスト
   • スモークテストの成功後に限り、mcp-publisher login github-oidc → mcp-publisher publish で MCP Registry のレコードを公開します。npm でバージョンが配信されるまで待機し、Registry からまだ見えない場合は再試行します。
4. 公開前のガードが実行されます。内容は、型チェック、テスト、ビルド、バイナリのスモークテスト（node dist/index.js --version）、および release:check（package.json と server.json のバージョンが一致することを検証）です。

開発者のターミナルから手動で公開することも引き続き可能です（bash scripts/publish.sh）。ただし、これは CI のリリース経路ではなく、provenance と承認ゲートが省略されます。一時的な復旧の場合にのみ使用してください。

問題・フィードバック

GitHub Issues。

ライセンス

MIT。