@brass-lantern/mcp 0.0.1-stage → 2.3.1

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,42 @@
+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”, whose message quotes the bare specifier. Anything
+        // else (a broken exports map, a malformed package.json, an exports target that’s missing, whose
+        // message names a path inside the package) 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/job.d.ts

@@ -0,0 +1,22 @@
+import { type Engine } from './engine.ts';
+/** One audit_world or play call: everything a worker needs, all structured-cloneable. */
+export interface Job {
+    op: 'audit' | 'play';
+    /** The world path as the agent gave it (already checked against the roots). */
+    path: string;
+    exportName?: string;
+    cwd: string;
+    commands?: string[];
+    seed?: number;
+}
+/** A tool reply in plain form. */
+export interface JobResult {
+    text: string;
+    isError: boolean;
+}
+/**
+ * Loads the world and its engine and runs the report; any failure becomes an error result. The
+ * worker calls this with the engine it imported; it runs the world's code in whatever thread
+ * calls it.
+ */
+export declare function runJob(job: Job, bundled: Engine): Promise<JobResult>;

package/dist/job.js

@@ -0,0 +1,29 @@
+import { resolveEngine } from "./engine.js";
+import { loadWorld, WorldLoadError } from "./load.js";
+import { auditReport, header, playReport } from "./tools.js";
+/**
+ * Loads the world and its engine and runs the report; any failure becomes an error result. The
+ * worker calls this with the engine it imported; it runs the world's code in whatever thread
+ * calls it.
+ */
+export async function runJob(job, bundled) {
+    let loaded;
+    try {
+        loaded = await loadWorld(job.path, job.exportName, job.cwd);
+    }
+    catch (error) {
+        if (error instanceof WorldLoadError)
+            return { text: error.message, isError: true };
+        return { text: `The world couldn’t be loaded: ${error instanceof Error ? error.message : String(error)}`, isError: true };
+    }
+    let resolved;
+    try {
+        resolved = await resolveEngine(loaded.file, bundled);
+        const text = job.op === 'audit' ? auditReport(loaded, resolved) : playReport(loaded, resolved, job.commands ?? [], job.seed);
+        return { text, isError: false };
+    }
+    catch (error) {
+        const lines = resolved ? [...header(loaded, resolved), ''] : [];
+        return { text: `${lines.join('\n')}${lines.length ? '\n' : ''}The engine threw: ${error instanceof Error ? error.message : String(error)}`, isError: true };
+    }
+}

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,106 @@
+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 as long as the loader lives. The server
+ * loads each world in a fresh worker thread, so there the hook and those modules last one call.
+ * The hook only touches modules whose importer carries the query; nothing else 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/run.d.ts

@@ -0,0 +1,16 @@
+import type { Job, JobResult } from './job.ts';
+/** How long a world gets by default: 10 s. */
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+/** The longest delay setTimeout honors (2^31 − 1 ms, about 24.8 days); past it, Node fires after 1 ms. */
+export declare const MAX_TIMEOUT_MS = 2147483647;
+/**
+ * Runs a job in a fresh worker thread, so a world that loops forever, calls process.exit(),
+ * crashes or writes to stdout can't freeze, end or corrupt the server. The worker's stdout and
+ * stderr go to this process's stderr. Never rejects: every outcome (a worker that can't even
+ * start included) is a result. `timeoutHint` ends the timeout message; `workerUrl` is for tests.
+ */
+export declare function runInWorker(job: Job, { timeoutMs: requested, timeoutHint, workerUrl }?: {
+    timeoutMs?: number;
+    timeoutHint?: string;
+    workerUrl?: URL;
+}): Promise<JobResult>;

package/dist/run.js

