forma-dsl-mcp 0.1.6 → 0.3.1

package/src/server.js

@@ -4,20 +4,35 @@
  * Tools are the part a model calls; resources are the part a client can attach to a
  * conversation by hand, and carry the same knowledge in a form a person can browse. Both
  * read from the same modules, so there is one description of the language here, not two.
+ *
+ * The knowledge is bundled rather than left to the error messages. A refusal names the
+ * alternatives, which is enough to correct a misspelling and not enough to learn a language:
+ * it teaches the name of a block and nothing about what that block means, what it takes, or
+ * which of its attributes interact. A caller with no manual can find `cone` from `frustum`
+ * that way; it cannot find `revolve` at all.
  */
 /** @import { Workspace } from './workspace.js' */
 
+import { createRequire } from 'node:module';
+
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
 
 import { CONSTRUCTS, LANGUAGE_CONSTANTS, LANGUAGE_FUNCTIONS } from './catalogue.js';
 import { EXAMPLES, EXAMPLES_BY_NAME } from './examples.js';
 import { PAGES, readPage } from './reference.js';
+import { clientWorkspace } from './roots.js';
 import { guide } from './guide.js';
 import { registerTools } from './tools.js';
 
-/** The package's own version, reported in the handshake. */
-export const VERSION = '0.1.0';
+/**
+ * The package's own version, reported in the handshake.
+ *
+ * Read from the manifest rather than written out here, because the two drifted the moment
+ * they were allowed to: a client was told 0.1.0 by a server published as 0.1.5, and nothing
+ * in the release could notice. `files` ships `src/` and npm always ships the manifest, so
+ * this resolves in the published package as well as in the tree.
+ */
+export const VERSION = createRequire(import.meta.url)('../package.json').version;
 
 /**
  * What the server tells a client it is for, offered as instructions during initialisation.
@@ -25,34 +40,42 @@ export const VERSION = '0.1.0';
  * Clients put this in front of the model before it has called anything, so it is the one
  * place to say the thing that changes behaviour most: check before you claim it works.
  */
-const INSTRUCTIONS = `This server knows forma, a declarative DSL for 3D solids, and can write
-and solve .forma documents.
+const INSTRUCTIONS = `This server knows forma, a declarative DSL for 3D solids, builds it with
+the real geometry kernel, and writes the documents it builds.
 
 Start with \`forma_guide\` — it is the language in one page. Use \`forma_blocks\` for the
 attributes of the blocks you are about to write, \`forma_examples\` for a working document of
 a similar shape, and \`forma_reference\` when you need the manual.
 
-Never hand a .forma document to anyone without running \`forma_check\` on it first. The check
-builds the geometry with the real kernel and reports the bounding box, the volume and the
-triangle count of every part, which is the only way to know that the model is the size that
-was asked for and has not silently solved to nothing. Write files with \`forma_write\`, which
-runs the same check and refuses a document that does not render.`;
+Never hand a .forma document to anyone without writing it through \`forma_write\`. It compiles
+the document, solves it and reports the bounding box, the volume and the triangle count of
+every part, which is the only way to know that the model is the size that was asked for and
+has not silently solved to nothing. A document that does not build is refused rather than
+written. Read one back with \`forma_read\`, and export a solid with \`forma_export_stl\`.
+
+Where those files go is the client's decision, not the server's: the tools read and write
+inside the directories the client declares as MCP roots, and a path is taken relative to the
+first of them. Every write reports the directory it landed in.`;
 
 /**
- * Builds the server, with every tool, resource and prompt registered.
+ * Builds the server, with every tool and resource registered.
  *
- * @param {Workspace} workspace The patch of filesystem the file tools may touch.
+ * The workspace is optional, and left out is the normal case: the server then takes its
+ * directories from whatever the connected client declares as its roots, which is the point —
+ * the client knows where the user's files belong and the server does not.
+ *
+ * @param {Workspace} [workspace] The patch of filesystem the tools may touch. Omitted, the
+ *   client's roots are used.
  * @returns {McpServer} The server, not yet connected to a transport.
  */
 export function createServer(workspace) {
   const server = new McpServer(
     { name: 'forma-dsl', version: VERSION },
-    { capabilities: { tools: {}, resources: {}, prompts: {} }, instructions: INSTRUCTIONS },
+    { capabilities: { tools: {}, resources: {} }, instructions: INSTRUCTIONS },
   );
 
-  registerTools(server, workspace);
+  registerTools(server, workspace ?? clientWorkspace(server.server));
   registerResources(server);
-  registerPrompts(server);
 
   return server;
 }
