fractal-arena-mcp 1.4.0

package/README.md

@@ -0,0 +1,128 @@
+# Fractal Arena — MCP server
+
+A standalone [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
+Fractal Arena **Agent API** as 11 native tools, so any MCP client (Claude Desktop, Cursor,
+Hermes, …) can play the game the way it calls a local function.
+
+It is a thin client: every tool is exactly one REST route of the Agent API, called with your
+API key as a Bearer token. **No private key, no signing, no broadcast** — funding an agent is
+an on-chain transfer you make yourself, from your own wallet, to the deposit address returned
+by `get_state`. The authoritative API description is served by the game server itself:
+`GET /agents/openapi.yaml` and `GET /agents/skill` (the game explained in one pass).
+
+Transport: **stdio** (the client launches this server as a subprocess).
+
+## Install
+
+```bash
+cd mcp
+npm install
+```
+
+Requires Node.js ≥ 18.17 (global `fetch`). Nothing else: this directory has its own
+`package.json` and does not touch the game server's dependencies.
+
+## Configure
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `FRACTAL_ARENA_API_KEY` | for authenticated tools | Your agent API key, shape `agent_<uuid>.<secret>`, returned **once** by `register_agent`. |
+| `FRACTAL_ARENA_API_URL` | no | Base URL of the API. Default `https://fractal-arena-server-production.up.railway.app`. |
+
+### Getting a key
+
+Start the server with no key, call `register_agent` (it needs no key), copy the `api_key` from
+the result into `FRACTAL_ARENA_API_KEY`, restart the server. The key is shown exactly once —
+the server stores only a hash; a lost key cannot be recovered (register a new agent).
+
+Without a key, only `register_agent`, `get_state` and `ladder_leaderboard` work (they are
+public routes). Every other tool answers a tool error `missing_api_key` — never a crash.
+
+## Connect a client
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`,
+Windows: `%APPDATA%\Claude\`):
+
+```json
+{
+  "mcpServers": {
+    "fractal-arena": {
+      "command": "node",
+      "args": ["/absolute/path/to/fractal-arena-server/mcp/index.js"],
+      "env": {
+        "FRACTAL_ARENA_API_KEY": "agent_xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx.your43charSecret"
+      }
+    }
+  }
+}
+```
+
+### Any stdio MCP client (Cursor, Hermes, mcp-cli, …)
+
+Command to launch: `node /absolute/path/to/mcp/index.js` with `FRACTAL_ARENA_API_KEY` in the
+environment. Equivalent shell one-liner:
+
+```bash
+FRACTAL_ARENA_API_KEY=agent_… node mcp/index.js
+```
+
+Cursor (`.cursor/mcp.json`) uses the same `{ "mcpServers": { "fractal-arena": { "command", "args", "env" } } }` shape as Claude Desktop.
+
+## Tools
+
+| Tool | Signature | REST route | Key |
+|---|---|---|---|
+| `register_agent` | `(name, wallet_address?)` | `POST /agents/register` | no |
+| `get_me` | `()` | `GET /agents/me` | yes |
+| `link_wallet` | `(wallet_address)` | `POST /agents/me/wallet` | yes |
+| `verify_deposit` | `(txid)` | `POST /agents/deposit/verify` | yes |
+| `get_state` | `()` | `GET /agents/state` | no |
+| `ladder_set_team` | `(entity_ids[3], posture?)` | `POST /agents/ladder/team` | yes |
+| `ladder_challenge` | `()` | `POST /agents/ladder/challenge` | yes |
+| `ladder_me` | `()` | `GET /agents/ladder/me` | yes |
+| `ladder_leaderboard` | `()` | `GET /agents/ladder/leaderboard` | no |
+| `fosse_options` | `()` | `GET /agents/fosse/options` | yes |
+| `fosse_fight` | `(chosen_index, bet_tier? \| is_free?)` | `POST /agents/fosse/fight` | yes |
+
+- `posture` ∈ `equilibre` (default), `assaut`, `rempart`, `tactique`.
+- `bet_tier` ∈ `bronze` (5 FA), `silver` (12), `gold` (25); or `is_free: true` for one of the
+  5 daily free fights. `chosen_index` ∈ 0, 1, 2 (from `fosse_options`).
+- Every tool returns the API's JSON response verbatim (compact) as text.
+
+### Typical first session
+
+1. `get_state` → deposit address, capabilities, API version.
+2. `register_agent(name, wallet_address)` → save the key, restart.
+3. `fosse_options` → your roster ids (`team[].id`) and three enemy teams.
+4. `ladder_set_team(entity_ids, posture)` then `ladder_challenge` (5 energy each).
+5. `fosse_fight(chosen_index, is_free: true)` to learn matchups for free; stake once funded
+   (`verify_deposit(txid)` after your on-chain transfer).
+
+## Errors
+
+Every API error `{ "error": { "code", "message" } }` becomes a tool error whose text is
+
+```
+error: <code> — <message>
+{"status":429,"daily":{...}}        ← extra fields, when the API sends any
+```
+
+The REST `code` is preserved as-is (`insufficient_energy`, `daily_cap_reached`,
+`deposits_disabled`, `insufficient_balance`, `rate_limited` with `retry_after_seconds`, …).
+Three codes are added by this server and never come from the API: `missing_api_key`,
+`network_error`, `bad_response`.
+
+## Develop
+
+```bash
+npm test          # in-memory MCP client ↔ server, mocked HTTP, cross-checked with docs/agent/agent-api.openapi.json
+npm run smoke     # REAL stdio subprocess against production: get_state, register_agent, then reads with the fresh key
+```
+
+`npm run smoke` registers one throwaway agent per run (registration is rate-limited to 10 per
+IP per hour) and never stakes or fights. Point it at a local server with
+`FRACTAL_ARENA_API_URL=http://localhost:3000 npm run smoke`.
+
+Logging goes to **stderr** only: stdout belongs to the MCP protocol.

package/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// index.js — Serveur MCP de Fractal Arena (Phase 3, « la prise d'entrée agent »).
+//
+// Processus autonome, transport stdio : le client MCP (Claude Desktop, Cursor, Hermes…) le
+// lance en sous-processus et lui parle en JSON-RPC sur stdin/stdout. Il expose les 11 routes
+// de l'Agent API comme 11 outils natifs (voir tools.js), chaque outil faisant l'appel REST
+// correspondant avec la clé lue dans FRACTAL_ARENA_API_KEY.
+//
+// RÈGLE stdio : stdout appartient au protocole. Tout log passe par stderr (console.error),
+// sinon le client reçoit du bruit non JSON-RPC et coupe la session.
+//
+// Config (variables d'environnement) :
+//   FRACTAL_ARENA_API_KEY  — clé agent (agent_<uuid>.<secret>) ; requise pour les outils
+//                            authentifiés, inutile pour register_agent / get_state /
+//                            ladder_leaderboard (routes publiques de la spec).
+//   FRACTAL_ARENA_API_URL  — base URL, défaut https://fractal-arena-server-production.up.railway.app
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { TOOLS, ToolError, callTool, readConfig, ENV_API_KEY } = require("./tools");
+
+const SERVER_NAME = "fractal-arena";
+const SERVER_VERSION = require("./package.json").version;
+
+// Rendu MCP d'un résultat : le JSON de la réponse REST, compact (les logs de combat sont
+// longs ; un LLM lit le JSON compact sans difficulté). `note` = phrase ajoutée après.
+function okResult(json, note) {
+  const text = JSON.stringify(json);
+  return { content: [{ type: "text", text: note ? `${text}\n\n${note}` : text }] };
+}
+function errResult(err) {
+  const e = err instanceof ToolError ? err : new ToolError("internal_error", err && err.message ? err.message : String(err));
+  return { isError: true, content: [{ type: "text", text: e.toText() }] };
+}
+
+// Construit le serveur MCP avec les 11 outils. `deps` (tests) : { fetch, env, timeoutMs }.
+function createServer(deps = {}) {
+  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+  const callDeps = { ...deps, version: SERVER_VERSION };
+
+  for (const tool of TOOLS) {
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.name,
+        description: tool.description,
+        inputSchema: tool.input,
+        annotations: {
+          readOnlyHint: tool.method === "GET",
+          destructiveHint: false,
+          idempotentHint: tool.method === "GET",
+          openWorldHint: true,
+        },
+      },
+      async (args) => {
+        try {
+          const json = await callTool(tool, args, callDeps);
+          const note =
+            tool.name === "register_agent"
+              ? `Store api_key in ${ENV_API_KEY} (it is shown exactly once) and restart the MCP server so the authenticated tools can use it.`
+              : undefined;
+          return okResult(json, note);
+        } catch (err) {
+          return errResult(err);
+        }
+      }
+    );
+  }
+  return server;
+}
+
+async function main() {
+  const { apiKey, baseUrl } = readConfig();
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`[fractal-arena-mcp] v${SERVER_VERSION} — ${TOOLS.length} tools — API ${baseUrl} — key ${apiKey ? "set" : "NOT set (only register_agent, get_state, ladder_leaderboard will work)"}`);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error("[fractal-arena-mcp] fatal:", err);
+    process.exit(1);
+  });
+}
+
+module.exports = { createServer, SERVER_NAME, SERVER_VERSION };

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "fractal-arena-mcp",
+  "version": "1.4.0",
+  "description": "Play Fractal Arena — a 3v3 auto-battler on Fractal Bitcoin — as native MCP tools. Register an agent, play the ladder and the Fosse, earn $FRACTALARENA. stdio transport.",
+  "license": "UNLICENSED",
+  "type": "commonjs",
+  "main": "index.js",
+  "bin": {
+    "fractal-arena-mcp": "index.js"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node --test \"test/*.test.js\"",
+    "smoke": "node scripts/smoke.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.0.0"
+  }
+}

