@plitzi/sdk-server 0.32.4 → 0.32.6

package/dist/modules/mcp/resources/schema.js

@@ -0,0 +1,43 @@
+import { buildDataSourceCatalog, buildInteractionCatalog } from "../catalogs/observed.js";
+import { findElementByRef, findPageByRef } from "../helpers/space.js";
+import { afterPrefix, dataSourcesUri, elementUri, folderUri, foldersUri, interactionsUri, pageUri, pagesUri, schemaVarsUri, settingsUri } from "../helpers/uris.js";
+import { envelope } from "./envelope.js";
+import { elementView, folderRefToAI, foldersToAI, pageSkeletonToAI, pageStylesToAI, pageSummariesToAI, schemaVariablesToAI, settingsToAI } from "../tools/operations/schema/translator.js";
+//#region src/modules/mcp/resources/schema.ts
+/** Element-schema reads: page listings/skeletons/styles, folders, single elements and schema variables. Returns
+*  undefined when the URI belongs to another domain, null when the shape is ours but the ref does not resolve. */
+var readSchemaResource = (space, env, uri) => {
+	if (uri === pagesUri(env)) return envelope(pageSummariesToAI(space.schema));
+	if (uri === foldersUri(env)) return envelope(foldersToAI(space.schema));
+	const folderRef = afterPrefix(uri, folderUri(env, ""));
+	if (folderRef !== void 0) {
+		const folder = folderRefToAI(space.schema, folderRef);
+		return folder ? envelope(folder) : null;
+	}
+	const pageItem = afterPrefix(uri, pageUri(env, ""));
+	if (pageItem !== void 0) {
+		if (pageItem.endsWith("/styles")) {
+			const ref = pageItem.slice(0, -7);
+			const page = findPageByRef(space.schema, ref);
+			return page ? envelope(pageStylesToAI(space.schema, space.style, page)) : null;
+		}
+		const page = findPageByRef(space.schema, pageItem);
+		return page ? envelope(pageSkeletonToAI(space.schema, page, space.style)) : null;
+	}
+	const elementRef = afterPrefix(uri, elementUri(env, ""));
+	if (elementRef !== void 0) {
+		const el = findElementByRef(space.schema, elementRef);
+		if (!el) return null;
+		const view = elementView(space.schema, el, space.style);
+		return {
+			stateVersion: view.version,
+			data: view.detail
+		};
+	}
+	if (uri === schemaVarsUri(env)) return envelope(schemaVariablesToAI(space.schema));
+	if (uri === settingsUri(env)) return envelope(settingsToAI(space.schema));
+	if (uri === interactionsUri(env)) return envelope(buildInteractionCatalog(space.schema));
+	if (uri === dataSourcesUri(env)) return envelope(buildDataSourceCatalog(space.schema));
+};
+//#endregion
+export { readSchemaResource };

package/dist/modules/mcp/resources/style.js

@@ -0,0 +1,34 @@
+import { afterPrefix, defUri, defsUri, globalUri, globalsUri, idUri, idsUri, styleVarUri, styleVarsUri } from "../helpers/uris.js";
+import { envelope } from "./envelope.js";
+import { definitionRefs, definitionToAI, globalStyleToAI, globalStyleTypes, idStyleIds, idStyleToAI, styleVariablesToAI } from "../tools/operations/style/translator.js";
+//#region src/modules/mcp/resources/style.ts
+/** Style-schema reads: definitions, global (per-type) styles and design-token variables by category. Returns
+*  undefined when the URI belongs to another domain, null when the shape is ours but the ref does not resolve. */
+var readStyleResource = (space, env, uri) => {
+	if (uri === defsUri(env)) return envelope(definitionRefs(space.style));
+	const defRef = afterPrefix(uri, defUri(env, ""));
+	if (defRef !== void 0) {
+		const def = definitionToAI(space.style, defRef);
+		return def ? envelope(def) : null;
+	}
+	if (uri === globalsUri(env)) return envelope(globalStyleTypes(space.style));
+	const componentType = afterPrefix(uri, globalUri(env, ""));
+	if (componentType !== void 0) {
+		const global = globalStyleToAI(space.style, componentType);
+		return global ? envelope(global) : null;
+	}
+	if (uri === idsUri(env)) return envelope(idStyleIds(space.style));
+	const targetId = afterPrefix(uri, idUri(env, ""));
+	if (targetId !== void 0) {
+		const idStyle = idStyleToAI(space.style, targetId);
+		return idStyle ? envelope(idStyle) : null;
+	}
+	if (uri === styleVarsUri(env)) return envelope(styleVariablesToAI(space.style));
+	const category = afterPrefix(uri, styleVarUri(env, ""));
+	if (category !== void 0) {
+		const byCategory = styleVariablesToAI(space.style);
+		return envelope(Object.hasOwn(byCategory, category) ? byCategory[category] : []);
+	}
+};
+//#endregion
+export { readStyleResource };

