# 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, Codex CLI, Cursor, or a custom agent — can read, mutate, save, and reopen Pascal projects programmatically with full Zod validation, atomic patches, undo-safe mutations, multimodal image inputs, and local SQLite persistence.

The branch is now local-first: scenes persist to `~/.pascal/data/pascal.db` through SQLite, using `bun:sqlite` in the MCP CLI and `node:sqlite` when the Next.js editor server imports the storage package. The earlier Supabase adapter, SQL migrations, and committed `test-reports/` artifacts have been removed.

## Motivation

Issue [#74 "Viewer component API definition"](https://github.com/pascalorg/editor/issues/74) 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 |
| `save_scene` / `load_scene` / `list_scenes` / `rename_scene` / `delete_scene` | Persist scenes in local SQLite |
| `list_templates` / `create_from_template` | Seed scenes from bundled templates |
| `generate_variants` | Fork and mutate scene variants |
| `photo_to_scene` | Vision sampling to scene graph, optionally saved |

### 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 ────────┐  │
│   │ (Bun CLI, loads node-shims first)                  │  │
│   └────────────────────────────────────────────────────┘  │
│                          │                                │
│                          ▼                                │
│   ┌──── createPascalMcpServer({ bridge }) ────┐            │
│   │  registerTools()                          │            │
│   │  registerVisionTools()                    │            │
│   │  registerResources()                      │            │
│   │  registerPrompts()                        │            │
│   └────────────────────────────────────────────┘           │
│                          │                                 │
│                          ▼                                 │
│   ┌──────────── SceneBridge + SceneStore ───────────────┐  │
│   │  headless Zustand store + Zundo                     │  │
│   │  local SQLite storage at ~/.pascal/data/pascal.db   │  │
│   │  Zod validation at every boundary                   │  │
│   └──────────────────────────────────────────────────────┘  │
│                          │                                 │
│                          ▼                                 │
│            @pascal-app/core (unchanged, new subpath exports) │
└──────────────────────────────────────────────────────────┘
```

## How to test locally

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

# Unit + integration tests (248 tests across 40 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, Claude Code, or Codex

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

```json
{
  "mcpServers": {
    "pascal": {
      "command": "bun",
      "args": ["/absolute/path/to/editor/packages/mcp/dist/bin/pascal-mcp.js"],
      "env": {
        "PASCAL_DATA_DIR": "/Users/you/.pascal/data"
      }
    }
  }
}
```

For Codex CLI:

```bash
codex mcp add pascal-dev \
  --env PASCAL_DATA_DIR="$HOME/.pascal/data" \
  -- bun "$PWD/packages/mcp/dist/bin/pascal-mcp.js"
```

Run the editor with the same `PASCAL_DATA_DIR`, then ask the MCP host to create
and `save_scene`; the scene is openable at `/scene/<id>`.

## 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.
7. **Local-only auth boundary.** The HTTP transport and editor scene API are intended for local development in this PR. Do not expose them on a public network without an auth layer.

## Cross-cutting changes

Documented in [`packages/mcp/CROSS_CUTTING.md`](./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. **`apps/editor` scene routes.** Adds local scene API routes and pages that read from the same SQLite `SceneStore` as MCP.
4. (Observation, not fixed) **`SiteNode.children` inconsistency.** Detailed in CROSS_CUTTING §2.

## Checklist

- ✅ `bunx biome check packages/mcp` — clean
- ✅ `bun run --cwd packages/mcp build` — tsc OK
- ✅ `bunx turbo build --filter=@pascal-app/mcp` — 2/2 tasks successful
- ✅ `bun test --cwd packages/mcp` — 248/248 tests pass across 40 files (965 expects)
- ✅ `bun run --cwd packages/mcp smoke` — spawns stdio server, registers 30 tools, exercises `get_scene` / `create_level` / `validate_scene` / `undo` end-to-end
- ✅ `bun test apps/editor/lib/scene-store-server.test.ts` — editor store singleton test passes
- ✅ Editor smoke — `/api/scenes/<id>` and `/scene/<id>` return 200 for a scene saved through MCP using the shared SQLite DB
- ✅ Local Codex MCP probe with `gpt-5.5` — saved a template scene through `pascal-dev`, then reloaded it and created a wall
- ✅ Docs: README with Claude Desktop, Claude Code, Codex CLI, Cursor configs + tool/resource/prompt tables, CHANGELOG, 3 examples
- ✅ Conventional commit series (9 commits on `feat/mcp-server`)
- ✅ No Supabase dependency, SQL migrations, or committed test-report artifacts
- ✅ `packages/core` changes are additive subpath exports plus URL-schema hardening
- ✅ Bun CLI; 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
feat(mcp,editor): add local SQLite scene persistence and editor scene routes
fix(mcp): remove Supabase backend and committed test reports
```

## Follow-up (future PRs)

- Align `SiteNode.children` to IDs-only (with `setScene` migration) — CROSS_CUTTING §2.
- Extract shared operation/service layer so MCP, CLI, and future REST/OpenAPI adapters do not duplicate business validation.
- 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).