@leek-wars/mcp

Serveur MCP (Model Context Protocol) officiel de Leek Wars, le jeu où l'on code l'IA de son poireau en LeekScript.

Branche-le à Claude, Cursor, Copilot ou n'importe quel client MCP pour donner à ton agent la documentation du langage, l'accès à ton compte, à ton code d'IA, et la capacité de lancer des combats de test puis d'en lire les rapports.

v1 read-first, soft-launch. Transport local (stdio) ; un endpoint distant (HTTP) viendra pour l'ouverture publique. Le coeur des outils est indépendant du transport.

Installation

Le serveur se lance via npx @leek-wars/mcp (ou node dist/stdio.js en local, depuis les sources).

Claude Code

claude mcp add leekwars --env LEEKWARS_API_KEY=lwk_xxxxxxxx -- npx -y @leek-wars/mcp

Claude Desktop / Cursor / autres (mcp.json)

{
  "mcpServers": {
    "leekwars": {
      "command": "npx",
      "args": ["-y", "@leek-wars/mcp"],
      "env": { "LEEKWARS_API_KEY": "lwk_xxxxxxxx" }
    }
  }
}

Configuration

| Variable | Défaut | Rôle | |---|---|---| | LEEKWARS_API_KEY | — | Clé API scopée (préfixe lwk_), créée depuis les paramètres de ton compte Leek Wars. Requise pour les outils authentifiés. | | LEEKWARS_API_URL | https://leekwars.com/api | Base de l'API. À changer pour cibler une stack locale/beta en développement. |

Les outils de documentation (leekscript_docs, api_reference) fonctionnent sans clé. Les autres nécessitent une clé portant le bon scope.

Outils

| Outil | Rôle requis | Description | |---|---|---| | leekscript_docs | aucun | Recherche dans les fonctions et constantes du langage LeekScript. | | api_reference | aucun | Catalogue des endpoints de l'API HTTP publique. | | get_account | player | Stats du compte : talent, habs, cristaux, classement, poireaux. | | list_ais | player | Arborescence des scripts LeekScript du compte. | | read_ai | player | Code source d'une IA par son chemin. | | list_test_scenarios | player | Scénarios de test enregistrés. | | start_test_fight | player | Lance un combat de test (non classé) depuis un scénario. | | get_fight | public / player | Résultat d'un combat (public) et logs de debug (player). |

Rôles disponibles

Une clé porte un rôle ; les rôles sont cumulatifs (chacun inclut les précédents). Choisis le plus restreint qui suffit.

| Rôle | Couvre | |---|---| | base | Données publiques : classements, profils/poireaux/combats des autres joueurs, game data. Déjà accessibles sans clé. | | player | Ton compte et ton jeu, lecture et écriture : profil, poireaux, loadouts, code des IA, combats de test, marché. | | account | Tout le reste, y compris sensible : messages privés, paramètres du compte. |

Un agent qui code ton IA et lance des combats a besoin du rôle player. data:refresh reste un scope à part, réservé aux administrateurs.

Développement

npm install
npm run build          # compile vers dist/
npm run dev            # tsx watch (rechargement à chaud)
npx tsx src/smoke.ts   # smoke-test en process (liste les outils + outils publics)
npm run typecheck

Cibler une stack locale :

LEEKWARS_API_URL=http://localhost:8500/api LEEKWARS_API_KEY=lwk_xxx npm run dev

Architecture

src/
  config.ts     lecture de l'environnement
  api.ts        client HTTP (auth par clé lwk_, erreurs normalisées)
  helpers.ts    fabriques de résultats MCP + garde d'erreur
  server.ts     createServer(client) — assemblage indépendant du transport
  stdio.ts      point d'entrée stdio (bin)
  tools/        docs · account · ai · fight

createServer(client) renvoie un McpServer prêt à brancher sur n'importe quel transport. L'ajout d'un transport HTTP distant (Streamable HTTP + OAuth) pour l'ouverture publique ne touchera pas les outils.

Notes

• Auth par clé, jamais par session. Les comptes admin sont IP-pinnés côté serveur : un JWT de session ne survivrait pas hors de son IP d'origine. La clé lwk_ scopée est la voie prévue pour un service.
• Rate limit : 5 requêtes/seconde par compte, 10 avec Leek Wars + (RateLimit::LIMIT_AUTHENTICATED × Subscription::RATE_LIMIT_FACTOR). Au-delà, l'API répond 429.
• Le serveur envoie tous ses logs sur stderr ; stdout est réservé au protocole MCP.