package/dist/modules/mcp/screenshotClient.js

@@ -0,0 +1,47 @@
+import { PREVIEW_TOKEN_PARAM } from "./constants.js";
+//#region src/modules/mcp/screenshotClient.ts
+var composeUrl = (base, pagePath, token) => {
+	const url = new URL(pagePath, base);
+	if (token) url.searchParams.set(PREVIEW_TOKEN_PARAM, token);
+	return url.toString();
+};
+/** Default `ScreenshotClient`: composes the navigable preview URL (renderBaseUrl + pagePath + `?__pt=token`) and
+*  POSTs it to the browser service. Any network/HTTP failure surfaces as `ok:false` so the tool can fall back to
+*  the HTML preview instead of hard-failing. */
+var createHttpScreenshotClient = ({ serviceUrl, renderBaseUrl, fetchImpl = fetch }) => ({ async capture({ pagePath, token, viewports }) {
+	const url = composeUrl(renderBaseUrl, pagePath, token);
+	let res;
+	try {
+		res = await fetchImpl(serviceUrl, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				url,
+				viewports
+			})
+		});
+	} catch (err) {
+		return {
+			ok: false,
+			error: "SCREENSHOT_UNREACHABLE",
+			message: `Browser service unreachable: ${String(err)}`
+		};
+	}
+	if (!res.ok) return {
+		ok: false,
+		error: "SCREENSHOT_FAILED",
+		message: `Browser service returned ${res.status}.`
+	};
+	const body = await res.json();
+	if (!body.images || body.images.length === 0) return {
+		ok: false,
+		error: "SCREENSHOT_EMPTY",
+		message: "Browser service returned no images."
+	};
+	return {
+		ok: true,
+		images: body.images
+	};
+} });
+//#endregion
+export { createHttpScreenshotClient };

package/dist/modules/mcp/server.js

@@ -1,29 +1,75 @@
-import { bindTools } from "./helpers.js";
-import { registerResources } from "./resources/index.js";
-import { tools_exports } from "./tools/index.js";
-import package_default from "../../package.js";
+import { emptySpaceMessage, unauthorizedSpaceMessage } from "./helpers/space.js";
+import { serverInstructions } from "./helpers/guide.js";
+import { createMcpLog } from "./helpers/log.js";
+import { registerResources } from "./resources/register.js";
+import { tools } from "./tools/index.js";
+import { isCallToolResult } from "../ai/toolkit.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
 //#region src/modules/mcp/server.ts
