Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.
TypeScript accessibilityalternativecloudflarecloudflare-workersdesignfreefrontendopen-sourceradix-uireactremixweb-developmentwebflowwebsite-builderwebsite-developmentwebsiteswebstudio
fix: Improve shared Slot selector guidance for MCP agents (#5910)
Oleg Isonenaf29a0cef717
diff --git a/packages/cli/src/commands/mcp.test.ts b/packages/cli/src/commands/mcp.test.tsindex 01e1e00f90..2d43e9bc87 100644--- a/packages/cli/src/commands/mcp.test.ts+++ b/packages/cli/src/commands/mcp.test.ts@@ -2,7 +2,10 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";import { tmpdir } from "node:os";import path from "node:path";import { afterEach, expect, test, vi } from "vitest";-import { listProjectSessionMcpTools } from "@webstudio-is/project-build/mcp";+import {+ createProjectSessionMcpCore,+ listProjectSessionMcpTools,+} from "@webstudio-is/project-build/mcp";import { publicApiOperations } from "@webstudio-is/protocol";import { __testing__, mcpOptions, prepareMcpProjectSession } from "./mcp";@@ -469,6 +472,38 @@ test("applies batch dry-run to every MCP run call", () => {]);});+test("explains extract-slot selectors in focused MCP discovery", async () => {+ const operation = publicApiOperations.find(+ ({ command }) => command === "extract-slot"+ );+ if (operation === undefined) {+ throw Error("Expected extract-slot operation");+ }+ const core = createProjectSessionMcpCore({+ operations: [operation],+ createProjectSession: () => {+ throw Error("meta.get_more_tools must not initialize a project session");+ },+ executeOperation: async () => {+ throw Error("meta.get_more_tools must not execute a project operation");+ },+ });++ const result = await core.callTool({+ name: "meta.get_more_tools",+ input: { tools: ["extract-slot"] },+ });+ const details = JSON.stringify(result.structuredContent.data);++ expect(details).toContain("leaf-to-root");+ expect(details).toContain(+ "The first id is the instance to extract, the second is its direct parent"+ );+ expect(details).toContain(+ '"instanceSelector":["header-section-id","body-id"]'+ );+});+test("persists MCP checkpoints across single-op-call processes", async () => {const tools = listProjectSessionMcpTools(publicApiOperations);const dir = await mkdtemp(path.join(tmpdir(), "webstudio-mcp-checkpoint-"));diff --git a/packages/project-build/src/contracts/__generated__/runtime-operation-contracts.ts b/packages/project-build/src/contracts/__generated__/runtime-operation-contracts.tsindex 719eecc174..5a09db50b0 100644--- a/packages/project-build/src/contracts/__generated__/runtime-operation-contracts.ts+++ b/packages/project-build/src/contracts/__generated__/runtime-operation-contracts.ts@@ -57649,6 +57649,8 @@ export const runtimeOperationContractData = [type: "string",minLength: 1,},+ description:+ 'Leaf-to-root occurrence path. The first id is the instance to extract, the second is its direct parent, and any remaining ids are successive ancestors toward the page root. Use the id and parentId returned by list-instances; for a section directly under Body, pass ["section-id", "body-id"].',},label: {type: "string",diff --git a/packages/project-build/src/mcp.ts b/packages/project-build/src/mcp.tsindex 9dc7872a48..f802390bbc 100644--- a/packages/project-build/src/mcp.ts+++ b/packages/project-build/src/mcp.ts@@ -1634,6 +1634,16 @@ export const mcpArgumentExamples: Record<string, readonly unknown[]> = {component: "@webstudio-is/sdk-components-react-radix:Switch",},],+ "extract-slot": [+ {+ instanceSelector: ["header-section-id", "body-id"],+ label: "Site header",+ },+ {+ instanceSelector: ["header-section-id", "page-wrapper-id", "body-id"],+ label: "Site header",+ },+ ],"insert-collection": [{parentInstanceId: "parent-id",diff --git a/packages/project-build/src/runtime/slot.test.ts b/packages/project-build/src/runtime/slot.test.tsindex f8bad2f59a..da5f967389 100644--- a/packages/project-build/src/runtime/slot.test.ts+++ b/packages/project-build/src/runtime/slot.test.ts@@ -181,6 +181,23 @@ describe("runtime slot utilities", () => {]);});+ test("explains the required selector order when the parent is invalid", () => {+ const instances = new Map([+ ["body", instance("body", "Body", [{ type: "id", value: "section" }])],+ ["section", instance("section", "Box")],+ ]);++ expect(() =>+ extractSharedSlot(+ { instances, props: new Map() },+ { instanceSelector: ["body", "section"] },+ { createId: () => "unused" }+ )+ ).toThrow(+ "instanceSelector must use leaf-to-root order: instanceSelector[1] must be the direct parent of instanceSelector[0]"+ );+ });+test("rejects attaching shared content inside itself", () => {const instances = new Map([[diff --git a/packages/project-build/src/runtime/slot.ts b/packages/project-build/src/runtime/slot.tsindex a5c4e1183b..88bdda7d72 100644--- a/packages/project-build/src/runtime/slot.ts+++ b/packages/project-build/src/runtime/slot.ts@@ -61,7 +61,12 @@ export const attachSharedSlotInput = z.object({});export const extractSharedSlotInput = z.object({- instanceSelector: z.array(z.string().min(1)).min(2),+ instanceSelector: z+ .array(z.string().min(1))+ .min(2)+ .describe(+ 'Leaf-to-root occurrence path. The first id is the instance to extract, the second is its direct parent, and any remaining ids are successive ancestors toward the page root. Use the id and parentId returned by list-instances; for a section directly under Body, pass ["section-id", "body-id"].'+ ),label: z.string().min(1).optional(),});@@ -291,7 +296,7 @@ export const extractSharedSlot = (if (childIndex === -1) {return throwBuilderRuntimeError("BAD_REQUEST",- "Instance selector does not identify a direct parent"+ 'instanceSelector must use leaf-to-root order: instanceSelector[1] must be the direct parent of instanceSelector[0]. Use the selected instance id followed by its parentId from list-instances, for example ["section-id", "body-id"].');}const fragment: Instance = {diff --git a/packages/protocol/src/builder-api/operation-docs.test.ts b/packages/protocol/src/builder-api/operation-docs.test.tsindex 08e5465abb..74a998ea41 100644--- a/packages/protocol/src/builder-api/operation-docs.test.ts+++ b/packages/protocol/src/builder-api/operation-docs.test.ts@@ -79,3 +79,24 @@ test("documents JSX insertion through the fragment field", () => {expect(text).not.toContain("structured Webstudio fragment");expect(text).not.toContain('"jsx"');});++test("documents extract-slot selector order with valid examples", () => {+ const docs = publicApiOperationDocumentation.find(+ ({ command }) => command === "extract-slot"+ );+ const operation = publicApiOperations.find(+ ({ command }) => command === "extract-slot"+ );+ const text = `${docs?.description}\n${docs?.examples.join("\n")}`;++ expect(text).toContain("leaf-to-root");+ expect(text).toContain("direct parent");+ expect(text).toContain("list-instances");+ expect(text).toContain('"instanceSelector":["header-section-id","body-id"]');+ expect(text).toContain(+ '"instanceSelector":["header-section-id","page-wrapper-id","body-id"]'+ );+ expect(JSON.stringify(operation?.inputSchema)).toContain(+ "The first id is the instance to extract, the second is its direct parent"+ );+});diff --git a/packages/protocol/src/builder-api/operation-docs.ts b/packages/protocol/src/builder-api/operation-docs.tsindex e198d01605..5a5af5617e 100644--- a/packages/protocol/src/builder-api/operation-docs.ts+++ b/packages/protocol/src/builder-api/operation-docs.ts@@ -343,9 +343,10 @@ const curatedPublicApiOperationDocumentation = [{command: "extract-slot",description:- "Convert an existing instance subtree into shared Slot content without cloning it",+ "Convert an existing instance subtree into shared Slot content without cloning it. instanceSelector is a leaf-to-root occurrence path: start with the instance to extract, then its direct parent, then each successive ancestor toward the page root. Use the id and parentId relationships returned by list-instances. The first example extracts a section directly under Body; the second extracts a section nested in a page wrapper.",examples: [- 'MCP tool: extract-slot {"instanceSelector":["instance-id","parent-id","root-id"],"label":"Site header"}',+ 'MCP tool: extract-slot {"instanceSelector":["header-section-id","body-id"],"label":"Site header"}',+ 'MCP tool: extract-slot {"instanceSelector":["header-section-id","page-wrapper-id","body-id"],"label":"Site header"}',],},{