@@ -136,84 +159,3 @@ function registerResources(server) {
   );
 }
 
-/**
- * Registers the prompts, which are the workflows worth having a name for.
- *
- * @param {McpServer} server The server.
- * @returns {void}
- */
-function registerPrompts(server) {
-  server.registerPrompt('model_a_part', {
-    title: 'Model a part in forma',
-    description: 'Walks from a description of a physical object to a checked .forma document.',
-    argsSchema: {
-      part: z.string().describe('What to model, e.g. "a wall bracket for a 35 mm pipe".'),
-      constraints: z.string().optional()
-        .describe('Dimensions, tolerances, print constraints — anything the result has to satisfy.'),
-      path: z.string().optional().describe('Where to write the finished document.'),
-    },
-  }, ({ part, constraints, path }) => ({
-    messages: [{
-      role: 'user',
-      content: {
-        type: 'text',
-        text: [
-          `Model this in forma: ${part}.`,
-          constraints ? `\nIt has to satisfy: ${constraints}` : '',
-          '',
-          'Work in this order:',
-          '1. Call `forma_guide` if you have not already read it this session.',
-          '2. Call `forma_examples` and read the one closest to what this is.',
-          '3. Decide what is a `param` (anything a person would reasonably change, with a '
-          + 'default, a min and a max) and what is a `local` (anything derived from those).',
-          '4. Write the document. Prefer a 2D profile given thickness by `extrude` or '
-          + '`revolve` over composing solids. Name any repeated feature — including the '
-          + 'negative of one — as a `component`. Give each physical piece its own `part` with '
-          + 'a colour.',
-          '5. Call `forma_check` with `solve: true`. Read the bounding box and the volume back '
-          + 'and confirm they are what was asked for. A part with zero volume means the model '
-          + 'silently produced nothing — fix it, do not report it as done.',
-          '6. Iterate until it renders and measures correctly.',
-          path
-            ? `7. Write it to \`${path}\` with \`forma_write\`.`
-            : '7. Offer to write it with `forma_write` once it checks out.',
-          '',
-          'Report the finished document along with its measured size, and say which params '
-          + 'drive which dimension.',
-        ].filter(Boolean).join('\n'),
-      },
-    }],
-  }));
-
-  server.registerPrompt('review_a_document', {
-    title: 'Review a .forma document',
-    description: 'Checks an existing document and reports what is wrong or fragile about it.',
-    argsSchema: { path: z.string().describe('The document to review.') },
-  }, ({ path }) => ({
-    messages: [{
-      role: 'user',
-      content: {
-        type: 'text',
-        text: [
-          `Review the forma document at \`${path}\`.`,
-          '',
-          'Call `forma_read` on it, then look for:',
-          '- parts that solved to nothing, or a bounding box that is not what the document '
-          + 'seems to intend;',
-          '- a `part` nested inside a transform or a boolean, which is silently dropped;',
-          '- a `difference` whose cutter ends exactly on a face, leaving a zero-thickness skin;',
-          '- dimensions written as bare numbers where a `param` or a `local` would say what '
-          + 'they mean;',
-          '- a `param` whose `min`/`max` the model does not actually clamp, since those bounds '
-          + 'are advisory and never enforced;',
-          '- geometry that would not print: unsupported overhangs, walls thinner than a nozzle, '
-          + 'a non-zero genus where a solid was meant.',
-          '',
-          'Re-check with different param values at the ends of their declared ranges — a model '
-          + 'that only works at its defaults is the common failure. Report what you found, and '
-          + 'propose the smallest edit that fixes each one.',
-        ].join('\n'),
-      },
-    }],
-  }));
-}

