@pascal-app/mcp 0.3.0 → 0.3.2

package/examples/coordinate-conventions-demo.md

@@ -0,0 +1,68 @@
+# Coordinate-conventions demo
+
+Companion scene for the **Coordinate conventions** section of
+[`../README.md`](../README.md). Stress-tests every claim that section
+makes against real Pascal-generated geometry, built entirely through the
+MCP API.
+
+## Load it
+
+```bash
+pascal-mcp --stdio --scene examples/coordinate-conventions-demo.json
+```
+
+The scene fits in a 50 m × 50 m ground-plane footprint at `level: 0`.
+
+## What's in the scene
+
+A flat ground level with four demos, plus a labelled compass at the
+origin so the world axes are unambiguous regardless of which viewport
+you're in.
+
+| Section | What | Why |
+|---|---|---|
+| Reference compass at the origin | 12 m `+X` and `+Z` axis bars with arrowhead tips, short `-X` / `-Z` stubs, an origin marker, plus zone labels naming each component of `[x, z]`. | Establishes which way `+X` and `+Z` actually point in world space, independent of viewport rotation. |
+| **Demo A** at world `(18, 0)` | Axis-aligned 6 m × 4 m rectangle. | Baseline that matches the only example currently in `examples/generate-apartment.md` style (`[0,0] → [10,0]`). |
+| **Demo B** at world `(18, 10)` | The proposed README example, **verbatim**: `polygon: [[0,0],[5.196,3.0],[3.196,6.464],[-2.0,3.464]]` at this offset. | Programmatically verified to be a 6 m × 4 m rectangle whose first edge is heading 30° CCW from `+X` (side lengths 6/4/6/4 m to 4 dp, `AB · AD = 0`, heading = 30.0007°). Confirms the README's worked example produces the geometry it claims. |
+| **Demo C** at world `(0, 22)` and `(10, 22)` | An **L** authored on a north-up page (page-+x right, page-+y up) drawn at half scale and faded; alongside it, the same L pasted into `[x, z]` **uncorrected**, drawn at full scale and vivid. | Makes the external-coordinate gotcha visual: the author's page-+y direction lands on world +Z, which does not correspond to "screen-up" in any of Pascal's viewports. |
+| **Demo D** at world `(22, 22)` and `(32, 22)` | Same pairing for the L with its second coordinate reflected (`z → 5 − z`) before paste. | Makes plain that z-reflection only "corrects" a true mirror; Pascal's viewports apply a *rotation*, so the reflection produces a mirror-image of Demo C rather than a page-correct L. |
+| Takeaway band on the south edge | Short labels summarising the convention. | Self-documenting; readable in any viewport without an external README. |
+
+## What it confirms
+
+Open the scene in Pascal (or render it from the JSON) and you can read
+each claim directly off the geometry:
+
+1. **`[x, z] → world (x, 0, z)` is exact, no sign flip.** Demo A and
+   Demo B both sit flat on the floor at Y = 0; their polygon vertices
+   round-trip through `save_scene` / `get_scene` byte-identical to what
+   was authored (graph hash matches, see `validate_scene` output).
+
+2. **Demo B is the rectangle the README says it is.** A simple analytic
+   check on its 4 vertices yields side lengths 6, 4, 6, 4 m (to 4 dp)
+   with the first edge at 30.0007° from +X and perpendicular adjacent
+   edges. No rendering required.
+
+3. **External page coordinates *rotate* (not mirror) when pasted as
+   `[x, z]` and viewed in Pascal.** Inspecting Demo C in the 2-D plan
+   panel: the page-up L lands rotated 90° clockwise, so the author's
+   "stem-up, foot-bottom-right" reads as "stem-on-right, foot-along-top"
+   on screen. Inspecting Demo D right next to it: the z-reflected
+   variant lands as the *mirror* of Demo C — neither matches a
+   page-correct L. That demonstrates why "reflect across the axis" is
+   the wrong corrective for an issue that is, in this viewport, a
+   rotation.
+
+4. **The 3-D "top-down" snap is offset 45° from world axes by default.**
+   Viewing the scene in 3-D and snapping to top-down from the default
+   iso camera shows the rectangular site polygon as a *diamond* (its
+   long edges are diagonals on screen, not axis-aligned). That's the
+   camera's "up" vector being inherited from the iso start; once you
+   orbit to a true axis-aligned top-down it goes away. The label
+   inviting reviewers to "verify against a guide image" exists for this
+   reason.
+
+## Reproducibility
+
+The canonical demo is the JSON file in this directory; load that file to compare
+the geometry against the notes above.

