@plitzi/sdk-mcp 0.37.9 → 0.37.10

package/dist/modules/mcp/tools/operations/schemaIds.js

@@ -1,6 +1,6 @@
 import { actionAccess, actionField, actionLimits, actionNode, actionTriggerParams } from "./actions/document.js";
 import { connectorConnection, readEndpoint, writeEndpoint } from "./connectors/manifest.js";
-import { bindingInput, elementInput, initialStateInput, interactionNode, position, ruleGroup, styleRefs, styleVariantInput } from "./schema/shared.js";
+import { bindingInput, elementAnchor, elementFlag, elementInput, initialStateInput, interactionNode, position, ruleGroup, styleRefs, styleVariantInput } from "./schema/shared.js";
 import { ancestors, ancestorsPatch, cssMap, cssPatchMap, definitionSlot, definitionSlotPatch, displayModeCss, displayModeCssPatch, themeValue } from "./style/shared.js";
 import { z } from "zod";
 //#region src/modules/mcp/tools/operations/schemaIds.ts
@@ -23,6 +23,8 @@ import { z } from "zod";
 *  the co-worker's own tool-schema converter alike. */
 var SHARED_SCHEMAS = [
 	[elementInput, "Element"],
+	[elementFlag, "ElementFlag"],
+	[elementAnchor, "ElementAnchor"],
 	[ruleGroup, "RuleGroup"],
 	[styleRefs, "StyleRefs"],
 	[initialStateInput, "InitialState"],

package/dist/modules/mcp/tools/preview.d.ts

@@ -50,6 +50,8 @@ export declare const previewShape: {
             client: "client";
             shared: "shared";
         }>>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteElement">;
         pageRef: z.ZodString;
@@ -74,6 +76,7 @@ export declare const previewShape: {
         layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         enabled: z.ZodOptional<z.ZodBoolean>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deletePage">;
         ref: z.ZodString;
@@ -118,6 +121,18 @@ export declare const previewShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteVariable">;
         name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"upsertFlag">;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        value: z.ZodBoolean;
+        rules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            when: z.ZodType<import('@plitzi/sdk-shared').RuleGroup, unknown, z.core.$ZodTypeInternals<import('@plitzi/sdk-shared').RuleGroup, unknown>>;
+            value: z.ZodBoolean;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"deleteFlag">;
+        name: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"upsertBinding">;
         pageRef: z.ZodString;
@@ -221,6 +236,7 @@ export declare const previewShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"patchSettings">;
         customCss: z.ZodOptional<z.ZodString>;
+        notifications: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>;
         keepState: z.ZodOptional<z.ZodBoolean>;
         stateStorage: z.ZodOptional<z.ZodEnum<{
             localStorage: "localStorage";

package/dist/modules/mcp/tools/render.d.ts

@@ -52,6 +52,8 @@ export declare const renderShape: {
             client: "client";
             shared: "shared";
         }>>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteElement">;
         pageRef: z.ZodString;
@@ -76,6 +78,7 @@ export declare const renderShape: {
         layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         enabled: z.ZodOptional<z.ZodBoolean>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deletePage">;
         ref: z.ZodString;
@@ -120,6 +123,18 @@ export declare const renderShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteVariable">;
         name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"upsertFlag">;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        value: z.ZodBoolean;
+        rules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            when: z.ZodType<import('@plitzi/sdk-shared').RuleGroup, unknown, z.core.$ZodTypeInternals<import('@plitzi/sdk-shared').RuleGroup, unknown>>;
+            value: z.ZodBoolean;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"deleteFlag">;
+        name: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"upsertBinding">;
         pageRef: z.ZodString;
@@ -223,6 +238,7 @@ export declare const renderShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"patchSettings">;
         customCss: z.ZodOptional<z.ZodString>;
+        notifications: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>;
         keepState: z.ZodOptional<z.ZodBoolean>;
         stateStorage: z.ZodOptional<z.ZodEnum<{
             localStorage: "localStorage";

package/dist/modules/mcp/tools/screenshot.d.ts

@@ -50,6 +50,8 @@ export declare const screenshotShape: {
             client: "client";
             shared: "shared";
         }>>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        anchor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteElement">;
         pageRef: z.ZodString;
@@ -74,6 +76,7 @@ export declare const screenshotShape: {
         layout: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         layoutContainer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         enabled: z.ZodOptional<z.ZodBoolean>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deletePage">;
         ref: z.ZodString;
@@ -118,6 +121,18 @@ export declare const screenshotShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"deleteVariable">;
         name: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"upsertFlag">;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        value: z.ZodBoolean;
+        rules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            when: z.ZodType<import('@plitzi/sdk-shared').RuleGroup, unknown, z.core.$ZodTypeInternals<import('@plitzi/sdk-shared').RuleGroup, unknown>>;
+            value: z.ZodBoolean;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"deleteFlag">;
+        name: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"upsertBinding">;
         pageRef: z.ZodString;
@@ -221,6 +236,7 @@ export declare const screenshotShape: {
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"patchSettings">;
         customCss: z.ZodOptional<z.ZodString>;
+        notifications: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>>;
         keepState: z.ZodOptional<z.ZodBoolean>;
         stateStorage: z.ZodOptional<z.ZodEnum<{
             localStorage: "localStorage";

package/dist/modules/mcp/tools/shared/draftBatch.d.ts

@@ -12,6 +12,8 @@ export type DraftResult = {
     draft: Space;
     outcome: MutationOutcome;
     warnings: string[];
+    /** Shorter ways to the same page this batch opened up. Never a reason to refuse it. */
+    suggestions: string[];
 };
 /**
  * A batch run on a copy of the space and read back — the one way every tool that takes operations handles them, so

package/dist/modules/mcp/tools/shared/draftBatch.js

@@ -1,6 +1,7 @@
 import { cloneSpace } from "../../helpers/space.js";
 import { expandOperations } from "./expandOperations.js";
 import { fixTouched, lintDraft } from "./lintDraft.js";
+import { newSuggestions } from "./newSuggestions.js";
 import { validateOperations } from "./validator/index.js";
 import { applyOperations } from "../apply/dispatch.js";
 //#region src/modules/mcp/tools/shared/draftBatch.ts
@@ -51,7 +52,8 @@ var draftBatch = (space, env, operations, mode = "space") => {
 		ops,
 		draft,
 		outcome,
-		warnings
+		warnings,
+		suggestions: newSuggestions(prepared.space, draft)
 	};
 };
 //#endregion

package/dist/modules/mcp/tools/shared/lintDraft.js

@@ -1,5 +1,5 @@
 import { findElementByRef, findPageByRef } from "../../helpers/space.js";
-import { elementSourceTypes, fixSpace, lintSpace } from "@plitzi/sdk-authoring";
+import { authoringCodeEntry, elementSourceTypes, fixSpace, lintSpace } from "@plitzi/sdk-authoring";
 import { validateSchema } from "@plitzi/sdk-schema/helpers/schemaValidator";
 import { styleWithoutTag } from "@plitzi/sdk-schema/helpers/styleWithoutTag";
 //#region src/modules/mcp/tools/shared/lintDraft.ts
@@ -76,6 +76,15 @@ var readingOf = (space) => {
 		]
 	};
 };
+/**
+* An issue as the agent reads it: led by its code, which is how it is filed — the agent has no skill page to look a
+* code up in, so what to write instead comes with it, from the same table `authorSpace` raises it from.
+*/
+var said = (issue) => `[${issue.code}] ${issue.message}`;
+var fixOf = (issue) => {
+	const entry = authoringCodeEntry(issue.code);
+	return entry ? `Write instead: ${entry.fix}.` : "";
+};
 var keyOf = (issue) => JSON.stringify([
 	issue.code,
 	issue.elementId ?? "",
@@ -123,11 +132,14 @@ var lintDraft = (draft, ops, before) => {
 	const preExisting = before && (candidates.length > 0 || touchedWarnings.length > 0) ? preExistingIn(readingOf(before).all, all) : () => false;
 	const toError = (issue) => ({
 		path: issue.elementId ? `element "${issue.elementId}"` : "schema",
-		message: preExisting(issue) ? `Pre-existing malformation in element "${issue.elementId ?? ""}": ${issue.message}` : issue.message,
-		hint: preExisting(issue) ? "This issue already exists in the space (NOT caused by your change), but the save is blocked until you fix it too, in this same batch." : ""
+		message: preExisting(issue) ? `Pre-existing malformation in element "${issue.elementId ?? ""}": ${said(issue)}` : said(issue),
+		hint: [preExisting(issue) ? "This issue already exists in the space (NOT caused by your change), but the save is blocked until you fix it too, in this same batch." : "", fixOf(issue)].filter(Boolean).join(" ")
 	});
 	const errors = candidates.filter((issue) => onTouched(issue) || !preExisting(issue)).map(toError);
-	const warnings = touchedWarnings.map((issue) => preExisting(issue) ? `Pre-existing issue in element "${issue.elementId ?? ""}": ${issue.message}` : issue.message);
+	const warnings = touchedWarnings.map((issue) => {
+		const line = [said(issue), fixOf(issue)].filter(Boolean).join(" ");
+		return preExisting(issue) ? `Pre-existing issue in element "${issue.elementId ?? ""}": ${line}` : line;
+	});
 	for (const id of touched) {
 		const tagless = styleWithoutTag(draft.schema.flat[id], draft.style);
 		if (tagless) warnings.push(`element "${id}" ${tagless}`);

package/dist/modules/mcp/tools/shared/newSuggestions.d.ts

@@ -0,0 +1,7 @@
+import { Space } from '../../helpers';
+/**
+ * The shorter ways to the same page a batch opened up — a header the agent just copied onto a third page, a button it
+ * gave a text child — and none the space already had: those were said when they appeared, and saying them on every
+ * batch would bury the new ones. Not problems: nothing here blocks anything.
+ */
+export declare const newSuggestions: (before: Space, after: Space) => string[];

package/dist/modules/mcp/tools/shared/newSuggestions.js

@@ -0,0 +1,20 @@
+import { suggestSpace } from "@plitzi/sdk-authoring";
+//#region src/modules/mcp/tools/shared/newSuggestions.ts
+var keyOf = ({ code, elementIds }) => `${code}|${[...elementIds].sort().join(",")}`;
+/**
+* The shorter ways to the same page a batch opened up — a header the agent just copied onto a third page, a button it
+* gave a text child — and none the space already had: those were said when they appeared, and saying them on every
+* batch would bury the new ones. Not problems: nothing here blocks anything.
+*/
+var newSuggestions = (before, after) => {
+	const had = new Set(suggestSpace({
+		schema: before.schema,
+		style: before.style
+	}).map(keyOf));
+	return suggestSpace({
+		schema: after.schema,
+		style: after.style
+	}).filter((suggestion) => !had.has(keyOf(suggestion))).map(({ code, message, saves }) => `[${code}] ${message}${saves > 0 ? ` (saves ${String(saves)} element${saves === 1 ? "" : "s"})` : ""}`);
+};
+//#endregion
+export { newSuggestions };

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

@@ -51,6 +51,8 @@ export declare const validateShape: {
             client: "client";
             shared: "shared";
         }>>;
+        flag: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
+        anchor: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
     }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"deleteElement">;
         pageRef: import('zod').ZodString;
@@ -75,6 +77,7 @@ export declare const validateShape: {
         layout: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
         layoutContainer: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
         enabled: import('zod').ZodOptional<import('zod').ZodBoolean>;
+        flag: import('zod').ZodOptional<import('zod').ZodNullable<import('zod').ZodString>>;
     }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"deletePage">;
         ref: import('zod').ZodString;
@@ -119,6 +122,18 @@ export declare const validateShape: {
     }, 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<{
+        type: import('zod').ZodLiteral<"upsertFlag">;
+        name: import('zod').ZodString;
+        description: import('zod').ZodOptional<import('zod').ZodString>;
+        value: import('zod').ZodBoolean;
+        rules: import('zod').ZodOptional<import('zod').ZodArray<import('zod').ZodObject<{
+            when: import('zod').ZodType<import('@plitzi/sdk-shared').RuleGroup, unknown, import('zod/v4/core').$ZodTypeInternals<import('@plitzi/sdk-shared').RuleGroup, unknown>>;
+            value: import('zod').ZodBoolean;
+        }, import('zod/v4/core').$strip>>>;
+    }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
+        type: import('zod').ZodLiteral<"deleteFlag">;
+        name: import('zod').ZodString;
     }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"upsertBinding">;
         pageRef: import('zod').ZodString;
@@ -222,6 +237,7 @@ export declare const validateShape: {
     }, import('zod/v4/core').$strip>, import('zod').ZodObject<{
         type: import('zod').ZodLiteral<"patchSettings">;
         customCss: import('zod').ZodOptional<import('zod').ZodString>;
+        notifications: import('zod').ZodOptional<import('zod').ZodRecord<import('zod').ZodString, import('zod').ZodNullable<import('zod').ZodString>>>;
         keepState: import('zod').ZodOptional<import('zod').ZodBoolean>;
         stateStorage: import('zod').ZodOptional<import('zod').ZodEnum<{
             localStorage: "localStorage";

package/dist/modules/mcp/tools/validate.js

@@ -8,20 +8,22 @@ var validateShape = {
 };
 var validate = (input, space) => {
 	const result = draftBatch(space, input.environment ?? "main", input.operations);
-	return result.ok ? {
-		valid: true,
-		errors: [],
-		warnings: result.warnings
-	} : {
+	if (!result.ok) return {
 		valid: false,
 		errors: result.errors,
 		warnings: result.warnings
 	};
+	return {
+		valid: true,
+		errors: [],
+		warnings: result.warnings,
+		...result.suggestions.length > 0 ? { suggestions: result.suggestions } : {}
+	};
 };
 var validateTool = defineTool({
 	name: "plitzi_validate",
 	title: "Validate",
-	description: "Check a batch of operations without executing them. Returns teachable errors and warnings — including any PRE-EXISTING malformation in a resource the batch touches (which blocks a save until fixed).",
+	description: "Check a batch of operations without executing them. Returns teachable errors and warnings — including any PRE-EXISTING malformation in a resource the batch touches (which blocks a save until fixed) — and suggestions: shorter ways to the same page the batch opens up (a layout, a component, an element’s own content).",
 	inputShape: validateShape,
 	access: "read",
 	run: (input, ctx) => validate(input, ctx.space)

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

@@ -1,4 +1,4 @@
-import { CssProps } from '@plitzi/sdk-authoring';
+import { NotificationsSpec, CssProps } from '@plitzi/sdk-authoring';
 import { ElementRuntime, Environment, WhileRunning } from '@plitzi/sdk-shared';
 export type Env = Environment;
 /** CSS declarations for one selector state. Keys are kebab-case CSS properties (see plitzi://css-properties).
@@ -197,6 +197,8 @@ export interface AIElementDetail {
     /** Where this element renders, when it is not the default 'shared'. An apiContainer reading through a connector
      *  is 'server'; one showing 'client' (or nothing) fetches from the browser instead and ignores its connector. */
     runtime?: ElementRuntime;
+    /** The feature flag it exists under — 'name' while on, '!name' while off — when it is gated at all. */
+    flag?: string;
     /** Which variant/visibility this element applies today (element.definition.initialState). */
     initialState?: AIInitialState;
     /** Data bindings on this element, grouped by category. */
@@ -255,7 +257,10 @@ export interface AISchemaVariable {
 /** Space-level settings: the arbitrary global CSS (`customCss`), state persistence, and the user/auth provider
  *  configuration. Every field is optional — a patch changes only the keys it sends. */
 export interface AISettings {
+    /** The space's own global CSS — without the notifications' rule, which reads as `notifications`. */
     customCss?: string;
+    /** How the toasts an `addNotification` step shows look: colours and shape, any CSS value. */
+    notifications?: NotificationsSpec;
     /** Keep `runtime.state` — what `setState` writes — across reloads, filed under whoever is signed in. */
     keepState?: boolean;
     stateStorage?: 'localStorage' | 'sessionStorage';

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

@@ -45,6 +45,8 @@ export interface WriteResponse {
     changed: ChangedResource[];
     elements?: WriteElement[];
     warnings?: string[];
+    /** Shorter ways to the same page the batch opened up. Never a reason it was refused. */
+    suggestions?: string[];
     errors?: ValidationError[];
     conflict?: {
         message: string;
@@ -85,6 +87,8 @@ export interface ValidationResult {
     valid: boolean;
     errors: ValidationError[];
     warnings: string[];
+    /** Shorter ways to the same page the batch would open up — a layout, a component, an element's own content. */
+    suggestions?: string[];
 }
 export interface SearchInput {
     query: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-mcp",
-  "version": "0.37.9",
+  "version": "0.37.10",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -30,14 +30,14 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.30.1",
-    "@plitzi/plitzi-sdk": "0.37.9",
-    "@plitzi/sdk-authoring": "0.37.9",
-    "@plitzi/sdk-elements": "0.37.9",
-    "@plitzi/sdk-interactions": "0.37.9",
-    "@plitzi/sdk-schema": "0.37.9",
-    "@plitzi/sdk-server": "0.37.9",
-    "@plitzi/sdk-shared": "0.37.9",
-    "@plitzi/sdk-style": "0.37.9",
+    "@plitzi/plitzi-sdk": "0.37.10",
+    "@plitzi/sdk-authoring": "0.37.10",
+    "@plitzi/sdk-elements": "0.37.10",
+    "@plitzi/sdk-interactions": "0.37.10",
+    "@plitzi/sdk-schema": "0.37.10",
+    "@plitzi/sdk-server": "0.37.10",
+    "@plitzi/sdk-shared": "0.37.10",
+    "@plitzi/sdk-style": "0.37.10",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "zod": "^4.6.5"