@pascal-app/mcp 0.2.0

package/dist/tools/scene-lifecycle/save-scene.js

@@ -0,0 +1,130 @@
+import { AnyNode } from '@pascal-app/core/schema';
+import { z } from 'zod';
+import { SceneVersionConflictError } from '../../storage/types';
+import { ErrorCode, throwMcpError } from '../errors';
+import { appendLiveSceneEvent } from '../live-sync';
+import { currentLevelContext, sceneMetaPayload } from './metadata';
+export const saveSceneInput = {
+    id: z.string().min(1).max(64).optional(),
+    name: z.string().min(1).max(200),
+    projectId: z.string().optional(),
+    expectedVersion: z.number().int().positive().optional(),
+    saveMode: z
+        .enum(['draft', 'checkpoint'])
+        .default('draft')
+        .describe('`draft` updates the browser-visible working model without polluting version history. `checkpoint` creates a meaningful saved version.'),
+    publish: z
+        .boolean()
+        .optional()
+        .describe('For checkpoint saves, publish the checkpoint as the browser-visible version.'),
+    thumbnail: z.string().url().optional(),
+    includeCurrentScene: z
+        .boolean()
+        .default(true)
+        .describe('If true, save the bridge current scene. If false, use the graph arg.'),
+    graph: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe('Full SceneGraph { nodes, rootNodeIds, collections? } to save instead of the bridge state.'),
+};
+export const saveSceneOutput = {
+    id: z.string(),
+    name: z.string(),
+    projectId: z.string().nullable(),
+    thumbnailUrl: z.string().nullable(),
+    version: z.number(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    ownerId: z.string().nullable(),
+    sizeBytes: z.number(),
+    nodeCount: z.number(),
+    url: z.string(),
+    editorUrl: z.string(),
+    published: z.boolean(),
+    isDraft: z.boolean(),
+    saveMode: z.enum(['draft', 'checkpoint']),
+    graphHash: z.string().optional(),
+    levelIds: z.array(z.string()),
+    defaultLevelId: z.string().nullable(),
+};
+export function registerSaveScene(server, bridge) {
+    server.registerTool('save_scene', {
+        title: 'Save scene',
+        description: 'Save the current scene (or a provided graph) to the SceneStore. Defaults to a browser-visible draft save so agents can iterate without creating many project versions. Use saveMode: "checkpoint" for meaningful version history.',
+        inputSchema: saveSceneInput,
+        outputSchema: saveSceneOutput,
+    }, async ({ id, name, projectId, expectedVersion, saveMode, publish, thumbnail, includeCurrentScene, graph, }) => {
+        let sceneGraph;
+        if (includeCurrentScene) {
+            const validation = bridge.validateScene();
+            if (!validation.valid) {
+                throwMcpError(ErrorCode.InvalidRequest, 'scene_invalid', { errors: validation.errors });
+            }
+            sceneGraph = bridge.exportSceneGraph();
+        }
+        else {
+            if (!graph) {
+                throwMcpError(ErrorCode.InvalidParams, 'graph_required: pass `graph` when includeCurrentScene is false');
+            }
+            // Security: revalidate every node with AnyNode schema (including the
+            // AssetUrl allowlist) BEFORE persisting. Without this, the save_scene
+            // graph arg is a bypass for the URL hardening in A7. See P4 report.
+            const rawNodes = graph.nodes;
+            if (!rawNodes || typeof rawNodes !== 'object') {
+                throwMcpError(ErrorCode.InvalidParams, 'graph.nodes must be an object');
+            }
+            const errors = [];
+            for (const [nodeId, node] of Object.entries(rawNodes)) {
+                const res = AnyNode.safeParse(node);
+                if (!res.success) {
+                    for (const issue of res.error.issues) {
+                        errors.push({
+                            nodeId,
+                            path: issue.path.map(String).join('.'),
+                            message: issue.message,
+                        });
+                    }
+                }
+            }
+            if (errors.length > 0) {
+                throwMcpError(ErrorCode.InvalidParams, 'graph_invalid', { errors });
+            }
+            sceneGraph = graph;
+        }
+        try {
+            const meta = await bridge.saveScene({
+                ...(id !== undefined ? { id } : {}),
+                name,
+                ...(projectId !== undefined ? { projectId } : {}),
+                graph: sceneGraph,
+                ...(thumbnail !== undefined ? { thumbnailUrl: thumbnail } : {}),
+                ...(expectedVersion !== undefined ? { expectedVersion } : {}),
+                saveMode,
+                ...(publish !== undefined ? { publish } : {}),
+                operation: 'save_scene',
+            });
+            await appendLiveSceneEvent(bridge, meta.id, meta.version, 'save_scene', sceneGraph);
+            if (includeCurrentScene) {
+                bridge.setActiveScene(meta);
+            }
+            const payload = {
+                ...sceneMetaPayload(meta, sceneGraph),
+                ...currentLevelContext(bridge),
+            };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(payload) }],
+                structuredContent: payload,
+            };
+        }
+        catch (err) {
+            if (err instanceof SceneVersionConflictError) {
+                throwMcpError(ErrorCode.InvalidRequest, 'version_conflict', {
+                    expectedVersion,
+                    id,
+                });
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            throwMcpError(ErrorCode.InvalidRequest, msg);
+        }
+    });
+}

