@plitzi/sdk-server 0.32.4 → 0.32.5

package/dist/src/modules/mcp/tools/shared/tool.d.ts

@@ -0,0 +1,50 @@
+import { z, ZodObject, ZodRawShape } from 'zod';
+import { Space } from '../../helpers';
+import { PreviewClient, ScreenshotClient, ScreenshotImage, Env, Persisters } from '../../types';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/** Everything a tool needs at call time: the loaded space, the target environment, and the persisters (only the
+ *  write tools use them). Built by whoever hosts the tools — the standalone MCP server or the in-process AI
+ *  engine — so a tool's behavior never touches spaceId resolution or adapters directly. `spaceId`, `preview` and
+ *  `screenshot` are present only when the host wired them (the visual-preview tools need them). */
+export interface ToolContext {
+    space: Space;
+    env: Env;
+    persisters: Persisters;
+    spaceId?: number;
+    preview?: PreviewClient;
+    screenshot?: ScreenshotClient;
+}
+/** A capability a tool depends on; the host skips registering a tool whose capability it did not wire (so
+ *  plitzi_screenshot simply does not appear when no browser service is configured). */
+export type ToolRequires = 'screenshot';
+/** Build the MCP CallToolResult for an image-returning tool: a text meta block followed by one image block per
+ *  PNG, so a vision-capable agent (or MCP client) sees the render directly. */
+export declare const imageResult: (images: ScreenshotImage[], meta: unknown) => CallToolResult;
+/** What a tool author writes: identity, the input schema that is the contract sent to the agent, and a typed
+ *  `run` (its args are inferred from `inputShape`, so no cast). `access` marks whether it persists — a 'write'
+ *  tool previews (dryRun) in plan mode and can persist in build mode; a 'read' tool never writes. */
+export interface ToolSpec<Shape extends ZodRawShape> {
+    name: string;
+    title: string;
+    description: string;
+    inputShape: Shape;
+    access: 'read' | 'write';
+    /** A host capability this tool needs; hosts that did not wire it skip registering the tool. */
+    requires?: ToolRequires;
+    run: (input: z.infer<ZodObject<Shape>>, ctx: ToolContext) => unknown;
+}
+/** What the registry holds and the hosts register from: the same metadata plus a type-erased `execute` that
+ *  validates raw args against the shape and delegates to the typed `run`. Produced by `defineTool`. */
+export interface ToolDef {
+    name: string;
+    title: string;
+    description: string;
+    inputShape: ZodRawShape;
+    access: 'read' | 'write';
+    requires?: ToolRequires;
+    execute: (args: unknown, ctx: ToolContext) => unknown;
+}
+/** Author a tool: give it its metadata, its input shape and a typed `run`. The returned descriptor parses the
+ *  raw args against the shape before handing them to `run`, so `run` is fully typed and no cast is needed.
+ *  Adding a tool is: call defineTool in its own file and append it to the `tools` registry. */
+export declare const defineTool: <Shape extends ZodRawShape>(spec: ToolSpec<Shape>) => ToolDef;

package/dist/src/modules/mcp/tools/shared/validator.d.ts

@@ -0,0 +1,4 @@
+import { Space } from '../../helpers';
+import { ValidationResult } from '../../types';
+import { Operation } from '../operations';
+export declare const validateOperations: (space: Space, ops: Operation[]) => ValidationResult;

package/dist/src/modules/mcp/tools/validate.d.ts

