@brass-lantern/mcp 0.0.0-stage → 2.3.0

package/dist/docs/pages.json

@@ -0,0 +1,74 @@
+[
+  {
+    "path": "index",
+    "title": "Home"
+  },
+  {
+    "path": "guide/getting-started",
+    "title": "Getting started"
+  },
+  {
+    "path": "guide/using-the-library",
+    "title": "Using the library"
+  },
+  {
+    "path": "guide/coding-agents",
+    "title": "Coding agents"
+  },
+  {
+    "path": "guide/z-machine",
+    "title": "Playing story files (Zork)"
+  },
+  {
+    "path": "guide/porting-zork",
+    "title": "Porting Zork"
+  },
+  {
+    "path": "guide/how-it-works",
+    "title": "How it works"
+  },
+  {
+    "path": "guide/intent-server",
+    "title": "The intent server"
+  },
+  {
+    "path": "guide/deploying",
+    "title": "Deploying"
+  },
+  {
+    "path": "guide/building-worlds/index",
+    "title": "Overview"
+  },
+  {
+    "path": "guide/building-worlds/two-rooms",
+    "title": "A two-room game"
+  },
+  {
+    "path": "guide/your-first-world",
+    "title": "The demo game: Snack Attack"
+  },
+  {
+    "path": "guide/building-worlds/recipes",
+    "title": "Recipes"
+  },
+  {
+    "path": "guide/testing",
+    "title": "Testing a world"
+  },
+  {
+    "path": "reference/world-schema",
+    "title": "World schema"
+  },
+  {
+    "path": "reference/conditions-and-events",
+    "title": "Conditions and events"
+  },
+  {
+    "path": "reference/commands",
+    "title": "Player commands"
+  },
+  {
+    "path": "reference/cartridges",
+    "title": "Cartridges and storage"
+  }
+]

package/dist/docs.d.ts

@@ -0,0 +1,21 @@
+export interface DocPage {
+    /** 'reference/world-schema', 'guide/building-worlds/index'. */
+    path: string;
+    title: string;
+    markdown: string;
+}
+export interface Docs {
+    index: string;
+    pages: DocPage[];
+}
+/** Reads a bundle written by scripts/bundle-docs.ts. */
+export declare function readDocs(dir: string): Docs;
+/** A page name as an agent might type it, as a bundle path. */
+export declare function normalizePage(page: string): string;
+export declare function docsReport(docs: Docs, args: {
+    page?: string;
+    query?: string;
+}): {
+    text: string;
+    isError: boolean;
+};

package/dist/docs.js

