Duolith docs

0061. The tool server answers through the Duolith command; create is a node command for now

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: WP14 (agent layer)

Context

The MCP tool server must check, format and build pages, and explain codes. The compiler is reachable two ways from TypeScript: the duolith binary, whose commands all accept --json, or the WebAssembly build the language server loads. Separately, apps need a scaffolder, and the command line has no create command; crates/cli belongs to Tooling.

Decision

The tool server runs the duolith binary (DUOLITH_BIN, else the repository's target/debug/duolith, else duolith on the PATH) and returns its JSON, so an agent sees exactly what the command line shows; it reads spec/ directly for lookups (kit parts, elements, utilities) and pages/ for routes. Screenshots use duolith dev on a port in 4330-4339 and Playwright, an optional dependency. It is built on the official MCP TypeScript SDK over stdio.

The scaffolder is a node command, packages/create/src/main.ts <name> --template blank|tabs|data, until the command line gains duolith create, which can call the same templates.

Alternatives considered

OptionWhy not
Load the WebAssembly compilerIt has no build or emit, needs the language server's build step, and would let the tool server and the command line disagree.
Add duolith create in Rust nowOutside the Agent surface's ownership; the templates and their tests do not depend on where the command lives.

Consequences

The tool server needs a built duolith; its tests skip without one locally and fail in CI. Relative paths given to tools are resolved against the folder the server was started in.