-var createMcpServer = (adapters = {}, engine, tools, prompts, resources) => {
-	const boundTools = bindTools([...Object.values(tools_exports), ...tools ?? []], adapters);
+var MCP_ENV = "main";
+var asText = (data) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(data)
+}] });
+var createMcpServer = ({ adapters, getSpaceId, preview, screenshot, logger }) => {
+	const log = createMcpLog(logger);
+	let spaceIdPromise;
+	const requireSpaceId = () => spaceIdPromise ??= getSpaceId().then((id) => {
+		if (!id) throw new Error(unauthorizedSpaceMessage);
+		return id;
+	});
+	const loadSpace = async () => {
+		const spaceId = await requireSpaceId();
+		const [schema, style, catalog] = await Promise.all([
+			adapters.getSchema?.(spaceId, MCP_ENV),
+			adapters.getStyle?.(spaceId, MCP_ENV),
+			adapters.getComponentCatalog?.(spaceId, MCP_ENV).catch(() => void 0)
+		]);
+		if (!schema || !style) throw new Error(emptySpaceMessage);
+		return {
+			schema,
+			style,
+			catalog
+		};
+	};
+	const { saveSchema, saveStyle } = adapters;
+	const persisters = {
+		schema: saveSchema ? async (schema) => saveSchema(await requireSpaceId(), MCP_ENV, schema) : void 0,
+		style: saveStyle ? async (style) => saveStyle(await requireSpaceId(), MCP_ENV, style) : void 0
+	};
+	let spacePromise;
+	const getSpace = () => spacePromise ??= loadSpace();
 	const server = new McpServer({
 		name: "plitzi-mcp",
-		version: package_default.version
+		version: "0.32.6"
+	}, { instructions: serverInstructions });
+	registerResources(server, getSpace, MCP_ENV, log);
+	const toolContext = async () => ({
+		space: await getSpace(),
+		env: MCP_ENV,
+		persisters,
+		spaceId: await requireSpaceId(),
+		preview,
+		screenshot
 	});
-	engine.setToolsAvailables(boundTools);
-	registerResources(server, resources, engine.readResource);
-	for (const tool of boundTools) {
-		if (!engine.can(tool.name)) continue;
-		const { title, description, inputSchema, annotations } = tool.mcpDefinition;
-		const definition = {
-			title,
-			description,
-			inputSchema,
-			annotations
-		};
-		server.registerTool(tool.name, definition, engine.execute(tool.name, tool.handler));
+	for (const tool of tools) {
+		if (tool.requires === "screenshot" && !screenshot) continue;
+		server.registerTool(tool.name, {
+			title: tool.title,
+			description: tool.description,
+			inputSchema: tool.inputShape
+		}, async (args) => {
+			const start = performance.now();
+			try {
+				const result = await tool.execute(args, await toolContext());
+				log.toolCall(tool.name, args, performance.now() - start);
+				return isCallToolResult(result) ? result : asText(result);
+			} catch (error) {
+				log.toolCall(tool.name, args, performance.now() - start, error);
+				throw error;
+			}
+		});
 	}
-	if (prompts) for (const prompt of prompts) server.registerPrompt(prompt.name, prompt.definition, engine.executePrompt(prompt.name, prompt.handler));
 	return server;
 };
 //#endregion

package/dist/modules/mcp/tools/apply/dispatch.js

@@ -0,0 +1,103 @@
+import { fail } from "../../helpers/opResult.js";
+import { deleteBinding } from "../operations/schema/bindings/deleteBinding.js";
+import { patchBinding } from "../operations/schema/bindings/patchBinding.js";
+import { upsertBinding } from "../operations/schema/bindings/upsertBinding.js";
+import { deleteElement } from "../operations/schema/elements/deleteElement.js";
+import { moveElement } from "../operations/schema/elements/moveElement.js";
+import { patchElement } from "../operations/schema/elements/patchElement.js";
+import { upsertElement } from "../operations/schema/elements/upsertElement.js";
+import { deleteFolder } from "../operations/schema/folders/deleteFolder.js";
+import { upsertFolder } from "../operations/schema/folders/upsertFolder.js";
+import { deleteInteraction } from "../operations/schema/interactions/deleteInteraction.js";
+import { patchInteractionNode } from "../operations/schema/interactions/patchInteractionNode.js";
+import { upsertInteractionFlow } from "../operations/schema/interactions/upsertInteractionFlow.js";
+import { deletePage } from "../operations/schema/pages/deletePage.js";
+import { upsertPage } from "../operations/schema/pages/upsertPage.js";
+import { patchSettings } from "../operations/schema/settings/patchSettings.js";
+import { deleteVariable } from "../operations/schema/variables/deleteVariable.js";
+import { upsertVariable } from "../operations/schema/variables/upsertVariable.js";
+import { deleteDefinition } from "../operations/style/definitions/deleteDefinition.js";
+import { patchDefinition } from "../operations/style/definitions/patchDefinition.js";
+import { upsertDefinition } from "../operations/style/definitions/upsertDefinition.js";
+import { deleteGlobalStyle } from "../operations/style/globalStyles/deleteGlobalStyle.js";
+import { patchGlobalStyle } from "../operations/style/globalStyles/patchGlobalStyle.js";
+import { upsertGlobalStyle } from "../operations/style/globalStyles/upsertGlobalStyle.js";
+import { deleteIdStyle } from "../operations/style/idStyles/deleteIdStyle.js";
+import { patchIdStyle } from "../operations/style/idStyles/patchIdStyle.js";
+import { upsertIdStyle } from "../operations/style/idStyles/upsertIdStyle.js";
+import { deleteStyleVariable } from "../operations/style/variables/deleteStyleVariable.js";
+import { upsertStyleVariable } from "../operations/style/variables/upsertStyleVariable.js";
+import { isStyleOp } from "../operations/index.js";
+//#region src/modules/mcp/tools/apply/dispatch.ts
+var executeOp = (space, env, op) => {
+	switch (op.type) {
+		case "upsertElement": return upsertElement(space, env, op);
+		case "patchElement": return patchElement(space, env, op);
+		case "deleteElement": return deleteElement(space, env, op);
+		case "moveElement": return moveElement(space, env, op);
+		case "upsertPage": return upsertPage(space, env, op);
+		case "deletePage": return deletePage(space, env, op);
+		case "upsertFolder": return upsertFolder(space, env, op);
+		case "deleteFolder": return deleteFolder(space, env, op);
+		case "upsertVariable": return upsertVariable(space, env, op);
+		case "deleteVariable": return deleteVariable(space, env, op);
+		case "upsertBinding": return upsertBinding(space, env, op);
+		case "patchBinding": return patchBinding(space, env, op);
+		case "deleteBinding": return deleteBinding(space, env, op);
+		case "upsertInteractionFlow": return upsertInteractionFlow(space, env, op);
+		case "patchInteractionNode": return patchInteractionNode(space, env, op);
+		case "deleteInteraction": return deleteInteraction(space, env, op);
+		case "patchSettings": return patchSettings(space, env, op);
+		case "upsertDefinition": return upsertDefinition(space, env, op);
+		case "patchDefinition": return patchDefinition(space, env, op);
+		case "deleteDefinition": return deleteDefinition(space, env, op);
+		case "upsertGlobalStyle": return upsertGlobalStyle(space, env, op);
+		case "patchGlobalStyle": return patchGlobalStyle(space, env, op);
+		case "deleteGlobalStyle": return deleteGlobalStyle(space, env, op);
+		case "upsertIdStyle": return upsertIdStyle(space, env, op);
+		case "patchIdStyle": return patchIdStyle(space, env, op);
+		case "deleteIdStyle": return deleteIdStyle(space, env, op);
+		case "upsertStyleVariable": return upsertStyleVariable(space, env, op);
+		case "deleteStyleVariable": return deleteStyleVariable(space, env, op);
+		default: return fail("type", `Unknown operation "${op.type}"`, "See the Operation union");
+	}
+};
+/** Apply operations in order to the space (mutating it). Records which schema(s) changed so the caller can
+*  persist each independently. Stops collecting counts for a failed op but records its errors. */
+var applyOperations = (space, env, ops) => {
+	const outcome = {
+		created: 0,
+		updated: 0,
+		deleted: 0,
+		staleResources: [],
+		elementRefs: [],
+		errors: [],
+		changedSchema: false,
+		changedStyle: false
+	};
+	const stale = /* @__PURE__ */ new Set();
+	const elements = /* @__PURE__ */ new Set();
+	for (let i = 0; i < ops.length; i++) {
+		const op = ops[i];
+		const result = executeOp(space, env, op);
+		if (result.errors) {
+			outcome.errors.push(...result.errors.map((e) => ({
+				...e,
+				path: `operations[${i}].${e.path}`
+			})));
+			continue;
+		}
+		if (isStyleOp(op.type)) outcome.changedStyle = true;
+		else outcome.changedSchema = true;
+		outcome.created += result.created;
+		outcome.updated += result.updated;
+		outcome.deleted += result.deleted;
+		for (const uri of result.staleResources) stale.add(uri);
+		for (const ref of result.elementRefs ?? []) elements.add(ref);
+	}
+	outcome.staleResources = Array.from(stale);
+	outcome.elementRefs = Array.from(elements);
+	return outcome;
+};
+//#endregion
+export { applyOperations };

package/dist/modules/mcp/tools/apply/index.js

@@ -0,0 +1,136 @@
+import { cloneSpace } from "../../helpers/space.js";
+import { environment, operations } from "../operations/index.js";
+import { applyOperations } from "./dispatch.js";
+import { changedResources, conflictMessage, detectConflicts, resolvedElements } from "./writeResult.js";
+import { defineTool } from "../shared/tool.js";
+import { validateOperations } from "../shared/validator/index.js";
+import { auditResources } from "../shared/validator/audit.js";
+import { z } from "zod";
+import { validateSchema } from "@plitzi/sdk-schema";
+//#region src/modules/mcp/tools/apply/index.ts
+var applyShape = {
+	environment,
+	dryRun: z.boolean().optional().describe("Validate and apply in memory only, WITHOUT persisting. Returns the same result (changed versions + full element detail) so you can inspect the outcome and decide on more changes before committing for real."),
+	expectedResourceVersions: z.record(z.string(), z.string()).optional().describe("Resource URI → the stateVersion you read; guards against concurrent edits"),
+	operations
+};
+var noWarnings = (warnings) => warnings.length > 0 ? warnings : void 0;
+var schemaErrorToValidation = (error) => ({
+	path: error.elementId ? `schema.${error.elementId}` : "schema",
+	message: error.message,
+	hint: "This batch would leave the schema inconsistent (broken parent/child link or a cycle); nothing was applied."
+});
+var apply = async (input, space, persisters) => {
+	const env = input.environment ?? "main";
+	const validation = validateOperations(space, input.operations);
+	if (!validation.valid) return {
+		applied: false,
+		persisted: false,
+		summary: {
+			created: 0,
+			updated: 0,
+			deleted: 0
+		},
+		changed: [],
+		errors: validation.errors,
+		warnings: noWarnings(validation.warnings)
+	};
+	const conflicts = detectConflicts(space, env, input.expectedResourceVersions);
+	if (conflicts.length > 0) return {
+		applied: false,
+		persisted: false,
+		summary: {
+			created: 0,
+			updated: 0,
+			deleted: 0
+		},
+		changed: [],
+		conflict: {
+			message: conflictMessage,
+			conflicts
+		}
+	};
+	const draft = cloneSpace(space);
+	const outcome = applyOperations(draft, env, input.operations);
+	if (outcome.errors.length > 0) return {
+		applied: false,
+		persisted: false,
+		summary: {
+			created: 0,
+			updated: 0,
+			deleted: 0
+		},
+		changed: [],
+		errors: outcome.errors,
+		warnings: noWarnings(validation.warnings)
+	};
+	const integrity = validateSchema(draft.schema);
+	if (!integrity.valid) return {
+		applied: false,
+		persisted: false,
+		summary: {
+			created: 0,
+			updated: 0,
+			deleted: 0
+		},
+		changed: [],
+		errors: integrity.errors.map(schemaErrorToValidation),
+		warnings: noWarnings(validation.warnings)
+	};
+	const audit = auditResources(draft, input.operations);
+	const warnings = [...validation.warnings, ...audit.warnings];
+	if (audit.errors.length > 0) return {
+		applied: false,
+		persisted: false,
+		summary: {
+			created: 0,
+			updated: 0,
+			deleted: 0
+		},
+		changed: [],
+		errors: audit.errors,
+		warnings: noWarnings(warnings)
+	};
+	if (input.dryRun) return {
+		applied: false,
+		dryRun: true,
+		summary: {
+			created: outcome.created,
+			updated: outcome.updated,
+			deleted: outcome.deleted
+		},
+		changed: changedResources(draft, env, outcome.staleResources),
+		elements: resolvedElements(draft, env, outcome.elementRefs),
+		warnings: noWarnings(warnings)
+	};
+	let persisted = true;
+	if (outcome.changedSchema) if (persisters?.schema) await persisters.schema(draft.schema);
+	else persisted = false;
+	if (outcome.changedStyle) if (persisters?.style) await persisters.style(draft.style);
+	else persisted = false;
+	return {
+		applied: true,
+		persisted,
+		summary: {
+			created: outcome.created,
+			updated: outcome.updated,
+			deleted: outcome.deleted
+		},
+		changed: changedResources(draft, env, outcome.staleResources),
+		elements: resolvedElements(draft, env, outcome.elementRefs),
+		warnings: noWarnings(warnings)
+	};
+};
+var applyTool = defineTool({
+	name: "plitzi_apply",
+	title: "Apply",
+	description: "Validate, apply and persist a batch of operations atomically. Returns the changed resources and their new versions, plus the full detail of every element it created or updated. Pass dryRun to apply in memory only (inspect the outcome without committing). Rejects the whole batch on any error or version conflict — INCLUDING a pre-existing malformation in any resource the batch touches (fix it in the same batch to unblock the save).",
+	inputShape: applyShape,
+	access: "write",
+	run: (input, ctx) => apply({
+		...input,
+		environment: ctx.env
+	}, ctx.space, ctx.persisters)
+});
+//#endregion
+export { apply, applyShape, applyTool };

package/dist/modules/mcp/tools/apply/writeResult.js

@@ -0,0 +1,37 @@
+import { elementUri } from "../../helpers/uris.js";
+import { readResource, resourceVersion } from "../../resources/router.js";
+//#region src/modules/mcp/tools/apply/writeResult.ts
+var detectConflicts = (space, env, expected) => {
+	if (!expected) return [];
+	const conflicts = [];
+	for (const [uri, version] of Object.entries(expected)) {
+		const current = resourceVersion(space, env, uri);
+		if (current !== null && current !== version) conflicts.push({
+			resourceUri: uri,
+			expectedVersion: version,
+			currentVersion: current
+		});
+	}
+	return conflicts;
+};
+var changedResources = (space, env, uris) => uris.map((uri) => ({
+	uri,
+	stateVersion: resourceVersion(space, env, uri) ?? ""
+}));
+/** Full detail of each created/updated element (by ref), skipping any that no longer resolve (e.g. deleted later
+*  in the same batch). Returns undefined when there is nothing, so the field stays off the response. */
+var resolvedElements = (space, env, refs) => {
+	const elements = refs.map((ref) => {
+		const uri = elementUri(env, ref);
+		const res = readResource(space, env, uri);
+		return res ? {
+			uri,
+			stateVersion: res.stateVersion,
+			...res.data
+		} : void 0;
+	}).filter((el) => el !== void 0);
+	return elements.length > 0 ? elements : void 0;
+};
+var conflictMessage = "Cannot apply: your data is stale. Re-read the changed resources and retry.";
+//#endregion
+export { changedResources, conflictMessage, detectConflicts, resolvedElements };