@@ -0,0 +1,89 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const MAX_SECTIONS = 5;
+const MAX_SECTION_CHARS = 4000;
+/** Reads a bundle written by scripts/bundle-docs.ts. */
+export function readDocs(dir) {
+    const list = JSON.parse(readFileSync(join(dir, 'pages.json'), 'utf8'));
+    return {
+        index: readFileSync(join(dir, 'llms.txt'), 'utf8'),
+        pages: list.map((p) => ({ ...p, markdown: readFileSync(join(dir, 'pages', `${p.path}.md`), 'utf8') })),
+    };
+}
+/** A page name as an agent might type it, as a bundle path. */
+export function normalizePage(page) {
+    const trimmed = page.trim().replace(/^\/+/, '').replace(/\.md$/, '');
+    if (trimmed === '' || trimmed.endsWith('/'))
+        return `${trimmed}index`;
+    return trimmed;
+}
+/** A page split at its headings: each heading with the text under it. */
+function sections(page) {
+    const out = [];
+    let current = { heading: page.title, text: '' };
+    // The open fence, if any. A fence opens on ``` or ~~~ (with an optional info string) and closes
+    // only on a bare fence of the same character at least as long, so a ```json line shown inside a
+    // ````text block doesn't end it.
+    let fence;
+    for (const line of page.markdown.split('\n')) {
+        const marker = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+        if (marker) {
+            const run = marker[1];
+            if (!fence)
+                fence = { char: run[0], length: run.length };
+            else if (run[0] === fence.char && run.length >= fence.length && marker[2].trim() === '')
+                fence = undefined;
+        }
+        const heading = !fence && /^#{1,4}\s+(.+)$/.exec(line);
+        if (heading) {
+            if (current.text.trim())
+                out.push(current);
+            current = { heading: heading[1].trim(), text: `${line}\n` };
+        }
+        else {
+            current.text += `${line}\n`;
+        }
+    }
+    if (current.text.trim())
+        out.push(current);
+    return out;
+}
+/** Counts how often `term` appears in `text`, up to `cap`, without a regex (both are plain lowercase strings). */
+function occurrences(text, term, cap) {
+    let n = 0;
+    for (let at = text.indexOf(term); at !== -1 && n < cap; at = text.indexOf(term, at + term.length))
+        n += 1;
+    return n;
+}
+export function docsReport(docs, args) {
+    if (args.page !== undefined) {
+        const wanted = normalizePage(args.page);
+        const page = docs.pages.find((p) => p.path === wanted);
+        if (!page)
+            return { isError: true, text: `No page “${args.page}”. Pages:\n${docs.pages.map((p) => `- ${p.path} (${p.title})`).join('\n')}` };
+        return { isError: false, text: page.markdown };
+    }
+    if (args.query !== undefined && args.query.trim() !== '') {
+        const terms = [...new Set(args.query.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 3))];
+        const scored = docs.pages
+            .flatMap((page) => sections(page).map((s) => ({ page, ...s })))
+            .map((s) => {
+            const heading = s.heading.toLowerCase();
+            const body = s.text.toLowerCase();
+            const score = terms.reduce((sum, t) => sum + (heading.includes(t) ? 3 : 0) + occurrences(body, t, 5), 0);
+            return { ...s, score };
+        })
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, MAX_SECTIONS);
+        if (scored.length === 0)
+            return { isError: false, text: `No sections matched “${args.query}”. Try other words, or call docs with no arguments for the index.` };
+        return {
+            isError: false,
+            text: scored
+                .map((s) => `## ${s.page.title} › ${s.heading}\nSource: ${s.page.path}\n\n${s.text.length > MAX_SECTION_CHARS ? `${s.text.slice(0, MAX_SECTION_CHARS)}\n[… cut; ask for the page “${s.page.path}” for all of it]` : s.text.trim()}`)
+                .join('\n\n'),
+        };
+    }
+    return { isError: false, text: `${docs.index}\n\nAsk for a page with “page” (e.g. reference/world-schema), or search with “query”.` };
+}

package/dist/engine.d.ts

@@ -0,0 +1,16 @@
+import type * as EngineModule from '@brass-lantern/engine';
+/** What the tools use of an engine. The parser helpers are optional: older engines may lack them. */
+export type Engine = Pick<typeof EngineModule, 'createGame' | 'auditWorld' | 'ENGINE_VERSION'> & Partial<Pick<typeof EngineModule, 'fallbackParse' | 'splitCommands' | 'andNames' | 'currentScore'>>;
+export interface ResolvedEngine {
+    engine: Engine;
+    version: string;
+    source: 'project' | 'bundled';
+    /** Why the project’s engine wasn’t used, when it was found but couldn’t be. */
+    note?: string;
+}
+/**
+ * The engine the world’s own project resolves (so a 2.2 project is audited by 2.2’s rules),
+ * else `bundled`. A project engine that can’t be resolved or imported, or lacks the API, falls back
+ * with a note; only a project with no engine installed falls back silently.
+ */
+export declare function resolveEngine(worldFile: string, bundled: Engine): Promise<ResolvedEngine>;

package/dist/engine.js

@@ -0,0 +1,40 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+/**
+ * The engine the world’s own project resolves (so a 2.2 project is audited by 2.2’s rules),
+ * else `bundled`. A project engine that can’t be resolved or imported, or lacks the API, falls back
+ * with a note; only a project with no engine installed falls back silently.
+ */
+export async function resolveEngine(worldFile, bundled) {
+    const fallback = (note) => ({ engine: bundled, version: bundled.ENGINE_VERSION, source: 'bundled', ...(note ? { note } : {}) });
+    let entry;
+    try {
+        entry = createRequire(worldFile).resolve('@brass-lantern/engine');
+    }
+    catch (error) {
+        const { code, message } = error;
+        // Silent only for a genuine “not installed”; anything else (a broken exports map, a malformed
+        // package.json) means the project has an engine we couldn’t use, which the agent should know.
+        if (code === 'MODULE_NOT_FOUND' && typeof message === 'string' && message.includes('@brass-lantern/engine'))
+            return fallback();
+        return fallback(`couldn’t resolve the project’s @brass-lantern/engine (${typeof message === 'string' ? message.split('\n')[0] : String(error)}); used the bundled engine`);
+    }
+    try {
+        const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(entry).href)));
+        if (typeof mod.createGame !== 'function' || typeof mod.auditWorld !== 'function') {
+            return fallback(`the project’s @brass-lantern/engine doesn’t export createGame and auditWorld; used the bundled engine`);
+        }
+        return { engine: mod, version: typeof mod.ENGINE_VERSION === 'string' ? mod.ENGINE_VERSION : 'unknown', source: 'project' };
+    }
+    catch (error) {
+        return fallback(`couldn’t load the project’s @brass-lantern/engine (${error instanceof Error ? error.message : String(error)}); used the bundled engine`);
+    }
+}

