Skip to content

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.

feat: Make MCP verification proportional (#6155)

Oleg Isonen95c867697f75
diff --git a/packages/project-build/src/mcp.test.ts b/packages/project-build/src/mcp.test.ts
index 2a6d0ab340..5340f7b623 100644
--- a/packages/project-build/src/mcp.test.ts
+++ b/packages/project-build/src/mcp.test.ts
@@ -1004,9 +1004,7 @@ describe("project session mcp adapter", () => {
).toMatchObject({
type: "object",
required:
- command === "preview.start"
- ? ["url", "running", "mode"]
- : ["running"],
+ command === "preview.start" ? ["running", "mode"] : ["running"],
properties: {
url: { type: "string" },
pid: { type: "integer" },
@@ -2812,7 +2810,9 @@ describe("project session mcp adapter", () => {
})
);
expect(result.structuredContent.meta).toMatchObject({
- next: [expect.stringContaining("run audit")],
+ next: [
+ expect.stringContaining("Run audit when the change is structural"),
+ ],
});
});
@@ -2836,7 +2836,7 @@ describe("project session mcp adapter", () => {
expect(result.structuredContent.meta.next).toEqual([
expect.stringContaining("run verify-bindings"),
- expect.stringContaining("run audit"),
+ expect.stringContaining("Run audit when the change is structural"),
]);
});
@@ -7023,6 +7023,88 @@ describe("project session mcp adapter", () => {
);
});
+ test("uses proportional verification for small value corrections", async () => {
+ const adapter = createProjectSessionMcpCore({
+ operations: publicMcpOperations,
+ createProjectSession: createSessionFactory(),
+ executeOperation: createExecuteOperation(),
+ captureScreenshot: vi.fn(),
+ startPreview: vi.fn(),
+ getPreviewStatus: vi.fn(),
+ guidance: testMcpGuidance,
+ });
+
+ const guide = await adapter.callTool({
+ name: "meta.guide",
+ input: { brief: "Correct one asset reference on the pricing page" },
+ });
+
+ expect(guide.structuredContent.data).toEqual(
+ expect.objectContaining({
+ taskScope: "small-value-or-reference-correction",
+ workflow: expect.arrayContaining([
+ "Focused search → atomic edit → targeted assertions.",
+ ]),
+ visionLoop: [],
+ slowOperation: expect.objectContaining({
+ confirmationRequired: true,
+ operation: "full production preview",
+ }),
+ })
+ );
+ });
+
+ test("preflights production preview before starting slow work", async () => {
+ const startPreview = vi.fn(async () => ({
+ url: "http://127.0.0.1:5173/",
+ running: true,
+ mode: "production" as const,
+ }));
+ const adapter = createProjectSessionMcpCore({
+ operations: publicMcpOperations,
+ createProjectSession: createSessionFactory(),
+ executeOperation: createExecuteOperation(),
+ startPreview,
+ getPreviewStatus: vi.fn(),
+ });
+
+ const result = await adapter.callTool({
+ name: "preview.start",
+ input: { mode: "production", maxDurationMs: 10_000 },
+ });
+
+ expect(startPreview).not.toHaveBeenCalled();
+ expect(result.structuredContent.data).toEqual(
+ expect.objectContaining({
+ confirmationRequired: true,
+ operation: "production preview build",
+ estimatedDuration: "30–60 seconds",
+ confirmationToken: expect.any(String),
+ fasterAlternative: expect.objectContaining({
+ operation: "targeted route validation",
+ }),
+ })
+ );
+
+ const confirmationToken = (
+ result.structuredContent.data as { confirmationToken: string }
+ ).confirmationToken;
+ const confirmed = await adapter.callTool({
+ name: "preview.start",
+ input: {
+ mode: "production",
+ maxDurationMs: 10_000,
+ confirmSlow: true,
+ confirmationToken,
+ },
+ });
+
+ expect(startPreview).toHaveBeenCalledOnce();
+ expect(confirmed.structuredContent.data).toEqual(
+ expect.objectContaining({ running: true, mode: "production" })
+ );
+ });
+
test("rejects invalid preview ports", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
diff --git a/packages/project-build/src/mcp.ts b/packages/project-build/src/mcp.ts
index df58a30138..e61c76b9d9 100644
--- a/packages/project-build/src/mcp.ts
+++ b/packages/project-build/src/mcp.ts
@@ -1562,6 +1562,22 @@ const previewInputSchema = {
"External image hostnames allowed by the generated preview optimizer, for example storage.example.com.",
items: { type: "string" },
},
+ maxDurationMs: {
+ type: "integer",
+ minimum: 1,
+ description:
+ "Maximum acceptable duration. Slow work returns a confirmation preflight instead of starting when it cannot reasonably fit this budget.",
+ },
+ confirmSlow: {
+ type: "boolean",
+ description:
+ "Must be true after explicit user consent for the unchanged slow-operation preflight.",
+ },
+ confirmationToken: {
+ type: "string",
+ description:
+ "Short-lived token returned by the unchanged slow-operation preflight.",
+ },
},
} as const satisfies ProjectSessionMcpInputSchema;
@@ -2455,7 +2471,25 @@ const previewStatusDataSchema = {
const previewDataSchema = {
...previewStatusDataSchema,
- required: ["url", "running", "mode"],
+ properties: {
+ ...previewStatusDataSchema.properties,
+ confirmationRequired: { type: "boolean" },
+ operation: { type: "string" },
+ estimatedDuration: { type: "string" },
+ reason: { type: "string" },
+ confirmationToken: { type: "string" },
+ fasterAlternative: {
+ type: "object",
+ properties: {
+ operation: { type: "string" },
+ estimatedDuration: { type: "string" },
+ limitations: { type: "string" },
+ },
+ required: ["operation", "estimatedDuration", "limitations"],
+ additionalProperties: false,
+ },
+ },
+ required: ["running", "mode"],
} as const satisfies InputJsonSchema;
const restorePointSummaryDataSchema = getZodObjectSchema(
@@ -4405,7 +4439,7 @@ const filterCapabilities = (tools: readonly ProjectSessionMcpTool[]) => {
};
const startupGuidance = [
- "For any multi-step authoring task, first call meta.guide with the user's objective and follow its complete workflow, including final audit, preview, and screenshot steps.",
+ "For any multi-step authoring task, first call meta.guide with the user's objective and follow its proportional workflow. Small corrections stop after focused assertions; preview and screenshots are required only when the requested outcome is visual or runtime-dependent.",
"Mutation responses can include meta.next. Treat those steps as required before reporting completion.",
"Every local-capable mutation exposes dryRun. Destructive delete, replace, and replace-all calls plan first; review the transaction, ask the user to confirm, then retry the unchanged call with confirmDestructive: true and meta.confirmation.token. Never retry blindly because changed input, version, or plan invalidates the short-lived token.",
readProjectBuildDoc("mcp-startup-guidance").trim(),
@@ -5876,6 +5910,48 @@ const metaGoalGuides = [
const metaGuideDetailedInputSchemaTools = new Set(["update-styles"]);
const metaGuideExampleTools = new Set(["upload-assets"]);
+const taskScopes = [
+ "small-value-or-reference-correction",
+ "focused-page-change",
+ "visual-change",
+ "structural-project-change",
+ "project-wide-migration",
+] as const;
+
+type TaskScope = (typeof taskScopes)[number];
+
+const classifyTaskScope = (brief: string): TaskScope => {
+ if (
+ /\b(project[- ]wide|site[- ]wide|all pages|every page|migration|migrate)\b/i.test(
+ brief
+ )
+ ) {
+ return "project-wide-migration";
+ }
+ if (
+ /\b(visual|layout|responsive|screenshot|typography|spacing|color|design)\b/i.test(
+ brief
+ )
+ ) {
+ return "visual-change";
+ }
+ if (
+ /\b(create|insert|delete|remove|move|wrap|unwrap|duplicate|reparent)\b.*\b(page|section|component|instance|element|tree|folder)\b/i.test(
+ brief
+ )
+ ) {
+ return "structural-project-change";
+ }
+ if (
+ /\b(correct|correction|fix|replace|update|change|typo)\b.*\b(value|text|copy|reference|asset|url|link|title|description|metadata|prop|binding)\b/i.test(
+ brief
+ )
+ ) {
+ return "small-value-or-reference-correction";
+ }
+ return "focused-page-change";
+};
+
const serializeMetaGuideTool = (
tool: ProjectSessionMcpTool,
includeHandshakeFields: boolean
@@ -5908,6 +5984,7 @@ const getMetaGuide = (
tools: readonly ProjectSessionMcpTool[],
guidance: ProjectSessionMcpGuidance | undefined
) => {
+ const taskScope = classifyTaskScope(brief);
const goalGuide = metaGoalGuides.find(({ pattern }) => pattern.test(brief));
const matches =
goalGuide === undefined
@@ -5919,7 +5996,12 @@ const getMetaGuide = (
const canDiffScreenshots = tools.some(
(tool) => tool.name === "screenshot.diff"
);
+ const isSmallCorrection = taskScope === "small-value-or-reference-correction";
+ const needsVisualVerification = taskScope === "visual-change";
const generalWorkflow = [
+ isSmallCorrection
+ ? "Focused search → atomic edit → targeted assertions."
+ : undefined,
"Use the fewest discovery calls needed for the immediate action.",
"Call permissions or status only when the task depends on capabilities or local session freshness.",
matches.some((tool) => tool.annotations.localCapable) &&
@@ -5930,14 +6012,33 @@ const getMetaGuide = (
"Use the smallest semantic mutation tool that matches the requested change.",
valuesVsBindingsRule,
"Use apply-patch only when no semantic mutation tool fits.",
- canVerifyVisually && guidance !== undefined
+ needsVisualVerification && canVerifyVisually && guidance !== undefined
? guidance.getVisionWorkflowSummary({ includeDiff: canDiffScreenshots })
: undefined,
].filter(Boolean);
return {
+ taskScope,
delegatedAgentRule:
"Do not spend the whole phase on discovery. If you are delegated/non-streaming and the parent asks for status within 30 seconds, run exactly one shortcut command such as webstudio meta.index or one explicit webstudio mcp single-op-call command, report its command/result, and wait before the next MCP command.",
workflow: goalGuide?.workflow ?? generalWorkflow,
+ visionLoop:
+ needsVisualVerification && canVerifyVisually && guidance !== undefined
+ ? guidance.getVisionVerificationLoop({
+ includeDiff: canDiffScreenshots,
+ })
+ : [],
+ slowOperation: {
+ confirmationRequired: true,
+ operation: "full production preview",
+ estimatedDuration: "30–60 seconds",
+ reason:
+ "Builds complete rendered output and is unnecessary for a focused value correction unless the requested outcome depends on layout or runtime behavior.",
+ fasterAlternative: {
+ operation: "targeted route validation",
+ estimatedDuration: "2–5 seconds",
+ limitations: "Does not visually inspect layout.",
+ },
+ },
tools: matches.map((tool) =>
serializeMetaGuideTool(tool, goalGuide === undefined)
),
@@ -7104,6 +7205,55 @@ const getPreviewInput = (input: unknown): ProjectSessionPreviewInput => {
};
};
+const slowOperationConfirmationTtlMs = 5 * 60 * 1000;
+
+const getProductionPreviewPreflight = async (input: unknown) => {
+ if (isRecord(input) === false || input.mode !== "production") {
+ return;
+ }
+ const previewInput = getPreviewInput(input);
+ const confirmationPayload = {
+ operation: "production preview build",
+ input: previewInput,
+ maxDurationMs:
+ typeof input.maxDurationMs === "number" ? input.maxDurationMs : undefined,
+ };
+ if (
+ input.confirmSlow === true &&
+ (await validateConfirmationToken(
+ typeof input.confirmationToken === "string"
+ ? input.confirmationToken
+ : undefined,
+ confirmationPayload
+ ))
+ ) {
+ return;
+ }
+ const { token } = await createConfirmationToken(
+ confirmationPayload,
+ slowOperationConfirmationTtlMs
+ );
+ const maxDurationMs =
+ typeof input.maxDurationMs === "number" ? input.maxDurationMs : undefined;
+ return {
+ running: false,
+ mode: "production" as const,
+ confirmationRequired: true,
+ operation: "production preview build",
+ estimatedDuration: "30–60 seconds",
+ reason:
+ maxDurationMs !== undefined && maxDurationMs < 30_000
+ ? `A full production preview cannot reasonably finish within the ${maxDurationMs}ms budget.`
+ : "A full production preview builds complete rendered output and is expected to exceed 10 seconds.",
+ confirmationToken: token,
+ fasterAlternative: {
+ operation: "targeted route validation",
+ estimatedDuration: "2–5 seconds",
+ limitations: "Does not visually inspect layout.",
+ },
+ };
+};
+
const getImportInput = (input: unknown): ProjectSessionImportInput => {
if (isRecord(input) === false) {
throw new Error("import input must be an object.");
@@ -7764,6 +7914,10 @@ export const createProjectSessionMcpCore = <Command extends string = string>({
return toMetaResult(await installOcr());
}
if (name === "preview.start" && startPreview !== undefined) {
+ const preflight = await getProductionPreviewPreflight(input);
+ if (preflight !== undefined) {
+ return toMetaResult(preflight);
+ }
return toMetaResult(
await startPreview(getPreviewInput(input), {
report: (message) => {
@@ -8087,10 +8241,10 @@ export const createProjectSessionMcpCore = <Command extends string = string>({
: []),
...(needsVisualVerification
? [
- "Before reporting completion, run audit for the changed page or project.",
+ "For a small fixed-value or reference correction, re-read the changed value and run only relevant focused assertions; stop when they pass. Run audit when the change is structural or broader.",
...(startPreview !== undefined && captureScreenshot !== undefined
? [
- "For visual changes, start a session preview and capture desktop and mobile screenshots before reporting completion.",
+ "Only when the requested outcome is visual or runtime-dependent, start a session preview and capture the necessary screenshots. Production preview requires a slow-operation preflight and explicit confirmation.",
]
: []),
]