package/src/tools.js

@@ -1,5 +1,5 @@
 /**
- * The tools the server offers, and how their results are worded.
+ * The three tools the server offers, and how their results are worded.
  *
  * Results are Markdown rather than JSON on purpose. Everything here is read by a language
  * model deciding what to write next, and a bounding box in a table is acted on where the
@@ -34,7 +34,7 @@ const say = (text, isError = false) => ({
  *
  * A thrown error becomes a protocol-level failure, which most clients surface as "the tool
  * broke" rather than as something the model can correct. A refusal it can read — a path
- * outside the root, a part that does not exist — belongs in the result instead.
+ * outside the roots, a part that does not exist — belongs in the result instead.
  *
  * @param {() => Promise<object>} handler What to run.
  * @returns {Promise<object>} Its result, or the failure as text.
@@ -189,45 +189,34 @@ export function formatReport(report) {
   lines.push(...parameterLines(report.parameters));
 
   if (report.scene) lines.push(...sceneLines(report.scene, report.stats));
-  else if (report.ok) lines.push('_Parsed only — pass `solve: true` to build the geometry and measure it._');
 
   return lines.join('\n');
 }
 
 /**
- * Resolves the `source`-or-`path` pair every document-taking tool accepts.
+ * Resolves the `source`-or-`path` pair the export tool accepts.
  *
  * @param {Workspace} workspace Where a path is resolved.
  * @param {{ source?: string, path?: string }} args What the caller gave.
- * @returns {Promise<{ source: string, from: string }>} The document, and where it came from.
+ * @returns {Promise<string>} The document.
  * @throws {Error} If neither or both were given.
  */
 async function documentFrom(workspace, { source, path }) {
   if (source && path) throw new Error('give either "source" or "path", not both');
-  if (source) return { source, from: 'the supplied source' };
-  if (path) return { source: await workspace.read(path), from: `\`${path}\`` };
-  throw new Error('give either "source" — the document itself — or "path" to one in the workspace');
+  if (source) return source;
+  if (path) return workspace.read(path);
+  throw new Error('give either "source" — the document itself — or "path" to one already written');
 }
 
-/** The arguments shared by every tool that takes a document and may render it. */
-const DOCUMENT_ARGS = {
-  source: z.string().optional().describe('The .forma document itself.'),
-  path: z.string().optional().describe('A .forma file in the workspace, instead of `source`.'),
-  model: z.string().optional().describe('Which model to build. Defaults to the first one declared.'),
-  params: z.record(z.string(), z.any()).optional()
-    .describe('Values for the document\'s params, by name. Anything not given uses its default.'),
-};
-
 /**
- * Registers every tool on a server.
+ * The language in one page, or one section of it.
+ *
+ * Registered first because it is what the server's instructions tell a model to read first.
  *
  * @param {McpServer} server The server.
- * @param {Workspace} workspace The patch of filesystem the file tools may touch.
  * @returns {void}
  */