@@ -0,0 +1,57 @@
+import { Worker } from 'node:worker_threads';
+/** How long a world gets by default: 10 s. */
+export const DEFAULT_TIMEOUT_MS = 10_000;
+/** The longest delay setTimeout honors (2^31 − 1 ms, about 24.8 days); past it, Node fires after 1 ms. */
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+// From source (tests, the repo) the worker is TypeScript and the engine resolves to its source;
+// published, both are plain JavaScript in dist/.
+const fromSource = import.meta.url.endsWith('.ts');
+const WORKER_URL = new URL(fromSource ? './worker.ts' : './worker.js', import.meta.url);
+// Published, the worker deliberately gets no flags: an empty execArgv stops it inheriting the
+// server's own (process.execArgv), which a world's worker has no business running under.
+const EXEC_ARGV = fromSource ? ['--import', 'tsx', '--conditions=@brass-lantern/source'] : [];
+/** How long a worker that has answered may linger before it is stopped. */
+const GRACE_MS = 500;
+const seconds = (ms) => String(Number((ms / 1000).toFixed(3)));
+/**
+ * Runs a job in a fresh worker thread, so a world that loops forever, calls process.exit(),
+ * crashes or writes to stdout can't freeze, end or corrupt the server. The worker's stdout and
+ * stderr go to this process's stderr. Never rejects: every outcome (a worker that can't even
+ * start included) is a result. `timeoutHint` ends the timeout message; `workerUrl` is for tests.
+ */
+export function runInWorker(job, { timeoutMs: requested = DEFAULT_TIMEOUT_MS, timeoutHint = 'Raise the server’s timeout.', workerUrl = WORKER_URL } = {}) {
+    // NaN means the default; anything past setTimeout's limit (Infinity included) is capped.
+    const timeoutMs = Number.isNaN(requested) ? DEFAULT_TIMEOUT_MS : Math.min(Math.max(requested, 1), MAX_TIMEOUT_MS);
+    return new Promise((resolve) => {
+        let worker;
+        try {
+            worker = new Worker(workerUrl, { workerData: job, stdout: true, stderr: true, execArgv: EXEC_ARGV });
+        }
+        catch (error) {
+            resolve({ isError: true, text: `The world runner couldn’t start: ${error instanceof Error ? error.message : String(error)}` });
+            return;
+        }
+        // Forwarded chunk by chunk rather than piped, so concurrent calls add no listeners to stderr.
+        const forward = (chunk) => process.stderr.write(chunk);
+        worker.stdout.on('data', forward);
+        worker.stderr.on('data', forward);
+        let settled = false;
+        const settle = (result, grace = GRACE_MS) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+            // A world may leave timers running: once the answer is in, the worker gets a moment to exit
+            // on its own (flushing its output to stderr), then goes.
+            if (grace === 0)
+                void worker.terminate();
+            else
+                setTimeout(() => void worker.terminate(), grace).unref();
+        };
+        const timer = setTimeout(() => settle({ isError: true, text: `The world didn’t finish within ${seconds(timeoutMs)} s (a script may loop forever). ${timeoutHint}` }, 0), timeoutMs);
+        worker.on('message', (result) => settle(typeof result?.text === 'string' ? { text: result.text, isError: result.isError === true } : { isError: true, text: 'The world crashed: its worker sent something other than a result.' }));
+        worker.on('error', (error) => settle({ isError: true, text: `The world crashed: ${error instanceof Error ? error.message : String(error)}` }));
+        worker.on('exit', (code) => settle({ isError: true, text: `The world ended before answering (exit code ${code}); a world shouldn’t call process.exit() or leave a top-level await pending.` }));
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1,47 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Engine } from './engine.ts';
+import { type Job, type JobResult } from './job.ts';
+export { quietStdout } from './stdio.ts';
+export type { Job, JobResult } from './job.ts';
+export interface ServerOptions {
+    /**
+     * @deprecated Only used by a custom runJob; pass `runJob: inProcessRunner(engine)` to run
+     * in-process with your engine (without the timeout). The default runner’s worker imports this
+     * package’s own @brass-lantern/engine (an engine can’t cross threads).
+     */
+    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;
+    /**
+     * How long one audit_world or play call may run before its worker is stopped, in milliseconds.
+     * Default 10 s. Must be a positive number (createServer throws a RangeError otherwise); past
+     * 2147483647 (about 24.8 days, setTimeout’s limit) it is capped.
+     */
+    timeoutMs?: number;
+    /** The last sentence of the timeout message, saying how to raise the limit. Default: “Raise the server’s timeout.” */
+    timeoutHint?: string;
+    /**
+     * Runs one audit_world or play call. Default: a fresh worker thread per call with the deadline
+     * above, so a world can’t freeze, end or write over the server.
+     */
+    runJob?: (job: Job) => Promise<JobResult>;
+}
+/**
+ * A runJob that runs each call in this thread with `engine` as the fallback engine: the 2.3.0
+ * behavior. No timeout and no isolation, so a world that loops forever freezes the server.
+ */
+export declare function inProcessRunner(engine: Engine): (job: Job) => Promise<JobResult>;
+/**
+ * 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,97 @@
+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 { runJob as runJobWith } from "./job.js";
+import { DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, runInWorker } from "./run.js";
+import { MAX_COMMANDS } 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.');
+/**
+ * A runJob that runs each call in this thread with `engine` as the fallback engine: the 2.3.0
+ * behavior. No timeout and no isolation, so a world that loops forever freezes the server.
+ */
+export function inProcessRunner(engine) {
+    return (job) => runJobWith(job, engine);
+}
+let bundledNoted = false;
+/**
+ * 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));
+        });
+    };
+    if (options.bundled && !options.runJob && !bundledNoted) {
+        bundledNoted = true;
+        process.stderr.write('brass-lantern-mcp: the bundled option is ignored (each call runs in a worker with this package’s engine); pass runJob: inProcessRunner(engine) to use your engine in-process.\n');
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (!(timeoutMs > 0))
+        throw new RangeError(`timeoutMs must be a positive number of milliseconds (it is capped at ${MAX_TIMEOUT_MS})`);
+    const { timeoutHint } = options;
+    const runJob = options.runJob ?? ((job) => runInWorker(job, { timeoutMs, timeoutHint }));
+    /** Checks the roots here (an outside path never reaches the runner), then runs the job. */
+    async function withWorld(job) {
+        if (!allowed(job.path))
+            return reply(`${job.path}: outside the allowed directories (${roots.join(', ')}). Start the server with --root <dir> to allow another.`, true);
+        const result = await runJob(job);
+        return reply(result.text, result.isError);
+    }
+    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({ op: 'audit', path, exportName, cwd: options.cwd }));
+    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({ op: 'play', path, exportName, cwd: options.cwd, 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;
+}