@debuffjp/mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @debuffjp/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [MCP](https://modelcontextprotocol.io) server that lets AI agents inspect, build, test and **play** a debuff game. It uses the same evidence a human would want: real state, real frames, real test results.
+
+## Setup
+
+New projects from `npm create debuff` include a `.mcp.json`, so MCP clients that read it (such as Claude Code) pick the server up automatically. For other clients:
+
+```bash
+claude mcp add debuff -- npx -y @debuffjp/mcp        # Claude Code
+```
+
+```json
+{
+  "mcpServers": {
+    "debuff": { "command": "npx", "args": ["-y", "@debuffjp/mcp"] }
+  }
+}
+```
+
+Run it from the game's folder, or pass `--root <dir>` (or set `DEBUFF_ROOT`).
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `inspect_project` | Dependencies, plugins and their contributions, assets, last build size |
+| `list_assets` | Every asset with its type, size and importer, plus warnings and possibly unused ids |
+| `build` | Production build plus size report; `leaks` must be empty |
+| `run_scenarios` | Run `scenarios/*.json` headless; per-step results, errors, captures |
+| `game_start` | Attach to the live game, or open a private headless copy, paused (see below) |
+| `game_step` | Advance fixed simulation steps (pausing first); returns state |
+| `game_pause` | Pause or resume a live game |
+| `game_frames` | Recent frame breakdown: update/render ms, catch-up steps, quads, draw calls, long tasks |
+| `game_notes` | Moments the human flagged in the overlay, with the state at that tick |
+| `game_input` | `press` / `release` keys; `tap`, `pointer_down`, `pointer_move`, `pointer_up` |
+| `game_state` | Scene, tick, renderer, frame stats, your `inspect()` data |
+| `game_params` / `game_set_param` | Read and tune typed params (validated) |
+| `game_capture` | The current frame as a PNG image |
+| `game_errors` | Runtime errors, explained: whose problem (your code, a rejected call, a debuff bug), the source line, a hint |
+| `game_stop` | Close the game |
+
+## Live and headless
+
+If you have the game open under `debuff dev`, `game_start` attaches to **that tab** (mode `live`). The overlay shows an **agent** badge, and every pause, step and param change the agent makes appears in its activity log, where you can undo it. Type a note in the overlay ("jump feels floaty here") to flag a moment; the agent reads it, along with the game state at that tick, through `game_notes`. `game_stop` resumes your game and disconnects.
+
+Otherwise, or with `mode: "headless"`, the agent gets a private copy in a headless browser. Time only advances through `game_step`, so what it sees is reproducible, and a scenario can replay it exactly.

package/bin/debuff-mcp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Committed shim so npm can link the bin before dist/ is built.
+import "../dist/cli.js";

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+const args = process.argv.slice(2);
+const rootFlag = args.indexOf("--root");
+const root = resolve(rootFlag >= 0 ? (args[rootFlag + 1] ?? ".") : (process.env.DEBUFF_ROOT ?? process.cwd()));
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const server = createServer({ root, version });
+await server.connect(new StdioServerTransport());
+// stdout carries the protocol, so diagnostics go to stderr.
+console.error(`debuff MCP server v${version} ready (root: ${root})`);
+const shutdown = async () => {
+    await server.close();
+    process.exit(0);
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+process.stdin.on("close", shutdown);
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AACxC,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;AAC/G,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAwB,CAAC;AAEzH,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AAC/C,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AAEjD,4DAA4D;AAC5D,OAAO,CAAC,KAAK,CAAC,sBAAsB,OAAO,iBAAiB,IAAI,GAAG,CAAC,CAAC;AAErE,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;IAC1B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC;AACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAChC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createServer, type ServerOptions } from "./server.js";
+export { type GameSession, HeadlessSession, LiveSession, type StartMode, startSession } from "./session.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,KAAK,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,KAAK,SAAS,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createServer } from "./server.js";
+export { HeadlessSession, LiveSession, startSession } from "./session.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAsB,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAoB,eAAe,EAAE,WAAW,EAAkB,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface ServerOptions {
+    /** Default project root for tools that don't receive one. */
+    root: string;
+    version: string;
+}
+/**
+ * debuff's MCP server: project tools (inspect, assets, build, scenarios) and live-game tools that drive
+ * a running game through the same dev hooks scenarios use. Every result is JSON, plus images for captures.
+ */
+export declare function createServer(options: ServerOptions): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AASpE,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAqR9D"}

