editor/packages/mcp/PR_DESCRIPTION.md

feat(mcp): add @pascal-app/mcp — Model Context Protocol server

Summary

Introduces a new workspace package @pascal-app/mcp (v0.1.0) that exposes the Pascal scene graph (@pascal-app/core) as MCP tools, resources, and prompts so any MCP-compatible AI host — Claude Desktop, Claude Code, Cursor, a custom agent — can read and mutate Pascal projects programmatically with full Zod validation, atomic patches, undo-safe mutations, and multimodal image inputs.

83 files changed, ~5,900 LOC across 68 source files + 27 test files; 142/142 tests pass.

Motivation

Issue #74 "Viewer component API definition" opens the question of how external consumers should drive Pascal. The viewer answers "embed in a React app." This PR answers the complementary case: drive Pascal from anything, without a browser — AI agents, CLI scripts, background services, or IDE plugins.

What's in the box

Tool inventory

Tool	Purpose
get_scene	Return full scene JSON
get_node	Fetch one node by ID
describe_node	Human summary: ancestry, children, properties
find_nodes	Filter by type / parentId / levelId / zoneId
measure	Distance between two nodes; area if zone
apply_patch	Atomic multi-op (create / update / delete). All-or-nothing
create_level	Create a level under a building
create_wall	Create a wall on a level with 2D endpoints
place_item	Place an item on a wall / ceiling / site
cut_opening	Cut a door or window into a wall at t ∈ [0,1]
set_zone	Create a zone polygon on a level
duplicate_level	Deep-clone a level subtree with new IDs
delete_node	Delete a node (with optional cascade)
undo / redo	Drive Zundo temporal store
export_json	Serialize scene to JSON (pretty or compact)
export_glb	Stub (not_implemented — renderer required)
validate_scene	Zod-validate every node
check_collisions	Item placement conflicts per level
analyze_floorplan_image	(Vision/sampling) Extract structured floor plan
analyze_room_photo	(Vision/sampling) Extract room dimensions + fixtures

Resources

URI	MIME	Purpose
pascal://scene/current	application/json	Full scene
pascal://scene/current/summary	text/markdown	Counts, areas, bbox
pascal://catalog/items	application/json	Item catalog (unavailable headless)
pascal://constraints/{levelId}	application/json	Slabs + wall footprints

Prompts

Prompt	Args
from_brief	brief, constraints?
iterate_on_feedback	feedback
renovation_from_photos	currentPhotos, referencePhotos, goals

Architecture

┌─── MCP host (Claude Desktop / Code / Cursor / custom) ───┐
│                          ▲                                │
│         stdio │ HTTP                                      │
│                          ▼                                │
│   ┌──────── packages/mcp/src/bin/pascal-mcp.ts ────────┐  │
│   │ (loads node-shims FIRST, then creates bridge)      │  │
│   └────────────────────────────────────────────────────┘  │
│                          │                                │
│                          ▼                                │
│   ┌──── createPascalMcpServer({ bridge }) ────┐            │
│   │  registerTools()  → 19 tools              │            │
│   │  registerVisionTools() → 2 tools          │            │
│   │  registerResources() → 4 resources        │            │
│   │  registerPrompts() → 3 prompts            │            │
│   └────────────────────────────────────────────┘           │
│                          │                                 │
│                          ▼                                 │
│   ┌──────────── SceneBridge ────────────────┐             │
│   │  headless Zustand store + Zundo         │             │
│   │  RAF polyfill at import time            │             │
│   │  zod validation at every boundary       │             │
│   └──────────────────────────────────────────┘             │
│                          │                                 │
│                          ▼                                 │
│            @pascal-app/core (unchanged, new subpath exports) │
└──────────────────────────────────────────────────────────┘

How to test locally

# From the repo root
bun install
bun run --cwd packages/core build
bun run --cwd packages/mcp build

# Unit + integration tests (142 tests across 27 files)
bun test --cwd packages/mcp

# End-to-end smoke test (spawns stdio server and exercises 4 tools)
bun run --cwd packages/mcp smoke

# Biome lint
bunx biome check packages/mcp

# Turbo build
bunx turbo build --filter=@pascal-app/mcp

Try it with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pascal": {
      "command": "node",
      "args": ["/absolute/path/to/editor/packages/mcp/dist/bin/pascal-mcp.js"]
    }
  }
}

