@brass-lantern/mcp 0.0.1-stage → 2.3.1

package/dist/stdio.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Stdout carries the MCP protocol, so a world's console output (at load or while a script runs)
+ * would corrupt it. Swaps the global console for one whose stdout and stderr are both
+ * process.stderr, so every method (log, dir, table, trace, …) lands there; the SDK transport
+ * writes through process.stdout.write directly, so it is unaffected. Returns a function that
+ * puts the original console back.
+ */
+export declare function quietStdout(): () => void;
+/**
+ * The directories worlds may load from: `cwd`, plus each `--root <dir>` (repeatable), resolved
+ * against `cwd`. A trailing `--root` with no directory is ignored, with a warning through `warn`.
+ */
+export declare function parseRoots(args: readonly string[], cwd: string, warn?: (message: string) => void): string[];
+/**
+ * How long one audit_world or play call may run, in milliseconds: `--timeout <seconds>` (the last
+ * one wins), else 10 s. A missing, non-numeric or non-positive value is ignored with a warning;
+ * one past setTimeout's limit (2147483 s, about 24.8 days) is capped at it, with a warning.
+ */
+export declare function parseTimeout(args: readonly string[], warn?: (message: string) => void): number;
+/**
+ * A world can throw after its tool call has returned (a timer, a stray promise). Node's default
+ * would end the server mid-session; instead, log the error to stderr and keep serving. Returns a
+ * function that removes the handlers.
+ */
+export declare function keepRunningOnCrash(log?: (...args: unknown[]) => void): () => void;

package/dist/stdio.js