@@ -0,0 +1,228 @@
+import { Space } from '../helpers';
+import { ValidateInput, ValidationResult } from '../types';
+export declare const validateShape: {
+    environment: import('zod').ZodOptional<import('zod').ZodString>;
+    operations: import('zod').ZodArray<import('zod').ZodDiscriminatedUnion<[import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"upsertElement">;
+        pageRef: import('zod').ZodString;
+        element: import('zod').ZodType<import('./operations').ElementInput, unknown, import('zod/v4/core').$ZodTypeInternals<import('./operations').ElementInput, unknown>>;
+        parentRef: import('zod').ZodOptional<import('zod').ZodString>;
+        position: import('zod').ZodOptional<import('zod').ZodEnum<{
+            inside: "inside";
+            before: "before";
+            after: "after";
+        }>>;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"patchElement">;
+        pageRef: import('zod').ZodString;
+        ref: import('zod').ZodString;
+        label: import('zod').ZodOptional<import('zod').ZodString>;
+        subType: import('zod').ZodOptional<import('zod').ZodString>;
+        props: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnknown>>;
+        style: import('zod').ZodOptional<import('zod').ZodObject<{
+            base: import('zod').ZodOptional<import('zod').ZodArray<import('zod').ZodString>>;
+            slots: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodArray<import('zod').ZodString>>>;
+        }, import('zod/v4/core').$strip>>;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"deleteElement">;
+        pageRef: import('zod').ZodString;
+        ref: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"moveElement">;
+        pageRef: import('zod').ZodString;
+        ref: import('zod').ZodString;
+        toParentRef: import('zod').ZodString;
+        position: import('zod').ZodEnum<{
+            inside: "inside";
+            before: "before";
+            after: "after";
+        }>;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"upsertPage">;
+        ref: import('zod').ZodString;
+        label: import('zod').ZodOptional<import('zod').ZodString>;
+        slug: import('zod').ZodOptional<import('zod').ZodString>;
+        folder: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+        default: import('zod').ZodOptional<import('zod').ZodBoolean>;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"deletePage">;
+        ref: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"upsertFolder">;
+        ref: import('zod').ZodString;
+        name: import('zod').ZodOptional<import('zod').ZodString>;
+        slug: import('zod').ZodOptional<import('zod').ZodString>;
+        parentId: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"deleteFolder">;
+        ref: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"upsertVariable">;
+        name: import('zod').ZodString;
+        variableType: import('zod').ZodString;
+        value: import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodBoolean]>;
+        category: import('zod').ZodOptional<import('zod').ZodString>;
+        subValues: import('zod').ZodOptional<import('zod').ZodArray<import('zod').ZodObject<{
+            when: import('zod').ZodUnknown;
+            value: import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodBoolean]>;
+        }, import('zod/v4/core').$strip>>>;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"deleteVariable">;
+        name: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+        tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+        mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+        states: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+            desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+        }, import('zod/v4/core').$strip>>>;
+        variants: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+            desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+        }, import('zod/v4/core').$strip>>>;
+        slots: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+            desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            states: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+                desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+                tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+                mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            }, import('zod/v4/core').$strip>>>;
+            variants: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+                desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+                tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+                mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            }, import('zod/v4/core').$strip>>>;
+        }, import('zod/v4/core').$strip>>>;
+        type: import('zod').ZodLiteral<"upsertDefinition">;
+        ref: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+        tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+        mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+        states: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+            desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+        }, import('zod/v4/core').$strip>>>;
+        variants: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+            desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+        }, import('zod/v4/core').$strip>>>;
+        slots: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+            desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            states: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+                desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+                tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+                mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            }, import('zod/v4/core').$strip>>>;
+            variants: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+                desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+                tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+                mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            }, import('zod/v4/core').$strip>>>;
+        }, import('zod/v4/core').$strip>>>;
+        type: import('zod').ZodLiteral<"patchDefinition">;
+        ref: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"deleteDefinition">;
+        ref: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+        tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+        mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+        states: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+            desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+        }, import('zod/v4/core').$strip>>>;
+        variants: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+            desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+        }, import('zod/v4/core').$strip>>>;
+        slots: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+            desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            states: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+                desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+                tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+                mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            }, import('zod/v4/core').$strip>>>;
+            variants: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+                desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+                tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+                mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber]>>>;
+            }, import('zod/v4/core').$strip>>>;
+        }, import('zod/v4/core').$strip>>>;
+        type: import('zod').ZodLiteral<"upsertGlobalStyle">;
+        componentType: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+        tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+        mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+        states: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+            desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+        }, import('zod/v4/core').$strip>>>;
+        variants: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+            desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+        }, import('zod/v4/core').$strip>>>;
+        slots: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+            desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            states: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+                desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+                tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+                mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            }, import('zod/v4/core').$strip>>>;
+            variants: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodObject<{
+                desktop: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+                tablet: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+                mobile: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodNull]>>>;
+            }, import('zod/v4/core').$strip>>>;
+        }, import('zod/v4/core').$strip>>>;
+        type: import('zod').ZodLiteral<"patchGlobalStyle">;
+        componentType: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"deleteGlobalStyle">;
+        componentType: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"upsertStyleVariable">;
+        category: import('zod').ZodEnum<{
+            color: "color";
+            spacing: "spacing";
+            shadow: "shadow";
+            custom: "custom";
+        }>;
+        name: import('zod').ZodString;
+        value: import('zod').ZodUnion<readonly [import('zod').ZodString, import('zod').ZodNumber, import('zod').ZodObject<{
+            light: import('zod').ZodOptional<import('zod').ZodString>;
+            dark: import('zod').ZodOptional<import('zod').ZodString>;
+            default: import('zod').ZodOptional<import('zod').ZodString>;
+        }, import('zod/v4/core').$strip>]>;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"deleteStyleVariable">;
+        category: import('zod').ZodEnum<{
+            color: "color";
+            spacing: "spacing";
+            shadow: "shadow";
+            custom: "custom";
+        }>;
+        name: import('zod').ZodString;
+    }, import('zod/v4/core').$strip>], "type">>;
+};
+export declare const validate: (input: ValidateInput, space: Space) => ValidationResult;
+export declare const validateTool: import('.').ToolDef;

