@instruktlabs/kiln 1.0.0 → 1.2.0

package/lib/mcp-core.js

@@ -0,0 +1,279 @@
+/**
+ * The protocol half of the Kiln MCP server, shared by the thin stdio entry
+ * (`src/mcp-server.ts`) and the in-process server the tests build
+ * (`createKilnMcpServer` in `src/mcp-engine.ts`): identity, instructions,
+ * the request handlers over a tool manifest, cache hints and the stdin guard.
+ *
+ * Nothing here imports the engine. That is the whole point: the entry bundles
+ * this module with a generated manifest and loads `mcp-engine` on the first
+ * call that needs it, so the handshake, `server/discover` and the tool list
+ * are answered in the time it takes Node to load the protocol library, not
+ * the time it takes to load three, zod, sharp and the registry. Codex gives
+ * an optional server one second before it goes on without its tools.
+ *
+ * The handlers are written on the low-level `Server` rather than `McpServer`
+ * because the advertised definitions must be exact bytes from the manifest
+ * (stable across processes, no library-side schema conversion at startup)
+ * and because the capabilities must say only what Kiln does: the list of
+ * tools and resources is fixed for a build, so no `listChanged` is
+ * advertised and none is acknowledged on `subscriptions/listen`.
+ */
+import { ProtocolError, ProtocolErrorCode, Server, } from '@modelcontextprotocol/server';
+import { EXTENSION_ID as MCP_APPS_EXTENSION_ID, RESOURCE_MIME_TYPE as MCP_APPS_MIME_TYPE, } from '@modelcontextprotocol/ext-apps/server';
+import { StdioServerTransport, serveStdio, } from '@modelcontextprotocol/server/stdio';
+import { readFile } from 'node:fs/promises';
+import { KILN_ASSET_WIDGET_URI } from "./asset-widget-uri.js";
+import { ENGINE_VERSION } from "./engine-identity.js";
+import { CATEGORY_MIGRATION_MESSAGE } from "./requirements-json.js";
+/** Server identity reported in the handshake and stamped into every 2026-07-28 result. */
+export const MCP_SERVER_NAME = 'kiln';
+export const MCP_SERVER_VERSION = ENGINE_VERSION;
+/**
+ * The spec's optional `instructions` field, returned by `initialize` and
+ * `server/discover`.
+ *
+ * This is the only orientation channel that survives every install shape. A
+ * user who configures the server by hand and opens an empty folder has no
+ * AGENTS.md, no CLAUDE.md and no registered skills -- but the skills do ship
+ * beside the server, so the useful thing to say is that they exist and where.
+ *
+ * At most 700 characters, with the essentials inside the first 512 (v1 contract
+ * rule 5): the text rides on every session start in every client, and the
+ * harnesses that cut it cut from the end. It names no absolute path, so the
+ * same bytes serve every installation.
+ */
+export const MCP_SERVER_INSTRUCTIONS = "Kiln turns JavaScript you write into GLB assets and returns rendered views. Work by reference: send a program once to kiln_validate or kiln_render, keep the returned programRef exactly, and use it for every later render, inspect, kiln_source and kiln_edit call; never resend a program to change part of it. Call kiln_discover first for helper contracts, with capabilities:true for the host's runtime, project and camera facts. Read viewFidelity before judging materials: a CPU view shows shape, not material; GPU views need the render service in render-service/. Agent Skills for authoring, refining, QA and scenes ship in skills/ beside this server's dist/; read the matching SKILL.md first.";
+export const MCP_OPERATION_INSTRUCTIONS = 'Kiln turns authored JavaScript into editable GLB assets and rendered views. Send source once to kiln_validate or kiln_render, then preserve the exact programRef for later reads, edits and renders. Use kiln_discover for helper contracts and full input shapes; use kiln_capabilities for host configuration and limits. Read viewFidelity before judging materials: CPU geometry views are not material evidence. Search saved assets with kiln_assets_search; reopen exact source with kiln_assets_restore. Browse materials with kiln_material_search and create with kiln_material_create. Save only when requested. Pin collection, asset and revision IDs for reuse and export.';
+/** Presentation hints for the asset viewer app, hidden from the language model. */
+export const KILN_WIDGET_META = {
+    ui: { prefersBorder: true, csp: { connectDomains: [], resourceDomains: [] } },
+    'openai/widgetDescription': 'Inspect the saved 3D asset and download its GLB or editable bundle.',
+    'openai/widgetPrefersBorder': true,
+};
+export const KILN_WIDGET_RESOURCE = {
+    uri: KILN_ASSET_WIDGET_URI,
+    name: 'kiln-asset-viewer',
+    mimeType: MCP_APPS_MIME_TYPE,
+    description: 'Interactive Kiln asset viewer and downloads',
+    _meta: KILN_WIDGET_META,
+};
+export const KILN_RESOURCE_TEMPLATES = {
+    assetFile: {
+        name: 'asset-file',
+        uriTemplate: 'kiln://assets/{collection}/{asset}/{revision}/{file}',
+        description: 'Saved GLB/source/preview/manifest/bundle, or derived runtime GLB and metadata sidecar.',
+    },
+    projectPackage: {
+        name: 'project-package',
+        uriTemplate: 'kiln://projects/{project}/{revision}/{profile}',
+        description: 'Exact editable project bundle or runtime derivative ZIP.',
+    },
+};
+/**
+ * Definitions, templates and the viewer page are fixed for a build, and a new
+ * build restarts the process, so a client may hold them for a day. Asset and
+ * project files are a user's own data: never shared, and re-read on demand.
+ */
+export const DEFINITION_TTL_MS = 86_400_000;
+const CACHE_HINTS = {
+    'server/discover': { ttlMs: DEFINITION_TTL_MS, cacheScope: 'public' },
+    'tools/list': { ttlMs: DEFINITION_TTL_MS, cacheScope: 'public' },
+    'resources/list': { ttlMs: DEFINITION_TTL_MS, cacheScope: 'public' },
+    'resources/templates/list': { ttlMs: DEFINITION_TTL_MS, cacheScope: 'public' },
+    'resources/read': { ttlMs: 0, cacheScope: 'private' },
+};
+/** Only what Kiln does: no `listChanged`, because the lists never change within a build. */
+export function kilnServerCapabilities() {
+    return {
+        tools: {},
+        resources: {},
+        extensions: { [MCP_APPS_EXTENSION_ID]: { mimeTypes: [MCP_APPS_MIME_TYPE] } },
+    };
+}
+const LOCAL_PATH = /(?<![A-Za-z0-9])(?:[A-Za-z]:[\\/]|\\\\[^\s"'`]+|\/(?:home|Users|tmp|var|opt|mnt|root|srv|private)\/)[^\s"'`)\]]*/gu;
+/**
+ * Rule 9 of the v1 contract: a diagnostic names the cause and the next call
+ * and carries no absolute local path. Raw filesystem errors do carry one, so
+ * the loading diagnostics pass through here before they reach a tool result.
+ */
+export function withoutLocalPaths(text) {
+    return text.replace(LOCAL_PATH, '<local path>');
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function readPackagedWidgetHtml() {
+    return readFile(new URL('../dist/viewer/chat.html', import.meta.url), 'utf8');
+}
+/** Build the server over a manifest; every call that needs the engine goes through `host()`. */
+export function createKilnServer(options) {
+    const { manifest } = options;
+    const tools = new Map(manifest.tools.map((tool) => [tool.name, tool]));
+    const templatePrefixes = manifest.resourceTemplates.map((template) => template.uriTemplate.slice(0, template.uriTemplate.indexOf('{')));
+    const server = new Server({ name: MCP_SERVER_NAME, version: MCP_SERVER_VERSION }, {
+        instructions: options.instructions ?? MCP_SERVER_INSTRUCTIONS,
+        capabilities: kilnServerCapabilities(),
+        cacheHints: CACHE_HINTS,
+    });
+    let listed = false;
+    server.setRequestHandler('tools/list', () => {
+        if (!listed) {
+            listed = true;
+            // After the return: the answer is written before anything else happens.
+            if (options.afterFirstToolList)
+                queueMicrotask(options.afterFirstToolList);
+        }
+        return { tools: manifest.tools };
+    });
+    server.setRequestHandler('tools/call', async (request, ctx) => {
+        const name = request.params.name;
+        const tool = tools.get(name);
+        if (!tool) {
+            // Unknown tools are protocol errors, as the spec asks; a model that
+            // misspells a name gets the list to pick from.
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown tool ${name}. This server provides: ${manifest.tools.map((t) => t.name).join(', ')}.`);
+        }
+        let host;
+        try {
+            host = await options.host();
+        }
+        catch (error) {
+            // The engine could not be loaded or configured. A result, not a dead
+            // server: the agent reads the next step and the session lives.
+            return { isError: true, content: [{ type: 'text', text: errorMessage(error) }] };
+        }
+        const result = await host.callTool(name, request.params.arguments ?? {}, {
+            signal: ctx.mcpReq.signal,
+        });
+        return server.projectCallToolResult(result, tool.outputSchema);
+    });
+    server.setRequestHandler('resources/list', () => ({ resources: manifest.resources }));
+    server.setRequestHandler('resources/templates/list', () => ({
+        resourceTemplates: manifest.resourceTemplates,
+    }));
+    server.setRequestHandler('resources/read', async (request) => {
+        const uri = request.params.uri;
+        if (uri === KILN_ASSET_WIDGET_URI) {
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: MCP_APPS_MIME_TYPE,
+                        text: await (options.widgetHtml ?? readPackagedWidgetHtml)(),
+                        _meta: KILN_WIDGET_META,
+                    },
+                ],
+                // The page is fixed for a build and carries no user data.
+                ttlMs: DEFINITION_TTL_MS,
+                cacheScope: 'public',
+            };
+        }
+        if (!templatePrefixes.some((prefix) => uri.startsWith(prefix))) {
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Resource not found: ${uri}. Readable URIs come from kiln_save, kiln_present, kiln_export and kiln_project results and follow ${manifest.resourceTemplates.map((t) => t.uriTemplate).join(' or ')}.`);
+        }
+        let host;
+        try {
+            host = await options.host();
+        }
+        catch (error) {
+            throw new ProtocolError(ProtocolErrorCode.InternalError, errorMessage(error));
+        }
+        try {
+            return { contents: [await host.readResource(uri)] };
+        }
+        catch (error) {
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, errorMessage(error));
+        }
+    });
+    return server;
+}
+/**
+ * Only explicit host startup configuration can supply a standalone session's
+ * policy. Parsed before the engine, because a wrong command line is the host's
+ * mistake and the only honest answer is an exit with the message.
+ */
+export function parseMcpArguments(argv) {
+    let file;
+    for (let index = 0; index < argv.length; index++) {
+        const option = argv[index];
+        if (option === '--category' || option?.startsWith('--category='))
+            throw new Error(CATEGORY_MIGRATION_MESSAGE);
+        if (option !== '--requirements')
+            throw new Error(`Unknown MCP option: ${option}`);
+        if (file !== undefined)
+            throw new Error('--requirements may be supplied only once.');
+        file = argv[++index];
+        if (!file || file.startsWith('-'))
+            throw new Error('--requirements requires a file path.');
+    }
+    return file === undefined ? {} : { requirementsFile: file };
+}
+const PROTOCOL_VERSION_META_KEY = 'io.modelcontextprotocol/protocolVersion';
+const CLIENT_CAPABILITIES_META_KEY = 'io.modelcontextprotocol/clientCapabilities';
+/** Requests a 2025 client may send before `initialize` has been answered. */
+const PRE_HANDSHAKE_METHODS = new Set(['initialize', 'ping']);
+function asRequest(message) {
+    const candidate = message;
+    return typeof candidate.method === 'string' && candidate.id !== undefined
+        ? candidate
+        : undefined;
+}
+function carriesProtocolVersion(params) {
+    const meta = params?._meta;
+    return typeof meta === 'object' && meta !== null && PROTOCOL_VERSION_META_KEY in meta;
+}
+/**
+ * Refuses a request that belongs to neither era: no per-request protocol
+ * version (so not a 2026-07-28 request) and no `initialize` before it (so not a
+ * 2025 session either). Under 2026-07-28 a request missing a required `_meta`
+ * field is malformed and answered -32602; under 2025-11-25 nothing but a ping
+ * may precede the handshake. The library would otherwise pin the connection to
+ * a 2025 instance and serve it, which hides a broken client.
+ */
+export function guardedStdioTransport(inner = new StdioServerTransport()) {
+    let handshakeSeen = false;
+    const guard = {
+        start: () => inner.start(),
+        send: (message, options) => inner.send(message, options),
+        close: () => inner.close(),
+    };
+    inner.onclose = () => guard.onclose?.();
+    inner.onerror = (error) => guard.onerror?.(error);
+    inner.onmessage = (message, extra) => {
+        const request = asRequest(message);
+        if (request &&
+            !handshakeSeen &&
+            !PRE_HANDSHAKE_METHODS.has(request.method) &&
+            !carriesProtocolVersion(request.params)) {
+            const refusal = {
+                jsonrpc: '2.0',
+                id: request.id,
+                error: {
+                    code: ProtocolErrorCode.InvalidParams,
+                    message: `${request.method} carries no protocol version and no initialize handshake preceded it. ` +
+                        `Either send initialize first (protocol 2025-11-25 or 2025-06-18), or put params._meta["${PROTOCOL_VERSION_META_KEY}"] = "2026-07-28" ` +
+                        `and params._meta["${CLIENT_CAPABILITIES_META_KEY}"] on every request.`,
+                },
+            };
+            void inner.send(refusal).catch(() => { });
+            return;
+        }
+        if (request?.method === 'initialize')
+            handshakeSeen = true;
+        guard.onmessage?.(message, extra);
+    };
+    return guard;
+}
+/**
+ * Serve over this process's stdio, both eras: a 2025 client opens with
+ * `initialize`, a 2026-07-28 client with `server/discover` or any request
+ * carrying the per-request envelope. The library owns the era decision; Kiln
+ * adds the pre-handshake guard above.
+ */
+export function serveKilnStdio(options, stdio = {}) {
+    return serveStdio(() => createKilnServer(options), {
+        legacy: 'serve',
+        transport: guardedStdioTransport(),
+        ...stdio,
+    });
+}

package/lib/mcp-engine.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The engine half of the Kiln MCP server: the registry's tool definitions,
+ * their execution as MCP results, the resource readers, and the packaged host
+ * that `dist/mcp-server.mjs` loads on the first call that needs it.
+ *
+ * `createKilnMcpServer` builds the complete in-process server (the protocol
+ * core over this engine) for tests and embedders. The stdio executable is
+ * `src/mcp-server.ts`, which must not import this module statically: it is
+ * built beside it as `dist/mcp-engine.mjs` and imported by file URL.
+ */
+import type { Server } from '@modelcontextprotocol/server';
+import { type KilnMcpHost, type KilnToolResult } from "./mcp-core.js";
+import { type KilnToolContext, type KilnToolDef } from "./tools/registry.js";
+export type { KilnToolResult } from "./mcp-core.js";
+/** Optional wire features whose support is not negotiated by core MCP. */
+export type KilnMcpCompatibilityOptions = {
+    /** Opt-in domain operation presentation generated from the shared registry. */
+    toolPresentation?: 'grouped' | 'operations';
+    /**
+     * Add core `resource_link` blocks for saved artifact files.
+     *
+     * Core MCP 2026-07-28 permits these blocks but exposes no client capability
+     * for them. They therefore remain opt-in while clients differ in how they
+     * consume them. The same resource descriptors always remain in JSON text and
+     * structured content, and every URI remains readable through resources/read.
+     */
+    artifactResourceLinks?: boolean;
+};
+/** Use the shared program-aware definitions, including standalone validation. */
+export declare function kilnMcpToolDefs(context?: KilnToolContext): KilnToolDef[];
+/**
+ * Run one def and shape its output as MCP content.
+ *
+ * Defs carrying a `media`/`mediaMulti` extractor return images, which is the whole
+ * point of `kiln_render`: the calling agent must literally see the render, not a
+ * description of it. The JSON that accompanies an image has its embedded base64
+ * stripped by the extractor, so pixels are never double-encoded onto the wire.
+ */
+export declare function runTool(def: KilnToolDef, args: unknown, options?: KilnMcpCompatibilityOptions): Promise<KilnToolResult>;
+/** The engine as the protocol core sees it: tool execution and resource reads over one context. */
+export declare function createKilnToolHost(context?: KilnToolContext, options?: KilnMcpCompatibilityOptions): KilnMcpHost & {
+    defs: KilnToolDef[];
+};
+/** Build the complete in-process server: the protocol core over this context's engine. */
+export declare function createKilnMcpServer(context?: KilnToolContext, options?: KilnMcpCompatibilityOptions): Server;
+export interface PackagedKilnHostOptions {
+    /** The host binding read from `--requirements`, validated here once the engine is up. */
+    requirements?: unknown;
+}
+/**
+ * The host behind the stdio executable. Everything that used to happen before
+ * the handshake happens here instead, on the first call that needs it: the
+ * workspace check, the render mode, the renderer probe and the stores. Each
+ * failure is a message that names the next step and no local path, because it
+ * is returned to the agent as a tool result.
+ */
+export declare function createPackagedKilnHost(options?: PackagedKilnHostOptions): Promise<KilnMcpHost & {
+    defs: KilnToolDef[];
+}>;

package/lib/mcp-engine.js

@@ -0,0 +1,289 @@
+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 { AsyncLocalStorage } from 'node:async_hooks';
+import { fileURLToPath } from 'node:url';
+import { localAssetLibrary } from "./assets-node.js";
+import { readAssetResource } from "./assets-resources.js";
+import { buildRenderPort, resolveRenderMode } from "./cli-render-mode.js";
+import { FileLiveReview } from "./live-review-node.js";
+import { createPackagedLocalToolContext } from "./local-runtime.js";
+import { LOOPBACK_HOSTNAMES } from "./loopback.js";
+import { createKilnServer, errorMessage, withoutLocalPaths, MCP_OPERATION_INSTRUCTIONS, } from "./mcp-core.js";
+import { buildMcpManifest } from "./mcp-manifest.js";
+import { localProgramStore } from "./program-store-node.js";
+import { validateRequirementsBinding } from "./requirements-context.js";
+import { describeInputError, schemaFields } from "./tools/actions.js";
+import { createKilnProgramToolRegistry, createKilnOperationToolRegistry, } from "./tools/registry.js";
+import { localWorkspaceRoot } from "./workspace-node.js";
+/** Use the shared program-aware definitions, including standalone validation. */
+export function kilnMcpToolDefs(context = {}) {
+    return createKilnProgramToolRegistry(context);
+}
+/**
+ * Run one def and shape its output as MCP content.
+ *
+ * Defs carrying a `media`/`mediaMulti` extractor return images, which is the whole
+ * point of `kiln_render`: the calling agent must literally see the render, not a
+ * description of it. The JSON that accompanies an image has its embedded base64
+ * stripped by the extractor, so pixels are never double-encoded onto the wire.
+ */
+export async function runTool(def, args, options = {}) {
+    const output = await def.run(args);
+    // Rule 9: a result that reports its own failure is an error to the harness
+    // too, so the model sees it as one instead of as a successful result that
+    // happens to say ok: false.
+    const failed = typeof output === 'object' && output !== null && output.ok === false
+        ? { isError: true }
+        : {};
+    // Rule 7: JSON on one line. The indented form cost 24% more tokens in the
+    // measured sessions and told the model nothing the keys do not.
+    const multi = def.mediaMulti?.(output);
+    if (multi) {
+        return {
+            ...failed,
+            content: [
+                ...multi.pngs.map((png) => ({
+                    type: 'image',
+                    data: Buffer.from(png).toString('base64'),
+                    mimeType: 'image/png',
+                })),
+                { type: 'text', text: JSON.stringify(multi.json) },
+            ],
+        };
+    }
+    const media = def.media?.(output);
+    if (media) {
+        return {
+            ...failed,
+            content: [
+                {
+                    type: 'image',
+                    data: Buffer.from(media.png).toString('base64'),
+                    mimeType: 'image/png',
+                },
+                { type: 'text', text: JSON.stringify(media.json) },
+            ],
+        };
+    }
+    // A def may render its own text when the default JSON would repeat itself.
+    const asText = def.text?.(output);
+    if (asText !== undefined)
+        return { ...failed, content: [{ type: 'text', text: asText }] };
+    const resources = output?.resources ?? [];
+    const includeResourceLinks = options.artifactResourceLinks === true;
+    const payload = resources.length && includeResourceLinks
+        ? { ...output, resources: undefined }
+        : output;
+    return {
+        ...failed,
+        content: [
+            { type: 'text', text: JSON.stringify(payload) },
+            ...(includeResourceLinks ? resources : []),
+        ],
+        ...(def.ui
+            ? {
+                structuredContent: output,
+                _meta: await def.ui.data(output),
+            }
+            : {}),
+    };
+}
+/** The engine as the protocol core sees it: tool execution and resource reads over one context. */
+export function createKilnToolHost(context = {}, options = {}) {
+    const requests = new AsyncLocalStorage();
+    const requestContext = {
+        ...context,
+        evaluationControls: () => {
+            const configured = context.evaluationControls?.() ?? {};
+            const signal = requests.getStore();
+            return {
+                ...configured,
+                ...(signal
+                    ? {
+                        signal: configured.signal ? AbortSignal.any([signal, configured.signal]) : signal,
+                    }
+                    : {}),
+            };
+        },
+    };
+    const defs = options.toolPresentation === 'operations'
+        ? createKilnOperationToolRegistry(requestContext)
+        : kilnMcpToolDefs(requestContext);
+    const byName = new Map(defs.map((def) => [def.name, def]));
+    return {
+        defs,
+        async callTool(name, args, request) {
+            const def = byName.get(name);
+            if (!def)
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${name} is not available in this session. Available: ${defs.map((d) => d.name).join(', ')}.`,
+                        },
+                    ],
+                };
+            try {
+                return await requests.run(request.signal, () => runTool(def, args, options));
+            }
+            catch (err) {
+                // A tool error is a result, not a transport failure: the calling agent
+                // should see the message and correct its program rather than lose the
+                // session. Rule 9: readable, naming the next step, with no local path.
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: withoutLocalPaths(describeInputError(name, err, { fields: schemaFields(def.inputSchema) }) ??
+                                errorMessage(err)),
+                        },
+                    ],
+                };
+            }
+        },
+        async readResource(uri) {
+            if (uri.startsWith('kiln://assets/')) {
+                if (!context.assetLibrary)
+                    throw new Error(`No asset library serves ${uri} here.`);
+                const file = await readAssetResource(context.assetLibrary, uri);
+                return {
+                    uri,
+                    mimeType: file.mimeType,
+                    ...(file.name.endsWith('.json') || file.name.endsWith('.js')
+                        ? { text: resourceText(file.name, file.bytes) }
+                        : { blob: Buffer.from(file.bytes).toString('base64') }),
+                };
+            }
+            if (uri.startsWith('kiln://projects/')) {
+                if (!context.projectBundleReader)
+                    throw new Error(`No project bundle reader serves ${uri} here.`);
+                const [project, revision, file, ...extra] = new URL(uri).pathname
+                    .split('/')
+                    .filter(Boolean)
+                    .map(decodeURIComponent);
+                if (extra.length ||
+                    !project ||
+                    !revision ||
+                    !['editable.zip', 'runtime.zip'].includes(file ?? ''))
+                    throw new Error('Invalid project package URI');
+                const bytes = await context.projectBundleReader(project, revision, file === 'editable.zip' ? 'editable' : 'runtime');
+                return { uri, mimeType: 'application/zip', blob: Buffer.from(bytes).toString('base64') };
+            }
+            throw new Error(`Resource not found: ${uri}`);
+        },
+    };
+}
+/**
+ * A saved manifest is pretty-printed on disk and one line as a resource: a Codex session
+ * read 33,563 characters of one, a quarter of them line breaks and indentation (H26;
+ * decision 27 of 2 October 2026). Source files and anything that is not JSON are served
+ * as they are.
+ */
+function resourceText(name, bytes) {
+    const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: name.endsWith('.js') }).decode(bytes);
+    if (!name.endsWith('.json'))
+        return text;
+    try {
+        return JSON.stringify(JSON.parse(text));
+    }
+    catch {
+        return text;
+    }
+}
+/** Build the complete in-process server: the protocol core over this context's engine. */
+export function createKilnMcpServer(context = {}, options = {}) {
+    const host = createKilnToolHost(context, options);
+    return createKilnServer({
+        ...(options.toolPresentation === 'operations'
+            ? { instructions: MCP_OPERATION_INSTRUCTIONS }
+            : {}),
+        manifest: buildMcpManifest(host.defs, context),
+        host: async () => host,
+    });
+}
+/**
+ * The host behind the stdio executable. Everything that used to happen before
+ * the handshake happens here instead, on the first call that needs it: the
+ * workspace check, the render mode, the renderer probe and the stores. Each
+ * failure is a message that names the next step and no local path, because it
+ * is returned to the agent as a tool result.
+ */
+export async function createPackagedKilnHost(options = {}) {
+    const env = process.env;
+    const requirements = options.requirements === undefined
+        ? undefined
+        : validateRequirementsBinding(options.requirements);
+    const workspace = env['KILN_WORKSPACE'];
+    if (workspace) {
+        // Keep setup code outside the runtime bundle; importing it must not turn its
+        // direct-entry check into another entrypoint for this MCP executable.
+        const setup = (await import(__rewriteRelativeImportExtension(new URL('../scripts/create-workspace.mjs', import.meta.url).href)));
+        let report;
+        try {
+            report = await setup.createWorkspace(workspace, 'claude', {
+                installation: fileURLToPath(new URL('..', import.meta.url)),
+                check: true,
+            });
+        }
+        catch (error) {
+            throw new Error(`The Kiln workspace could not be checked (${withoutLocalPaths(errorMessage(error))}). In the workspace folder run kiln-init . --repair from the current Kiln installation, then restart the MCP session.`);
+        }
+        if (report.status !== 'current')
+            throw new Error(`Kiln workspace is out of date${report.runtimeChanged ? ' (runtime changed)' : ''}: ${report.files
+                .filter((entry) => entry.status !== 'customized')
+                .map((entry) => entry.path)
+                .join(', ')}. In the workspace folder run kiln-init . --check, then kiln-init . --upgrade (or kiln-init . --repair if the installation moved), and restart the MCP session.`);
+    }
+    const mode = resolveRenderMode();
+    // One probe before the first connection, so no client attach waits on a network
+    // round trip -- but NOT a decision that lasts the session. `autoSpawn` hands
+    // back a port that starts the packaged renderer on the first view that needs
+    // one, which is the only ordering a user can actually achieve: the harness owns
+    // this process's lifecycle, so "start the renderer first" was never theirs to do.
+    const context = await createPackagedLocalToolContext({
+        ...(await buildRenderPort(mode, env['KILN_RENDER_PORT_URL'], { autoSpawn: true })),
+        requirements,
+        assetLibrary: localAssetLibrary(),
+        ...(env.KILN_LIVE_REVIEW !== 'off'
+            ? {
+                liveReview: new FileLiveReview(localWorkspaceRoot(), {
+                    transport: 'mcp',
+                    workId: env.KILN_WORK_ITEM,
+                }),
+            }
+            : {}),
+    });
+    context.programStore = localProgramStore();
+    // Decision 12: the lean and compact defaults are compared live with the same
+    // briefs, switched per session here so the advertised schema never changes.
+    const detail = env['KILN_RESULT_DETAIL'];
+    if (detail) {
+        if (detail !== 'lean' && detail !== 'compact')
+            throw new Error('KILN_RESULT_DETAIL must be lean or compact (full is per call). Correct the variable and restart the MCP session.');
+        context.resultDetail = detail;
+    }
+    const deliveryBase = env['KILN_ASSET_DOWNLOAD_BASE_URL'];
+    if (deliveryBase) {
+        const base = new URL(deliveryBase);
+        if (base.protocol !== 'https:' &&
+            !(base.protocol === 'http:' && LOOPBACK_HOSTNAMES.includes(base.hostname)))
+            throw new Error('KILN_ASSET_DOWNLOAD_BASE_URL must use HTTPS or loopback HTTP. Correct the variable and restart the MCP session.');
+        context.assetDownloadUrls = async (collection, assetId, revisionId) => Object.fromEntries(['asset.glb', 'editable.zip', 'source.kiln.js', 'preview.png', 'manifest.json'].map((file) => [
+            file,
+            new URL(`files/${collection}/${assetId}/${revisionId}/${file}?download`, base.href.endsWith('/') ? base.href : `${base.href}/`).href,
+        ]));
+    }
+    // stdout is the MCP transport; diagnostics must never touch it.
+    console.error(`kiln engine ready (${mode})`);
+    return createKilnToolHost(context, {
+        artifactResourceLinks: env['KILN_MCP_RESOURCE_LINKS'] === '1',
+    });
+}

package/lib/mcp-manifest.d.ts

@@ -0,0 +1,15 @@
+import { type KilnMcpManifest, type KilnMcpManifestTemplate, type KilnMcpManifestTool } from "./mcp-core.js";
+import { type KilnToolContext, type KilnToolDef } from "./tools/registry.js";
+/** The input schema as advertised: an object root first, the rest as converted. */
+export declare function toolInputJsonSchema(def: KilnToolDef): KilnMcpManifestTool['inputSchema'];
+/** One registry definition as one `tools/list` entry, keys in the order the wire has always carried them. */
+export declare function toolManifestEntry(def: KilnToolDef): KilnMcpManifestTool;
+/** Which templates a context can serve: asset files need a library, project packages a bundle reader. */
+export declare function resourceTemplatesFor(context: KilnToolContext): KilnMcpManifestTemplate[];
+export declare function buildMcpManifest(defs: KilnToolDef[], context: KilnToolContext): KilnMcpManifest;
+/**
+ * The manifest the packaged server advertises: the full surface with both
+ * templates, built from a context shaped like the packaged host's but with no
+ * environment of its own, so the file is the same on every machine.
+ */
+export declare function packagedMcpManifest(): KilnMcpManifest;