Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
/**
* 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 { AsyncLocalStorage } from 'node:async_hooks';
import { fileURLToPath } from 'node:url';
import { localAssetLibrary } from './assets-node';
import { type AssetLink, readAssetResource } from './assets-resources';
import { buildRenderPort, resolveRenderMode } from './cli-render-mode';
import { exportRootWriterFromEnv } from './export-root-node';
import { FileLiveReview } from './live-review-node';
import { createPackagedLocalToolContext } from './local-runtime';
import { LOOPBACK_HOSTNAMES } from './loopback';
import {
createKilnServer,
errorMessage,
type KilnContentBlock,
type KilnMcpHost,
type KilnResourceContents,
type KilnToolResult,
withoutLocalPaths,
MCP_OPERATION_INSTRUCTIONS,
} from './mcp-core';
import { buildMcpManifest } from './mcp-manifest';
import { localProgramStore } from './program-store-node';
import { validateRequirementsBinding } from './requirements-context';
import { describeInputError, schemaFields } from './tools/actions';
import {
buildProgramGlb,
createKilnProgramToolRegistry,
createKilnOperationToolRegistry,
type KilnToolContext,
type KilnToolDef,
} from './tools/registry';
import { localWorkspaceRoot } from './workspace-node';
export type { KilnToolResult } from './mcp-core';
/** 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 function kilnMcpToolDefs(context: KilnToolContext = {}): KilnToolDef[] {
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: KilnToolDef,
args: unknown,
options: KilnMcpCompatibilityOptions = {},
): Promise<KilnToolResult> {
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 as { ok?: unknown }).ok === false
? { isError: true as const }
: {};
// 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): KilnContentBlock => ({
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 as { resources?: AssetLink[] } | null)?.resources ?? [];
const includeResourceLinks = options.artifactResourceLinks === true;
const payload =
resources.length && includeResourceLinks
? { ...(output as object), resources: undefined }
: output;
return {
...failed,
content: [
{ type: 'text', text: JSON.stringify(payload) },
...(includeResourceLinks ? resources : []),
],
...(def.ui
? {
structuredContent: output as Record<string, unknown>,
_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: KilnToolContext = {},
options: KilnMcpCompatibilityOptions = {},
): KilnMcpHost & { defs: KilnToolDef[] } {
const requests = new AsyncLocalStorage<AbortSignal>();
const requestContext: KilnToolContext = {
...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] as const));
return {
defs,
async callTool(name, args, request): Promise<KilnToolResult> {
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): Promise<KilnResourceContents> {
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') };
}
if (uri.startsWith('kiln://programs/')) {
const [program, sha256, file, ...extra] = new URL(uri).pathname
.split('/')
.filter(Boolean)
.map(decodeURIComponent);
if (extra.length || !program || !sha256 || file !== 'asset.glb')
throw new Error('Invalid program build URI');
const rendered = await buildProgramGlb(program, requestContext);
// Rebuilt on read, so this host's policy or engine can have moved since the export.
if (rendered.artifactGlbSha256 !== `sha256:${sha256}`)
throw new Error(
`${program} no longer builds to ${sha256} on this host. Call kiln_export with this programRef again for the current bytes.`,
);
return {
uri,
mimeType: 'model/gltf-binary',
blob: Buffer.from(rendered.glb).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: string, bytes: Uint8Array): string {
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: KilnToolContext = {},
options: KilnMcpCompatibilityOptions = {},
): Server {
const host = createKilnToolHost(context, options);
return createKilnServer({
...(options.toolPresentation === 'operations'
? { instructions: MCP_OPERATION_INSTRUCTIONS }
: {}),
manifest: buildMcpManifest(host.defs, context),
host: async () => host,
});
}
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 async function createPackagedKilnHost(
options: PackagedKilnHostOptions = {},
): Promise<KilnMcpHost & { defs: KilnToolDef[] }> {
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(
new URL('../scripts/create-workspace.mjs', import.meta.url).href
)) as {
createWorkspace: (
root: string,
harness: string,
options: { installation: string; check: true },
) => Promise<{
status: string;
runtimeChanged: boolean;
files: { path: string; status: string }[];
}>;
};
let report: Awaited<ReturnType<typeof setup.createWorkspace>>;
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 assetLibrary = localAssetLibrary();
// Checked at start: a bad root fails every call with the fix, never a write elsewhere.
const exportRoot = await exportRootWriterFromEnv(env, {
collectionRoots: assetLibrary.collections().map(({ id }) => assetLibrary.directory(id)),
workspaceRoot: localWorkspaceRoot(),
});
const context = await createPackagedLocalToolContext({
...(await buildRenderPort(mode, env['KILN_RENDER_PORT_URL'], { autoSpawn: true })),
requirements,
assetLibrary,
...(exportRoot ? { exportRoot } : {}),
...(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',
});
}