Serveur MCP Courtship
Commit 7 nov. 2026Fournit un runtime MCP régi par l'efficacité et un banc d'essai pour contrôler et inspecter les jeux LOVE (Lua).
Aussi connu sous grimmdev/Courtship
- Étoiles
- 0
- Outils
- —
- Téléchargements, 30 jours
- —
- Dernière version
- 1.0.2
- Dernier commit
- 7 nov. 2026
- Licence
- Apache-2.0
Qu'est-ce que Courtship MCP ?
Fournit un runtime MCP régi par l'efficacité et un banc d'essai pour contrôler et inspecter les jeux LOVE (Lua).
Résumé généré à partir du README du projet
À propos du MCP server Courtship
Courtship sert de runtime MCP spécialisé et de banc d'essai conçu pour les développeurs travaillant sur des jeux LOVE (Lua). Il agit comme un proxy régi par l'efficacité entre un client IA, tel que Claude Desktop ou Cursor, et un environnement de jeu en direct. En gérant la manière dont les données sont transmises à l'agent, il empêche l'inflation du contexte et réduit les coûts de tokens grâce à un système de mise en forme des réponses qui élague les graphes d'entités volumineux et compresse les captures d'écran.
Les utilisateurs peuvent le déployer sous forme de binaire statique natif ou via Docker. Le serveur fournit des outils essentiels pour la manipulation de jeux, notamment Agent Joypad pour simuler des entrées clavier, le pas de frame déterministe pour les tests de physique, et des diagnostics de crash sécurisés qui permettent à un agent de se rétablir après une erreur sans perdre la connexion. Il inclut également un index hors ligne de la documentation de l'API LOVE 12 utilisant SQLite FTS5 pour une recherche rapide. Cela en fait un environnement complet pour les tests de jeux automatisés, le débogage et le développement.
Ce que vous pouvez faire avec
- 1Simuler les mouvements du joueurUn agent IA peut exécuter des séquences de touches cadencées pour tester des mécaniques de jeu comme le saut ou la marche.
- 2Déboguer les plantages de jeuLorsqu'un bug survient, l'agent peut inspecter la stack trace et les variables locales pour appliquer un correctif à chaud (hot-fix).
- 3Vérifier la cohérence de la physiqueLes développeurs peuvent utiliser un pas de temps fixe (fixed delta time stepping) pour s'assurer que la physique et les collisions d'un jeu de plateforme sont validées sans jitter temporel.
- 4Réduire la consommation de tokensLe serveur limite la quantité de données envoyées à l'IA en supprimant les champs vides et en plafonnant la profondeur des objets.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Comment installer Courtship MCP
Formats vérifiés le 10 nov. 2026Ajouter à CursorAjouter à GooseInstaller Courtship MCP dans Claude Code
$ claude mcp add courtship -- docker run -i --rm ghcr.io/grimmdev/courtship:1.0.2Installer Courtship MCP dans Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"courtship": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/grimmdev/courtship:1.0.2"
]
}
}
}Installer Courtship MCP dans VS Code
.vscode/mcp.json
{
"servers": {
"courtship": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/grimmdev/courtship:1.0.2"
]
}
}
}Installer Courtship MCP dans VS Code CLI
$ code --add-mcp '{"name":"courtship","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/grimmdev/courtship:1.0.2"]}'Installer Courtship MCP dans Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"courtship": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/grimmdev/courtship:1.0.2"
]
}
}
}Installer Courtship MCP dans Codex
$ codex mcp add courtship -- docker run -i --rm ghcr.io/grimmdev/courtship:1.0.2Installer Courtship MCP dans Codex config.toml
~/.codex/config.toml
[mcp_servers.courtship] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/grimmdev/courtship:1.0.2"]
Installer Courtship MCP dans Gemini CLI
$ gemini mcp add -s user courtship docker -- run -i --rm ghcr.io/grimmdev/courtship:1.0.2Installer Courtship MCP dans Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"courtship": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/grimmdev/courtship:1.0.2"
]
}
}
}Vérifications automatisées
Exécuté le 14 nov. 2026Rapport complet →Pas encore vérifié. Un serveur nécessite un score de 80, aucune faille sérieuse et suffisamment de données pour que nous puissions effectuer les vérifications. Fonctionnement des vérifications · Ce qu'il faut corriger pour gagner des points
- Dépôt source lié et accessiblegrimmdev/courtship is public and reachablegithub.com/grimmdev/courtship ↗Réussi
- Le nom du package correspond au dépôt sourceNon vérifié
- Provenance du build (attestation Sigstore)Non vérifié
- Licence open source (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Réussi
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-11-07github.com/grimmdev/courtship ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNon vérifié
- Aucun avis critique dans le package ou ses dépendancesNon vérifié
- Aucune instruction cachée destinée au modèle0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésNon vérifié
- Le point de terminaison distant répond à la poignée de main MCPNon vérifié
README
Voir sur GitHubThe protocol layer between your agent and your LOVE game.
courtship (court) is an all-in-one, efficiency-governed MCP runtime and task-level benchmarking harness for LOVE game development. It natively encapsulates live-game inspection, code execution, Agent Joypad input simulation, safe crash recovery, and an offline LOVE 12 API docs index in a single zero-dependency static binary, while also capable of acting as a governing efficiency proxy in front of existing upstream servers.
1. Problem & Thesis
The LOVE Model Context Protocol (MCP) ecosystem is functional but ungoverned. Raw bridges emit monolithic game state objects, eager documentation dumps, and hundreds of unpruned keys on every interaction, causing context bloat and runaway token cost.
Courtship acts as the measurement and remediation layer, proving three foundational claims:
| Claim | Goal | Empirically Measured | Status |
|---|---|---|---|
| 1. Standing Context Tax | Cut standing schema context by >=70% | 76.5% reduction (340 vs 1,450 tokens) | Proven |
| 2. Response Shaping Spend | Cut per-task token spend by >=40% | 53.4% average reduction | Proven |
| 3. Unified Router Efficiency | Beat separate MCP servers for mixed tasks | -40% latency, -33% calls via local FTS5 | Proven |
2. Architecture
+-----------------+ 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)
The proxy operates as a daemon with an internal registry, not a dumb passthrough. Tool schemas remain daemon-side until hydrated on-demand, expiring after N inactive turns.
3. GitHub MCP Registry & Client Setup
Courtship is published to the official Model Context Protocol (MCP) Registry under the verified namespace:
io.github.grimmdev/courtship
Installation in VS Code / Cursor / Claude Desktop
Option A: Native Binary (Fastest)
Download the binary from Releases or build via cargo build --release --bin court.
Add to your MCP client configuration (mcp.json or claude_desktop_config.json):
{
"mcpServers": {
"courtship": {
"command": "court",
"args": ["proxy"]
}
}
}
Option B: Containerized via Docker / GitHub Packages
Run without installing local dependencies:
{
"mcpServers": {
"courtship": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/grimmdev/courtship:latest"
]
}
}
}
4. Core Capabilities
4.1 Standing Surface (< 500 Tokens)
Only 5 compact meta-tools are exposed permanently in standing context (~340 tokens), keeping context clean while allowing the agent to discover or invoke any game tool on-demand:
discover_tools(query, limit): Fuzzy discovery without schema ingestion.load_tool_schema(name): Hydrates full JSON schema on-demand.call_tool(name, args): Executes tool through compression filters.love_task(goal, context): Intelligent intent router (docs vs inspect vs exec).report_usage(): Session token, call, and latency accounting.
4.2 Built-in Game Capabilities (Available via call_tool & discover_tools)
simulate_input(sequence): Agent Joypad: Dispatches timed keyboard inputs (press,keydown,keyup).step_frames(count, dt): Deterministic Frame Stepping: Advances physics by N ticks at fixed dt.get_last_crash(): Safe Crash Diagnostics: Non-fatal stack trace and locals recovery.clear_crash(): Resumes game loop after hot-patching.visual_diff(image_a, image_b): Visual Regression: Compares two screenshots and returns bounding boxes.get_objects(): Returns active entity coordinates and types in lean format.get_screenshot(): Returns downscaled, cropped PNG framebuffers.run_lua(code): Evaluates arbitrary Lua inside the game loop.
4.3 Safe Crash Interception (love.errhand override)
Prevents the infamous LOVE "Blue Screen of Death" from crashing the process or severing the MCP bridge when an agent introduces a bug:
- Replaces
love.errhandto pause execution and render an in-game diagnostic HUD rather than terminating. - Extracts offending source file, line number,
debug.traceback(), and active local variables. - Keeps the TCP socket listener active so the agent can inspect the failure via
get_last_crash(), write a fix, and hot-reload.
4.4 Agent Joypad & Deterministic Physics Verification
Enables agents to test game mechanics that require time and movement:
- Input Sequencing: Dispatches timed action series (e.g. hold
Dfor 1.2s, pressSpace, release). - Frame Stepping: Advances
love.update(dt)by exact frame counts at fixed delta time (default1/60), eliminating wall-clock jitter when validating platformer physics and collisions.
4.5 8-Rule Response Shaper
Every tool return and notification passes through deterministic shaping:
- Field Projection: Prunes entity graphs to
{id, type, name, x, y}. - Null/Empty Stripping: Drops empty arrays, objects, and empty strings.
- Depth Capping: Deep object graphs (>3 levels) collapsed to
"<table: N keys>". - Array Slicing & Cursors: Arrays >50 items sliced with cursor hints stored in memory.
- Token Ceiling: Automatically truncates and budgets payloads exceeding
max_tokens. - Screenshot Compression: Region crop and bilinear downscaling (0.5 default) to prevent vision token blowouts.
- Delta Mode: Continuous streams (
watch_game_state) suppress identical ticks to 0 tokens. - Doc Pruning: Strips wiki navigation chrome and deduplicates code samples.
4.6 Zero-Instrumentation Launcher (court run)
Wraps any existing LOVE game dynamically:
court run ./mygame --mcp-port 12345
Automatically mounts source files and hooks love.update, love.draw, and the bridge without modifying your repository. For manual integration, court init generates the 5-line inline hook.
5. Benchmark Results
Running court bench --compare lovepilot,courtship on reference suites:
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% - -
Reference Suites Breakdown
platformer(physics simulation + jump logic): -54.3% tokensui_heavy(draw call stress + minimap + HUD): -52.1% tokensmenu_nested(deep 6-level UI entity tree): -53.9% tokens
6. CLI Reference
Run the MCP Proxy
court proxy --port 12345
court proxy --eager # Fallback exposing full upstream tools
Run Benchmarks & CI Regression Gates
# 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
Launch LOVE Game
court run ./fixtures/platformer
court run ./fixtures/platformer --shim-only
Offline Documentation Index
court docs search "rectangle"
court docs search "love.physics.newWorld"
Environment & Token Tax Audit
court doctor
court doctor --ci
7. Configuration (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. License
Dual-licensed under either:
- MIT License (LICENSE-MIT)
- Apache License, Version 2.0 (LICENSE-APACHE)
Questions sur Courtship MCP
Comment ajouter Courtship MCP à Claude Code ?
Exécutez claude mcp add courtship -- docker run -i --rm ghcr.io/grimmdev/courtship:1.0.2 dans votre terminal. Ajoutez --scope user pour le rendre disponible dans tous les projets.
Comment ajouter Courtship MCP à Cursor ?
Ouvrez ~/.cursor/mcp.json et ajoutez le serveur sous mcpServers, avec la configuration Cursor indiquée dans la section d'installation ci-dessus.
Courtship peut-il empêcher un jeu de planter pendant le développement ?
Oui, il remplace le gestionnaire d'erreurs standard pour mettre l'exécution en pause et fournir un HUD de diagnostic avec les traces de la pile (stack traces) et les variables locales au lieu de terminer le processus.