package/dist/tools/scene-lifecycle/test-utils.d.ts

@@ -0,0 +1,39 @@
+import { SceneBridge } from '../../bridge/scene-bridge';
+import { type SceneOperations } from '../../operations';
+import { type ProjectCreateOptions, type ProjectStatus, type SceneListOptions, type SceneMeta, type SceneMutateOptions, type SceneSaveOptions, type SceneStore, type SceneWithGraph } from '../../storage/types';
+export type StoredTextContent = {
+    type: string;
+    text: string;
+};
+export declare function parseToolText(content: StoredTextContent[]): Record<string, unknown>;
+export declare function createTestSceneOperations(options?: {
+    bridge?: SceneBridge;
+    store?: InMemorySceneStore;
+}): {
+    bridge: SceneBridge;
+    store: InMemorySceneStore;
+    operations: SceneOperations;
+};
+/**
+ * In-memory `SceneStore` for tests. Backed by a plain `Map` keyed by id.
+ * Implements the full interface including optimistic concurrency via
+ * `expectedVersion`.
+ */
+export declare class InMemorySceneStore implements SceneStore {
+    readonly backend: "sqlite";
+    private readonly data;
+    private readonly projects;
+    private idCounter;
+    private projectCounter;
+    createProject(opts: ProjectCreateOptions): Promise<ProjectStatus>;
+    getProjectStatus(id: string): Promise<ProjectStatus | null>;
+    save(opts: SceneSaveOptions): Promise<SceneMeta>;
+    load(id: string): Promise<SceneWithGraph | null>;
+    list(opts?: SceneListOptions): Promise<SceneMeta[]>;
+    delete(id: string, opts?: SceneMutateOptions): Promise<boolean>;
+    rename(id: string, newName: string, opts?: SceneMutateOptions): Promise<SceneMeta>;
+    private touchProject;
+    private toMeta;
+    private toProjectStatus;
+}
+//# sourceMappingURL=test-utils.d.ts.map

package/dist/tools/scene-lifecycle/test-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../../src/tools/scene-lifecycle/test-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AACvD,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAC9E,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,kBAAkB,EAEvB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAEf,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAA;AAG5B,MAAM,MAAM,iBAAiB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9D,wBAAgB,aAAa,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEnF;AAED,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE;IAClD,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,KAAK,CAAC,EAAE,kBAAkB,CAAA;CAC3B,GAAG;IACF,MAAM,EAAE,WAAW,CAAA;IACnB,KAAK,EAAE,kBAAkB,CAAA;IACzB,UAAU,EAAE,eAAe,CAAA;CAC5B,CAKA;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,UAAU;IACnD,QAAQ,CAAC,OAAO,EAAG,QAAQ,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoC;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAWtB;IACH,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,cAAc,CAAI;IAEpB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IAejE,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAK3D,IAAI,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC;IA+DhD,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAShD,IAAI,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAanD,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAW/D,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC;IAmBxF,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,MAAM;IAoBd,OAAO,CAAC,eAAe;CA0BxB"}