-export function registerTools(server, workspace) {
-  // --- knowing the language ---------------------------------------------------------------
-
+function registerGuide(server) {
   server.registerTool('forma_guide', {
     title: 'The forma language in brief',
     description:
@@ -241,7 +230,18 @@ export function registerTools(server, workspace) {
     },
     annotations: { readOnlyHint: true, openWorldHint: false },
   }, async ({ section }) => attempt(async () => say(guide(section))));
+}
 
+/**
+ * What every block takes, read from the library's own registry.
+ *
+ * Names are answered in full rather than as a list, because a caller that has to guess at
+ * an attribute spends a build finding out it guessed wrong.
+ *
+ * @param {McpServer} server The server.
+ * @returns {void}
+ */
+function registerBlocks(server) {
   server.registerTool('forma_blocks', {
     title: 'Block and declaration reference',
     description:
@@ -294,7 +294,18 @@ export function registerTools(server, workspace) {
     lines.push('_Call again with `names` for the attribute tables._');
     return say(lines.join('\n'));
   }));
+}
 
+/**
+ * Every function an expression may call, and the two named constants.
+ *
+ * There are no user-defined functions in forma, so this answer is complete rather than a
+ * sample — which is worth saying, because it is what stops a caller inventing one.
+ *
+ * @param {McpServer} server The server.
+ * @returns {void}
+ */
+function registerFunctions(server) {
   server.registerTool('forma_functions', {
     title: 'Builtin functions and constants',
     description:
@@ -316,7 +327,18 @@ export function registerTools(server, workspace) {
     '',
     table(['Name', 'Value'], LANGUAGE_CONSTANTS.map((c) => [`\`${c.name}\``, c.value])),
   ].join('\n'))));
+}
 
+/**
+ * The bundled manual: search it, read a page, or list what there is.
+ *
+ * The manual ships with the package rather than being fetched, so the answers stay true to
+ * the version installed and work with no network at all.
+ *
+ * @param {McpServer} server The server.
+ * @returns {void}
+ */
+function registerReference(server) {
   server.registerTool('forma_reference', {
     title: 'The reference manual',
     description:
@@ -357,7 +379,18 @@ export function registerTools(server, workspace) {
       table(['Page', 'Title', 'About'], PAGES.map((each) => [`\`${each.path}\``, each.title, each.about])),
     ].join('\n'));
   }));
+}
 
+/**
+ * Complete documents that render, to read before writing something new.
+ *
+ * Every one is rendered by this package's tests at both ends of every parameter's range, so
+ * an example cannot teach a mistake without the build failing.
+ *
+ * @param {McpServer} server The server.
+ * @returns {void}
+ */
+function registerExamples(server) {
   server.registerTool('forma_examples', {
     title: 'Worked documents',
     description:
@@ -393,48 +426,38 @@ export function registerTools(server, workspace) {
     ].join('\n'));
   }));
 
-  // --- writing and checking ----------------------------------------------------------------
-
-  server.registerTool('forma_check', {
-    title: 'Check and measure a document',
-    description:
-      'Parses a .forma document and, unless told not to, builds one of its models with the '
-      + 'real geometry kernel. Reports any error with the line, the column and an excerpt with '
-      + 'a caret on it, and reports a successful build as a table of parts with their bounding '
-      + 'boxes, volumes, triangle counts and genus. This is how you find out whether what you '
-      + 'wrote is the size you meant, is watertight, and is not silently empty. Use it after '
-      + 'every edit.',
-    inputSchema: {
-      ...DOCUMENT_ARGS,
-      solve: z.boolean().optional()
-        .describe('Run the geometry kernel. Default true; false parses only, which is faster while drafting.'),
-    },
-    annotations: { readOnlyHint: true, openWorldHint: false },
-  }, async (args) => attempt(async () => {
-    const { source, from } = await documentFrom(workspace, args);
-    const report = await checkDocument(source, {
-      model: args.model ?? null,
-      params: args.params ?? {},
-      solve: args.solve ?? true,
-    });
-    return {
-      content: [{ type: /** @type {'text'} */ ('text'), text: `${formatReport(report)}\n\n_Checked ${from}._` }],
-      ...(report.ok ? {} : { isError: false }),
-    };
-  }));
+  // --- writing and building ----------------------------------------------------------------
+}
 