package/dist/src/modules/mcp/types/aiSchema.d.ts

@@ -0,0 +1,126 @@
+import { Environment } from '@plitzi/sdk-shared';
+export type Env = Environment;
+/** CSS declarations for one selector state. Keys are kebab-case CSS properties (see plitzi://css-properties). */
+export type CssProps = Record<string, string | number>;
+export interface DisplayModeCss {
+    desktop?: CssProps;
+    tablet?: CssProps;
+    mobile?: CssProps;
+}
+export interface ResourceEnvelope<T> {
+    stateVersion: string;
+    data: T;
+}
+/**
+ * Read projections follow a filesystem model: list cheap summaries/skeletons, then read one element's detail
+ * on demand. Heavy per-element data (props, style) lives only in AIElementDetail, never in the listings.
+ */
+export interface AIPageSummary {
+    ref: string;
+    label: string;
+    slug: string;
+    default: boolean;
+    /** The ref of the folder this page lives in (a PageFolder id), or undefined for a root-level page. */
+    folder?: string;
+    elementCount: number;
+}
+/** A page folder in the sidebar tree. `ref` is the folder's id (there is no separate aiRef); pages reference it
+ *  by that id via their `folder`, and nested folders via `parentId`. */
+export interface AIFolder {
+    ref: string;
+    name: string;
+    slug: string;
+    parentId?: string;
+}
+export interface AISkeletonNode {
+    ref: string;
+    type: string;
+    label: string;
+    subType?: string;
+    /** The class refs this node attaches on its base selector — names only, no CSS. Lets an agent map element →
+     *  class straight from the page skeleton, without a per-element read just to learn which class it uses. */
+    base?: string[];
+    /** Class refs attached on non-base slots (slot → class refs), names only. */
+    slots?: Record<string, string[]>;
+    childCount: number;
+    children?: AISkeletonNode[];
+}
+export interface AIPageSkeleton {
+    ref: string;
+    label: string;
+    slug: string;
+    default: boolean;
+    /** Route params bound by the slug (e.g. ":spaceId" → ["spaceId"]). Valid as {{name}} references on this page,
+     *  alongside the space-level plitzi://schema-variables. */
+    routeParams: string[];
+    tree: AISkeletonNode[];
+}
+/** Every style a page uses in one payload: the class definitions its elements attach (deduplicated, with CSS)
+ *  and the global element selectors that affect any element type present on the page. Collapses "what styles
+ *  does this page use" to a single read, with no reliance on a shared class-naming prefix. */
+export interface AIPageStyles {
+    ref: string;
+    definitions: AIDefinition[];
+    globalStyles: AIGlobalStyle[];
+}
+export interface AIElementDetail {
+    ref: string;
+    type: string;
+    subType?: string;
+    label: string;
+    pageRef: string;
+    parentRef?: string;
+    props?: Record<string, unknown>;
+    style: {
+        base: string[];
+        slots: Record<string, string[]>;
+    };
+    /** CSS of the definitions referenced by `style` (keyed by class ref), inlined so an edit needs no follow-up
+     *  read of each definition. Present only for refs that resolve to a definition. */
+    resolvedStyle?: Record<string, AIDefinition>;
+    /** Global (type 'element') styles that also affect this element because they target its type — every element of
+     *  the type inherits them. Read-only here (not editable as definitions); shown so the effective CSS is complete. */
+    globalStyles?: AIGlobalStyle[];
+    childRefs?: string[];
+}
+/** A global element style (a type 'element' StyleItem): its CSS applies to every element whose type equals
+ *  `appliesToType`. It is not an addressable class definition — editing it would change every such element. */
+export interface AIGlobalStyle extends AIDefinition {
+    appliesToType: string;
+}
+export interface AIDefinitionSlot extends DisplayModeCss {
+    states?: Record<string, DisplayModeCss>;
+    variants?: Record<string, DisplayModeCss>;
+}
+export interface AIDefinition extends AIDefinitionSlot {
+    ref: string;
+    slots?: Record<string, AIDefinitionSlot>;
+}
+export type StyleVariableCategory = 'color' | 'spacing' | 'shadow' | 'custom';
+export type StyleVariableValue = string | number | {
+    light?: string;
+    dark?: string;
+    default?: string;
+};
+export interface AIStyleVariable {
+    name: string;
+    reference: string;
+    value: StyleVariableValue;
+}
+export interface AISchemaVariable {
+    name: string;
+    reference: string;
+    category: string;
+    type: string;
+    value: string | number | boolean;
+    subValues?: Array<{
+        when: unknown;
+        value: string | number | boolean;
+    }>;
+}
+export interface ValidationError {
+    path: string;
+    message: string;
+    hint: string;
+    validValues?: unknown[];
+}

