forma-dsl-mcp 0.2.2 → 0.3.2

package/README.md

@@ -2,6 +2,7 @@
 
 [![Release](https://github.com/kalpak44/forma-dsl/actions/workflows/release.yml/badge.svg)](https://github.com/kalpak44/forma-dsl/actions/workflows/release.yml)
 [![npm](https://img.shields.io/npm/v/forma-dsl-mcp.svg)](https://www.npmjs.com/package/forma-dsl-mcp)
+[![M8ven Verified](https://m8ven.ai/api/agent-verify/badge?score=100)](https://m8ven.ai/verified/verify?id=d3529b4756004447)
 
 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
@@ -234,6 +235,21 @@ 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.
 
+## Privacy
+
+This server makes **no network requests**. It imports no HTTP, socket or DNS module and calls
+no `fetch`; the geometry kernel is WebAssembly loaded from disk and the manual is bundled in
+this tarball, so it works with no network at all. There is no telemetry, no analytics, no
+update check and no account.
+
+It writes only inside the directories your client declares as MCP roots, never replaces a file
+unless told to, and leaves nothing elsewhere — no cache, no config, no logs.
+
+Your MCP client is a separate program with its own policy. Documents you ask a model to write
+travel wherever that client sends them, which this server neither controls nor sees.
+
+Full text: [PRIVACY.md](https://github.com/kalpak44/forma-dsl/blob/main/PRIVACY.md).
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-dsl-mcp",
-  "version": "0.2.2",
+  "version": "0.3.2",
   "description": "A stdio MCP server that knows the forma DSL and writes .forma documents that render.",
   "keywords": [
     "mcp",
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
-    "forma-dsl": "^0.2.2",
+    "forma-dsl": "^0.3.2",
     "zod": "^4.1.13"
   }
 }

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/tools.js

@@ -17,6 +17,25 @@ import { GUIDE_SECTIONS, guide } from './guide.js';
 import { PAGES, readPage, searchReference } from './reference.js';
 import { checkDocument, exportStl } from './document.js';
 
+/**
+ * What a tool that only reads what this package already carries is.
+ *
+ * All four hints are stated rather than just `readOnlyHint`, because the omitted ones are not
+ * absent: the specification gives `destructiveHint` a default of **true** and `idempotentHint`
+ * a default of **false**. A tool declaring neither is therefore advertising itself as
+ * destructive and unrepeatable — which, for a call that hands back a page of the manual, is
+ * simply untrue, and a cautious client is entitled to act on it.
+ *
+ * `openWorldHint` is false because every answer is bundled with the package. Nothing here
+ * reaches the network, so the domain is closed and stays closed offline.
+ */
+const READS_ONLY = Object.freeze({
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+});
+
 /**
  * Wraps text as a tool result.
  *
@@ -209,15 +228,14 @@ async function documentFrom(workspace, { source, path }) {
 }
 
 /**
- * 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 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:
@@ -229,9 +247,20 @@ export function registerTools(server, workspace) {
       section: z.enum(/** @type {[string, ...string[]]} */ (GUIDE_SECTIONS)).optional()
         .describe('One section, instead of the whole guide.'),
     },
-    annotations: { readOnlyHint: true, openWorldHint: false },
+    annotations: READS_ONLY,
   }, 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:
@@ -246,7 +275,7 @@ export function registerTools(server, workspace) {
       group: z.string().optional()
         .describe('One group, e.g. "2D shapes", "Transforms", "Refinement", "Declarations".'),
     },
-    annotations: { readOnlyHint: true, openWorldHint: false },
+    annotations: READS_ONLY,
   }, async ({ names, group }) => attempt(async () => {
     const all = [...CONSTRUCTS.values()];
 
@@ -284,14 +313,25 @@ 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:
       'Every function an expression may call, with its arity, and the two named constants. '
       + 'There are no user-defined functions in forma, so this is the complete set.',
     inputSchema: {},
-    annotations: { readOnlyHint: true, openWorldHint: false },
+    annotations: READS_ONLY,
   }, async () => attempt(async () => say([
     '# Functions',
     '',
@@ -306,7 +346,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:
@@ -318,7 +369,7 @@ export function registerTools(server, workspace) {
       query: z.string().optional().describe('Words to search for, e.g. "revolve profile axis".'),
       page: z.string().optional().describe('One page to read, e.g. "reference/conversions.md".'),
     },
-    annotations: { readOnlyHint: true, openWorldHint: false },
+    annotations: READS_ONLY,
   }, async ({ query, page }) => attempt(async () => {
     if (page) {
       const found = await readPage(page);
@@ -347,7 +398,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:
@@ -357,7 +419,7 @@ export function registerTools(server, workspace) {
     inputSchema: {
       name: z.string().optional().describe('One example to read in full.'),
     },
-    annotations: { readOnlyHint: true, openWorldHint: false },
+    annotations: READS_ONLY,
   }, async ({ name }) => attempt(async () => {
     if (name) {
       const example = EXAMPLES_BY_NAME.get(name);
@@ -384,7 +446,20 @@ export function registerTools(server, workspace) {
   }));
 
   // --- 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: 'Check, then write a .forma file',
     description:
@@ -425,7 +500,19 @@ export function registerTools(server, workspace) {
       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 document back',
     description:
@@ -437,13 +524,25 @@ export function registerTools(server, workspace) {
       solve: z.boolean().optional()
         .describe('Run the geometry kernel. Default true; false parses only, which is faster.'),
     },
-    annotations: { readOnlyHint: true, openWorldHint: false },
+    annotations: READS_ONLY,
   }, async ({ path, solve }) => attempt(async () => {
     const source = await workspace.read(path);
     const report = await checkDocument(source, { solve: solve ?? true });
     return say(['```hcl', source.trimEnd(), '```', '', formatReport(report)].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: 'Render and write a binary STL',
     description:
@@ -481,3 +580,27 @@ export function registerTools(server, workspace) {
     );
   }));
 }
+
+/**
+ * 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);
+}