package/dist/tools/scene-lifecycle/test-utils.js

@@ -0,0 +1,211 @@
+import { SceneBridge } from '../../bridge/scene-bridge';
+import { createSceneOperations } from '../../operations';
+import { SceneNotFoundError, SceneVersionConflictError, } from '../../storage/types';
+import { computeGraphHash, editorUrlFor } from './metadata';
+export function parseToolText(content) {
+    return JSON.parse(content[0].text);
+}
+export function createTestSceneOperations(options) {
+    const bridge = options?.bridge ?? new SceneBridge();
+    const store = options?.store ?? new InMemorySceneStore();
+    const operations = createSceneOperations({ bridge, store });
+    return { bridge, store, operations };
+}
+/**
+ * In-memory `SceneStore` for tests. Backed by a plain `Map` keyed by id.
+ * Implements the full interface including optimistic concurrency via
+ * `expectedVersion`.
+ */
+export class InMemorySceneStore {
+    backend = 'sqlite';
+    data = new Map();
+    projects = new Map();
+    idCounter = 0;
+    projectCounter = 0;
+    async createProject(opts) {
+        const id = opts.id ?? `project_${++this.projectCounter}`;
+        const now = new Date().toISOString();
+        this.projects.set(id, {
+            id,
+            name: opts.name,
+            ownerId: opts.ownerId ?? null,
+            isPrivate: opts.isPrivate ?? true,
+            thumbnailUrl: null,
+            createdAt: now,
+            updatedAt: now,
+        });
+        return this.toProjectStatus(id);
+    }
+    async getProjectStatus(id) {
+        if (!(this.projects.has(id) || this.data.has(id)))
+            return null;
+        return this.toProjectStatus(id);
+    }
+    async save(opts) {
+        const existing = opts.id ? this.data.get(opts.id) : undefined;
+        if (existing) {
+            if (opts.expectedVersion !== undefined && existing.version !== opts.expectedVersion) {
+                throw new SceneVersionConflictError(`Expected version ${opts.expectedVersion}, have ${existing.version}`);
+            }
+            const now = new Date().toISOString();
+            const nodeCount = Object.keys(opts.graph.nodes ?? {}).length;
+            const serialized = JSON.stringify(opts.graph);
+            const updated = {
+                id: existing.id,
+                name: opts.name,
+                projectId: opts.projectId ?? existing.projectId,
+                thumbnailUrl: opts.thumbnailUrl ?? existing.thumbnailUrl,
+                version: existing.version + 1,
+                createdAt: existing.createdAt,
+                updatedAt: now,
+                ownerId: opts.ownerId ?? existing.ownerId,
+                sizeBytes: serialized.length,
+                nodeCount,
+                editorUrl: existing.editorUrl ?? `/editor/${existing.id}`,
+                url: existing.url ?? `/editor/${existing.id}`,
+                published: true,
+                graphHash: computeGraphHash(opts.graph),
+                graph: opts.graph,
+            };
+            this.data.set(existing.id, updated);
+            this.touchProject(existing.id, opts.name, updated.updatedAt);
+            return this.toMeta(updated);
+        }
+        if (opts.expectedVersion !== undefined) {
+            throw new SceneVersionConflictError('Cannot pass expectedVersion for a new scene');
+        }
+        const id = opts.id ?? `scene_${++this.idCounter}`;
+        const now = new Date().toISOString();
+        const serialized = JSON.stringify(opts.graph);
+        const nodeCount = Object.keys(opts.graph.nodes ?? {}).length;
+        const record = {
+            id,
+            name: opts.name,
+            projectId: opts.projectId ?? (this.projects.has(id) ? id : null),
+            thumbnailUrl: opts.thumbnailUrl ?? null,
+            version: 1,
+            createdAt: now,
+            updatedAt: now,
+            ownerId: opts.ownerId ?? null,
+            sizeBytes: serialized.length,
+            nodeCount,
+            editorUrl: `/editor/${id}`,
+            url: `/editor/${id}`,
+            published: true,
+            graphHash: computeGraphHash(opts.graph),
+            graph: opts.graph,
+        };
+        this.data.set(id, record);
+        this.touchProject(id, opts.name, now);
+        return this.toMeta(record);
+    }
+    async load(id) {
+        const rec = this.data.get(id);
+        if (!rec)
+            return null;
+        return {
+            ...rec,
+            graph: JSON.parse(JSON.stringify(rec.graph)),
+        };
+    }
+    async list(opts) {
+        let scenes = Array.from(this.data.values()).map((r) => this.toMeta(r));
+        if (opts?.projectId !== undefined) {
+            scenes = scenes.filter((s) => s.projectId === opts.projectId);
+        }
+        if (opts?.ownerId !== undefined) {
+            scenes = scenes.filter((s) => s.ownerId === opts.ownerId);
+        }
+        scenes.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
+        if (opts?.limit !== undefined)
+            scenes = scenes.slice(0, opts.limit);
+        return scenes;
+    }
+    async delete(id, opts) {
+        const rec = this.data.get(id);
+        if (!rec)
+            throw new SceneNotFoundError(`Scene ${id} not found`);
+        if (opts?.expectedVersion !== undefined && rec.version !== opts.expectedVersion) {
+            throw new SceneVersionConflictError(`Expected version ${opts.expectedVersion}, have ${rec.version}`);
+        }
+        return this.data.delete(id);
+    }
+    async rename(id, newName, opts) {
+        const rec = this.data.get(id);
+        if (!rec)
+            throw new SceneNotFoundError(`Scene ${id} not found`);
+        if (opts?.expectedVersion !== undefined && rec.version !== opts.expectedVersion) {
+            throw new SceneVersionConflictError(`Expected version ${opts.expectedVersion}, have ${rec.version}`);
+        }
+        const updated = {
+            ...rec,
+            name: newName,
+            version: rec.version + 1,
+            updatedAt: new Date().toISOString(),
+        };
+        this.data.set(id, updated);
+        this.touchProject(id, newName, updated.updatedAt);
+        return this.toMeta(updated);
+    }
+    touchProject(id, name, updatedAt) {
+        const existing = this.projects.get(id);
+        if (existing) {
+            this.projects.set(id, { ...existing, name, updatedAt });
+            return;
+        }
+        this.projects.set(id, {
+            id,
+            name,
+            ownerId: null,
+            isPrivate: true,
+            thumbnailUrl: null,
+            createdAt: updatedAt,
+            updatedAt,
+        });
+    }
+    toMeta(rec) {
+        const editorUrl = editorUrlFor(rec);
+        return {
+            id: rec.id,
+            name: rec.name,
+            projectId: rec.projectId,
+            thumbnailUrl: rec.thumbnailUrl,
+            version: rec.version,
+            createdAt: rec.createdAt,
+            updatedAt: rec.updatedAt,
+            ownerId: rec.ownerId,
+            sizeBytes: rec.sizeBytes,
+            nodeCount: rec.nodeCount,
+            editorUrl,
+            url: editorUrl,
+            published: rec.published ?? true,
+            graphHash: rec.graphHash ?? computeGraphHash(rec.graph),
+        };
+    }
+    toProjectStatus(id) {
+        const project = this.projects.get(id);
+        const scene = this.data.get(id);
+        const now = new Date().toISOString();
+        const editorUrl = `/editor/${id}`;
+        return {
+            id,
+            projectId: id,
+            name: scene?.name ?? project?.name ?? id,
+            editorUrl,
+            url: editorUrl,
+            ownerId: scene?.ownerId ?? project?.ownerId ?? null,
+            thumbnailUrl: scene?.thumbnailUrl ?? project?.thumbnailUrl ?? null,
+            publishedVersion: scene?.version ?? null,
+            latestVersion: scene?.version ?? null,
+            draftVersion: null,
+            browserVisibleVersion: scene?.version ?? null,
+            version: scene?.version ?? 0,
+            isEmpty: !scene || scene.nodeCount === 0,
+            sizeBytes: scene?.sizeBytes ?? 0,
+            nodeCount: scene?.nodeCount ?? 0,
+            graphHash: scene?.graphHash ?? (scene ? computeGraphHash(scene.graph) : null),
+            createdAt: scene?.createdAt ?? project?.createdAt ?? now,
+            updatedAt: scene?.updatedAt ?? project?.updatedAt ?? now,
+        };
+    }
+}