package/examples/embed-in-agent.ts

@@ -0,0 +1,82 @@
+/**
+ * Programmatic `@pascal-app/mcp` usage.
+ *
+ * Runs a full MCP client/server pair over the in-memory transport inside a
+ * single Bun process. Useful for agent frameworks and tests that want to
+ * drive Pascal without spawning a subprocess.
+ *
+ * Compile with the package's `tsc --build`, or run directly with Bun:
+ *
+ *   bun run packages/mcp/examples/embed-in-agent.ts
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
+import { createPascalMcpServer, SceneBridge } from '@pascal-app/mcp'
+
+async function main(): Promise<void> {
+  // 1. Spin up the headless bridge. `loadDefault()` seeds a Site → Building →
+  //    Level stack so the client has something to query immediately.
+  const bridge = new SceneBridge()
+  bridge.loadDefault()
+  const server = createPascalMcpServer({ bridge })
+
+  // 2. Link the server to an in-memory client. Exactly the same API surface
+  //    as the stdio / HTTP transports, but without any process boundary.
+  const [srvT, cliT] = InMemoryTransport.createLinkedPair()
+  const client = new Client({ name: 'my-agent', version: '0.1.0' })
+  await Promise.all([server.connect(srvT), client.connect(cliT)])
+
+  // 3. Discover available capabilities.
+  const tools = await client.listTools()
+  console.log(
+    'available tools:',
+    tools.tools.map((t) => t.name),
+  )
+
+  // 4. Inspect the current scene.
+  const scene = await client.callTool({ name: 'get_scene', arguments: {} })
+  console.log('scene snapshot:', JSON.stringify(scene, null, 2))
+
+  // 5. Find the default level, create a 5 m wall, and undo it.
+  const levels = await client.callTool({
+    name: 'find_nodes',
+    arguments: { type: 'level' },
+  })
+  const levelId = (levels.structuredContent as { nodes: Array<{ id: string }> }).nodes[0]?.id
+
+  if (levelId) {
+    const created = await client.callTool({
+      name: 'create_wall',
+      arguments: {
+        levelId,
+        start: [0, 0],
+        end: [5, 0],
+        thickness: 0.2,
+        height: 2.5,
+      },
+    })
+    console.log('created wall:', created.structuredContent)
+
+    const undone = await client.callTool({ name: 'undo', arguments: { steps: 1 } })
+    console.log('undone:', undone.structuredContent)
+  }
+
+  // 6. Validate and export.
+  const validation = await client.callTool({ name: 'validate_scene', arguments: {} })
+  console.log('validation:', validation.structuredContent)
+
+  const exported = await client.callTool({
+    name: 'export_json',
+    arguments: { pretty: true },
+  })
+  console.log('export size:', (exported.structuredContent as { json: string }).json.length)
+
+  await client.close()
+  await server.close()
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/examples/generate-apartment.md

@@ -0,0 +1,242 @@
+# Generate a 2-bed apartment from a brief
+
+This example walks through a realistic session with an MCP host (Claude
+Desktop, Claude Code, or Cursor) that has `pascal-mcp` configured. The agent
+uses the `from_brief` prompt to turn a short brief into a concrete scene.
+
+## The brief
+
+> **User:** Claude, create a 2-bedroom 1-bath apartment in 80 m² in Spain.
+
+The host UI lets the user select the **`from_brief`** prompt and fills in:
+
+```text
+brief: "2-bedroom 1-bath apartment in 80 m² in Spain, open-plan living /
+         kitchen, bathroom on the interior wall"
+constraints: "Spanish building regulations; ceiling height 2.5 m"
+```
+
+## What the agent does
+
+The prompt returns a system message instructing the agent to start from an
+empty site, read the current scene, and emit incremental `apply_patch` calls.
+The agent proceeds roughly like this:
+
+### 1. Inspect the current scene
+
+```jsonc
+// tool: get_scene
+{ "name": "get_scene", "arguments": {} }
+```
+
+Response (trimmed):
+
+```jsonc
+{
+  "nodes": {
+    "site-1": { "type": "site", "id": "site-1", "children": [/* ... */] },
+    "building-1": { "type": "building", "id": "building-1", "parentId": "site-1" },
+    "level-1":    { "type": "level",    "id": "level-1",    "parentId": "building-1",
+                    "elevation": 0, "height": 2.5 }
+  },
+  "rootNodeIds": ["site-1"]
+}
+```
+
+The default scene is a Site → Building → Level stack with no walls. The
+agent decides to work on `level-1` and targets a 10 m × 8 m = 80 m² outline.
+
+### 2. Create the perimeter walls
+
+The agent chooses a rectangular outline with its origin at (0, 0):
+
+```jsonc
+// tool: apply_patch
+{
+  "name": "apply_patch",
+  "arguments": {
+    "patches": [
+      { "op": "create", "parentId": "level-1",
+        "node": { "type": "wall", "start": [0, 0], "end": [10, 0],
+                  "thickness": 0.2, "height": 2.5 } },
+      { "op": "create", "parentId": "level-1",
+        "node": { "type": "wall", "start": [10, 0], "end": [10, 8],
+                  "thickness": 0.2, "height": 2.5 } },
+      { "op": "create", "parentId": "level-1",
+        "node": { "type": "wall", "start": [10, 8], "end": [0, 8],
+                  "thickness": 0.2, "height": 2.5 } },
+      { "op": "create", "parentId": "level-1",
+        "node": { "type": "wall", "start": [0, 8], "end": [0, 0],
+                  "thickness": 0.2, "height": 2.5 } }
+    ]
+  }
+}
+```
+
+Response:
+
+```jsonc
+{ "applied": 4 }
+```
+
+### 3. Create interior partitions
+
+Two bedrooms on the east side, bathroom on the interior wall, open-plan
+living / kitchen on the west.
+
+```jsonc
+// tool: apply_patch
+{
+  "name": "apply_patch",
+  "arguments": {
+    "patches": [
+      { "op": "create", "parentId": "level-1",
+        "node": { "type": "wall", "start": [5.5, 0], "end": [5.5, 8],
+                  "thickness": 0.15, "height": 2.5 } },
+      { "op": "create", "parentId": "level-1",
+        "node": { "type": "wall", "start": [5.5, 4], "end": [10, 4],
+                  "thickness": 0.15, "height": 2.5 } },
+      { "op": "create", "parentId": "level-1",
+        "node": { "type": "wall", "start": [5.5, 5.5], "end": [8, 5.5],
+                  "thickness": 0.15, "height": 2.5 } },
+      { "op": "create", "parentId": "level-1",
+        "node": { "type": "wall", "start": [8, 4], "end": [8, 5.5],
+                  "thickness": 0.15, "height": 2.5 } }
+    ]
+  }
+}
+```
+
+### 4. Define zones
+
+The agent declares the rooms so later queries and item placement can target
+them by name:
+
+```jsonc
+// tool: set_zone  (called once per zone)
+{
+  "name": "set_zone",
+  "arguments": {
+    "levelId": "level-1",
+    "label": "Living / Kitchen",
+    "polygon": [[0, 0], [5.5, 0], [5.5, 8], [0, 8]]
+  }
+}
+// → { "zoneId": "zone-living" }
+
+{
+  "name": "set_zone",
+  "arguments": {
+    "levelId": "level-1",
+    "label": "Bedroom 1",
+    "polygon": [[5.5, 0], [10, 0], [10, 4], [5.5, 4]]
+  }
+}
+// → { "zoneId": "zone-bed1" }
+
+{
+  "name": "set_zone",
+  "arguments": {
+    "levelId": "level-1",
+    "label": "Bedroom 2",
+    "polygon": [[5.5, 5.5], [10, 5.5], [10, 8], [5.5, 8]]
+  }
+}
+// → { "zoneId": "zone-bed2" }
+
+{
+  "name": "set_zone",
+  "arguments": {
+    "levelId": "level-1",
+    "label": "Bathroom",
+    "polygon": [[5.5, 4], [8, 4], [8, 5.5], [5.5, 5.5]]
+  }
+}
+// → { "zoneId": "zone-bath" }
+```
+
+### 5. Cut doors and windows
+
+The agent uses `cut_opening` to add entry doors on each interior partition
+and windows on the south and east façades:
+
+```jsonc
+// tool: cut_opening  (called once per opening)
+{
+  "name": "cut_opening",
+  "arguments": {
+    "wallId": "wall-south",       // perimeter wall [0,0] → [10,0]
+    "type": "window",
+    "position": 0.25,             // 25% along centerline
+    "width": 1.2,
+    "height": 1.2
+  }
+}
+// → { "openingId": "window-south-1" }
+```
+
+```jsonc
+{
+  "name": "cut_opening",
+  "arguments": {
+    "wallId": "wall-bed1",        // partition wall to Bedroom 1
+    "type": "door",
+    "position": 0.4,
+    "width": 0.9,
+    "height": 2.1
+  }
+}
+// → { "openingId": "door-bed1" }
+```
+
+The agent repeats this for Bedroom 2's door, the bathroom door, and two
+more windows on the east façade.
+
+### 6. Validate and report
+
+```jsonc
+// tool: validate_scene
+{ "name": "validate_scene", "arguments": {} }
+```
+
+Response:
+
+```jsonc
+{ "valid": true, "errors": [] }
+```
+
+The agent then reads the scene summary for its response to the user:
+
+```jsonc
+// resource: pascal://scene/current/summary
+{ "uri": "pascal://scene/current/summary" }
+```
+
+The host displays the returned Markdown: 1 site, 1 building, 1 level, 8
+walls, 4 zones, 3 doors, 3 windows; usable area ~78 m²; perimeter ~36 m.
+
+### 7. Iterate
+
+The user follows up:
+
+> **User:** Swap the bathroom and bedroom 2 — I want the bathroom near the
+> entrance.
+
+The agent loads the `iterate_on_feedback` prompt and issues a single
+`apply_patch` that updates the polygon of `zone-bath` and `zone-bed2` and
+moves the corresponding partition walls. Because mutation goes through the
+Zustand store, the user can `undo` the change if they dislike it:
+
+```jsonc
+{ "name": "undo", "arguments": { "steps": 1 } }
+// → { "undone": 1 }
+```
+
+## Takeaways
+
+- Mutations batch inside a single `apply_patch` so that `undo` rolls back
+  the whole logical change.
+- Zones are not walls — they're polygon annotations that make later queries
+  (`find_nodes({ zoneId })`) and planning steps much easier for the agent.
+- The agent never needs to speak to `@pascal-app/viewer`: everything the
+  host sees flows through tools + resources + prompts.

package/examples/photo-to-scene.md

@@ -0,0 +1,119 @@
+# Floor-plan photo to Pascal scene
+
+The `photo_to_scene` orchestrator takes a single floor-plan photo and
+returns a saved, navigable Pascal scene. It chains vision (via MCP
+sampling) → scene build → save in one call, so an agent doesn't have to
+stitch three tools together manually.
+
+> **Note:** `photo_to_scene` uses MCP sampling to call the host's model.
+> Hosts that do not advertise `sampling` capability will receive a
+> structured `sampling_unavailable` error; fall back to the text-only
+> `from_brief` prompt in that case.
+
+## The brief
+
+A user drops a photo of a hand-drawn floor plan into the chat and types:
+
+> **User:** here's a floor plan photo, turn it into a Pascal scene.
+
+## The tool call
+
+The agent reads the attachment as a data URI and issues a single tool call:
+
+```jsonc
+// tool: photo_to_scene
+{
+  "name": "photo_to_scene",
+  "arguments": {
+    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD...",
+    "scaleHint": "1 cm = 1 m, approx 20 m²",
+    "name": "Weekend flat"
+  }
+}
+```
+
+Optional knobs:
+
+- `save` (default `true`) — if `false`, the response includes `graph`
+  inline instead of persisting to the `SceneStore`.
+- `defaultWallThickness` (default `0.2` m) — used when the vision model
+  doesn't propose a per-wall thickness.
+- `defaultWallHeight` (default `2.6` m) — applied to every generated wall
+  since the vision schema only captures 2D geometry.
+
+## What happens under the hood
+
+1. The orchestrator issues an MCP sampling request to the host with the
+   image and a structured JSON-only system prompt, mirroring
+   `analyze_floorplan_image`. The host's model returns walls, rooms, and
+   approximate dimensions as JSON.
+2. The reply is validated against a strict Zod schema. Unparseable or
+   schema-failing responses surface as `sampling_response_unparseable` /
+   `sampling_response_invalid` MCP errors.
+3. A fresh `SceneGraph` is built using the core schema factories: a
+   `site` → `building` → `level 0` skeleton, then one `WallNode` per
+   vision wall and one `ZoneNode` per vision room. Each node is
+   re-parsed with `AnyNode.safeParse`; invalid ones are dropped with a
+   warning appended to `notes`.
+4. `bridge.setScene(...)` swaps the live scene so any follow-up MCP call
+   (`find_nodes`, `measure`, `apply_patch`, ...) operates on the new
+   geometry.
+5. If `save: true`, the graph is persisted via `SceneStore.save` and the
+   response carries `sceneId` + `url: /scene/<id>`.
+
+## The response
+
+```jsonc
+{
+  "sceneId": "scene_01hx8a...",
+  "url": "/scene/scene_01hx8a...",
+  "walls": 4,
+  "rooms": 1,
+  "confidence": 0.82
+}
+```
+
+When `save: false` instead:
+
+```jsonc
+{
+  "walls": 4,
+  "rooms": 1,
+  "confidence": 0.82,
+  "graph": {
+    "nodes": { /* flat id → node dict */ },
+    "rootNodeIds": ["site_..."],
+    "collections": {}
+  }
+}
+```
+
+If any wall or room failed schema validation, the response includes a
+`notes` string summarising what was dropped.
+
+## Opening the scene
+
+The user follows `url` in their browser:
+
+```
+https://your-pascal-host/scene/scene_01hx8a...
+```
+
+...and lands in the editor with the new scene loaded, camera auto-framed
+on the building footprint.
+
+## Follow-up prompts
+
+Because the bridge now holds the new scene, subsequent agent turns can
+operate on it without reloading:
+
+> **User:** add a door on the south wall between Living and Kitchen.
+
+The agent calls `find_nodes({ type: "wall" })`, picks the appropriate
+wall, and issues `cut_opening` — no extra wiring needed.
+
+## Takeaways
+
+- `photo_to_scene` is a one-shot primitive: one call, one scene.
+- Vision confidence is surfaced so the agent can warn the user.
+- v0.1 covers walls + zones; doors, windows, items are follow-up tools.