+/**
+ * Build a document, and write it only if it built.
+ *
+ * The measurement is the point, not the file: a caller that is told the bounding box, the
+ * volume and the triangle count knows whether the model is the size that was asked for and
+ * has not silently solved to nothing. A refusal leaves nothing on disk.
+ *
+ * @param {McpServer} server The server.
+ * @param {Workspace} workspace The patch of filesystem the tool may touch.
+ * @returns {void}
+ */
+function registerWrite(server, workspace) {
   server.registerTool('forma_write', {
-    title: 'Write a .forma file',
+    title: 'Check, then write a .forma file',
     description:
-      'Checks a document and writes it into the workspace. The check runs first and a document '
-      + 'that does not render is refused, so a file on disk is one that works — pass '
-      + '`force: true` to write it anyway. Refuses to replace an existing file unless '
-      + '`overwrite` is set.',
+      'Builds a .forma document with the real geometry kernel and, if it renders, writes it. '
+      + 'The result is the measurement: a table of every part with its bounding box, volume, '
+      + 'triangle count and genus, or the error with the line, the column and an excerpt with '
+      + 'a caret on it. This is how you find out whether what you wrote is the size you meant, '
+      + 'is watertight, and is not silently empty. A document that does not render is refused '
+      + 'and nothing is written — pass `force: true` to write it anyway. Refuses to replace an '
+      + 'existing file unless `overwrite` is set.',
     inputSchema: {
-      path: z.string().describe('Where to write, relative to the workspace root. Must end in .forma.'),
+      path: z.string()
+        .describe('Where to write, relative to the first directory the client declared as a root. Must end in .forma.'),
       source: z.string().describe('The document.'),
-      model: z.string().optional().describe('Which model to check. Defaults to the first one.'),
-      params: z.record(z.string(), z.any()).optional().describe('Param values to check with.'),
+      model: z.string().optional().describe('Which model to build. Defaults to the first one declared.'),
+      params: z.record(z.string(), z.any()).optional()
+        .describe('Values for the document\'s params, by name. Anything not given uses its default.'),
       overwrite: z.boolean().optional().describe('Replace the file if it already exists. Default false.'),
       force: z.boolean().optional().describe('Write even if the document does not render. Default false.'),
     },
@@ -452,19 +475,35 @@ export function registerTools(server, workspace) {
 
     const written = await workspace.write(path, source, { overwrite, extension: '.forma' });
     return say([
-      `Wrote \`${written.relative}\` — ${written.bytes} bytes${written.replaced ? ', replacing what was there' : ''}.`,
+      `Wrote \`${written.relative}\` under \`${written.root}\` — ${written.bytes} bytes`
+      + `${written.replaced ? ', replacing what was there' : ''}.`,
       '',
       formatReport(report),
     ].join('\n'));
   }));
+}
 
