forma-dsl-mcp 0.3.9 → 0.4.0

package/README.md

@@ -15,6 +15,10 @@ it.
 
 It speaks over stdio, and there is nothing to configure.
 
+**[The site](https://kalpak44.github.io/forma-dsl/)** ·
+**[Try the editor](https://kalpak44.github.io/forma-dsl/editor/)** ·
+**[Read the reference](https://kalpak44.github.io/forma-dsl/docs/)**
+
 ## Installing it
 
 **Claude Code**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-dsl-mcp",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "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.32.1",
-    "forma-dsl": "^0.3.9",
+    "forma-dsl": "^0.4.0",
     "zod": "^4.1.13"
   }
 }

package/src/reference/cli.md

@@ -28,6 +28,10 @@ evaluator's own position.
 
 A `<file>` of `-` reads the document from stdin. `params` and `models` take `--json`.
 
+A document, and an `-o`/`--out` that names one, must resolve inside the directory the command
+is run in: a path that leaves it - by `..`, an absolute path, or a symlink pointing out of the
+tree - is refused with exit code 2.
+
 ### `render`
 
 | Option | Default | What it does |
@@ -36,6 +40,7 @@ A `<file>` of `-` reads the document from stdin. `params` and `models` take `--j
 | `-m, --model <name>` | the first declared | which [model](reference/model.md) to build |
 | `--part <name>` | see below | one [part](reference/part.md) by name |
 | `-p, --param <name=val>` | each param's own default | a value for one declared [param](reference/param.md). Repeatable |
+| `--params <file>` | - | a JSON object of values by name. `-p` wins over it |
 | `--segments <n>` | the kernel's own | a fixed segment count for every curve |
 | `--min-angle <deg>` | the kernel's own | smallest angle between adjacent segments of a curve |
 | `--min-edge <n>` | the kernel's own | smallest length a curve segment may be shortened to |
@@ -52,16 +57,67 @@ makes a mess of them.
 
 ---
 
-## Parameter values
+## Passing parameters
+
+Three ways, and they compose.
 
-A value is JSON where it parses as JSON, and the string as written otherwise. That is what
-makes all four of these arrive as the type the document expects, with no second layer of
-quoting:
+**One at a time, on the command line.** A value is JSON where it parses as JSON, and the
+string as written otherwise - so there is no second layer of quoting to get wrong:
 
 ```bash
 forma render part.forma -p count=6 -p center=true -p size=[10,20] -p label=M6
 ```
 
+| Written | Arrives as |
+| --- | --- |
+| `-p count=6` | the number `6` |
+| `-p center=true` | the boolean `true` |
+| `-p size=[10,20]` | the list `[10, 20]` |
+| `-p label=M6` | the string `"M6"` |
+
+**From a file.** `--params` takes a JSON object of values by name - the thing you commit and
+diff, rather than assemble in a shell loop:
+
+```json
+{
+  "height": 36,
+  "label": "M6",
+  "center": true
+}
+```
+
+```bash
+forma render riser.forma --params params.json -o riser.stl
+```
+
+It has to be a JSON **object**. An array or a bare number parses but names nothing, and is
+refused with exit code 2 rather than quietly contributing nothing. Like every other path, it
+must resolve inside the directory the command runs in.
+
+**Both.** `-p` wins over `--params`, which is what a build matrix wants: the values every
+variant shares live in the file, and the one that varies goes on the line.
+
+```bash
+for h in 8 20 40; do
+  forma render riser.forma --params shared.json -p "height=$h" -o "build/riser-$h.stl"
+done
+```
+
+And the document will tell you what it takes, so the first `params.json` need not be written
+by hand:
+
+```bash
+forma params riser.forma --json | jq 'map({(.name): .default}) | add' > params.json
+```
+
+```json
+{
+  "height": 20,
+  "label": "A",
+  "center": false
+}
+```
+
 ---
 
 ## In a pipeline
@@ -96,13 +152,13 @@ A failure is reported where an editor and a CI annotation can both find it: the
 `file:line:column:` prefix, then the lines around it with a caret under the column.
 
 ```
-riser.forma:7:23: size must be positive
- 5 |   part "body" {
- 6 |     extrude {
- 7 |       rect { size = [-40, 20] }
-   |                     ^
- 8 |     }
- 9 |   }
+riser.forma:7:7: rounded_rect: unknown attribute "corner_radius" - rounded_rect reads "center", "radius", "segments", "size"
+5 |     extrude {
+6 |       height = var.height
+7 |       rounded_rect { size = [40, 20]  corner_radius = 4 }
+  |       ^
+8 |     }
+9 |   }
 ```
 
 The position comes from the error itself - see [Errors](errors.md) for what each stage raises
@@ -110,7 +166,7 @@ and what it means.
 
 ---
 
-## Building a matrix
+## What a document declares
 
 `params --json` is the document describing itself, which is what lets a script build every
 variant without being told what the variants are:
@@ -132,11 +188,8 @@ forma params riser.forma --json
 ]
 ```
 
-```bash
-for h in 8 20 40; do
-  forma render riser.forma -p "height=$h" -o "build/riser-$h.stl"
-done
-```
+`required` is true for a param declared with no default, which is one that has to be supplied
+before the document will build at all.
 
 ---