package/dist/src/modules/mcp/types/index.d.ts

@@ -0,0 +1,4 @@
+export type * from './aiSchema';
+export type * from './toolTypes';
+export type * from './previewTypes';
+export type * from './screenshotTypes';

package/dist/src/modules/mcp/types/previewTypes.d.ts

@@ -0,0 +1,25 @@
+import { ValidationError } from './aiSchema';
+import { Operation } from '../tools/operations';
+export type PreviewRequestBody = {
+    spaceId: number;
+    env?: string;
+    pageRef?: string;
+    operations?: Operation[];
+};
+export type PreviewResult = {
+    ok: true;
+    token?: string;
+    pagePath: string;
+    html: string;
+    stateVersion: string;
+} | {
+    ok: false;
+    error: string;
+    message: string;
+    errors?: ValidationError[];
+};
+/** How the MCP tools reach the renderer. The consumer injects an implementation (an HTTP client to the SSR
+ *  `/preview` endpoint, or an in-process call when co-located); absent means preview is not wired. */
+export type PreviewClient = {
+    render: (body: PreviewRequestBody) => Promise<PreviewResult>;
+};

package/dist/src/modules/mcp/types/screenshotTypes.d.ts

@@ -0,0 +1,29 @@
+export type Viewport = {
+    label: string;
+    width: number;
+    height: number;
+};
+export type ScreenshotImage = {
+    label: string;
+    mimeType: string;
+    data: string;
+};
+export type ScreenshotResult = {
+    ok: true;
+    images: ScreenshotImage[];
+} | {
+    ok: false;
+    error: string;
+    message: string;
+};
+export type ScreenshotInput = {
+    pagePath: string;
+    token?: string;
+    viewports: Viewport[];
+};
+/** How plitzi_screenshot reaches the headless-browser service. The consumer injects an implementation (an HTTP
+ *  client to the dedicated browser pod); absent → the tool is not registered. A capture that fails (pod down)
+ *  returns `ok:false` rather than throwing, so the tool can degrade to the HTML preview. */
+export type ScreenshotClient = {
+    capture: (input: ScreenshotInput) => Promise<ScreenshotResult>;
+};

package/dist/src/modules/mcp/types/toolTypes.d.ts