+/**
+ * Read a document back, with its current measurements.
+ *
+ * Source and measurements together, because editing something last touched in another
+ * session means needing both.
+ *
+ * @param {McpServer} server The server.
+ * @param {Workspace} workspace The patch of filesystem the tool may touch.
+ * @returns {void}
+ */
+function registerRead(server, workspace) {
   server.registerTool('forma_read', {
-    title: 'Read a .forma file',
-    description: 'Reads a document from the workspace and checks it, so you see the source and '
-      + 'its current state together.',
+    title: 'Read a document back',
+    description:
+      'Reads a .forma file the client has given access to and builds it, so you see the source '
+      + 'and its current measurements together. Use it before editing something you did not '
+      + 'write in this session.',
     inputSchema: {
-      path: z.string().describe('The file, relative to the workspace root.'),
-      solve: z.boolean().optional().describe('Run the geometry kernel. Default true.'),
+      path: z.string().describe('The file, relative to the first directory the client declared as a root.'),
+      solve: z.boolean().optional()
+        .describe('Run the geometry kernel. Default true; false parses only, which is faster.'),
     },
     annotations: { readOnlyHint: true, openWorldHint: false },
   }, async ({ path, solve }) => attempt(async () => {
@@ -472,40 +511,41 @@ export function registerTools(server, workspace) {
     const report = await checkDocument(source, { solve: solve ?? true });
     return say(['```hcl', source.trimEnd(), '```', '', formatReport(report)].join('\n'));
   }));
+}
 
-  server.registerTool('forma_list', {
-    title: 'List the .forma files in the workspace',
-    description: 'Every .forma document under the workspace root, so you can find what is '
-      + 'already here instead of guessing at names.',
-    inputSchema: {},
-    annotations: { readOnlyHint: true, openWorldHint: false },
-  }, async () => attempt(async () => {
-    const files = await workspace.list('.forma');
-    if (!files.length) return say(`No .forma files under ${workspace.root}.`);
-    const plural = files.length > 1 ? 's' : '';
-    return say([
-      `# ${files.length} document${plural} under ${workspace.root}`,
-      '',
-      ...files.map((file) => `- \`${file}\``),
-    ].join('\n'));
-  }));
-
+/**
+ * Render a document and write one part, or every part unioned, as binary STL.
+ *
+ * Takes a document either as source or as a path already on disk, so a caller that has just
+ * written one does not have to hold it a second time.
+ *
+ * @param {McpServer} server The server.
+ * @param {Workspace} workspace The patch of filesystem the tool may touch.
+ * @returns {void}
+ */
+function registerExportStl(server, workspace) {
   server.registerTool('forma_export_stl', {
-    title: 'Export a model as binary STL',
+    title: 'Render and write a binary STL',
     description:
-      'Renders a document and writes one part — or every part unioned — as a binary STL into '
-      + 'the workspace. Lengths are unitless in forma and STL has no unit either; every '
-      + 'consumer treats them as millimetres.',
+      'Renders a document and writes one part — or every part unioned — as a binary STL. '
+      + 'Lengths are unitless in forma and STL has no unit either; every consumer treats them '
+      + 'as millimetres.',
     inputSchema: {
-      ...DOCUMENT_ARGS,
-      out: z.string().describe('Where to write, relative to the workspace root. Must end in .stl.'),
+      source: z.string().optional().describe('The .forma document itself.'),
+      path: z.string().optional()
+        .describe('A .forma file the client has given access to, instead of `source`.'),
+      model: z.string().optional().describe('Which model to build. Defaults to the first one declared.'),
+      params: z.record(z.string(), z.any()).optional()
+        .describe('Values for the document\'s params, by name. Anything not given uses its default.'),
+      out: z.string()
+        .describe('Where to write, relative to the first directory the client declared as a root. Must end in .stl.'),
       part: z.string().optional()
         .describe('One part by name. Omitted, a single-part model exports that part and a multi-part model exports them unioned.'),
       overwrite: z.boolean().optional().describe('Replace the file if it already exists. Default false.'),
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   }, async (args) => attempt(async () => {
-    const { source } = await documentFrom(workspace, args);
+    const source = await documentFrom(workspace, args);
     const result = await exportStl(source, {
       model: args.model ?? null,
       params: args.params ?? {},
@@ -516,8 +556,32 @@ export function registerTools(server, workspace) {
       extension: '.stl',
     });
     return say(
-      `Wrote \`${written.relative}\` — ${written.bytes} bytes, ${result.triangles} triangles, `
-      + `from model \`${result.model}\`, part \`${result.part}\`.`,
+      `Wrote \`${written.relative}\` under \`${written.root}\` — ${written.bytes} bytes, `
+      + `${result.triangles} triangles, from model \`${result.model}\`, part \`${result.part}\`.`,
     );
   }));
 }
+
+/**
+ * Registers every tool on a server.
+ *
+ * One function per tool, so this reads as the list of what the server offers and each tool's
+ * schema, description and handler stay together where they are edited.
+ *
+ * @param {McpServer} server The server.
+ * @param {Workspace} workspace The patch of filesystem the file tools may touch.
+ * @returns {void}
+ */
+export function registerTools(server, workspace) {
+  // Knowing the language.
+  registerGuide(server);
+  registerBlocks(server);
+  registerFunctions(server);
+  registerReference(server);
+  registerExamples(server);
+
+  // Writing and building.
+  registerWrite(server, workspace);
+  registerRead(server, workspace);
+  registerExportStl(server, workspace);
+}