Courtship

---

1. 課題と基本方針

LOVE Model Context Protocol（MCP）エコシステムは機能していますが、統制されていません。生のブリッジは、モノリシックなゲーム状態オブジェクト、先回りしたドキュメントのダンプ、削減されていない何百ものキーをインタラクションのたびに出力するため、コンテキストが肥大化し、トークンコストが際限なく増大します。

Courtshipは測定と是正を担うレイヤーとして、次の3つの基本的な主張を実証します。

主張	目標	実測値	状態
1. 常駐コンテキストの負担	常駐スキーマのコンテキストを70%以上削減	76.5%削減（340トークン対1,450トークン）	実証済み
2. 応答整形によるコスト	タスクごとのトークン消費量を40%以上削減	平均53.4%削減	実証済み
3. 統合ルーターの効率性	複合タスクで個別のMCPサーバーを上回る	ローカルFTS5によりレイテンシ40%減、呼び出し33%減	実証済み

---

2. アーキテクチャ

+-----------------+       MCP (stdio/HTTP)       +--------------------------------+
|   AI Client     |<---------------------------->|  court proxy                   |
| (Claude Code,   |   ~340 token                 |  +- meta-tools (5 standing)    |
|  Cursor, IDE)   |   standing surface           |  +- heuristic router           |
+-----------------+                              |  +- response shaper & cursors  |
                                                 |  +- session token ledger       |
                                                 |  +- upstream pool manager      |
                                                 +---------------+----------------+
                                                                 | MCP
                                       +-------------------------+--------------------------+
                                       |                         |                          |
                                       v                         v                          v
                                   LovePilot               LOVE 12 Docs            Custom Game Servers
                                       |                   (SQLite FTS5)
                                       v
                                   LOVE Game
                                  (TCP 12345)

このプロキシは、単なるパススルーではなく、内部レジストリを備えたデーモンとして動作します。ツールのスキーマはデーモン側に保持され、必要に応じてオンデマンドで読み込まれます。Nターンにわたって使用されない場合は期限切れになります。

---

3. GitHub MCPレジストリとクライアントのセットアップ

Courtshipは、検証済みの名前空間で公式Model Context Protocol（MCP）レジストリに公開されています。

io.github.grimmdev/courtship

VS Code／Cursor／Claude Desktopへのインストール

オプションA：ネイティブバイナリ（最速）

Releasesからバイナリをダウンロードするか、cargo build --release --bin courtでビルドします。

MCPクライアントの設定（mcp.jsonまたはclaude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "courtship": {
      "command": "court",
      "args": ["proxy"]
    }
  }
}

オプションB：Docker／GitHub Packagesを使ったコンテナ化

ローカルの依存関係をインストールせずに実行できます。

{
  "mcpServers": {
    "courtship": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/grimmdev/courtship:latest"
      ]
    }
  }
}

---

4. 主な機能

4.1 常駐インターフェース（500トークン未満）

常駐コンテキストでは、コンパクトなメタツール5つだけを常時公開します（約340トークン）。これにより、コンテキストをすっきり保ちながら、エージェントは必要に応じて任意のゲームツールを見つけて呼び出せます。

• discover_tools(query, limit)：スキーマを読み込まずに、あいまい検索でツールを見つけます。
• load_tool_schema(name)：完全なJSONスキーマをオンデマンドで読み込みます。
• call_tool(name, args)：圧縮フィルターを通してツールを実行します。
• love_task(goal, context)：インテントをインテリジェントに振り分けるルーター（ドキュメント参照／検査／実行）。
• report_usage()：セッションのトークン数、呼び出し回数、レイテンシを集計します。

4.2 組み込みゲーム機能（call_tool と discover_tools から利用可能）

• simulate_input(sequence): エージェント用ジョイパッド：時間指定のキーボード入力（press、keydown、keyup）を送信します。
• step_frames(count, dt): 決定論的なフレームステップ：固定の dt で物理演算を N ティック進めます。
• get_last_crash(): 安全なクラッシュ診断：致命的でないスタックトレースとローカル変数を取得します。
• clear_crash(): ホットパッチ適用後にゲームループを再開します。
• visual_diff(image_a, image_b): ビジュアルリグレッション：2 つのスクリーンショットを比較し、バウンディングボックスを返します。
• get_objects(): 有効なエンティティの座標と種類を簡潔な形式で返します。
• get_screenshot(): 縮小・切り抜き済みの PNG フレームバッファーを返します。
• run_lua(code): ゲームループ内で任意の Lua を評価します。

4.3 安全なクラッシュのインターセプト（love.errhand のオーバーライド）

エージェントがバグを導入しても、プロセスがクラッシュしたり MCP ブリッジが切断されたりしないよう、悪名高い LOVE の 「ブルースクリーン」 を防ぎます。