package/dist/load.d.ts

@@ -0,0 +1,22 @@
+import type { World } from '@brass-lantern/engine';
+/** The module kinds a world can be written as. */
+export declare const WORLD_EXTENSIONS: readonly string[];
+/** A world file that couldn't be loaded: its message is the tool’s reply. */
+export declare class WorldLoadError extends Error {
+}
+/** A world is an object with rooms, items, characters and a starting room. */
+export declare function isWorldShaped(value: unknown): value is World;
+export interface LoadedWorld {
+    world: World;
+    /** The absolute path loaded. */
+    file: string;
+    /** The export the world came from ('default' for a default export). */
+    exportName: string;
+}
+/**
+ * Loads a world module fresh (no module or transpile cache, so an edit is seen on the next call),
+ * resolving `path` against `cwd`. The export is the one named, else a world default export, else
+ * the only world-shaped named export. Every failure is a WorldLoadError whose message starts with
+ * the path as given.
+ */
+export declare function loadWorld(path: string, exportName: string | undefined, cwd: string): Promise<LoadedWorld>;

package/dist/load.js

@@ -0,0 +1,105 @@
+import { existsSync } from 'node:fs';
+import { register } from 'node:module';
+import { extname, isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createJiti } from 'jiti';
+import { createJiti as createNativeJiti } from 'jiti/native';
+/** The module kinds a world can be written as. */
+export const WORLD_EXTENSIONS = ['.ts', '.mts', '.js', '.mjs'];
+/** A world file that couldn't be loaded: its message is the tool’s reply. */
+export class WorldLoadError extends Error {
+}
+/** A world is an object with rooms, items, characters and a starting room. */
+export function isWorldShaped(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return ['rooms', 'items', 'npcs'].every((key) => typeof v[key] === 'object' && v[key] !== null) && typeof v.startRoom === 'string';
+}
+/**
+ * jiti hands native ES modules (.mjs, and .js in a "type": "module" package) to Node's loader,
+ * which caches by URL, so jiti's own moduleCache: false can't refresh them. Those files are
+ * imported natively under a unique ?bl= query instead, and this resolve hook carries the query
+ * onto every file they import by a relative or absolute specifier, so a helper edit is seen too.
+ * Bare specifiers (packages) are never touched, whatever their real path: a symlinked package
+ * (workspaces, npm link) has no /node_modules/ in its resolved URL, and re-instantiating it per
+ * load would leak its whole graph. So packages stay cached and are not reloaded; each call keeps
+ * one generation of the world's own project files for the life of the process. The hook only
+ * touches modules whose importer carries the query; nothing else in the process is affected.
+ */
+const FRESH_HOOK = `
+export async function resolve(specifier, context, next) {
+  const result = await next(specifier, context);
+  const parent = context.parentURL;
+  const query = parent && /[?&]bl=\\d+/.exec(parent);
+  if (query && /^(\\.{1,2}\\/|\\/|file:)/.test(specifier) && result.url.startsWith('file:') && !result.url.includes('?')) {
+    return { ...result, url: result.url + '?' + query[0].replace(/^&/, '') };
+  }
+  return result;
+}`;
+// jiti/native is a plain import() living in node_modules, so a bundler or test runner (Vitest's
+// module runner rewrites an import() in our own source) can't route it around the loader hook.
+const native = createNativeJiti(import.meta.url);
+let hookRegistered = false;
+let generation = 0;
+async function importNativeFresh(file) {
+    if (!hookRegistered) {
+        register(`data:text/javascript,${encodeURIComponent(FRESH_HOOK)}`);
+        hookRegistered = true;
+    }
+    return (await native.import(`${pathToFileURL(file).href}?bl=${++generation}`));
+}
+function jitiImport(file) {
+    return createJiti(import.meta.url, { moduleCache: false, fsCache: false, tryNative: false }).import(file);
+}
+/** Native and fresh; ES syntax in a CommonJS-typed .js falls back to jiti. */
+async function importModule(file) {
+    try {
+        return await importNativeFresh(file);
+    }
+    catch (error) {
+        // jiti only for what it exists for: ES syntax in a .js of a CommonJS-typed package.
+        // Anything else (a throw at top level, a real syntax error) is Node's error to report.
+        if (error instanceof SyntaxError && /import statement outside a module|Unexpected token 'export'|Cannot use 'import\.meta'/.test(error.message)) {
+            return jitiImport(file);
+        }
+        throw error;
+    }
+}
+/**
+ * Loads a world module fresh (no module or transpile cache, so an edit is seen on the next call),
+ * resolving `path` against `cwd`. The export is the one named, else a world default export, else
+ * the only world-shaped named export. Every failure is a WorldLoadError whose message starts with
+ * the path as given.
+ */
+export async function loadWorld(path, exportName, cwd) {
+    const file = isAbsolute(path) ? path : resolve(cwd, path);
+    if (!WORLD_EXTENSIONS.includes(extname(file)))
+        throw new WorldLoadError(`${path}: a world is a .ts, .mts, .js or .mjs module`);
+    if (!existsSync(file))
+        throw new WorldLoadError(`${path}: no such file (looked in ${cwd})`);
+    let mod;
+    try {
+        mod = (await (extname(file) === '.mjs' || extname(file) === '.js' ? importModule(file) : jitiImport(file)));
+    }
+    catch (error) {
+        throw new WorldLoadError(`${path}: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`);
+    }
+    const exportsList = () => Object.keys(mod).join(', ') || 'none';
+    if (exportName !== undefined) {
+        if (!(exportName in mod))
+            throw new WorldLoadError(`${path}: no export “${exportName}” (exports: ${exportsList()})`);
+        const value = mod[exportName];
+        if (!isWorldShaped(value))
+            throw new WorldLoadError(`${path}: export “${exportName}” isn’t a world (a world has rooms, items, npcs and startRoom)`);
+        return { world: value, file, exportName };
+    }
+    if (isWorldShaped(mod.default))
+        return { world: mod.default, file, exportName: 'default' };
+    const candidates = Object.keys(mod).filter((key) => key !== 'default' && isWorldShaped(mod[key]));
+    if (candidates.length === 1)
+        return { world: mod[candidates[0]], file, exportName: candidates[0] };
+    if (candidates.length === 0)
+        throw new WorldLoadError(`${path}: no world-shaped export (exports: ${exportsList()})`);
+    throw new WorldLoadError(`${path}: several worlds (${candidates.join(', ')}); name one with “export”`);
+}