@@ -0,0 +1,75 @@
+import { Console } from 'node:console';
+import { resolve } from 'node:path';
+import { DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS } from "./run.js";
+/**
+ * Stdout carries the MCP protocol, so a world's console output (at load or while a script runs)
+ * would corrupt it. Swaps the global console for one whose stdout and stderr are both
+ * process.stderr, so every method (log, dir, table, trace, …) lands there; the SDK transport
+ * writes through process.stdout.write directly, so it is unaffected. Returns a function that
+ * puts the original console back.
+ */
+export function quietStdout() {
+    const saved = globalThis.console;
+    globalThis.console = new Console({ stdout: process.stderr, stderr: process.stderr });
+    return () => {
+        globalThis.console = saved;
+    };
+}
+/**
+ * The directories worlds may load from: `cwd`, plus each `--root <dir>` (repeatable), resolved
+ * against `cwd`. A trailing `--root` with no directory is ignored, with a warning through `warn`.
+ */
+export function parseRoots(args, cwd, warn = (m) => process.stderr.write(`${m}\n`)) {
+    const roots = [cwd];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] !== '--root')
+            continue;
+        const dir = args[i + 1];
+        if (dir === undefined)
+            warn('brass-lantern-mcp: --root needs a directory; ignored');
+        else
+            roots.push(resolve(cwd, dir));
+        i += 1;
+    }
+    return roots;
+}
+/**
+ * How long one audit_world or play call may run, in milliseconds: `--timeout <seconds>` (the last
+ * one wins), else 10 s. A missing, non-numeric or non-positive value is ignored with a warning;
+ * one past setTimeout's limit (2147483 s, about 24.8 days) is capped at it, with a warning.
+ */
+export function parseTimeout(args, warn = (m) => process.stderr.write(`${m}\n`)) {
+    const DEFAULT = DEFAULT_TIMEOUT_MS;
+    const MAX_MS = MAX_TIMEOUT_MS;
+    let ms = DEFAULT;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] !== '--timeout')
+            continue;
+        const value = args[i + 1];
+        const seconds = value === undefined || value.trim() === '' ? NaN : Number(value);
+        if (Number.isFinite(seconds) && seconds > 0) {
+            ms = Math.min(seconds * 1000, MAX_MS);
+            if (seconds * 1000 > MAX_MS)
+                warn(`brass-lantern-mcp: --timeout is capped at ${Math.floor(MAX_MS / 1000)} seconds`);
+        }
+        else
+            warn(`brass-lantern-mcp: --timeout needs a positive number of seconds; using ${DEFAULT / 1000}`);
+        i += 1;
+    }
+    return ms;
+}
+/**
+ * A world can throw after its tool call has returned (a timer, a stray promise). Node's default
+ * would end the server mid-session; instead, log the error to stderr and keep serving. Returns a
+ * function that removes the handlers.
+ */
+export function keepRunningOnCrash(log = (...args) => console.error(...args)) {
+    const onException = (error) => log('brass-lantern-mcp: uncaught exception:', error);
+    const onRejection = (reason) => log('brass-lantern-mcp: unhandled rejection:', reason);
+    process.on('uncaughtException', onException);
+    process.on('unhandledRejection', onRejection);
+    return () => {
+        process.off('uncaughtException', onException);
+        process.off('unhandledRejection', onRejection);
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvedEngine } from './engine.ts';
+import type { LoadedWorld } from './load.ts';
+export declare const MAX_COMMANDS = 500;
+export declare const MAX_LINES = 2000;
+/** The lines every engine tool opens with: which world, which engine. */
+export declare function header(loaded: LoadedWorld, resolved: ResolvedEngine): string[];
+export declare function auditReport(loaded: LoadedWorld, resolved: ResolvedEngine): string;
+export declare function playReport(loaded: LoadedWorld, resolved: ResolvedEngine, commands: string[], seed?: number): string;

package/dist/tools.js

@@ -0,0 +1,82 @@
+export const MAX_COMMANDS = 500;
+export const MAX_LINES = 2000;
+/** How many of a long transcript’s last lines survive the cut. */
+const TAIL_LINES = 200;
+const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+/** The lines every engine tool opens with: which world, which engine. */
+export function header(loaded, resolved) {
+    const whose = resolved.source === 'project' ? 'the project’s' : 'bundled with the MCP server';
+    return [
+        `World: ${loaded.exportName} in ${loaded.file}`,
+        `Engine: @brass-lantern/engine ${resolved.version} (${whose})`,
+        ...(resolved.note ? [`Note: ${resolved.note}`] : []),
+    ];
+}
+export function auditReport(loaded, resolved) {
+    const w = loaded.world;
+    const problems = resolved.engine.auditWorld(w);
+    const size = [
+        count(Object.keys(w.rooms).length, 'room', 'rooms'),
+        count(Object.keys(w.items).length, 'item', 'items'),
+        count(Object.keys(w.npcs).length, 'character', 'characters'),
+        count(Object.keys(w.events ?? {}).length, 'event', 'events'),
+    ].join(', ');
+    return [
+        ...header(loaded, resolved),
+        `Size: ${size}`,
+        '',
+        problems.length === 0 ? 'No problems.' : `${count(problems.length, 'problem', 'problems')}:`,
+        ...problems.map((p) => `- ${p}`),
+    ].join('\n');
+}
+/** The pieces of a typed line the regex parser can’t read (what the intent server would be asked about). */
+function unread(resolved, world, line) {
+    const { splitCommands, fallbackParse, andNames } = resolved.engine;
+    if (!splitCommands || !fallbackParse)
+        return [];
+    return splitCommands(line, world.verbs, andNames?.(world)).filter((piece) => !fallbackParse(piece, world.verbs));
+}
+export function playReport(loaded, resolved, commands, seed = 1) {
+    const world = loaded.world;
+    const game = resolved.engine.createGame(world, { seed });
+    const run = commands.slice(0, MAX_COMMANDS);
+    const transcript = [...game.opening];
+    let awaiting = false;
+    let ran = 0;
+    let over = game.state.gameOver;
+    for (const command of run) {
+        if (over)
+            break;
+        transcript.push(`> ${command}`);
+        // An answer to “Which do you mean?” isn’t a command, so it isn’t checked as one.
+        const missed = awaiting ? [] : unread(resolved, world, command);
+        if (missed.length > 0) {
+            transcript.push(`[not understood by the parser: ${missed.map((p) => `“${p}”`).join(', ')}. With the intent server running, an LLM would get a chance to read it.]`);
+        }
+        const reply = game.send(command);
+        transcript.push(...reply.lines);
+        awaiting = reply.awaiting;
+        over = reply.gameOver;
+        ran += 1;
+    }
+    // Over the cap, keep the opening and the ending (where the run finished), and cut the middle.
+    const shown = transcript.length > MAX_LINES
+        ? [...transcript.slice(0, MAX_LINES - TAIL_LINES), `[… ${transcript.length - MAX_LINES} lines cut (over ${MAX_LINES}) …]`, ...transcript.slice(-TAIL_LINES)]
+        : transcript;
+    const s = game.state;
+    const state = {
+        room: `${world.rooms[s.currentRoom]?.name ?? s.currentRoom} (${s.currentRoom})`,
+        inventory: Object.entries(s.locations ?? {})
+            .filter(([, place]) => place === 'player')
+            .map(([id]) => world.items[id]?.name ?? id),
+        flags: Object.keys(s.flags).filter((f) => s.flags[f]).sort(),
+        score: resolved.engine.currentScore?.(world, s) ?? s.vars?.score ?? null,
+        moves: s.moveCount,
+        gameOver: s.gameOver,
+    };
+    const notes = [
+        ...(commands.length > MAX_COMMANDS ? [`Only the first ${MAX_COMMANDS} commands ran.`] : []),
+        ...(over && ran < run.length ? [`Game over after ${ran} of ${run.length} commands.`] : []),
+    ];
+    return [...header(loaded, resolved), `Seed: ${seed}`, '', ...shown, '', ...notes, 'Final state:', '```json', JSON.stringify(state, null, 2), '```'].join('\n');
+}

package/dist/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/worker.js

@@ -0,0 +1,6 @@
+// The worker entry: runs one audit_world or play job (workerData) and posts the result back.
+// Its stdout and stderr are piped to the server's stderr, and run.ts terminates it on the deadline.
+import { parentPort, workerData } from 'node:worker_threads';
+import * as bundled from '@brass-lantern/engine';
+import { runJob } from "./job.js";
+parentPort?.postMessage(await runJob(workerData, bundled));

package/package.json

@@ -1 +1,47 @@
-{"name":"@brass-lantern/mcp","version":"0.0.1-stage","description":"Placeholder; the real package is published by CI.","license":"MIT"}
+{
+  "name": "@brass-lantern/mcp",
+  "version": "2.3.1",
+  "author": "Todd Greco <mrballistic@gmail.com>",
+  "description": "A Model Context Protocol server for brass-lantern: lets a coding agent audit, play and read the docs for the text-adventure world it is writing.",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/mrballistic/brass-lantern.git", "directory": "packages/mcp" },
+  "homepage": "https://mrballistic.github.io/brass-lantern/",
+  "bugs": "https://github.com/mrballistic/brass-lantern/issues",
+  "keywords": ["text-adventure", "interactive-fiction", "mcp", "model-context-protocol", "coding-agent"],
+  "type": "module",
+  "sideEffects": false,
+  "bin": { "brass-lantern-mcp": "./dist/cli.js" },
+  "exports": {
+    ".": { "@brass-lantern/source": "./src/server.ts", "types": "./dist/server.d.ts", "default": "./dist/server.js" },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/server.d.ts",
+  "files": ["dist", "!dist/**/*.map", "README.md", "LICENSE"],
+  "scripts": {
+    "prebuild": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.build.json && tsx scripts/bundle-docs.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint .",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@brass-lantern/engine": "^2.3.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "jiti": "^2.7.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.12.0",
+    "eslint": "^10.12.0",
+    "globals": "^17.0.0",
+    "tsx": "^4.23.15",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.71.0",
+    "vitest": "^5.0.3"
+  },
+  "publishConfig": { "access": "public", "provenance": true },
+  "engines": { "node": ">=24" }
+}