Restart Claude Desktop. Ask it: "Use the Pascal MCP to create a 3-bedroom apartment at 100m²."

Known limitations

1. GLB export is not implemented. Three.js is browser-only; headless GLB export would require a significant additional effort. export_glb returns a structured { status: 'not_implemented' } response.
2. Vision tools require host sampling support. analyze_floorplan_image / analyze_room_photo defer the vision work to the host via MCP sampling. Hosts without sampling capability get a structured sampling_unavailable error. No vision model is bundled.
3. Headless mode doesn't regenerate geometry. Wall mitering, slab triangulation, CSG cutouts, etc. run only in the browser renderer. MCP clients can manipulate node data freely, but derived geometry (mitered wall corners, cut-out walls with door/window holes) is recomputed only when a browser loads the scene via @pascal-app/viewer.
4. loadAssetUrl/saveAsset are browser-only. Items with asset://<id> URLs can't be resolved in Node. Supply absolute URLs or data: URIs if you need them usable outside the browser.
5. SiteNode.children inconsistency. Site's children hold full node objects while every other container holds ID strings (see CROSS_CUTTING.md §2). MCP works around this by traversing via the flat nodes dict. Upstream alignment proposed as a follow-up.
6. Catalog unavailable in headless mode. pascal://catalog/items and place_item's catalog resolution fall back to a placeholder asset payload until the core exposes a Node-consumable catalog.

Cross-cutting changes

Documented in packages/mcp/CROSS_CUTTING.md:

1. packages/core/package.json — additive subpath exports. Adds ./schema, ./store, ./material-library, ./spatial-grid, ./wall. Needed because the main entry re-exports browser-only systems; subpath entries let Node consumers skip them. Zero impact on existing consumers (apps/editor, @pascal-app/viewer still use the main entry).
2. .github/workflows/mcp-ci.yml — new CI. Runs on PRs touching mcp/core; installs with Bun 1.3.0, builds, tests, biome-checks.
3. (Observation, not fixed) SiteNode.children inconsistency. Detailed in CROSS_CUTTING §2.

Checklist

• ✅ bunx biome check packages/mcp — clean (73 files, 0 errors)
• ✅ bun run --cwd packages/mcp build — tsc OK
• ✅ bunx turbo build --filter=@pascal-app/mcp — 2/2 tasks successful
• ✅ bun test --cwd packages/mcp — 142/142 tests pass across 27 files (328 expects)
• ✅ bun run --cwd packages/mcp smoke — spawns stdio server, registers 21 tools, exercises get_scene / create_level / validate_scene / undo end-to-end
• ✅ Docs: README with host configs + tool/resource/prompt tables, CHANGELOG, 3 examples
• ✅ Conventional commit series (9 commits on feat/mcp-server)
• ✅ No modifications to @pascal-app/viewer or apps/editor
• ✅ packages/core changes are purely additive (subpath exports only)
• ✅ Node 18+ compatible; RAF polyfill loads before any core import
• ✅ Strict TypeScript (no any without reason; no @ts-expect-error); Zod at every boundary
• ✅ Every mutation goes through the Zustand store (undo-safe via Zundo)

Commit series

feat(mcp): scaffold package and confirm headless bridge viability
feat(mcp): finalize scaffolding and factory entry
feat(mcp): add headless scene bridge with RAF polyfill
feat(mcp): implement 19 scene query and mutation tools
feat(mcp): add resources and prompts
feat(mcp): add multimodal vision tools via MCP sampling
feat(mcp): add stdio + streamable HTTP transports, CLI, and smoke test
docs(mcp): add README, examples, and changelog
chore(mcp): add CI workflow and document cross-cutting changes

Follow-up (future PRs)

• Align SiteNode.children to IDs-only (with setScene migration) — CROSS_CUTTING §2.
• Expose a Node-consumable item catalog from @pascal-app/core so place_item can resolve real catalog IDs.
• Surface real spatial-grid collision detection (currently a simple AABB pass in check_collisions).
• Post-build chmod +x dist/bin/pascal-mcp.js step so fresh installs get an executable bin without a manual chmod.
• Consider a separate @pascal-app/systems package so @pascal-app/core can go data-only (breaking change, larger refactor).