forma-dsl-mcp 0.1.6 → 0.3.1

package/README.md

@@ -5,93 +5,235 @@
 
 A [Model Context Protocol](https://modelcontextprotocol.io) server that knows
 [forma](https://www.npmjs.com/package/forma-dsl) — the declarative DSL for 3D solids — and
-writes `.forma` documents that render.
+builds it with the real geometry kernel, so a `.forma` document is measured before anyone is
+told it works.
 
-It speaks over stdio, so any MCP client can launch it:
+It carries the language with it: the guide, the block reference, the worked examples and the
+full manual are bundled, so a model learns the syntax from the server rather than guessing at
+it.
+
+It speaks over stdio, and there is nothing to configure.
+
+## Installing it
+
+**Claude Code**
+
+```bash
+claude mcp add forma -- npx -y forma-dsl-mcp
+```
+
+**Codex**
+
+```bash
+codex mcp add forma -- npx -y forma-dsl-mcp
+```
+
+or, in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.forma]
+command = "npx"
+args = ["-y", "forma-dsl-mcp"]
+```
+
+**Claude Desktop, and anything else that takes a JSON block**
 
 ```json
 {
   "mcpServers": {
     "forma": {
       "command": "npx",
-      "args": ["-y", "forma-dsl-mcp"],
-      "env": { "FORMA_MCP_ROOT": "/absolute/path/to/your/models" }
+      "args": ["-y", "forma-dsl-mcp"]
     }
   }
 }
 ```
 
-`FORMA_MCP_ROOT` is the only configuration. It defaults to the working directory the client
-launches the server in, and **every path the file tools accept is confined to it** — an
-absolute path, a `..` that climbs out, or a symlink pointing out of the tree is refused
-rather than followed.
+## Where the files go
+
+The server does not choose. It asks the client over MCP's
+[roots](https://modelcontextprotocol.io/specification/basic/roots) capability, and reads and
+writes only inside the directories the client hands over. A relative path is taken against
+the first of them, and every write reports the directory it landed in.
+
+**Every path is confined to those directories** — an absolute path outside them, a `..` that
+climbs out, or a symlink pointing out of the tree is refused rather than followed. When the
+client says its roots have changed, the server re-reads them before the next call.
+
+A client that does not implement roots gets the working directory it launched the server in,
+which is the one location it did choose. Codex can set that explicitly:
+
+```toml
+[mcp_servers.forma]
+command = "npx"
+args = ["-y", "forma-dsl-mcp"]
+cwd = "/absolute/path/to/your/models"
+```
 
 ## Why it is not just a prompt
 
 A model that has read the language's documentation still writes forma that does not build.
-The difference this server makes is that it **runs the geometry kernel**. `forma_check`
-compiles the document, solves it with [Manifold](https://github.com/elalish/manifold) and
-reports back the bounding box, the volume, the triangle count and the genus of every part —
-so the question "is this the size that was asked for, and is it actually a solid?" is
-answered before anyone is told the work is done. A part that silently solved to nothing is
-called out by name.
-
-`forma_write` runs that same check and **refuses to write a document that does not render**.
+The difference this server makes is that it **runs the geometry kernel**. Every tool compiles
+the document, solves it with [Manifold](https://github.com/elalish/manifold) and reports back
+the bounding box, the volume, the triangle count and the genus of every part — so the
+question "is this the size that was asked for, and is it actually a solid?" is answered
+before the work is handed over. A part that silently solved to nothing is called out by name,
+and an error comes back with the line, the column and an excerpt with a caret on it.
+
+`forma_write` **refuses to write a document that does not render**.
+
+Refusals carry the vocabulary too: an unknown block comes back with every block there is, and
+an unknown attribute with the ones that block reads. That is the backstop, not the teacher —
+it is enough to correct a misspelling and not enough to learn a language, since it gives the
+name of a block and nothing about what that block means or what it takes. `forma_guide`,
+`forma_blocks` and `forma_reference` are what answer that, and they are bundled so they
+answer offline.
 
 Everything the server says about the language is answerable to the language. The block and
 function catalogue is merged with the library's own registries at load time, and the tests
-assert that the two agree: a block added, renamed or given a new dimensionality in
-`forma-dsl` fails this package's build rather than becoming a confident wrong answer. Every
-worked example is rendered by the test suite, at both ends of every parameter's declared
-range.
+assert the two agree: a block added, renamed or given a new dimensionality in `forma-dsl`
+fails this package's build rather than becoming a confident wrong answer. Every worked example
+is rendered by the test suite.
 
 ## Tools
 
+**Learning the language**
+
 | Tool | What it does |
 | --- | --- |
 | `forma_guide` | The language in one page: structure, nesting, dimensionality, units, syntax, the mistakes that cost the most time |
 | `forma_blocks` | Every block with its attributes, defaults, dimensionality and caveats |
 | `forma_functions` | Every builtin function and constant, with arity |
-| `forma_reference` | The full reference manual, searchable and readable page by page |
 | `forma_examples` | Complete documents that render, each showing one way of building a real part |
-| `forma_check` | Parse, build and **measure** — errors with a line, a column and an excerpt with a caret; parts with their boxes, volumes and triangle counts |
-| `forma_write` | Check, then write a `.forma` file into the workspace |
+| `forma_reference` | The full reference manual, searchable and readable page by page |
+
+**Building with it**
+
+| Tool | What it does |
+| --- | --- |
+| `forma_write` | Check, then write a `.forma` file |
 | `forma_read` | Read a document back, checked |
-| `forma_list` | Every `.forma` file under the root |
 | `forma_export_stl` | Render and write a binary STL |
 
-## Resources and prompts
+## Resources
 
-Resources carry the same knowledge in a form a person can attach by hand:
+The same knowledge in the form a person can attach to a conversation by hand:
 
 - `forma://guide` — the language in brief
 - `forma://catalogue` — every block and function, as JSON
 - `forma://reference/{path}` — one page of the manual
 - `forma://example/{name}` — one worked document
 
-Two prompts name the workflows worth having a name for: `model_a_part`, which walks from a
-description of a physical object to a checked document, and `review_a_document`, which reads
-an existing one and looks for the failures that are silent.
+## Asking for a part
+
+Install it in Codex as above, `cd` to wherever you keep your models, and ask:
+
+> **you** — build me a forma file with a tree in it
+
+> **codex** — Where should I put it?
+
+> **you** — the current folder
+
+Codex reads the language before it writes any: `forma_guide` for the shape of a document,
+`forma_blocks` for the attributes of the blocks it is about to use — here `cone`, `translate`
+and `for` — and `forma_examples` for a document of a similar shape. Then it writes, and
+`forma_write` builds what it wrote with the real kernel before anything reaches the disk.
+
+Where the vocabulary runs out, the refusals carry it. A guess at a block that does not exist
+comes back with every block that does, and a guess at an attribute with the ones that block
+reads:
+
+```
+unknown block "frustum" — the blocks are "align", "for", "if", "part", "box", "circle",
+  "cone", "cylinder", "difference", … "union"
+
+cone: unknown attribute "bottom_radius" — cone reads "center", "height", "radius",
+  "segments", "top_radius"
+```
+
+Then it lands, and the tool answers with the part rather than with a claim about it:
+
+```
+Wrote `tree.forma` under `/home/you/models` — 537 bytes.
+
+| Part     | Colour  | Opacity | Size (X × Y × Z) | Volume    | Triangles | Genus |
+| `trunk`  | #6b4423 |       1 | 8 × 8 × 30       | 1004.682  |       108 |     0 |
+| `canopy` | #2f7d32 |       1 | 28 × 28 × 30     | 5193.4555 |       358 |     0 |
+
+Overall bounding box: 28 × 28 × 51 (min -14, -14, 0, max 14, 14, 51)
+Triangles: 466
+```
+
+`tree.forma`:
+
+```hcl
+param trunk_height { type = number  default = 30  min = 10  max = 60 }
+param canopy_layers { type = number  default = 3  min = 1  max = 6 }
+
+local canopy_base = trunk_height * 0.7
+
+model "tree" {
+  part "trunk" {
+    color = "#6b4423"
+    cone { radius = 4  top_radius = 2.5  height = var.trunk_height }
+  }
+
+  part "canopy" {
+    color = "#2f7d32"
+    for i in range(var.canopy_layers) {
+      translate {
+        offset = [0, 0, canopy_base + i * 8]
+        cone { radius = 14 - i * 3  top_radius = 0  height = 14 }
+      }
+    }
+  }
+}
+```
+
+The document above is a test in this repo rather than an illustration: `test/server.test.js`
+builds it, checks both parts came out solid, drives `trunk_height` to the top of its declared
+range, and exports it. The wrong guesses are asserted to name their own corrections.
+
+## More to ask for
+
+> Model a wall bracket that carries a 35 mm pipe 60 mm off the wall. Two M5 screw holes in
+> the backplate, 50 mm apart. Make the pipe diameter and the standoff params, and write it
+> to `bracket.forma`.
+
+> Write `enclosure.forma`: a 90 × 60 × 25 mm box with 2 mm walls, open at the top, with a lid
+> that drops in on a 0.3 mm clearance lip. Wall thickness and clearance are params. Give the
+> body and the lid separate parts so I can see them apart.
+
+> Read `bracket.forma` and re-check it at both ends of every param's declared range. Anything
+> that solves to nothing or changes the bounding box in a way the document did not intend,
+> tell me about before you change it.
+
+> Take `enclosure.forma`, set the wall thickness to 3 mm, and export just the lid to
+> `lid.stl`.
+
+Two things are worth asking for by name, because they are what the kernel is there to answer:
+the **bounding box**, to confirm the part is the size you meant, and the **genus**, to confirm
+a part that should be a plain solid has not ended up with a hole through it.
+
+## The bundled manual
+
+`src/reference/` is a copy of [`apps/docs/content`](../../apps/docs/content/README.md), which
+is a private workspace and cannot be depended on from something that ships to npm. The copy is
+what lets the server answer offline. It is made by `npm run sync:reference -w forma-dsl-mcp`
+and compared byte for byte against the original by the tests, so it cannot drift: edit the
+manual, re-run the sync, and the test passes again.
 
 ## Running it from source
 
 ```bash
 npm install
-npm test -w forma-dsl-mcp                  # 140+ tests, including the protocol end to end
+npm test -w forma-dsl-mcp                  # including the protocol end to end
 node packages/forma-dsl-mcp/src/bin.js     # the server, on stdio
 ```
 
 Point a client at `node /absolute/path/to/packages/forma-dsl-mcp/src/bin.js` to use the
 working tree rather than the published package.
 
-## The bundled manual
-
-`src/reference/` is a copy of [`apps/docs/content`](../../apps/docs/content/README.md), which
-is a private workspace and cannot be depended on from something that ships to npm. The copy
-is what lets the server answer offline. It is made by `npm run sync:reference -w
-forma-dsl-mcp` and compared byte for byte against the original by the tests, so it cannot
-drift: edit the manual, re-run the sync, and the test passes again.
-
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-dsl-mcp",
-  "version": "0.1.6",
+  "version": "0.3.1",
   "description": "A stdio MCP server that knows the forma DSL and writes .forma documents that render.",
   "keywords": [
     "mcp",
@@ -13,7 +13,7 @@
     "parametric",
     "stl"
   ],
-  "homepage": "https://github.com/kalpak44/forma-dsl/tree/main/packages/forma-dsl-mcp#readme",
+  "homepage": "https://kalpak44.github.io/forma-dsl/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kalpak44/forma-dsl.git",
@@ -41,12 +41,12 @@
   "scripts": {
     "start": "node src/bin.js",
     "test": "node --test",
-    "sync:reference": "node scripts/sync-reference.mjs",
-    "check:package": "node scripts/check-package.mjs"
+    "check:package": "node scripts/check-package.mjs",
+    "sync:reference": "node scripts/sync-reference.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
-    "forma-dsl": "^0.1.6",
+    "forma-dsl": "^0.3.1",
     "zod": "^4.1.13"
   }
 }