package/dist/tools/scene-query.d.ts

@@ -0,0 +1,57 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { SceneOperations } from '../operations';
+export declare const levelScopedInput: {
+    levelId: z.ZodOptional<z.ZodString>;
+};
+export declare const listLevelsOutput: {
+    activeSceneId: z.ZodNullable<z.ZodString>;
+    levelCount: z.ZodNumber;
+    occupiedStoryCount: z.ZodNumber;
+    supportLevelCount: z.ZodNumber;
+    roofLevelIds: z.ZodArray<z.ZodString>;
+    levels: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+};
+export declare const getLevelSummaryOutput: {
+    levelId: z.ZodString;
+    levelName: z.ZodOptional<z.ZodString>;
+    role: z.ZodString;
+    metadataRole: z.ZodNullable<z.ZodString>;
+    isOccupiedStory: z.ZodBoolean;
+    isSupportLevel: z.ZodBoolean;
+    referenceLevelId: z.ZodNullable<z.ZodString>;
+    counts: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    walls: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    zones: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    items: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    slabs: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    ceilings: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+};
+export declare const getWallsOutput: {
+    levelId: z.ZodString;
+    walls: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+};
+export declare const getZonesOutput: {
+    levelId: z.ZodString;
+    zones: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+};
+export declare const verifySceneOutput: {
+    ok: z.ZodBoolean;
+    valid: z.ZodBoolean;
+    levelCount: z.ZodNumber;
+    occupiedStoryCount: z.ZodNumber;
+    supportLevelCount: z.ZodNumber;
+    roofLevelIds: z.ZodArray<z.ZodString>;
+    activeSceneId: z.ZodNullable<z.ZodString>;
+    levels: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    emptyLevelIds: z.ZodArray<z.ZodString>;
+    issues: z.ZodArray<z.ZodString>;
+    hasIssues: z.ZodBoolean;
+};
+export declare function registerListLevels(server: McpServer, bridge: SceneOperations): void;
+export declare function registerGetLevelSummary(server: McpServer, bridge: SceneOperations): void;
+export declare function registerGetWalls(server: McpServer, bridge: SceneOperations): void;
+export declare function registerGetZones(server: McpServer, bridge: SceneOperations): void;
+export declare function registerVerifyScene(server: McpServer, bridge: SceneOperations): void;
+export declare function registerSceneQueryTools(server: McpServer, bridge: SceneOperations): void;
+//# sourceMappingURL=scene-query.d.ts.map

package/dist/tools/scene-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-query.d.ts","sourceRoot":"","sources":["../../src/tools/scene-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAWpD,eAAO,MAAM,gBAAgB;;CAE5B,CAAA;AAID,eAAO,MAAM,gBAAgB;;;;;;;CAO5B,CAAA;AAED,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;CAcjC,CAAA;AAED,eAAO,MAAM,cAAc;;;CAG1B,CAAA;AAED,eAAO,MAAM,cAAc;;;CAG1B,CAAA;AAED,eAAO,MAAM,iBAAiB;;;;;;;;;;;;CAY7B,CAAA;AA2YD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAyCnF;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAgBxF;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAmBjF;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAmBjF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAkQpF;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAMxF"}