package/dist/server.d.ts

@@ -0,0 +1,23 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Engine } from './engine.ts';
+export { quietStdout } from './stdio.ts';
+export interface ServerOptions {
+    /** The engine to use when a world’s project has none of its own. */
+    bundled: Engine;
+    /** Where the docs bundle is. Default: the one shipped with this package (dist/docs). */
+    docsDir?: string;
+    /** Relative world paths resolve against this (the client’s launch directory). */
+    cwd: string;
+    /** Worlds must live inside one of these directories (symlinks resolved). Default: [cwd]. */
+    roots?: string[];
+    version: string;
+}
+/**
+ * The brass-lantern MCP server, unconnected: pass it a transport. Stdout-based transports also
+ * want quietStdout(), so a world’s console output can’t corrupt the protocol.
+ *
+ * Loading a .mjs or .js world registers a process-wide module resolve hook (once). It only acts
+ * on imports made by modules this server loaded under its own ?bl= query, so the rest of the
+ * process resolves as before.
+ */
+export declare function createServer(options: ServerOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,96 @@
+import { realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { docsReport, readDocs } from "./docs.js";
+import { resolveEngine } from "./engine.js";
+import { loadWorld, WorldLoadError } from "./load.js";
+import { auditReport, header, MAX_COMMANDS, playReport } from "./tools.js";
+export { quietStdout } from "./stdio.js";
+const reply = (text, isError = false) => ({ content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) });
+const PATH = z.string().min(1).describe('The world module: a .ts, .mts, .js or .mjs file, relative to the directory the server was started in, or absolute.');
+const EXPORT = z.string().min(1).optional().describe('Which export is the world. Default: the default export, else the only world-shaped export.');
+/**
+ * The brass-lantern MCP server, unconnected: pass it a transport. Stdout-based transports also
+ * want quietStdout(), so a world’s console output can’t corrupt the protocol.
+ *
+ * Loading a .mjs or .js world registers a process-wide module resolve hook (once). It only acts
+ * on imports made by modules this server loaded under its own ?bl= query, so the rest of the
+ * process resolves as before.
+ */
+export function createServer(options) {
+    const docsDir = options.docsDir ?? fileURLToPath(new URL('./docs/', import.meta.url));
+    const server = new McpServer({ name: 'brass-lantern', version: options.version });
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return p;
+        }
+    };
+    const roots = (options.roots ?? [options.cwd]).map((r) => real(resolve(options.cwd, r)));
+    const allowed = (path) => {
+        const file = real(resolve(options.cwd, path));
+        return roots.some((root) => {
+            const rel = relative(root, file);
+            return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+        });
+    };
+    /** Loads the world and its engine, runs `report`, and turns any failure into an error result. */
+    async function withWorld(path, exportName, report) {
+        if (!allowed(path))
+            return reply(`${path}: outside the allowed directories (${roots.join(', ')}). Start the server with --root <dir> to allow another.`, true);
+        let loaded;
+        try {
+            loaded = await loadWorld(path, exportName, options.cwd);
+        }
+        catch (error) {
+            if (error instanceof WorldLoadError)
+                return reply(error.message, true);
+            return reply(`The world couldn’t be loaded: ${error instanceof Error ? error.message : String(error)}`, true);
+        }
+        let resolved;
+        try {
+            resolved = await resolveEngine(loaded.file, options.bundled);
+            return reply(report(loaded, resolved));
+        }
+        catch (error) {
+            const lines = resolved ? [...header(loaded, resolved), ''] : [];
+            return reply(`${lines.join('\n')}${lines.length ? '\n' : ''}The engine threw: ${error instanceof Error ? error.message : String(error)}`, true);
+        }
+    }
+    server.registerTool('audit_world', {
+        title: 'Audit a Brass Lantern world',
+        description: 'Checks a world file the way the engine’s auditWorld does: exits that go nowhere, conditions that don’t parse, effects naming things that don’t exist, unmapped flag labels and more. Reports the engine version used.',
+        inputSchema: { path: PATH, export: EXPORT },
+    }, ({ path, export: exportName }) => withWorld(path, exportName, auditReport));
+    server.registerTool('play', {
+        title: 'Play commands in a Brass Lantern world',
+        description: `Starts a fresh game (seeded, so runs repeat exactly) and types each command, as a player would, with no LLM. Returns the transcript and the final state (room, inventory, flags, score, moves, game over). Each call starts from the beginning; at most ${MAX_COMMANDS} commands.`,
+        inputSchema: {
+            path: PATH,
+            export: EXPORT,
+            commands: z.array(z.string()).min(1).describe('Commands to type, in order (e.g. ["open drawer", "take key", "north"]).'),
+            seed: z.number().int().optional().describe('Random seed. Default 1.'),
+        },
+    }, ({ path, export: exportName, commands, seed }) => withWorld(path, exportName, (loaded, resolved) => playReport(loaded, resolved, commands, seed)));
+    server.registerTool('docs', {
+        title: 'Brass Lantern documentation',
+        description: 'The docs for this version: with no arguments, the index of pages; with “page”, one page’s markdown (e.g. reference/world-schema); with “query”, the best-matching sections. If both are given, “page” wins.',
+        inputSchema: {
+            page: z.string().optional().describe('A page path from the index, e.g. reference/world-schema or guide/building-worlds/recipes.'),
+            query: z.string().optional().describe('Words to search the docs for, e.g. "timers fuses".'),
+        },
+    }, ({ page, query }) => {
+        try {
+            const r = docsReport(readDocs(docsDir), { page, query });
+            return reply(r.text, r.isError);
+        }
+        catch (error) {
+            return reply(`The docs bundle couldn’t be read (${error instanceof Error ? error.message : String(error)}).`, true);
+        }
+    });
+    return server;
+}

package/dist/stdio.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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[];
+/**
+ * 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,49 @@
+import { Console } from 'node:console';
+import { resolve } from 'node:path';
+/**
+ * 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;
+}
+/**
+ * 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');
+}