• love.errhand を置き換え、終了する代わりに実行を一時停止し、ゲーム内に診断 HUD を表示します。
• 問題のあるソースファイル、行番号、debug.traceback()、有効なローカル変数を抽出します。
• TCP ソケットのリスナーを有効なまま維持するため、エージェントは get_last_crash() で障害を調査し、修正を作成してホットリロードできます。

4.4 エージェント用ジョイパッドと決定論的な物理演算の検証

時間や移動を必要とするゲームの仕組みを、エージェントがテストできるようにします。

• 入力シーケンス：時間指定のアクション系列（例：D を 1.2 秒間押し続け、Space を押してから離す）を送信します。
• フレームステップ：固定のデルタ時間（デフォルトは 1/60）で正確なフレーム数分だけ love.update(dt) を進めます。これにより、プラットフォーマーの物理演算や衝突を検証する際の実時間の揺らぎを排除します。

4.5 8 ルールのレスポンスシェイパー

すべてのツールの戻り値と通知に、決定論的な整形を適用します。

1. フィールドの射影：エンティティグラフを {id, type, name, x, y} に絞り込みます。
2. null／空値の削除：空の配列、オブジェクト、文字列を除外します。
3. 深度の上限設定：深いオブジェクトグラフ（3 階層超）を "<table: N keys>" にまとめます。
4. 配列の分割とカーソル：50 件を超える配列を分割し、カーソルのヒントをメモリに保存します。
5. トークン上限：max_tokens を超えるペイロードを自動的に切り詰め、予算内に収めます。
6. スクリーンショットの圧縮：リージョンの切り抜きとバイリニア縮小（デフォルト 0.5）により、ビジョントークンの急増を防ぎます。
7. 差分モード：連続ストリーム（watch_game_state）では、同一のティックを抑制してトークン消費を 0 にします。
8. ドキュメントの整理：Wiki のナビゲーション要素を取り除き、コードサンプルの重複を排除します。

4.6 計測不要のランチャー（court run）

既存の LOVE ゲームを動的にラップします。

court run ./mygame --mcp-port 12345

リポジトリを変更することなく、ソースファイルを自動的にマウントし、love.update、love.draw、ブリッジをフックします。手動で統合する場合は、court init で 5 行のインラインフックを生成できます。

---

5. ベンチマーク結果

参照スイートに対して court bench --compare lovepilot,courtship を実行した結果：

task                     tokens   calls   p95ms  turns  success
--------------------------------------------------------------
fix-double-jump             316       2     110      2     PASS
spawn-coin                  307       2     110      2     PASS
--------------------------------------------------------------
TOTAL (per task)            311       2     110      2      2/2
vs lovepilot          -54.3%   -33%    -40%     -         -

参照スイートの内訳

• platformer（物理演算シミュレーション＋ジャンプロジック）：トークンを -54.3% 削減
• ui_heavy（描画呼び出しの負荷テスト＋ミニマップ＋HUD）：トークンを -52.1% 削減
• menu_nested（6 階層の深い UI エンティティツリー）：トークンを -53.9% 削減

---

6. CLI リファレンス

MCP プロキシを実行する

court proxy --port 12345
court proxy --eager # Fallback exposing full upstream tools

ベンチマークと CI リグレッションゲートを実行する

# Compare candidate against raw baseline
court bench --suite ./suites/platformer.yaml --compare lovepilot,courtship

# Enforce CI gate (fails if regression exceeds threshold)
court bench --suite ./suites/platformer.yaml --ci --max-regression 10.0

# Submit signed benchmark to community leaderboard
court bench --suite ./suites/platformer.yaml --compare lovepilot,courtship --submit

LOVE ゲームを起動する

court run ./fixtures/platformer
court run ./fixtures/platformer --shim-only

オフラインドキュメントインデックス

court docs search "rectangle"
court docs search "love.physics.newWorld"

環境とトークンコストの監査

court doctor
court doctor --ci

---

7. 設定（courtship.toml）

[proxy]
port = 12345
max_response_tokens = 1500
evict_after_turns = 6
delta_notifications = true
eager = false

[upstream.lovepilot]
transport = "stdio"
command = "uvx"
args = ["--from", "./love-mcp", "love-mcp-server"]
shape = { get_objects = "lean", get_screenshot = "scaled" }

[upstream.docs]
transport = "builtin"
index = "./lua54-love12.sqlite"

[bench]
suite_dir = "./suites"
baseline = ".courtship/baseline.json"
max_regression = "10%"

---

8. ライセンス

次のいずれかのライセンスの下でデュアルライセンスされています。

• MIT License（LICENSE-MIT）
• Apache License, Version 2.0（LICENSE-APACHE）