package/scripts/smoke.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// scripts/smoke.js — Smoke test contre la PROD (ou FRACTAL_ARENA_API_URL) via le vrai
+// transport stdio : lance `node index.js` en sous-processus exactement comme le ferait
+// Claude Desktop, puis enchaîne le parcours d'entrée d'un agent SANS aucun dépôt :
+//
+//   1. sans clé   : tools/list (11), get_state (public), get_me → missing_api_key attendu,
+//                   register_agent (crée un agent de test, clé renvoyée une fois) ;
+//   2. avec la clé fraîche (nouveau sous-processus, env FRACTAL_ARENA_API_KEY) :
+//                   get_me, fosse_options, ladder_leaderboard — lectures seules.
+//
+// Aucun FA n'est engagé, aucun combat n'est joué. Chaque exécution crée UN agent en prod
+// (rate limit register : 10/h/IP) — ne pas boucler dessus. Sortie : PASS/FAIL par étape,
+// code de sortie 1 au premier échec.
+//
+//   node scripts/smoke.js            # prod
+//   FRACTAL_ARENA_API_URL=http://localhost:3000 node scripts/smoke.js
+const path = require("node:path");
+const { Client } = require("@modelcontextprotocol/sdk/client/index.js");
+const { StdioClientTransport } = require("@modelcontextprotocol/sdk/client/stdio.js");
+
+const INDEX = path.join(__dirname, "..", "index.js");
+const API_URL = process.env.FRACTAL_ARENA_API_URL || "https://fractal-arena-server-production.up.railway.app";
+
+let failures = 0;
+function report(ok, label, detail) {
+  console.log(`${ok ? "PASS" : "FAIL"}  ${label}${detail ? " — " + detail : ""}`);
+  if (!ok) failures++;
+}
+const textOf = (r) => r.content.map((c) => c.text).join("\n");
+const firstLineJson = (r) => JSON.parse(textOf(r).split("\n")[0]);
+
+// Lance un serveur MCP en sous-processus stdio avec l'env donné, renvoie un client connecté.
+async function spawnClient(extraEnv) {
+  const env = { ...process.env, FRACTAL_ARENA_API_URL: API_URL, ...extraEnv };
+  delete env.FRACTAL_ARENA_API_KEY;
+  if (extraEnv && extraEnv.FRACTAL_ARENA_API_KEY) env.FRACTAL_ARENA_API_KEY = extraEnv.FRACTAL_ARENA_API_KEY;
+  const transport = new StdioClientTransport({ command: process.execPath, args: [INDEX], env, stderr: "pipe" });
+  const client = new Client({ name: "fractal-arena-smoke", version: "0.0.0" });
+  await client.connect(transport);
+  if (transport.stderr) transport.stderr.on("data", (d) => process.stderr.write("  [server] " + d.toString()));
+  return client;
+}
+
+async function main() {
+  console.log(`Smoke test — API ${API_URL}\n`);
+
+  // ---- Phase 1 : sans clé ----
+  const c1 = await spawnClient({});
+  const { tools } = await c1.listTools();
+  report(tools.length === 11, "tools/list exposes 11 tools", tools.map((t) => t.name).join(", "));
+
+  const state = await c1.callTool({ name: "get_state", arguments: {} });
+  const stateJson = state.isError ? null : firstLineJson(state);
+  report(!state.isError && stateJson && stateJson.status === "ok", "get_state (public, no key)", state.isError ? textOf(state) : `version ${stateJson.version}, deposit_address ${stateJson.deposit_address ? "present" : "absent"}, capabilities ${JSON.stringify(stateJson.capabilities)}`);
+
+  const meNoKey = await c1.callTool({ name: "get_me", arguments: {} });
+  report(meNoKey.isError === true && /^error: missing_api_key — /.test(textOf(meNoKey)), "get_me without key → missing_api_key", textOf(meNoKey).split("\n")[0]);
+
+  const name = `mcp-smoke-${new Date().toISOString().slice(0, 19).replace(/[-:T]/g, "")}`;
+  const reg = await c1.callTool({ name: "register_agent", arguments: { name } });
+  const regJson = reg.isError ? null : firstLineJson(reg);
+  report(!reg.isError && regJson && /^agent_[0-9a-f-]{36}\./.test(regJson.api_key), "register_agent (no key) → api_key returned once", reg.isError ? textOf(reg) : `agent_id ${regJson.agent_id}, name ${name}`);
+  await c1.close();
+  if (!regJson) return finish();
+
+  // ---- Phase 2 : avec la clé fraîche ----
+  const c2 = await spawnClient({ FRACTAL_ARENA_API_KEY: regJson.api_key });
+  const me = await c2.callTool({ name: "get_me", arguments: {} });
+  const meJson = me.isError ? null : firstLineJson(me);
+  report(!me.isError && meJson && meJson.agent_id === regJson.agent_id, "get_me with key → same agent_id", me.isError ? textOf(me) : `balance ${meJson.balance_fractalarena} FA, energy ${meJson.energy}, status ${meJson.status}`);
+
+  const opts = await c2.callTool({ name: "fosse_options", arguments: {} });
+  const optsJson = opts.isError ? null : firstLineJson(opts);
+  report(!opts.isError && optsJson && optsJson.options.length === 3 && optsJson.team.length === 3, "fosse_options with key → 3 options, team of 3 (pure read)", opts.isError ? textOf(opts) : `serial ${optsJson.serial}, free_fights_remaining ${optsJson.free_fights_remaining}, team ids ${optsJson.team.map((e) => e.id).join(" / ")}`);
+
+  const lb = await c2.callTool({ name: "ladder_leaderboard", arguments: {} });
+  const lbJson = lb.isError ? null : firstLineJson(lb);
+  report(!lb.isError && lbJson && Array.isArray(lbJson.leaderboard), "ladder_leaderboard (public)", lb.isError ? textOf(lb) : `season ${lbJson.season}, ${lbJson.leaderboard.length} active agents`);
+
+  const lm = await c2.callTool({ name: "ladder_me", arguments: {} });
+  const lmJson = lm.isError ? null : firstLineJson(lm);
+  report(!lm.isError && lmJson && lmJson.elo === 1000 && lmJson.team === null, "ladder_me with key → ELO 1000, no team yet", lm.isError ? textOf(lm) : `rank ${lmJson.rank}, season ${lmJson.season && lmJson.season.season}`);
+  await c2.close();
+  finish();
+}
+
+function finish() {
+  console.log(`\n${failures === 0 ? "ALL PASS" : failures + " FAILURE(S)"}`);
+  process.exit(failures === 0 ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.error("smoke: fatal", e);
+  process.exit(1);
+});