package/src/bin.js

@@ -5,25 +5,29 @@
  * Nothing may be written to stdout but the protocol — a stray `console.log` corrupts the
  * JSON-RPC stream and the client disconnects with an error that names nothing. Everything
  * this file has to say goes to stderr, which clients collect as the server's log.
+ *
+ * There is nothing to configure here. Where the file tools may read and write is asked of
+ * the client over MCP's `roots` capability once it has connected, so the directories are
+ * the client's to choose and to change.
  */
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
-import { Workspace } from './workspace.js';
 import { VERSION, createServer } from './server.js';
-
-/**
- * Where the file tools are allowed to read and write.
- *
- * Defaults to the working directory, which is what a client that launches the server inside
- * a project gives it. `FORMA_MCP_ROOT` overrides it.
- */
-const root = process.env.FORMA_MCP_ROOT ?? process.cwd();
+import { askClientForRoots } from './roots.js';
 
 try {
-  const workspace = await Workspace.open(root);
-  const server = createServer(workspace);
+  const server = createServer();
+
+  // Logged for the operator's benefit, not the protocol's: a server writing somewhere
+  // unexpected is the failure worth being able to see in the client's log.
+  server.server.oninitialized = () => {
+    askClientForRoots(server.server)
+      .then((roots) => console.error(`forma-dsl-mcp: working in ${roots.join(', ')}`))
+      .catch(() => {});
+  };
+
   await server.connect(new StdioServerTransport());
-  console.error(`forma-dsl-mcp ${VERSION} ready — workspace ${workspace.root}`);
+  console.error(`forma-dsl-mcp ${VERSION} ready`);
 } catch (error) {
   console.error(`forma-dsl-mcp failed to start: ${error?.message ?? error}`);
   process.exit(1);

package/src/document.js

@@ -20,6 +20,19 @@ import {
 /** How many lines of source to show either side of an error. */
 const CONTEXT_LINES = 2;
 
+/**
+ * How much geometry one document may build before the server refuses it.
+ *
+ * This server exists to build text a model wrote, which is the case the library leaves a
+ * budget off for. Nesting limits and `range` each bound one loop; only this bounds two of
+ * them nested, and that shape asks for more geometry than the process can finish — on a pipe,
+ * with no request timeout of its own, that is a server that never answers again.
+ *
+ * Set far above any honest document: the worked examples build tens of blocks. A model that
+ * reaches this has written a loop it did not mean to.
+ */
+const MAX_NODES = 50_000;
+
 /**
  * The context reused across calls, so an edit-and-recheck loop pays only for the subtrees
  * that changed.
@@ -195,7 +208,7 @@ export async function checkDocument(source, options = {}) {
   /** @type {RenderResult} */
   let result;
   try {
-    result = await render(source, { model, params, context: shared });
+    result = await render(source, { model, params, context: shared, maxNodes: MAX_NODES });
   } catch (error) {
     return { ok: false, stage: 'render', ...declared, error: diagnose('render', error, source) };
   }
@@ -255,7 +268,7 @@ export async function exportStl(source, options = {}) {
   const { model = null, params = {}, part = null } = options;
 
   shared ??= await EvaluationContext.create();
-  const result = await render(source, { model, params, context: shared });
+  const result = await render(source, { model, params, context: shared, maxNodes: MAX_NODES });
 
   let solid;
   let name;

package/src/reference/errors.md

@@ -135,11 +135,11 @@ Raised while building geometry.
 
 | Message | Cause |
 | --- | --- |
-| `unknown block "bloop"` | Not a builtin and not a declared component. Check the spelling against the [block list](README.md#shapes) |
+| `unknown block "bloop" — the blocks are …` | Not a builtin and not a declared component. The message lists every block there is, this document's own components first |
 | `"box" does not take a label` | Only [`part`](reference/part.md) takes a meaningful label |
 | `"box" is a shape and cannot contain other blocks` | A shape is a leaf. Usually a missing `}` swallowed the next block |
 | `"translate" needs at least one shape inside it` | An operation with nothing to act on |
-| `box: unknown attribute "colour"` | Every block rejects attributes it did not read, so a typo fails loudly |
+| `box: unknown attribute "colour" — box reads …` | Every block rejects attributes it did not read, so a typo fails loudly, and names what it would have read |
 | `attribute "size" is set twice` | The same attribute written twice in one block |
 | `box: "size" must be a number or an array of 3 numbers` | Wrong shape of value |
 | `circle: "radius" must be a finite number` | A `NaN` or `Infinity` reached the block |
@@ -149,13 +149,19 @@ Raised while building geometry.
 | `cylinder: give "radius"/"diameter", or both "bottom_radius" and "top_radius"` | One end radius on its own is ambiguous |
 | `offset: "join" must be one of "Square", "Round", "Miter"` | An enum attribute with an unrecognised value |
 
-### `box: unknown attribute "colour"`
+### `box: unknown attribute "colour" — box reads "center", "size"`
 
 Worth dwelling on, because it is the error that saves the most time. A misspelled attribute
 would otherwise be silent, and the model would render subtly wrong with nothing to point at.
 The one exception is a [`param`](reference/param.md) block, which is metadata and passes
 anything through.
 
+Both this and `unknown block` carry the alternatives, because the reader is often a program
+with no copy of this manual: an error that says only what is wrong leaves it guessing at
+spellings. A block that branches on which of two spellings it was given — `radius` against
+`diameter` — reads only one of them, so the list is what that call would accept rather than
+always the whole set.
+
 ---
 
 ## Dimensionality

package/src/reference.js

@@ -68,17 +68,19 @@ const BY_PATH = new Map(PAGES.map((page) => [page.path, page]));
  * @returns {Promise<string[]>} Paths relative to the manual's root, sorted.
  */
 export async function discoverPages() {
-  /** @type {string[]} */
-  const found = [];
+  // Subdirectories are independent of each other, so they are walked together rather than
+  // one after the next; the sort at the end is what makes the result order-stable regardless.
   const walk = async (directory) => {
-    for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const found = await Promise.all(entries.map(async (entry) => {
       const child = join(directory, entry.name);
-      if (entry.isDirectory()) await walk(child);
-      else if (entry.name.endsWith('.md')) found.push(relative(ROOT, child));
-    }
+      if (entry.isDirectory()) return walk(child);
+      return entry.name.endsWith('.md') ? [relative(ROOT, child)] : [];
+    }));
+    return found.flat();
   };
-  await walk(ROOT);
-  return found.sort((a, b) => a.localeCompare(b));
+
+  return (await walk(ROOT)).sort((a, b) => a.localeCompare(b));
 }
 
 /**

package/src/roots.js

@@ -0,0 +1,81 @@
+/**
+ * Where the client says the files may go.
+ *
+ * The server does not get to choose the patch of disk it writes to. The MCP `roots`
+ * capability is the client's declaration of which directories it is handing over, and asking
+ * for it — rather than reading an environment variable the client cannot see — is the whole
+ * of this module. A client that declares nothing gets the directory it launched the server
+ * in, which is the one location it did choose.
+ */
+import { fileURLToPath } from 'node:url';
+
+import { RootsListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+
+import { Workspace } from './workspace.js';
+
+/**
+ * The part of the low-level server this module needs.
+ *
+ * Named structurally rather than as the SDK's `Server`, which is deprecated in favour of
+ * `McpServer` — but `McpServer` does not carry `listRoots` or `setNotificationHandler`, so the
+ * low-level object is genuinely the right one to take. Describing the three members used is
+ * both the honest contract and what lets a test hand this a stub.
+ *
+ * @typedef {object} RootsClient
+ * @property {() => ({ roots?: object } | undefined)} getClientCapabilities What the client
+ *   declared at initialisation.
+ * @property {() => Promise<{ roots?: Array<{ uri?: string }> }>} listRoots Asks it for them.
+ * @property {(schema: object, handler: () => unknown) => void} setNotificationHandler
+ *   Registers interest in a notification it may send.
+ */
+
+/**
+ * Asks the client which directories the server may work in.
+ *
+ * Every failure funnels to the launch directory rather than to an error: a client that does
+ * not implement roots is the common case, not a broken one, and a server that refuses to
+ * work with such a client is worse than one that writes where it was started.
+ *
+ * @param {RootsClient} server The low-level server, once a client is connected.
+ * @returns {Promise<string[]>} Absolute directories, in the order the client gave them.
+ */
+export async function askClientForRoots(server) {
+  if (!server.getClientCapabilities()?.roots) return [process.cwd()];
+
+  /** @type {{ roots?: Array<{ uri: string }> }} */
+  let result;
+  try {
+    result = await server.listRoots();
+  } catch (error) {
+    const why = /** @type {Error} */ (error)?.message ?? String(error);
+    console.error(`forma-dsl-mcp: the client would not list its roots (${why})`);
+    return [process.cwd()];
+  }
+
+  // Roots are URIs, and the spec allows schemes this server cannot write to. Anything that
+  // is not a local file is dropped rather than guessed at.
+  const directories = (result?.roots ?? [])
+    .map((root) => root?.uri)
+    .filter((uri) => typeof uri === 'string' && uri.startsWith('file://'))
+    .map((uri) => fileURLToPath(uri));
+
+  return directories.length ? directories : [process.cwd()];
+}
+
+/**
+ * A workspace that takes its roots from the connected client, and re-reads them when the
+ * client says they have changed.
+ *
+ * The roots are asked for lazily, at the first file tool call, because `roots/list` is a
+ * request back to the client and there is no client to ask until initialisation is done.
+ *
+ * @param {RootsClient} server The low-level server the client connects to.
+ * @returns {Workspace} The workspace, with nothing resolved yet.
+ */
+export function clientWorkspace(server) {
+  const workspace = new Workspace(() => askClientForRoots(server));
+  server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+    workspace.forget();
+  });
+  return workspace;
+}