@cplace/mcp-server 1.7.10 → 1.8.5

package/dist/tools/layout.d.ts

@@ -1,7 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { CplaceApiClient } from '../api.js';
-export declare const LayoutContextSchema: z.ZodUnion<[z.ZodObject<{
+export declare const LayoutContextSchema: z.ZodEffects<z.ZodUnion<[z.ZodObject<{
     type: z.ZodLiteral<"page">;
     pageUID: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -25,12 +25,20 @@ export declare const LayoutContextSchema: z.ZodUnion<[z.ZodObject<{
     workspaceId: string;
     typeInternalName: string;
     alternativeLayoutName?: string | undefined;
-}>]>;
+}>]>, {
+    type: "page";
+    pageUID: string;
+} | {
+    type: "type";
+    workspaceId: string;
+    typeInternalName: string;
+    alternativeLayoutName?: string | undefined;
+}, unknown>;
 export declare const LAYOUT_TOOL_DEFINITIONS: {
-    readonly cplace_define_layout: {
-        readonly description: "Define a complete page or type layout atomically using a layout.define() low-code script.\n\nWHEN TO USE:\n- Use this tool when you know the full layout structure upfront\n- Replaces the entire layout in a single atomic operation (no partial updates)\n- More efficient than sequential add-row/add-widget calls for complete layouts\n\nKEY BEHAVIORS:\n- The script must call layout.define() exactly once\n- The entire layout is atomically replaced — previous layout is fully overwritten\n- Script timeout: 30 seconds\n- Widget IDs: auto-generated if omitted; if provided without '_' prefix, '_' is prepended automatically\n\nRESPONSE OUTCOMES:\n- VALID_COMPLETE: Layout saved, all widgets fully configured\n- VALID_INCOMPLETE: Layout saved, but some widgets have missing optional configuration (warnings returned)\n- Validation errors: Layout NOT saved — structural or widget errors returned with details\n- Generic errors: Entity not found, permission denied, script errors\n\nVALIDATION FEEDBACK:\n- Structural errors: invalid column proportions (must be 3-12 each, sum to 12 per row)\n- Widget errors: unknown widget types, invalid configurations\n- Warnings: widgets saved but missing optional configuration (e.g., search filter not set)\n\nTIP: After a VALID_INCOMPLETE response, re-run layout.define() with corrected widget configuration to resolve warnings.\n\nCOMMON WIDGET TYPES (platform, always available):\ncf.platform.attributes, cf.cplace.platform.attributesGroup,\ncf.platform.wiki, cf.platform.richString, cf.cplace.demoWidgets.demoRichString,\ncf.platform.embeddedSearchAsTable, cf.cplace.platform.tableWidget,\ncf.platform.connectedBarChart, cf.platform.connectedPieChart,\ncf.platform.connectedMatrix, cf.platform.connectedTableFilter,\ncf.platform.incomingReferences, cf.platform.comments, cf.platform.files,\ncf.cplace.visualizations.scriptingHighcharts\n\nFor app-dependent widgets not in this list, call cplace_list_widget_definitions with embeddingContext \"AS_WIDGET\".";
+    readonly cplace_execute_layout_script: {
+        readonly description: "Execute a layout script — either a full layout.define() replacement or per-widget edit verbs.\n\nTWO MODES (determined by script content):\n\nMODE 1 — FULL REPLACE (layout.define):\n- Script calls layout.define() exactly once to declare the complete layout structure\n- Replaces the entire layout atomically\n- Same behavior as before\n\nMODE 2 — EDIT VERBS (per-widget):\n- Script calls one or more edit methods: layout.updateWidget(), layout.addWidget(), layout.removeWidget(), layout.moveWidget(), layout.addRow(), layout.compact()\n- Each call collects an operation; all operations commit atomically or fail together\n- Cannot mix layout.define() with edit verbs in the same script\n\nEDIT VERBS:\n  layout.updateWidget(\"widgetId\", { \"cf.cplace.x\": newValue })  — partial config merge (only specified keys change)\n  layout.addWidget({ widgetType: \"cf.platform.wiki\", position: { rowIndex: 0, columnIndex: 0, widgetIndex: 0 }, configuration: { ... } })\n  layout.removeWidget(\"widgetId\")\n  layout.moveWidget(\"widgetId\", { rowIndex: 1, columnIndex: 0, widgetIndex: 0 })\n  layout.addRow(rowIndex, [6, 6])  — column proportions must sum to 12\n  layout.compact()  — remove empty rows\n\nWORKFLOW for per-widget edit:\n1. Read: cplace_get_layout_script with widgetIds to get layout.updateWidget() fragments\n2. Edit: modify the config values in the fragment\n3. Execute: post the modified script via this tool\n\nKEY BEHAVIORS (for layout.define mode):\n- The script must call layout.define() exactly once\n- The entire layout is atomically replaced — previous layout is fully overwritten\n- Script timeout: 30 seconds\n- Widget IDs: MUST be omitted from layout.define. Ids are assigned by the server and returned in the response. Use the returned id in subsequent layout.updateWidget() calls.\n\nRESPONSE OUTCOMES:\n- VALID_COMPLETE: Layout saved, all widgets fully configured\n- VALID_INCOMPLETE: Layout saved, but some widgets have missing optional configuration (warnings returned)\n- Validation errors: Layout NOT saved — structural or widget errors returned with details\n- Generic errors: Entity not found, permission denied, script errors\n\nVALIDATION FEEDBACK:\n- Structural errors: invalid column proportions (must be 3-12 each, sum to 12 per row)\n- Widget errors: unknown widget types, invalid configurations\n- Warnings: widgets saved but missing optional configuration (e.g., search filter not set)\n\nTIP: After a VALID_INCOMPLETE response, re-run layout.define() with corrected widget configuration to resolve warnings.\n\nCOMMON WIDGET TYPES (platform, always available):\ncf.platform.attributes, cf.cplace.platform.attributesGroup,\ncf.platform.wiki, cf.platform.richString, cf.cplace.demoWidgets.demoRichString,\ncf.platform.embeddedSearchAsTable, cf.cplace.platform.tableWidget,\ncf.platform.connectedBarChart, cf.platform.connectedPieChart,\ncf.platform.connectedMatrix, cf.platform.connectedTableFilter,\ncf.platform.incomingReferences, cf.platform.comments, cf.platform.files,\ncf.cplace.visualizations.scriptingHighcharts\n\nFor app-dependent widgets not in this list, call cplace_list_widget_definitions with embeddingContext \"AS_WIDGET\".\n\nRICHSTRING WIDGETS AND EMBEDDED WIDGETS (decoded form):\nRichString widgets (cf.platform.richString, cf.cplace.demoWidgets.demoRichString)\nhold HTML in their 'content' config. Embedded widgets inside that HTML are\nexpressed in decoded form:\n  <embeddedwidget id=\"id_w1\" type=\"cf.platform.singleAttribute\">{\"properties\":{\"attribute\":\"name\"}}</embeddedwidget>\n\nSemantics when submitting a script:\n  • Tag with an existing id + same type → update (properties replace current)\n  • Tag without id → insert new embedded widget (backend assigns id)\n  • Existing id omitted from new content → delete\n  • Unknown id, duplicate id, or type change for same id → error\n\nRaw base64 <embeddedwidget>BASE64</embeddedwidget> tags are REJECTED on writes.\nFetch current decoded form via cplace_get_layout_script.\n\nIMPORTANT: Decoded <embeddedwidget> tags must appear directly inline in a content: value.\nDo NOT build the tag in a variable and pass it — the parser rejects tags outside content: literals.\n  ✅ layout.updateWidget(\"id\", { content: '<embeddedwidget type=\"...\">...</embeddedwidget>' });\n  ❌ var tag = '<embeddedwidget ...>...</embeddedwidget>'; layout.updateWidget(\"id\", { content: tag });\n\nFor atomic single-embedded-widget edits without rewriting the full script,\nsee cplace_layout_richstring_* tools.";
         readonly inputSchema: {
-            readonly context: z.ZodUnion<[z.ZodObject<{
+            readonly context: z.ZodEffects<z.ZodUnion<[z.ZodObject<{
                 type: z.ZodLiteral<"page">;
                 pageUID: z.ZodString;
             }, "strip", z.ZodTypeAny, {
@@ -54,17 +62,25 @@ export declare const LAYOUT_TOOL_DEFINITIONS: {
                 workspaceId: string;
                 typeInternalName: string;
                 alternativeLayoutName?: string | undefined;
-            }>]>;
+            }>]>, {
+                type: "page";
+                pageUID: string;
+            } | {
+                type: "type";
+                workspaceId: string;
+                typeInternalName: string;
+                alternativeLayoutName?: string | undefined;
+            }, unknown>;
             readonly script: z.ZodString;
         };
         readonly annotations: {
-            readonly title: "Define Layout";
+            readonly title: "Execute Layout Script";
         };
     };
     readonly cplace_get_layout_overview: {
         readonly description: "Get layout structure for page or type. Provides an overview of the layout grid including rows, columns, and widget summaries for both page and type layouts.";
         readonly inputSchema: {
-            readonly context: z.ZodUnion<[z.ZodObject<{
+            readonly context: z.ZodEffects<z.ZodUnion<[z.ZodObject<{
                 type: z.ZodLiteral<"page">;
                 pageUID: z.ZodString;
             }, "strip", z.ZodTypeAny, {
@@ -88,16 +104,24 @@ export declare const LAYOUT_TOOL_DEFINITIONS: {
                 workspaceId: string;
                 typeInternalName: string;
                 alternativeLayoutName?: string | undefined;
-            }>]>;
+            }>]>, {
+                type: "page";
+                pageUID: string;
+            } | {
+                type: "type";
+                workspaceId: string;
+                typeInternalName: string;
+                alternativeLayoutName?: string | undefined;
+            }, unknown>;
         };
         readonly annotations: {
             readonly title: "Get Layout Overview";
         };
     };
     readonly cplace_get_layout_widget_details: {
-        readonly description: "Get detailed widget configuration from page or type layout. Extracts specific widget information from the layout structure.";
+        readonly description: "Get detailed widget configuration from page or type layout. Extracts specific widget information from the layout structure.\n\nRichString widget content appears in decoded form: `<embeddedwidget id=\"…\" type=\"…\">{\"properties\":{…}}</embeddedwidget>` — no base64.";
         readonly inputSchema: {
-            readonly context: z.ZodUnion<[z.ZodObject<{
+            readonly context: z.ZodEffects<z.ZodUnion<[z.ZodObject<{
                 type: z.ZodLiteral<"page">;
                 pageUID: z.ZodString;
             }, "strip", z.ZodTypeAny, {
@@ -121,17 +145,25 @@ export declare const LAYOUT_TOOL_DEFINITIONS: {
                 workspaceId: string;
                 typeInternalName: string;
                 alternativeLayoutName?: string | undefined;
-            }>]>;
+            }>]>, {
+                type: "page";
+                pageUID: string;
+            } | {
+                type: "type";
+                workspaceId: string;
+                typeInternalName: string;
+                alternativeLayoutName?: string | undefined;
+            }, unknown>;
             readonly widgetId: z.ZodString;
         };
         readonly annotations: {
             readonly title: "Get Layout Widget Details";
         };
     };
-    readonly cplace_get_layout_definition: {
-        readonly description: "Get the current layout as a layout.define() JavaScript definition for a page or type layout.\n\nWHEN TO USE:\n- To read the current layout before modifying it (read-edit-write workflow)\n- To inspect the full layout definition including widget configurations and embedded layouts\n- To copy a layout from one page/type to another\n\nRETURNS:\n- The layout as a layout.define({...}) definition string, ready to be modified and posted back via cplace_define_layout\n- Widget config values are in the INPUT format accepted by cplace_define_layout (references as UID strings, rich strings as markup strings, localized strings as {locale: value} maps)\n\nROUND-TRIP WORKFLOW:\n1. GET: Use this tool to retrieve the current layout definition\n2. EDIT: Modify the definition as needed\n3. APPLY: Use cplace_define_layout to apply the modified definition";
+    readonly cplace_get_layout_script: {
+        readonly description: "Get the current layout as an executable script for a page or type layout.\n\nTWO MODES (determined by widgetIds parameter):\n\nWITHOUT widgetIds: Returns the full layout as a layout.define({...}) script (same as before).\n\nWITH widgetIds: Returns layout.updateWidget(\"id\", {config}) fragments for just the specified widgets.\nThe output is directly executable — post it back via cplace_execute_layout_script.\n\nROUND-TRIP WORKFLOW:\n1. GET: Use this tool (with widgetIds for selective read, without for full layout)\n2. EDIT: Modify the script as needed\n3. APPLY: Use cplace_execute_layout_script to apply\n\nRichString widget content is returned in decoded form:\n  <embeddedwidget id=\"…\" type=\"…\">{\"properties\":{…}}</embeddedwidget>\nThe output is directly executable — base64 tags are never emitted.";
         readonly inputSchema: {
-            readonly context: z.ZodUnion<[z.ZodObject<{
+            readonly context: z.ZodEffects<z.ZodUnion<[z.ZodObject<{
                 type: z.ZodLiteral<"page">;
                 pageUID: z.ZodString;
             }, "strip", z.ZodTypeAny, {
@@ -155,16 +187,25 @@ export declare const LAYOUT_TOOL_DEFINITIONS: {
                 workspaceId: string;
                 typeInternalName: string;
                 alternativeLayoutName?: string | undefined;
-            }>]>;
+            }>]>, {
+                type: "page";
+                pageUID: string;
+            } | {
+                type: "type";
+                workspaceId: string;
+                typeInternalName: string;
+                alternativeLayoutName?: string | undefined;
+            }, unknown>;
+            readonly widgetIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         };
         readonly annotations: {
-            readonly title: "Get Layout Definition";
+            readonly title: "Get Layout Script";
         };
     };
     readonly cplace_edit_layout: {
-        readonly description: "Edit a layout using str_replace — find an exact text match and replace it. Reads the current layout.define() definition, applies the replacement, and writes back. Use this instead of cplace_define_layout when making small changes to large layouts to avoid reproducing the entire definition.";
+        readonly description: "Edit a layout using str_replace — find an exact text match and replace it. Reads the current layout.define() definition, applies the replacement, and writes back. Use this instead of cplace_execute_layout_script when making small changes to large layouts to avoid reproducing the entire definition.\n\nRichString widget content is in decoded form. `old_str` must match the decoded form exactly as returned by cplace_get_layout_script. Raw base64 <embeddedwidget> tags are rejected in both `old_str` and `new_str`.";
         readonly inputSchema: {
-            readonly context: z.ZodUnion<[z.ZodObject<{
+            readonly context: z.ZodEffects<z.ZodUnion<[z.ZodObject<{
                 type: z.ZodLiteral<"page">;
                 pageUID: z.ZodString;
             }, "strip", z.ZodTypeAny, {
@@ -188,7 +229,15 @@ export declare const LAYOUT_TOOL_DEFINITIONS: {
                 workspaceId: string;
                 typeInternalName: string;
                 alternativeLayoutName?: string | undefined;
-            }>]>;
+            }>]>, {
+                type: "page";
+                pageUID: string;
+            } | {
+                type: "type";
+                workspaceId: string;
+                typeInternalName: string;
+                alternativeLayoutName?: string | undefined;
+            }, unknown>;
             readonly old_str: z.ZodString;
             readonly new_str: z.ZodString;
             readonly replace_all: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;

package/dist/tools/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/tools/layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAO5C,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;IAW0F,CAAC;AAa3H,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+N1B,CAAC;AAYX,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,QA2V7E"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/tools/layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAe5C,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAWgD,CAAC;AAajF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqO1B,CAAC;AAYX,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,QAqY7E"}