Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

6.4 KB
Raw Blame
import { readFile, writeFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { packagedMcpManifest } from '../src/mcp-manifest';
import { toolManifestEntry } from '../src/mcp-manifest';
import { createKilnOperationToolRegistry } from '../src/tools/registry';
import { createLocalToolContext } from '../src/local-runtime';
import { localAssetLibrary } from '../src/assets-node';

export const toolReferencePath = fileURLToPath(new URL('../docs/tools.md', import.meta.url));
export const operationReferencePath = fileURLToPath(
  new URL('../docs/tools-operations.md', import.meta.url),
);

/** Host-neutral named profile with asset/material storage and no local-only services. */
export function operationReferenceMarkdown(): string {
  const local = createLocalToolContext({ assetLibrary: localAssetLibrary() }, {});
  const tools = createKilnOperationToolRegistry({
    assetLibrary: local.assetLibrary,
    materialLibrary: local.materialLibrary,
  }).map(toolManifestEntry);
  return `${[
    '# Named operation reference',
    'Available in package version 1.2.0 and later. Generated with `bun run docs:tools` from the same engine registry as the default [local tools](tools.md). This profile supplies asset and material storage without project/review or renderer-control callbacks. Other host capabilities can change the tool list; connected tools/list is authoritative. See the [embedding contract](sdk.md#named-operation-presentation).',
    'Select this presentation explicitly with `createKilnMcpServer(context, { toolPresentation: "operations" })`. Existing local tool names and actions remain the default. Host authentication, request quotas, isolation and persistence policy are outside this engine reference.',
    'Use kiln_discover for helper contracts and complete shape: records; kiln_capabilities reports configuration, not proof of successful rendering. Material creation requires a typed definition. Search results preserve collection, asset/material and revision identity. Saving remains an explicit decision.',
    ...tools.flatMap((tool) => [
      `## ${tool.name}`,
      tool.description,
      '<details>\n<summary>Input JSON Schema</summary>\n',
      `\`\`\`json\n${JSON.stringify(tool.inputSchema, null, 2)}\n\`\`\`\n\n</details>`,
    ]),
  ].join('\n\n')}\n`;
}

/**
 * The published tool reference: the definitions the packaged server advertises,
 * byte for byte the manifest's (`src/generated/mcp-manifest.json`), pretty-printed.
 *
 * Exported so the drift check can be a test rather than a command nobody runs.
 * `--check` existed from the start and appeared in no workflow and no test, which
 * is how `docs/tools.md` came to understate every tuple schema for a week: zod
 * 4.6.2 changed `z.toJSONSchema` to emit `items: false`, `minItems` and
 * `maxItems` for fixed-length tuples, the in-range bump took it, and the only
 * thing that would have noticed was opt-in.
 */
export function toolReferenceMarkdown(): string {
  const manifest = packagedMcpManifest();
  return `${[
    '# Tool reference',
    'Generated with `bun run docs:tools` from the definitions the packaged stdio server advertises (the same bytes as `src/generated/mcp-manifest.json`). Change the registry in `src/tools/registry.ts` to update names, descriptions or schemas; `bun run docs:tools --check` reports drift.',
    'Use these tools through your connected agent. Supply `code` once (or `file`, a path inside the workspace), then pass the returned `programRef` to later calls. References identify exact source revisions and are kept in the workspace program store across sessions and processes. [Source workflow](programs.md) · [Camera recipes](cameras.md) · [Geometry guide](geometry.md).',
    'Call `kiln_discover({capabilities:true})` for the current host limits, the configured project and export/camera support. Nested records that the schemas keep opaque (`draft`, `patch`, `payload`, `capture`, `shot`) are described in full by `kiln_discover({ ids: ["shape:project-draft"] })` and the other `shape:` entries. The schema below describes inputs; actual image replies include fidelity and capture metadata. Source reads return exact text, edits return a new revision, and failed builds return their errors.',
    'kiln_project, kiln_material and kiln_review are injected by the packaged local host; an embedding advertises them only when it supplies the corresponding store, and the connected tools/list is authoritative. Projects are optional: authoring tools accept projectId, projectRevision and independent materialDependencies, and projectId:null selects standalone work. See [projects and live review](projects-and-live-review.md) for CLI equivalents, project packages and exact reviewed saves.',
    'kiln_export_to is advertised only when the host sets KILN_EXPORT_ROOT, an existing absolute directory outside every collection and .kiln/. It writes a saved revision under that root and never replaces a file; kiln_export stays read-only. See [export profiles](export-profiles.md#mcp).',
    'Renderer capabilities distinguish configured routing, dependency readiness, endpoint health and unverified authentication. Use kiln_renderer with action=reprobe after renderer setup or repair to refresh the current session. Material capabilities list approved texture IDs by allowed slot for the selected evaluator. Capability inspection never starts a renderer, requests an image or fetches texture bytes; ordinary catalog search is offline. See [renderer readiness and resources](rendering.md).',
    ...manifest.tools.flatMap((tool) => [
      `## ${tool.name}`,
      tool.description,
      '<details>\n<summary>Input JSON Schema</summary>\n',
      `\`\`\`json\n${JSON.stringify(tool.inputSchema, null, 2)}\n\`\`\`\n\n</details>`,
    ]),
  ].join('\n\n')}\n`;
}

// Only when run as a command. Importing this module must not write a file or set
// an exit code -- the test below it imports the builder.
if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
  for (const [path, content] of [
    [toolReferencePath, toolReferenceMarkdown()],
    [operationReferencePath, operationReferenceMarkdown()],
  ] as const) {
    if (process.argv.includes('--check')) {
      if ((await readFile(path, 'utf8').catch(() => '')) !== content) {
        console.error('Tool reference differs from the registry. Run bun run docs:tools.');
        process.exitCode = 1;
      }
    } else {
      await writeFile(path, content);
      console.log(`Wrote ${path}.`);
    }
  }
}