package/dist/server.js

@@ -0,0 +1,198 @@
+import { resolve } from "node:path";
+import { buildReport, compileAssets, findUnused, inspectProject, loadConfig, runScenarios, viteConfig } from "@debuffjp/cli";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { startSession } from "./session.js";
+const json = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
+const fail = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+/**
+ * debuff's MCP server: project tools (inspect, assets, build, scenarios) and live-game tools that drive
+ * a running game through the same dev hooks scenarios use. Every result is JSON, plus images for captures.
+ */
+export function createServer(options) {
+    const server = new McpServer({ name: "debuff", version: options.version }, {
+        instructions: "Tools for building 2D web games with debuff. Start with inspect_project. To see the game, call game_start, then game_state / game_capture. " +
+            "If the human has the game open under `debuff dev`, game_start attaches to it (mode live): they see your actions in their overlay, and their " +
+            "flagged moments are in game_notes, so read those first. Otherwise you get a private paused copy (mode headless) where time only advances through game_step. " +
+            "Use game_pause before inspecting a live game, and game_frames to explain stutter. Prefer tuning params (game_params, game_set_param) over code changes, " +
+            "and verify changes with run_scenarios. Creative direction belongs to the human: propose alternatives rather than deciding art or feel.",
+    });
+    const rootOf = (root) => resolve(options.root, root ?? ".");
+    let session;
+    const live = () => {
+        if (!session)
+            throw new Error("No game running. Call game_start first.");
+        return session;
+    };
+    const safely = (fn) => async (args) => {
+        try {
+            return await fn(args);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : String(err));
+        }
+    };
+    const root = { root: z.string().optional().describe("Project root, relative to the server's root. Default: the server's root.") };
+    // ---- project tools -------------------------------------------------------------------------
+    server.registerTool("inspect_project", {
+        title: "Inspect project",
+        description: "Summary of the project: dependencies, plugins and their contributions, assets, last build size.",
+        inputSchema: root,
+        annotations: { readOnlyHint: true },
+    }, safely(async ({ root: r }) => json(await inspectProject(rootOf(r)))));
+    server.registerTool("list_assets", {
+        title: "List assets",
+        description: "Run the asset pipeline: every asset id, type, size and importer, plus generated files, warnings and possibly unused ids.",
+        inputSchema: root,
+        annotations: { readOnlyHint: true },
+    }, safely(async ({ root: r }) => {
+        const dir = rootOf(r);
+        const { plugins, atlas } = await loadConfig(dir);
+        const { manifest, importedBy, outputs, warnings } = await compileAssets(dir, { plugins, atlas });
+        return json({ assets: manifest.assets, importedBy, generated: [...outputs.keys()], warnings, unused: findUnused(dir, manifest) });
+    }));
+    server.registerTool("build", {
+        title: "Production build",
+        description: "Build for production and return the size report (raw, gzip, brotli per file). `leaks` lists dev-only code found in the output; it must be empty.",
+        inputSchema: root,
+    }, safely(async ({ root: r }) => {
+        const dir = rootOf(r);
+        const { build } = await import("vite");
+        await build(await viteConfig(dir, { logLevel: "silent" }));
+        return json(buildReport(resolve(dir, "dist")));
+    }));
+    server.registerTool("run_scenarios", {
+        title: "Run scenarios",
+        description: "Run scenarios/*.json (or the given files) in a headless browser. Returns per-step results, runtime errors, captures and final state.",
+        inputSchema: {
+            ...root,
+            files: z.array(z.string()).optional().describe("Scenario files relative to the root. Default: all."),
+            update: z.boolean().optional().describe("Accept new captures as baselines. Only when the human has approved the visual change."),
+        },
+    }, safely(async ({ root: r, files, update }) => {
+        const dir = rootOf(r);
+        const { plugins } = await loadConfig(dir);
+        const reports = await runScenarios({ root: dir, files: files ?? [], plugins, update: update ?? false, strict: false });
+        return json({ passed: reports.filter((x) => x.ok).length, total: reports.length, reports });
+    }));
+    // ---- live game tools -----------------------------------------------------------------------
+    server.registerTool("game_start", {
+        title: "Start game",
+        description: "Connect to the game. auto (default): attach to the human's live game if `debuff dev` has it open in a browser, else start a private " +
+            "headless copy, paused. Returns the mode, state and how many notes the human has flagged. Replaces any running session.",
+        inputSchema: {
+            ...root,
+            page: z.string().optional().describe('Path to open in headless mode. Default "/".'),
+            mode: z.enum(["auto", "live", "headless"]).optional().describe("Default auto."),
+        },
+    }, safely(async ({ root: r, page, mode }) => {
+        await session?.stop();
+        session = undefined;
+        session = await startSession(rootOf(r), { ...(page ? { page } : {}), ...(mode ? { mode } : {}) });
+        return json({ mode: session.mode, url: session.url, state: await session.call("state") });
+    }));
+    server.registerTool("game_state", {
+        title: "Game state",
+        description: "Current scene, tick, time, renderer, frame stats, the scene's inspect() data and plugin inspect data.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, safely(async () => json(await live().call("state"))));
+    server.registerTool("game_step", {
+        title: "Advance time",
+        description: "Advance the simulation by fixed steps (60 per second by default) and return the new state.",
+        inputSchema: { steps: z.number().int().min(1).max(36_000).describe("Fixed simulation steps to run.") },
+    }, safely(async ({ steps }) => json(await live().call("step", steps))));
+    server.registerTool("game_input", {
+        title: "Send input",
+        description: "Keyboard or pointer input. press/release take a KeyboardEvent.code (e.g. Space, ArrowLeft, KeyZ). tap/pointer_down/pointer_move take logical x, y. " +
+            "Input takes effect on the next game_step.",
+        inputSchema: {
+            action: z.enum(["press", "release", "tap", "pointer_down", "pointer_move", "pointer_up"]),
+            code: z.string().optional().describe("For press/release."),
+            x: z.number().optional(),
+            y: z.number().optional(),
+        },
+    }, safely(async ({ action, code, x, y }) => {
+        const s = live();
+        if (action === "press" || action === "release") {
+            if (!code)
+                throw new Error(`${action} needs a key code`);
+            await s.call(action, code);
+        }
+        else if (action === "pointer_up") {
+            await s.call("pointerUp");
+        }
+        else {
+            if (x === undefined || y === undefined)
+                throw new Error(`${action} needs x and y`);
+            await s.call({ tap: "tap", pointer_down: "pointerDown", pointer_move: "pointerMove" }[action], x, y);
+        }
+        return json({ ok: true });
+    }));
+    server.registerTool("game_params", {
+        title: "List params",
+        description: "Every tunable param group: schema (type, default, min, max, units, description) and current values.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, safely(async () => json(await live().call("params"))));
+    server.registerTool("game_set_param", {
+        title: "Set param",
+        description: "Set a tunable param live. Values are validated against the param's type and range. Changes last until game_start or a reload.",
+        inputSchema: { group: z.string(), key: z.string(), value: z.union([z.number(), z.boolean()]) },
+    }, safely(async ({ group, key, value }) => {
+        await live().call("setParam", group, key, value);
+        return json({ ok: true, group, key, value });
+    }));
+    server.registerTool("game_capture", {
+        title: "Capture frame",
+        description: "Screenshot of the current frame as a PNG image.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, safely(async () => {
+        const dataUrl = await live().call("capture");
+        return { content: [{ type: "image", data: dataUrl.slice(dataUrl.indexOf(",") + 1), mimeType: "image/png" }] };
+    }));
+    server.registerTool("game_pause", {
+        title: "Pause or resume",
+        description: "Pause or resume a live game (headless games are always paused). game_step also pauses first.",
+        inputSchema: { paused: z.boolean() },
+    }, safely(async ({ paused }) => json(await live().call(paused ? "pause" : "resume"))));
+    server.registerTool("game_frames", {
+        title: "Frame breakdown",
+        description: "Recent frames, oldest first: intervalMs (what the player feels), updateMs, renderMs, steps (>1 means catching up), quads, drawCalls and " +
+            "longTaskMs (browser-reported main-thread stalls). Use it to explain stutter; in headless mode times reflect stepping, not real play.",
+        inputSchema: { count: z.number().int().min(1).max(240).optional().describe("Default 60.") },
+        annotations: { readOnlyHint: true },
+    }, safely(async ({ count }) => json(await live().call("frames", count ?? 60))));
+    server.registerTool("game_notes", {
+        title: "Human notes",
+        description: "Moments the human flagged in the overlay (live mode): their words, the tick, the scene's inspect() state then, and the frames leading up to it.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, safely(async () => json(await live().call("notes"))));
+    server.registerTool("game_errors", {
+        title: "Runtime errors",
+        description: "Runtime errors since the game started, explained: kind (your-code, debuff-usage, debuff-bug, outside), where (source file:line, " +
+            "source-mapped), a hint, the loop phase and tick, and a repeat count. A loop error stops the game; fix it, then game_pause false to resume. " +
+            "For debuff-bug, tell the human and share reportUrl rather than working around it.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, safely(async () => json(await live().call("errors"))));
+    server.registerTool("game_stop", {
+        title: "Stop game",
+        description: "Headless: close the browser and dev server. Live: resume the human's game and disconnect.",
+        inputSchema: {},
+    }, safely(async () => {
+        await session?.stop();
+        session = undefined;
+        return json({ ok: true });
+    }));
+    const close = server.close.bind(server);
+    server.close = async () => {
+        await session?.stop();
+        session = undefined;
+        await close();
+    };
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,50 @@
+/** A running game an agent can drive through the dev hooks. */
+export interface GameSession {
+    /**
+     * "live": the game the human has open under `debuff dev`, running in real time; the agent's actions
+     * show in their overlay. "headless": a private paused copy where time only advances via step.
+     */
+    readonly mode: "live" | "headless";
+    readonly url: string;
+    call<R = unknown>(method: string, ...args: unknown[]): Promise<R>;
+    stop(): Promise<void>;
+}
+export type StartMode = "auto" | "live" | "headless";
+/** Live if `debuff dev` is running with a page open (or `mode` says so), else headless. */
+export declare function startSession(root: string, options?: {
+    mode?: StartMode;
+    page?: string;
+    width?: number;
+    height?: number;
+}): Promise<GameSession>;
+/** The developer's own browser tab, reached through the dev server's agent link. */
+export declare class LiveSession implements GameSession {
+    readonly url: string;
+    private readonly attachment;
+    readonly mode = "live";
+    private constructor();
+    static find(root: string): Promise<LiveSession | undefined>;
+    call<R = unknown>(method: string, ...args: unknown[]): Promise<R>;
+    stop(): Promise<void>;
+}
+/**
+ * A private game: the project's dev server plus a headless browser page in controlled mode
+ * (`?debuff-scenario`), so time only advances when an agent steps it.
+ */
+export declare class HeadlessSession implements GameSession {
+    readonly url: string;
+    private readonly server;
+    private readonly browser;
+    private readonly page;
+    readonly mode = "headless";
+    private constructor();
+    static start(root: string, options?: {
+        page?: string;
+        width?: number;
+        height?: number;
+    }): Promise<HeadlessSession>;
+    /** Call a `window.__DEBUFF_DEV__` method. */
+    call<R = unknown>(method: string, ...args: unknown[]): Promise<R>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAeA,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAClE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAErD,2FAA2F;AAC3F,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GACjF,OAAO,CAAC,WAAW,CAAC,CAUtB;AAED,oFAAoF;AACpF,qBAAa,WAAY,YAAW,WAAW;IAG3C,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAH7B,QAAQ,CAAC,IAAI,UAAU;IACvB,OAAO,eAGH;IAEJ,OAAa,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAoBhE;IAEK,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAStE;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAI1B;CACF;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,WAAW;IAG/C,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IALvB,QAAQ,CAAC,IAAI,cAAc;IAC3B,OAAO,eAKH;IAEJ,OAAa,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,eAAe,CAAC,CAyB3H;IAED,6CAA6C;IAC7C,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAEhE;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAG1B;CACF"}

package/dist/session.js

@@ -0,0 +1,119 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { AGENT_PATHS, callHook, createDevServer, DEV_SERVER_FILE, hooksReady, launchBrowser, } from "@debuffjp/cli";
+/** Live if `debuff dev` is running with a page open (or `mode` says so), else headless. */
+export async function startSession(root, options = {}) {
+    const mode = options.mode ?? "auto";
+    if (mode !== "headless") {
+        const live = await LiveSession.find(root);
+        if (live)
+            return live;
+        if (mode === "live") {
+            throw new Error("No live game found. Run `debuff dev` and open the game in a browser, or use mode headless.");
+        }
+    }
+    return HeadlessSession.start(root, options);
+}
+/** The developer's own browser tab, reached through the dev server's agent link. */
+export class LiveSession {
+    url;
+    attachment;
+    mode = "live";
+    constructor(url, attachment) {
+        this.url = url;
+        this.attachment = attachment;
+    }
+    static async find(root) {
+        let info;
+        try {
+            info = JSON.parse(readFileSync(join(root, DEV_SERVER_FILE), "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+        try {
+            const res = await fetch(new URL(AGENT_PATHS.status, info.url), { signal: AbortSignal.timeout(1500) });
+            const status = (await res.json());
+            if (status.pages === 0)
+                return undefined;
+            // Hold an attach connection while this session lives, so the overlay shows the agent until it stops
+            // (or the agent process exits), not just right after an action.
+            const attachment = new AbortController();
+            const held = await fetch(new URL(AGENT_PATHS.attach, info.url), { signal: attachment.signal });
+            void held.body?.pipeTo(new WritableStream()).catch(() => undefined);
+            return new LiveSession(info.url, attachment);
+        }
+        catch {
+            return undefined; // stale file: the dev server is gone
+        }
+    }
+    async call(method, ...args) {
+        const res = await fetch(new URL(AGENT_PATHS.rpc, this.url), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ method, args }),
+        });
+        const body = (await res.json());
+        if (!body.ok)
+            throw new Error(body.error);
+        return body.result;
+    }
+    async stop() {
+        // The human's tab: leave it running, just let go of any pause the agent made.
+        await this.call("resume").catch(() => undefined);
+        this.attachment.abort();
+    }
+}
+/**
+ * A private game: the project's dev server plus a headless browser page in controlled mode
+ * (`?debuff-scenario`), so time only advances when an agent steps it.
+ */
+export class HeadlessSession {
+    url;
+    server;
+    browser;
+    page;
+    mode = "headless";
+    constructor(url, server, browser, page) {
+        this.url = url;
+        this.server = server;
+        this.browser = browser;
+        this.page = page;
+    }
+    static async start(root, options = {}) {
+        const server = await createDevServer(root, { port: 0, logLevel: "error" });
+        await server.listen();
+        const base = server.resolvedUrls?.local[0];
+        if (!base) {
+            await server.close();
+            throw new Error("Dev server did not report a URL");
+        }
+        let browser;
+        try {
+            browser = await launchBrowser();
+            const page = await browser.newPage({
+                viewport: { width: options.width ?? 960, height: options.height ?? 540 },
+                deviceScaleFactor: 1,
+            });
+            const url = new URL(options.page ?? "/", base);
+            url.searchParams.set("debuff-scenario", "1");
+            await page.goto(url.toString());
+            await page.waitForFunction(hooksReady, undefined, { timeout: 15_000 });
+            return new HeadlessSession(url.toString(), server, browser, page);
+        }
+        catch (err) {
+            await browser?.close();
+            await server.close();
+            throw err;
+        }
+    }
+    /** Call a `window.__DEBUFF_DEV__` method. */
+    call(method, ...args) {
+        return this.page.evaluate(callHook, [method, args]);
+    }
+    async stop() {
+        await this.browser.close();
+        await this.server.close();
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@debuffjp/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for debuff: lets AI agents inspect, build, test and play a debuff game",
+  "keywords": [
+    "game",
+    "mcp",
+    "agents",
+    "model-context-protocol",
+    "debuff"
+  ],
+  "license": "MIT",
+  "homepage": "https://debuff.jp",
+  "bugs": "https://github.com/debuffjp/debuff/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/debuffjp/debuff.git",
+    "directory": "tooling/mcp"
+  },
+  "type": "module",
+  "bin": {
+    "debuff-mcp": "bin/debuff-mcp.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@debuffjp/cli": "0.1.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.7",
+    "playwright-core": "^1.64.1",
+    "vite": "^8.3.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  }
+}