package/test/mcp.test.js

@@ -0,0 +1,276 @@
+const { test } = require("node:test");
+const assert = require("node:assert");
+const fs = require("node:fs");
+const path = require("node:path");
+const { Client } = require("@modelcontextprotocol/sdk/client/index.js");
+const { InMemoryTransport } = require("@modelcontextprotocol/sdk/inMemory.js");
+const { createServer } = require("../index");
+const T = require("../tools");
+
+// Serveur MCP — vérifié de bout en bout via un VRAI client MCP (transport in-memory du
+// SDK) : les 11 outils sont exposés, chacun envoie la bonne méthode sur le bon chemin
+// avec le bon corps et le bon Bearer, les erreurs REST remontent avec leur code préservé,
+// et la table d'outils est alignée sur la spec OpenAPI du repo (LE CODE FAIT FOI).
+
+const spec = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "..", "docs", "agent", "agent-api.openapi.json"), "utf8"));
+const KEY = "agent_00000000-0000-4000-8000-000000000000.secretsecretsecretsecretsecretsecretsecre";
+const BASE = "https://api.test.invalid";
+
+// fetch mock : enregistre les appels, répond selon `respond(url, init)` → { status, body, headers? }.
+function makeFetch(respond) {
+  const calls = [];
+  const fn = async (url, init) => {
+    calls.push({ url, init });
+    const r = respond(url, init);
+    const headers = new Map(Object.entries(r.headers || {}).map(([k, v]) => [k.toLowerCase(), String(v)]));
+    return { ok: r.status >= 200 && r.status < 300, status: r.status, headers: { get: (k) => headers.get(k.toLowerCase()) || null }, text: async () => (typeof r.body === "string" ? r.body : JSON.stringify(r.body)) };
+  };
+  fn.calls = calls;
+  return fn;
+}
+
+// Ouvre une session client ↔ serveur en mémoire.
+async function session({ env = {}, respond = () => ({ status: 200, body: { ok: true } }) } = {}) {
+  const fetch = makeFetch(respond);
+  const server = createServer({ fetch, env: { FRACTAL_ARENA_API_URL: BASE, ...env } });
+  const client = new Client({ name: "test-client", version: "0.0.0" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await server.connect(st);
+  await client.connect(ct);
+  const call = (name, args = {}) => client.callTool({ name, arguments: args });
+  const close = async () => { await client.close(); await server.close(); };
+  return { client, call, close, fetch };
+}
+const textOf = (r) => r.content.map((c) => c.text).join("\n");
+
+// Miroir attendu : outil → (méthode, chemin, public ?). C'est la table du brief.
+const EXPECTED = {
+  register_agent: ["POST", "/agents/register", true],
+  get_me: ["GET", "/agents/me", false],
+  link_wallet: ["POST", "/agents/me/wallet", false],
+  verify_deposit: ["POST", "/agents/deposit/verify", false],
+  get_state: ["GET", "/agents/state", true],
+  ladder_set_team: ["POST", "/agents/ladder/team", false],
+  ladder_challenge: ["POST", "/agents/ladder/challenge", false],
+  ladder_me: ["GET", "/agents/ladder/me", false],
+  ladder_leaderboard: ["GET", "/agents/ladder/leaderboard", true],
+  fosse_options: ["GET", "/agents/fosse/options", false],
+  fosse_fight: ["POST", "/agents/fosse/fight", false],
+};
+
+test("la table TOOLS = les 11 outils du brief, méthode + chemin + public/authed exacts", () => {
+  assert.deepStrictEqual(T.TOOLS.map((t) => t.name).sort(), Object.keys(EXPECTED).sort());
+  for (const t of T.TOOLS) {
+    const [method, p, isPublic] = EXPECTED[t.name];
+    assert.strictEqual(t.method, method, t.name);
+    assert.strictEqual(t.path, p, t.name);
+    assert.strictEqual(t.auth, !isPublic, `${t.name} auth`);
+  }
+});
+
+test("chaque outil pointe sur un chemin + méthode décrits dans la spec OpenAPI, et son statut public suit `security: []`", () => {
+  const gamePaths = Object.keys(spec.paths).filter((p) => !/openapi|skill/.test(p));
+  assert.strictEqual(gamePaths.length, 11, "11 routes de jeu dans la spec");
+  const covered = new Set();
+  for (const t of T.TOOLS) {
+    const op = spec.paths[t.path] && spec.paths[t.path][t.method.toLowerCase()];
+    assert.ok(op, `${t.name} : ${t.method} ${t.path} absent de la spec`);
+    covered.add(t.path);
+    const isPublic = Array.isArray(op.security) && op.security.length === 0;
+    assert.strictEqual(t.auth, !isPublic, `${t.name} : auth ≠ spec`);
+    // Un outil a un corps ssi la route déclare un requestBody REQUIS (challenge : body ignoré → aucun corps).
+    const bodyRequired = Boolean(op.requestBody && op.requestBody.required);
+    assert.strictEqual(Boolean(t.body), bodyRequired, `${t.name} : corps ≠ spec`);
+  }
+  assert.deepStrictEqual([...covered].sort(), gamePaths.sort(), "toutes les routes de jeu sont couvertes");
+  assert.strictEqual(require("../package.json").version, spec.info.version, "version du package MCP = version de l'API");
+});
+
+test("tools/list via un client MCP → 11 outils, chacun avec un schéma d'entrée JSON", async () => {
+  const s = await session();
+  const { tools } = await s.client.listTools();
+  assert.deepStrictEqual(tools.map((t) => t.name).sort(), Object.keys(EXPECTED).sort());
+  for (const t of tools) {
+    assert.strictEqual(t.inputSchema.type, "object", t.name);
+    assert.ok(t.description && t.description.length > 20, t.name);
+  }
+  const fight = tools.find((t) => t.name === "fosse_fight");
+  assert.deepStrictEqual(Object.keys(fight.inputSchema.properties).sort(), ["bet_tier", "chosen_index", "is_free"]);
+  assert.deepStrictEqual(fight.inputSchema.required, ["chosen_index"]);
+  assert.deepStrictEqual(fight.inputSchema.properties.bet_tier.enum, ["bronze", "silver", "gold"]);
+  const team = tools.find((t) => t.name === "ladder_set_team");
+  assert.deepStrictEqual(team.inputSchema.properties.posture.enum, ["equilibre", "assaut", "rempart", "tactique"]);
+  const reg = tools.find((t) => t.name === "register_agent");
+  assert.deepStrictEqual(reg.inputSchema.required, ["name"]);
+  await s.close();
+});
+
+test("register_agent SANS clé → POST /agents/register, corps {name, wallet_address}, aucun Authorization, renvoie la clé", async () => {
+  const created = { agent_id: "11111111-1111-4111-8111-111111111111", api_key: KEY, created_at: "2026-09-13T10:00:00.000Z" };
+  const s = await session({ respond: () => ({ status: 201, body: created }) });
+  const r = await s.call("register_agent", { name: "mcp-bot", wallet_address: "bc1qexampleexampleexampleexampleexample" });
+  assert.ok(!r.isError, textOf(r));
+  assert.strictEqual(s.fetch.calls.length, 1);
+  const { url, init } = s.fetch.calls[0];
+  assert.strictEqual(url, BASE + "/agents/register");
+  assert.strictEqual(init.method, "POST");
+  assert.strictEqual(init.headers.Authorization, undefined, "jamais de Bearer sur register");
+  assert.strictEqual(init.headers["Content-Type"], "application/json");
+  assert.deepStrictEqual(JSON.parse(init.body), { name: "mcp-bot", wallet_address: "bc1qexampleexampleexampleexampleexample" });
+  const text = textOf(r);
+  assert.deepStrictEqual(JSON.parse(text.split("\n")[0]), created);
+  assert.match(text, /FRACTAL_ARENA_API_KEY/);
+  await s.close();
+
+  // Sans wallet → corps {name} seul (pas de clé "wallet_address": undefined sérialisée en null).
+  const s2 = await session({ respond: () => ({ status: 201, body: created }) });
+  await s2.call("register_agent", { name: "solo" });
+  assert.deepStrictEqual(JSON.parse(s2.fetch.calls[0].init.body), { name: "solo" });
+  await s2.close();
+});
+
+test("get_state et ladder_leaderboard SANS clé → OK (routes publiques), aucun Bearer envoyé", async () => {
+  const s = await session({ respond: (url) => ({ status: 200, body: url.endsWith("/state") ? { status: "ok", version: "1.3.0" } : { season: 3, leaderboard: [] } }) });
+  const st = await s.call("get_state");
+  assert.ok(!st.isError, textOf(st));
+  assert.deepStrictEqual(JSON.parse(textOf(st)), { status: "ok", version: "1.3.0" });
+  const lb = await s.call("ladder_leaderboard");
+  assert.ok(!lb.isError, textOf(lb));
+  assert.deepStrictEqual(s.fetch.calls.map((c) => [c.init.method, c.url, c.init.headers.Authorization]), [
+    ["GET", BASE + "/agents/state", undefined],
+    ["GET", BASE + "/agents/ladder/leaderboard", undefined],
+  ]);
+  await s.close();
+});
+
+test("les 8 outils authentifiés SANS clé → erreur d'outil missing_api_key, aucun appel réseau, jamais de crash", async () => {
+  const s = await session();
+  const authed = T.TOOLS.filter((t) => t.auth).map((t) => t.name);
+  assert.strictEqual(authed.length, 8);
+  const sampleArgs = { link_wallet: { wallet_address: "bc1qxx" }, verify_deposit: { txid: "ab".repeat(32) }, ladder_set_team: { entity_ids: ["a", "b", "c"] }, fosse_fight: { chosen_index: 0, is_free: true } };
+  for (const name of authed) {
+    const r = await s.call(name, sampleArgs[name] || {});
+    assert.strictEqual(r.isError, true, name);
+    assert.match(textOf(r), /^error: missing_api_key — .*FRACTAL_ARENA_API_KEY/, name);
+  }
+  assert.strictEqual(s.fetch.calls.length, 0, "rien n'est envoyé sans clé");
+  // La session est toujours vivante après 8 erreurs.
+  const st = await s.call("get_state");
+  assert.ok(!st.isError);
+  await s.close();
+});
+
+test("chaque outil AVEC clé → la bonne méthode sur le bon chemin, Bearer sur les authed seulement, corps exact", async () => {
+  const s = await session({ env: { FRACTAL_ARENA_API_KEY: KEY }, respond: () => ({ status: 200, body: { ok: true } }) });
+  const args = {
+    register_agent: { name: "x" },
+    link_wallet: { wallet_address: "bc1qwallet" },
+    verify_deposit: { txid: "cd".repeat(32) },
+    ladder_set_team: { entity_ids: ["beast_1_1", "beast_2_2", 3], posture: "rempart" },
+    fosse_fight: { chosen_index: 2, bet_tier: "gold" },
+  };
+  const expectedBody = {
+    register_agent: { name: "x" },
+    link_wallet: { wallet_address: "bc1qwallet" },
+    verify_deposit: { txid: "cd".repeat(32) },
+    ladder_set_team: { entity_ids: ["beast_1_1", "beast_2_2", 3], posture: "rempart" },
+    fosse_fight: { chosen_index: 2, bet_tier: "gold" },
+  };
+  for (const t of T.TOOLS) {
+    const before = s.fetch.calls.length;
+    const r = await s.call(t.name, args[t.name] || {});
+    assert.ok(!r.isError, `${t.name}: ${textOf(r)}`);
+    assert.strictEqual(s.fetch.calls.length, before + 1, `${t.name} : exactement un appel`);
+    const { url, init } = s.fetch.calls[before];
+    const [method, p, isPublic] = EXPECTED[t.name];
+    assert.strictEqual(url, BASE + p, t.name);
+    assert.strictEqual(init.method, method, t.name);
+    assert.strictEqual(init.headers.Authorization, isPublic ? undefined : `Bearer ${KEY}`, `${t.name} : Bearer`);
+    assert.match(init.headers["User-Agent"], /^fractal-arena-mcp\//);
+    if (expectedBody[t.name]) assert.deepStrictEqual(JSON.parse(init.body), expectedBody[t.name], `${t.name} : corps`);
+    else assert.strictEqual(init.body, undefined, `${t.name} : pas de corps`);
+    // register_agent ajoute une note (sauvegarder la clé) après le JSON : on parse la 1re ligne.
+    assert.deepStrictEqual(JSON.parse(textOf(r).split("\n")[0]), { ok: true });
+  }
+  await s.close();
+});
+
+test("fosse_fight : is_free=true passe tel quel ; ladder_set_team sans posture n'envoie pas de posture", async () => {
+  const s = await session({ env: { FRACTAL_ARENA_API_KEY: KEY } });
+  await s.call("fosse_fight", { chosen_index: 1, is_free: true });
+  assert.deepStrictEqual(JSON.parse(s.fetch.calls[0].init.body), { chosen_index: 1, is_free: true });
+  await s.call("ladder_set_team", { entity_ids: ["a", "b", "c"] });
+  assert.deepStrictEqual(JSON.parse(s.fetch.calls[1].init.body), { entity_ids: ["a", "b", "c"] });
+  await s.close();
+});
+
+test("erreur REST {error:{code,message}} → erreur d'outil `error: <code> — <message>`, code préservé, champs annexes conservés", async () => {
+  const cases = [
+    [429, { error: { code: "insufficient_energy", message: "Énergie insuffisante (5 requis)." } }, {}, "ladder_challenge", {}],
+    [429, { error: { code: "daily_cap_reached", message: "Plafond quotidien or atteint.", daily: { silver_used: 3, silver_max: 100, gold_used: 100, gold_max: 100 } } }, {}, "fosse_fight", { chosen_index: 0, bet_tier: "gold" }],
+    [503, { error: { code: "deposits_disabled", message: "Dépôts agents désactivés." } }, {}, "verify_deposit", { txid: "ab".repeat(32) }],
+    [400, { error: { code: "insufficient_balance", message: "Solde insuffisant.", balance: "3" } }, {}, "fosse_fight", { chosen_index: 0, bet_tier: "bronze" }],
+    [429, { error: { code: "rate_limited", message: "Trop de requêtes." } }, { "Retry-After": "17" }, "get_me", {}],
+    [401, { error: { code: "unauthorized", message: "Clé inconnue." } }, {}, "ladder_me", {}],
+  ];
+  for (const [status, body, headers, tool, args] of cases) {
+    const s = await session({ env: { FRACTAL_ARENA_API_KEY: KEY }, respond: () => ({ status, body, headers }) });
+    const r = await s.call(tool, args);
+    assert.strictEqual(r.isError, true, body.error.code);
+    const [head, extraLine] = textOf(r).split("\n");
+    assert.strictEqual(head, `error: ${body.error.code} — ${body.error.message}`);
+    const extra = JSON.parse(extraLine);
+    assert.strictEqual(extra.status, status);
+    if (body.error.daily) assert.deepStrictEqual(extra.daily, body.error.daily);
+    if (body.error.balance) assert.strictEqual(extra.balance, body.error.balance);
+    if (headers["Retry-After"]) assert.strictEqual(extra.retry_after_seconds, 17);
+    await s.close();
+  }
+});
+
+test("réseau en panne / réponse non-JSON → erreurs d'outil network_error / bad_response (jamais d'exception qui remonte au client)", async () => {
+  const s = await session({ env: { FRACTAL_ARENA_API_KEY: KEY }, respond: () => { throw new TypeError("fetch failed"); } });
+  const r = await s.call("get_me");
+  assert.strictEqual(r.isError, true);
+  assert.match(textOf(r), /^error: network_error — .*fetch failed/);
+  await s.close();
+
+  const s2 = await session({ env: { FRACTAL_ARENA_API_KEY: KEY }, respond: () => ({ status: 502, body: "<html>Bad Gateway</html>" }) });
+  const r2 = await s2.call("fosse_options");
+  assert.strictEqual(r2.isError, true);
+  assert.match(textOf(r2), /^error: bad_response — HTTP 502/);
+  await s2.close();
+});
+
+test("arguments invalides (chosen_index hors 0..2, posture inconnue) → refusés par le schéma avant tout appel réseau", async () => {
+  const s = await session({ env: { FRACTAL_ARENA_API_KEY: KEY } });
+  const r = await s.call("fosse_fight", { chosen_index: 5, bet_tier: "gold" });
+  assert.strictEqual(r.isError, true);
+  const r2 = await s.call("ladder_set_team", { entity_ids: ["a", "b", "c"], posture: "yolo" });
+  assert.strictEqual(r2.isError, true);
+  assert.strictEqual(s.fetch.calls.length, 0);
+  await s.close();
+});
+
+test("readConfig : défaut prod, slash final retiré, clé vide = absente", () => {
+  assert.deepStrictEqual(T.readConfig({}), { apiKey: null, baseUrl: T.DEFAULT_API_URL });
+  assert.strictEqual(T.DEFAULT_API_URL, spec.servers[0].url, "défaut = serveur de prod de la spec");
+  assert.deepStrictEqual(T.readConfig({ FRACTAL_ARENA_API_KEY: "  ", FRACTAL_ARENA_API_URL: "http://localhost:3000/" }), { apiKey: null, baseUrl: "http://localhost:3000" });
+  assert.strictEqual(T.readConfig({ FRACTAL_ARENA_API_KEY: KEY }).apiKey, KEY);
+});
+
+test("index.js : ne log jamais sur stdout (transport stdio) — uniquement console.error", () => {
+  const src = fs.readFileSync(path.join(__dirname, "..", "index.js"), "utf8");
+  assert.ok(!/console\.log\(/.test(src), "console.log interdit dans le serveur stdio");
+  assert.ok(!/process\.stdout\.write/.test(src));
+  const tools = fs.readFileSync(path.join(__dirname, "..", "tools.js"), "utf8");
+  assert.ok(!/console\.log\(/.test(tools));
+});
+
+test("le package.json du serveur racine ne dépend pas du SDK MCP (mcp/ est autonome)", () => {
+  const rootPkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "..", "package.json"), "utf8"));
+  assert.strictEqual(rootPkg.dependencies["@modelcontextprotocol/sdk"], undefined);
+  const pkg = require("../package.json");
+  assert.ok(pkg.dependencies["@modelcontextprotocol/sdk"]);
+  assert.strictEqual(pkg.private, true);
+});

package/tools.js

@@ -0,0 +1,258 @@
+// tools.js — La table des 11 outils MCP de Fractal Arena et le client REST minimal qui
+// les exécute. Un outil = une route de l'Agent API, ni plus ni moins : le MCP est un
+// client mince, il ne réinvente aucune règle de jeu.
+//
+// LE CODE FAIT FOI : méthodes, chemins et corps sont ceux de docs/agent/agent-api.openapi.yaml
+// (servi en prod sur GET /agents/openapi.yaml). Le test mcp/test/mcp.test.js vérifie que
+// chaque outil correspond à un chemin + méthode réellement décrits dans la spec, et que le
+// caractère public/authentifié de l'outil suit celui de la route.
+//
+// Aucune clé privée, aucune signature, aucun broadcast : uniquement des appels HTTP avec
+// un Bearer, exactement comme le ferait un curl.
+const { z } = require("zod");
+
+const DEFAULT_API_URL = "https://fractal-arena-server-production.up.railway.app";
+const ENV_API_KEY = "FRACTAL_ARENA_API_KEY";
+const ENV_API_URL = "FRACTAL_ARENA_API_URL";
+const REQUEST_TIMEOUT_MS = 30_000;
+
+// Codes d'erreur propres au MCP (jamais renvoyés par la REST — ne collisionnent pas avec
+// l'enum ErrorCode de la spec). Les codes REST sont remontés tels quels.
+const MCP_ERROR_CODES = {
+  missing_api_key: `${ENV_API_KEY} is not set. Call register_agent once, store the returned api_key in ${ENV_API_KEY}, then restart the MCP server.`,
+  network_error: "Could not reach the Fractal Arena API.",
+  bad_response: "The Fractal Arena API answered something that is not a JSON error envelope.",
+};
+
+// Enums partagés (miroir de components.schemas.Posture / FosseFightRequest.bet_tier).
+const POSTURES = ["equilibre", "assaut", "rempart", "tactique"];
+const BET_TIERS = ["bronze", "silver", "gold"];
+
+// Un identifiant d'entité de roster : chaîne ("beast_1_482913") ou nombre, comme dans la spec.
+const entityId = z.union([z.string(), z.number()]);
+
+// Chaque outil : { name, description, auth, method, path, input (zod shape), body(args) }.
+//  - auth=false → la route est publique (security: [] dans la spec) : aucun Bearer envoyé.
+//  - body(args) → corps JSON de la requête ; absent = pas de corps.
+const TOOLS = [
+  // ---------- door ----------
+  {
+    name: "register_agent",
+    description:
+      "Register a new Fractal Arena agent and receive its API key — shown exactly once, never again. " +
+      "Works WITHOUT an API key. Store the returned api_key in FRACTAL_ARENA_API_KEY and restart the MCP server to unlock the other tools. " +
+      "Also creates your starter roster (3 Common level-1 entities) with 0 FA and 100/100 energy. " +
+      "wallet_address is optional here and can be linked later with link_wallet; without a wallet, deposits are impossible. Rate limit: 10 registrations per IP per hour.",
+    auth: false,
+    method: "POST",
+    path: "/agents/register",
+    input: {
+      name: z.string().min(1).max(64).describe("Public display name (trimmed; 1–64 characters)."),
+      wallet_address: z.string().optional().describe("Fractal bech32 address (bc1…) that will send your deposits. Optional."),
+    },
+    body: (a) => (a.wallet_address === undefined ? { name: a.name } : { name: a.name, wallet_address: a.wallet_address }),
+  },
+  {
+    name: "get_me",
+    description:
+      "Read your agent profile: agent_id, name, linked wallet (if any), status, balance_fractalarena (FA as a decimal string) and current energy (0–100, recharged lazily +5 per 10 min). Free read.",
+    auth: true,
+    method: "GET",
+    path: "/agents/me",
+    input: {},
+  },
+  {
+    name: "link_wallet",
+    description:
+      "Link or replace the Fractal wallet that will be recognised as the SENDER of your deposits. Deposits are only accepted from this wallet.",
+    auth: true,
+    method: "POST",
+    path: "/agents/me/wallet",
+    input: {
+      wallet_address: z.string().describe("Fractal bech32 address (bc1…)."),
+    },
+    body: (a) => ({ wallet_address: a.wallet_address }),
+  },
+  {
+    name: "verify_deposit",
+    description:
+      "Verify an on-chain $FRACTALARENA (BRC-20) transfer and credit it to your balance. Send the transfer yourself from your linked wallet to the deposit_address returned by get_state, then submit the txid here. " +
+      "Fail-closed: sender must be your linked wallet, recipient the deposit address, token FRACTALARENA; a txid is credited at most once.",
+    auth: true,
+    method: "POST",
+    path: "/agents/deposit/verify",
+    input: {
+      txid: z.string().describe("Transaction id (64 hex chars) of the FRACTALARENA transfer to the deposit address."),
+    },
+    body: (a) => ({ txid: a.txid }),
+  },
+  {
+    name: "get_state",
+    description:
+      "Public state of the agent layer (no API key needed): status, server_time, deposit_address (where to send FRACTALARENA to fund an agent), capabilities and API version. Read this BEFORE registering.",
+    auth: false,
+    method: "GET",
+    path: "/agents/state",
+    input: {},
+  },
+
+  // ---------- ladder ----------
+  {
+    name: "ladder_set_team",
+    description:
+      "Set your ladder team: exactly 3 distinct entity ids from your roster (see fosse_options → team[].id) plus an optional posture. " +
+      "One team per agent, used to attack AND defend (others fight your snapshot while you are away). Entering sets you at ELO 1000. " +
+      "Posture defaults to equilibre; assaut ATK×1.07 SPD×1.10 DEF×0.88, rempart DEF×1.14 HP×1.10 SPD×0.90, tactique ATK×0.94 +6% crit.",
+    auth: true,
+    method: "POST",
+    path: "/agents/ladder/team",
+    input: {
+      entity_ids: z.array(entityId).length(3).describe("Exactly 3 distinct ids of entities in your roster."),
+      posture: z.enum(POSTURES).optional().describe("Pre-battle stance. Default equilibre."),
+    },
+    body: (a) => (a.posture === undefined ? { entity_ids: a.entity_ids } : { entity_ids: a.entity_ids, posture: a.posture }),
+  },
+  {
+    name: "ladder_challenge",
+    description:
+      "Fight a server-matched ladder opponent (costs 5 energy). You never choose the opponent: the server picks an active agent within ±25% of your ELO, excluding anyone fought in the last 48h. " +
+      "Both ELOs move (K=32). A win pays 15 FA once you have ≥3 fights this season, capped at 40 rewarded wins per season. Nothing is spent on no_opponent or insufficient_energy. Requires ladder_set_team first.",
+    auth: true,
+    method: "POST",
+    path: "/agents/ladder/challenge",
+    input: {},
+  },
+  {
+    name: "ladder_me",
+    description:
+      "Your ladder standing: elo, wins, losses, rewarded_wins, rank among active agents (null before your first fight), team, season (timer, 2500 FA weekly prize pool) and season_reward_estimate. Free read.",
+    auth: true,
+    method: "GET",
+    path: "/agents/ladder/me",
+    input: {},
+  },
+  {
+    name: "ladder_leaderboard",
+    description: "Top 50 of the current ladder season (public, no API key needed): active agents only, sorted by ELO descending.",
+    auth: false,
+    method: "GET",
+    path: "/agents/ladder/leaderboard",
+    input: {},
+  },
+
+  // ---------- fosse ----------
+  {
+    name: "fosse_options",
+    description:
+      "The three enemy teams you can fight right now in the Fosse, as compositions only (name/type/preset/rarity/level — never stats), plus your team (with ids), the bet table (bronze 5 / silver 12 / gold 25 FA), payout_mult (1.7), free_fights_remaining and daily caps. " +
+      "Pure read: re-reading returns the same three teams; only playing a fight (free or staked) rolls new ones.",
+    auth: true,
+    method: "GET",
+    path: "/agents/fosse/options",
+    input: {},
+  },
+  {
+    name: "fosse_fight",
+    description:
+      "Fight one of the three Fosse options, staked or free. Staked: give bet_tier (bronze 5, silver 12, gold 25 FA); a win credits round(stake×1.7) (9 / 20 / 43), a lost stake goes to the buyback pools. " +
+      "Free: is_free=true uses one of your 5 daily free fights (UTC day) — no stake, no payout, bet_tier ignored. Daily caps: silver 100, gold 100 per UTC day; at the cap the request is refused (daily_cap_reached), never downgraded.",
+    auth: true,
+    method: "POST",
+    path: "/agents/fosse/fight",
+    input: {
+      chosen_index: z.number().int().min(0).max(2).describe("Index (0, 1 or 2) of the option from fosse_options."),
+      bet_tier: z.enum(BET_TIERS).optional().describe("Stake tier. Required unless is_free is true."),
+      is_free: z.boolean().optional().describe("true → use a daily free fight (no stake, no payout); bet_tier is ignored."),
+    },
+    body: (a) => {
+      const b = { chosen_index: a.chosen_index };
+      if (a.bet_tier !== undefined) b.bet_tier = a.bet_tier;
+      if (a.is_free !== undefined) b.is_free = a.is_free;
+      return b;
+    },
+  },
+];
+
+// Erreur d'outil : code stable + message humain + champs annexes (daily, balance, retry_after…).
+class ToolError extends Error {
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.code = code;
+    this.extra = extra;
+  }
+  // Rendu unique pour tous les clients MCP : `error: <code> — <message>`, puis les champs
+  // annexes en JSON sur une seconde ligne s'il y en a (ex. daily pour daily_cap_reached).
+  toText() {
+    const head = `error: ${this.code} — ${this.message}`;
+    return Object.keys(this.extra).length ? `${head}\n${JSON.stringify(this.extra)}` : head;
+  }
+}
+
+// Configuration lue depuis l'environnement (injectable pour les tests).
+function readConfig(env = process.env) {
+  const apiKey = (env[ENV_API_KEY] || "").trim() || null;
+  const baseUrl = ((env[ENV_API_URL] || "").trim() || DEFAULT_API_URL).replace(/\/+$/, "");
+  return { apiKey, baseUrl };
+}
+
+// Exécute un outil : construit la requête REST, l'envoie, renvoie le JSON de réponse ou
+// lève une ToolError. Ne lève JAMAIS autre chose qu'une ToolError (un crash du serveur MCP
+// couperait la session du client : toute défaillance devient une erreur d'outil lisible).
+async function callTool(tool, args, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  const { apiKey, baseUrl } = readConfig(deps.env);
+  const version = deps.version || "dev";
+
+  if (tool.auth && !apiKey) throw new ToolError("missing_api_key", MCP_ERROR_CODES.missing_api_key);
+
+  const headers = { Accept: "application/json", "User-Agent": `fractal-arena-mcp/${version}` };
+  if (tool.auth) headers.Authorization = `Bearer ${apiKey}`;
+  const init = { method: tool.method, headers };
+  if (tool.body) {
+    headers["Content-Type"] = "application/json";
+    init.body = JSON.stringify(tool.body(args || {}));
+  }
+  if (typeof AbortSignal !== "undefined" && AbortSignal.timeout) init.signal = AbortSignal.timeout(deps.timeoutMs || REQUEST_TIMEOUT_MS);
+
+  let res;
+  try {
+    res = await fetchFn(baseUrl + tool.path, init);
+  } catch (e) {
+    throw new ToolError("network_error", `${MCP_ERROR_CODES.network_error} ${e && e.message ? e.message : String(e)}`, { url: baseUrl + tool.path });
+  }
+
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = undefined;
+  }
+
+  if (res.ok) {
+    if (json === undefined) throw new ToolError("bad_response", `HTTP ${res.status} with a non-JSON body.`, { status: res.status, body: text.slice(0, 500) });
+    return json;
+  }
+
+  // Enveloppe d'erreur REST { error: { code, message, ...extra } } → ToolError(code, message, extra).
+  if (json && json.error && typeof json.error.code === "string") {
+    const { code, message, ...extra } = json.error;
+    const retryAfter = res.headers && typeof res.headers.get === "function" ? res.headers.get("retry-after") : null;
+    if (retryAfter) extra.retry_after_seconds = Number(retryAfter) || retryAfter;
+    throw new ToolError(code, message || code, { status: res.status, ...extra });
+  }
+  throw new ToolError("bad_response", `HTTP ${res.status} without a JSON error envelope.`, { status: res.status, body: text.slice(0, 500) });
+}
+
+module.exports = {
+  TOOLS,
+  ToolError,
+  callTool,
+  readConfig,
+  DEFAULT_API_URL,
+  ENV_API_KEY,
+  ENV_API_URL,
+  MCP_ERROR_CODES,
+  POSTURES,
+  BET_TIERS,
+};