@@ -0,0 +1,138 @@
+import { AIDefinition, AIElementDetail, ValidationError } from './aiSchema';
+import { Operation } from '../tools/operations';
+import { Schema, Style } from '@plitzi/sdk-shared';
+/** The element schema and the style schema persist independently (Space model / Style model), so each has
+ *  its own optional persister. When one is absent, that schema is applied in memory but reported unsaved. */
+export interface Persisters {
+    schema?: (schema: Schema) => Promise<void>;
+    style?: (style: Style) => Promise<void>;
+}
+export interface Conflict {
+    resourceUri: string;
+    expectedVersion: string;
+    currentVersion: string;
+}
+export interface ChangedResource {
+    uri: string;
+    stateVersion: string;
+}
+/** Full detail of a created/updated element, plus its own uri and stateVersion so a follow-up edit of the same
+ *  element can guard with optimistic concurrency without an intermediate read. */
+export type WriteElement = AIElementDetail & {
+    uri: string;
+    stateVersion: string;
+};
+/** Write result: what changed and the new versions, plus the full detail of every element created/updated (with
+ *  its uri + stateVersion) so the caller has that context without a follow-up read. Other resources (pages,
+ *  definitions, variables) still report only uri+version — re-read them if needed. */
+export interface WriteResponse {
+    applied: boolean;
+    dryRun?: boolean;
+    persisted?: boolean;
+    summary: {
+        created: number;
+        updated: number;
+        deleted: number;
+    };
+    changed: ChangedResource[];
+    elements?: WriteElement[];
+    warnings?: string[];
+    errors?: ValidationError[];
+    conflict?: {
+        message: string;
+        conflicts: Conflict[];
+    };
+}
+/** The outcome of applying a batch to the space in memory: counts, which schema(s) changed (so the caller can
+ *  persist each independently), the invalidated resource URIs and the refs of the elements it created/updated. */
+export interface MutationOutcome {
+    created: number;
+    updated: number;
+    deleted: number;
+    staleResources: string[];
+    elementRefs: string[];
+    errors: ValidationError[];
+    changedSchema: boolean;
+    changedStyle: boolean;
+}
+export interface ApplyInput {
+    environment?: string;
+    dryRun?: boolean;
+    expectedResourceVersions?: Record<string, string>;
+    operations: Operation[];
+}
+export interface ValidateInput {
+    environment?: string;
+    operations: Operation[];
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: string[];
+}
+export interface SearchInput {
+    query: string;
+    filters?: {
+        type?: string;
+        pageRef?: string;
+    };
+    /** 'detail' inlines each hit's full props/style so an edit needs no follow-up read. */
+    include?: 'detail';
+    /** Max element hits to return in this page (default 50). */
+    limit?: number;
+    /** Element hits to skip before this page (default 0). */
+    offset?: number;
+}
+export interface SearchHit {
+    pageRef: string;
+    ref: string;
+    uri: string;
+    pageUri: string;
+    stateVersion: string;
+    parentRef?: string;
+    /** Ancestor labels from the page down to and including this element. */
+    path: string[];
+    label: string;
+    type: string;
+    matches: string[];
+    detail?: AIElementDetail;
+}
+export interface SearchPageHit {
+    ref: string;
+    uri: string;
+    stateVersion: string;
+    label: string;
+    slug: string;
+    matches: string[];
+}
+export interface SearchResponse {
+    results: SearchHit[];
+    /** Total element hits matching the query across all pages, before offset/limit. */
+    total: number;
+    /** Element hits skipped before this page (echoes the request's offset, defaulted). */
+    offset: number;
+    /** Page size applied to element hits (echoes the request's limit, defaulted). */
+    limit: number;
+    /** The offset to pass next to fetch the following page. Present only while more hits remain past this page. */
+    nextOffset?: number;
+    /** Style definitions whose ref matches the query, with their full CSS — so finding a class by name closes the
+     *  loop to its style without a separate read. Present only when at least one definition matches. */
+    definitions?: AIDefinition[];
+    /** Pages whose name or slug matches the query (element hits never include pages). Each carries the page uri +
+     *  stateVersion, ready to open or edit. Present only when at least one page matches. */
+    pages?: SearchPageHit[];
+}
+export interface ReadInput {
+    uris: string[];
+}
+export interface ReadHit {
+    uri: string;
+    stateVersion?: string;
+    data?: unknown;
+    error?: string;
+    message?: string;
+    hint?: string;
+}
+export interface ReadResponse {
+    results: ReadHit[];
+}

package/dist/src/modules/ssr/buildBody.d.ts

@@ -1,9 +1,9 @@
 import { TtlCache } from '../../helpers/cache';
 import { RequestMetrics } from '../../helpers/metrics';
 import { PluginManager } from '../../plugins/manager';
-import { Environment, SSRRenderResult, SSRRequest, SSRServerConfig, SSRTemplateFn } from '@plitzi/sdk-shared';
+import { Environment, OfflineDataRaw, SSRRenderResult, SSRRequest, SSRServerConfig, SSRTemplateFn } from '@plitzi/sdk-shared';
 export type BuildBodyResult = {
     body?: string;
     result: SSRRenderResult;
 };
-export declare const buildBody: (req: SSRRequest, config: SSRServerConfig, spaceId: number, environment: Environment, revision: number, renderFn: SSRTemplateFn, pluginManager: PluginManager, offlineDataCache?: TtlCache<string>, metrics?: RequestMetrics) => Promise<BuildBodyResult>;
+export declare const buildBody: (req: SSRRequest, config: SSRServerConfig, spaceId: number, environment: Environment, revision: number, renderFn: SSRTemplateFn, pluginManager: PluginManager, offlineDataCache?: TtlCache<string>, metrics?: RequestMetrics, offlineDataOverride?: OfflineDataRaw) => Promise<BuildBodyResult>;