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.

docs: Simplify MCP setup (#6311)

Oleg Isonen7ff42abfb550
diff --git a/docs/university/mcp.md b/docs/university/mcp.md
index 9167d50629..e3e6c68d82 100644
--- a/docs/university/mcp.md
+++ b/docs/university/mcp.md
@@ -11,6 +11,15 @@ icon: robot
**Webstudio MCP v0.0.0-webstudio-version**
+## Introduction
+
+All you need to do is install the Codex desktop app or Claude Desktop and tell
+it:
+
+> Install Webstudio CLI and use MCP.
+
+---
+
{% hint style="info" %}
This reference is generated from the Webstudio CLI source in the same Builder
revision. GitBook publishes it when that revision is successfully released.
diff --git a/package.json b/package.json
index d6ff77461f..2874d2b5af 100644
--- a/package.json
+++ b/package.json
@@ -13,15 +13,14 @@
"lint": "oxlint --deny-warnings",
"check:package-boundaries": "node scripts/check-package-boundaries.mjs",
"check:generated-api": "pnpm --filter @webstudio-is/project-build generate-runtime-operation-contracts && pnpm --filter @webstudio-is/builder generate-server-only-api-metadata && node scripts/check-clean-files.mjs packages/project-build/src/contracts/__generated__/runtime-operation-contracts.ts packages/protocol/src/builder-api/__generated__/server-only-router-operation-metadata.ts",
- "check:generated-docs": "pnpm --filter @webstudio-is/project-build generate-docs && pnpm --filter webstudio generate-docs && pnpm docs:mcp:test && pnpm docs:mcp:typecheck && pnpm docs:content-engine:test && pnpm docs:mcp:check && pnpm docs:content-engine:check && node scripts/check-clean-files.mjs packages/project-build/src/docs.generated.ts packages/cli/src/docs.generated.ts",
+ "check:generated-docs": "pnpm --filter @webstudio-is/project-build generate-docs && pnpm --filter webstudio generate-docs && pnpm docs:mcp:typecheck && pnpm docs:content-engine:test && pnpm docs:mcp:check && pnpm docs:content-engine:check && node scripts/check-clean-files.mjs packages/project-build/src/docs.generated.ts packages/cli/src/docs.generated.ts",
"check:fixture-sizes": "tsx scripts/check-fixture-sizes.ts",
"docs:mcp:sync": "tsx scripts/docs/generate-mcp-docs.ts",
"docs:mcp:check": "pnpm docs:mcp:sync && node scripts/check-clean-files.mjs docs/university/mcp.md",
- "docs:mcp:test": "tsx --test scripts/docs/generate-mcp-docs.test.ts",
"docs:mcp:typecheck": "tsc --noEmit -p scripts/docs/tsconfig.json",
"docs:content-engine:sync": "tsx scripts/docs/generate-content-engine-docs.ts",
"docs:content-engine:check": "pnpm docs:content-engine:sync && node scripts/check-clean-files.mjs docs/university/foundations/content-engine-reference.md",
- "docs:content-engine:test": "tsx --test scripts/docs/generate-content-engine-docs.test.ts && pnpm --filter webstudio exec vitest run src/content-engine-reference.test.ts",
+ "docs:content-engine:test": "pnpm --filter webstudio exec vitest run src/content-engine-reference.test.ts",
"test:packages": "pnpm -r --filter '!@webstudio-is/builder' --filter '!webstudio' test",
"test:cli": "pnpm --filter webstudio test",
"test:builder:core": "pnpm --filter @webstudio-is/builder exec vitest run --project 'core-*'",
diff --git a/packages/cli/src/cli.test.ts b/packages/cli/src/cli.test.ts
index bbc8f15c6a..670b7fd37d 100644
--- a/packages/cli/src/cli.test.ts
+++ b/packages/cli/src/cli.test.ts
@@ -243,24 +243,6 @@ describe("registerCommands", () => {
expect(getTopLevelMcpToolHint(["unknown-command"])).toBeUndefined();
});
- test("root help points low-context agents to mcp meta.index first", async () => {
- const output = await getHelpOutput(["--help"]);
-
- expect(output).toContain("Project editing / LLM quick start");
- expect(output).toContain("webstudio man project-editing");
- expect(output).toContain("webstudio meta.index");
- expect(output).toContain("webstudio insert-fragment");
- expect(output).toContain("webstudio mcp single-op-call meta.index");
- expect(output).toContain(
- "webstudio mcp single-op-call meta.get-more-tools"
- );
- expect(output).toContain(
- "webstudio insert-fragment --input-file .temp/insert-fragment.json --dry-run"
- );
- expect(output).not.toContain("<$.Box");
- expect(output).toContain("node packages/cli/local.js");
- });
-
test("registers high-level API commands and mcp command", () => {
const { yargs, commands } = createYargs();
@@ -318,45 +300,6 @@ describe("registerCommands", () => {
}
});
- test("keeps grouped subcommands out of top-level help", async () => {
- const rootHelp = await getHelpOutput(["--help"]);
-
- expect(rootHelp).toContain("webstudio import");
- expect(rootHelp).toContain("webstudio publish");
- expect(rootHelp).toContain("webstudio domains");
- expect(rootHelp).toContain("webstudio schema [topic]");
- expect(rootHelp).toContain("webstudio mcp");
- expect(rootHelp).toContain("call MCP tools from the shell");
- expect(rootHelp).not.toContain("webstudio publish deploy");
- expect(rootHelp).not.toContain("webstudio domains list");
-
- const publishHelp = await getHelpOutput(["publish", "--help"]);
- expect(publishHelp).toContain("webstudio publish deploy");
- expect(publishHelp).toContain("webstudio publish list");
-
- const domainsHelp = await getHelpOutput(["domains", "--help"]);
- expect(domainsHelp).toContain("webstudio domains list");
- expect(domainsHelp).toContain("webstudio domains create");
- });
-
- test("shows audit-specific flags and examples", async () => {
- const output = await getHelpOutput(["audit", "--help"]);
-
- expect(output).toContain("webstudio audit");
- expect(output).toContain("--scopes");
- expect(output).toContain("--severities");
- expect(output).toContain("--page-path");
- expect(output).toContain("--page-id");
- expect(output).toContain("--limit");
- expect(output).toContain("--cursor");
- expect(output).toContain("--verbose");
- expect(output).toContain("--rendered");
- expect(output).toContain("--route-example");
- expect(output).toContain("--image-domain");
- expect(output).toContain("--confirm-large-run");
- expect(output).not.toContain("single-op-call <tool>");
- });
-
test("keeps every documented audit CLI example compatible with audit help", async () => {
const docs = await readFile(
new URL("./docs/api-use-cases.md", import.meta.url),
@@ -375,12 +318,4 @@ describe("registerCommands", () => {
expect(output).not.toContain("single-op-call <tool>");
}
});
-
- test("documents registry inspection as a read-only nested command", async () => {
- const output = await getHelpOutput(["registry", "inspect", "--help"]);
-
- expect(output).toContain("--source");
- expect(output).toContain("--item");
- expect(output).toContain("No files are installed");
- });
});
diff --git a/packages/cli/src/commands/api-command-docs.test.ts b/packages/cli/src/commands/api-command-docs.test.ts
index 0b122e1ca4..4235e0b669 100644
--- a/packages/cli/src/commands/api-command-docs.test.ts
+++ b/packages/cli/src/commands/api-command-docs.test.ts
@@ -177,19 +177,6 @@ test("documents MCP use cases with JSON object inputs", () => {
}
});
-test("requires consent before the documented visual workflow", () => {
- const scenario = useCaseScenarios.find(
- ({ useCase }) => useCase === "Visually verify rendered work with AI vision"
- );
- expect(scenario?.commands).toEqual(
- expect.arrayContaining([expect.stringContaining("preview.start")])
- );
- expect(scenario?.notes?.[0]).toContain(
- "only when the user explicitly requests visual verification or opts in"
- );
- expect(scenario?.notes?.[0]).toContain("Do not start preview");
-});
-
test("keeps the documented breakpoint style input executable", async () => {
const line = readCliDoc("api-use-cases")
.split("\n")
@@ -206,82 +193,6 @@ test("keeps the documented breakpoint style input executable", async () => {
).rejects.toThrow("MCP metadata reads must not execute operations.");
});
-test("does not require publishing or sync before MCP editing", () => {
- for (const document of ["manual-llm", "manual-mcp"] as const) {
- const manual = readCliDoc(document);
- const prose = manual.replaceAll(/\s+/g, " ");
- expect(prose).toContain("local CLI");
- expect(prose).toContain("connect");
- expect(prose).toContain("optional");
- expect(prose).toContain("restart");
- expect(prose).not.toContain(
- "followed by `webstudio sync`, then retry `webstudio connect"
- );
- }
- const llmManual = readCliDoc("manual-llm").replaceAll(/\s+/g, " ");
- expect(llmManual).toContain(
- "MCP reads and edits the latest editable Builder build directly"
- );
- expect(llmManual).toContain(
- "including for projects that have never been published"
- );
-});
-
-test("keeps JSX examples readable inside JSON inputs", () => {
- for (const document of [
- "api-use-cases",
- "manual-llm",
- "manual-mcp",
- ] as const) {
- expect(readCliDoc(document)).not.toContain('ws:tag=\\"');
- }
-});
-
-test("documents the Assets result shape", () => {
- for (const document of ["api-use-cases", "manual-llm"] as const) {
- const contents = readCliDoc(document);
- expect(contents).toContain("<dataSourceName>.data");
- expect(contents).toContain("<dataSourceName>.meta");
- expect(contents).toContain("posts.data");
- expect(contents).toContain("post.data");
- expect(contents).toContain("post.data.content.text");
- // Webstudio makes property access safe while compiling expressions, so
- // agent guidance must use the direct source form instead of optional chains.
- expect(contents).not.toContain("?.");
- }
-});
-
-test("documents storage-efficient Assets queries for agents", () => {
- for (const document of ["api-use-cases", "manual-llm"] as const) {
- const contents = readCliDoc(document);
- expect(contents).toContain('output.mode:"fields"');
- expect(contents).toContain("only fields");
- expect(contents).toContain("includeMetadata:false");
- expect(contents).toContain("__diagnostics__.query");
- expect(contents).toContain("__diagnostics__.database");
- expect(contents).toContain("must not be summed");
- expect(contents).toContain("truncated");
- }
-});
-
-test("directs agents to deferred Markdown bodies", () => {
- for (const document of ["api-use-cases", "manual-llm"] as const) {
- const contents = readCliDoc(document);
- expect(contents).toContain('content.mode:"markdown-body-ref"');
- expect(contents).toContain("document reference");
- expect(contents).toContain("selected files");
- }
-
- const tools = createMetadataOnlyMcpAdapter().listTools();
- for (const name of ["create-assets-resource", "update-assets-resource"]) {
- const description = tools.find((tool) => tool.name === name)?.description;
- expect(description).toContain("markdown-body-ref");
- expect(description).toContain("document reference");
- expect(description).toContain("<dataSourceName>.data");
- expect(description).toContain("content.text");
- }
-});
-
test("documents MCP examples with current tool input fields", () => {
const adapter = createMetadataOnlyMcpAdapter();
const toolInputFields = new Map(
diff --git a/packages/cli/src/commands/api-command-metadata.test.ts b/packages/cli/src/commands/api-command-metadata.test.ts
index dd67cafdef..903017613a 100644
--- a/packages/cli/src/commands/api-command-metadata.test.ts
+++ b/packages/cli/src/commands/api-command-metadata.test.ts
@@ -54,7 +54,7 @@ test("describes every grouped CLI command", () => {
}
});
-test("describes root CLI commands once for help-oriented docs", () => {
+test("registers root CLI commands once", () => {
const commands = topLevelCliCommandMetadata.map(({ command }) => command);
expect(new Set(commands).size).toBe(commands.length);
expect(commands.at(0)).toBe("init");
@@ -77,10 +77,6 @@ test("describes root CLI commands once for help-oriented docs", () => {
expect(commands).not.toEqual(
expect.arrayContaining(["publish deploy", "domains list"])
);
- for (const metadata of topLevelCliCommandMetadata) {
- expect(metadata.description.length).toBeGreaterThan(0);
- expect(metadata.examples.length).toBeGreaterThan(0);
- }
});
test("formats removed shell commands as MCP tools", () => {
@@ -127,7 +123,7 @@ test("returns command-specific options when available", () => {
);
});
-test("describes JSON as optional for human-readable permissions", () => {
+test("configures JSON as optional for human-readable permissions", () => {
const yargs = { option: vi.fn().mockReturnThis() };
const metadata = apiCommandMetadata.find(
(item) => item.command === "permissions"
@@ -136,11 +132,10 @@ test("describes JSON as optional for human-readable permissions", () => {
expect(metadata).toBeDefined();
getApiCommandOptions(metadata!)(yargs as never);
- expect(yargs.option).toHaveBeenCalledWith("json", {
- type: "boolean",
- describe: "Print a machine-readable JSON response to stdout",
- default: false,
- });
+ expect(yargs.option).toHaveBeenCalledWith(
+ "json",
+ expect.objectContaining({ type: "boolean", default: false })
+ );
});
test("parses redirect status as a string option", () => {
diff --git a/packages/cli/src/commands/link.test.ts b/packages/cli/src/commands/link.test.ts
index 31f7eeed4a..129fe76bf0 100644
--- a/packages/cli/src/commands/link.test.ts
+++ b/packages/cli/src/commands/link.test.ts
@@ -1,4 +1,3 @@
-import { log } from "@clack/prompts";
import { afterEach, beforeEach, expect, test, vi } from "vitest";
import {
copyFile,
@@ -11,7 +10,7 @@ import {
import { dirname, join } from "node:path";
import { tmpdir } from "node:os";
import { GLOBAL_CONFIG_FILE, LOCAL_CONFIG_FILE } from "../config";
-import { link, parseShareLink, saveShareLink, validateShareLink } from "./link";
+import { parseShareLink, saveShareLink, validateShareLink } from "./link";
const originalCwd = process.cwd();
const projectId = "11111111-1111-4111-8111-111111111111";
@@ -43,21 +42,6 @@ afterEach(async () => {
vi.restoreAllMocks();
});
-test("offers immediate local CLI use without requiring native MCP setup", async () => {
- vi.spyOn(log, "info").mockImplementation(() => {});
- const step = vi.spyOn(log, "step").mockImplementation(() => {});
-
- await link({ link: shareLink });
-
- expect(step).toHaveBeenCalledWith(
- expect.stringContaining("webstudio meta.index` immediately")
- );
- expect(step).toHaveBeenCalledWith(
- expect.stringContaining("webstudio connect <client>` is optional")
- );
- expect(step).not.toHaveBeenCalledWith(expect.stringContaining("sync"));
-});
-
test("parses and validates share links", () => {
expect(parseShareLink(shareLink)).toEqual({
origin: "https://example.com",
diff --git a/packages/cli/src/commands/man.test.ts b/packages/cli/src/commands/man.test.ts
index 158e42fca7..a12ac2ca4e 100644
--- a/packages/cli/src/commands/man.test.ts
+++ b/packages/cli/src/commands/man.test.ts
@@ -10,10 +10,6 @@ import {
mcpOnlyApiCommandMetadata,
topLevelCliCommandMetadata,
} from "./api-command-metadata";
-import {
- generatedAppDependencyNotes,
- getVisionVerificationLoop,
-} from "../mcp-guidance";
import { man } from "./man";
afterEach(() => {
@@ -84,22 +80,6 @@ test("rejects invalid compact manual pagination", () => {
);
});
-test("prints the complete manual in verbose mode", () => {
- vi.spyOn(console, "info").mockImplementation(() => undefined);
-
- man({ json: false, verbose: true });
-
- const output = vi.mocked(console.info).mock.calls.at(-1)?.[0];
- expect(output).toContain("# Webstudio Complete CLI Manual");
- expect(output).toContain("## Top-Level Commands");
- expect(output).toContain("## MCP Capabilities");
- expect(output).toContain("webstudio://project/tools");
- expect(output).toContain("webstudio insert-fragment '<json>'");
- expect(output).toContain("webstudio mcp single-op-call insert-fragment");
- expect(output).not.toContain("## MCP Argument Examples");
- expect(output).not.toContain("### insert-component");
-});
-
test("prints the complete manual as verbose json", () => {
vi.spyOn(console, "info").mockImplementation(() => undefined);
@@ -108,62 +88,12 @@ test("prints the complete manual as verbose json", () => {
const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
expect(output.topic).toBe("all");
expect(output.focusedTopics).toEqual(["api", "llm", "mcp", "content-engine"]);
- expect(output.mcp.discovery).toContain("meta.index");
expect(output.mcp.resources).toContain("webstudio://project/components");
- expect(output.mcp.capabilities).toEqual(
- expect.arrayContaining([expect.stringContaining("Instances/components")])
- );
- expect(output.mcp.boundary).toContain("webstudio insert-fragment");
- expect(output.mcp.boundary).toContain("webstudio mcp single-op-call");
expect(output).not.toHaveProperty("topics");
expect(output.mcp).not.toHaveProperty("commands");
expect(output.mcp).not.toHaveProperty("argumentExamples");
});
-test("prints api manual with patch workflow and examples", () => {
- vi.spyOn(console, "info").mockImplementation(() => undefined);
-
- man({ topic: "api", json: false, verbose: true });
-
- const output = vi.mocked(console.info).mock.calls.at(-1)?.[0];
- expect(output).toContain("webstudio permissions --json");
- expect(output).toContain("Supported namespaces");
- expect(output).toContain("## Use Case Index");
- expect(output).toContain("## CLI Capability Inventory");
- expect(output).toContain("## Known CLI Gaps");
- expect(output).toContain("Create page template");
- expect(output).toContain("MCP tool: create-page-template");
- expect(output).toContain("MCP tool: reorder-page-template");
- expect(output).toContain("Generate from design input");
- expect(output).toContain("### Top-Level Commands");
- expect(output).toContain("### High-Level API Commands By Area");
- expect(output).toContain("### MCP Tool Operations");
- expect(output).toContain("webstudio mcp");
- expect(output).toContain("## Project Session Cache");
- expect(output).toContain("Use --refresh");
- expect(output).toContain("meta.session");
- expect(output).toContain("Visually verify rendered work with AI vision");
- expect(output).toContain("MCP tool: list-breakpoints {}");
- expect(output).not.toContain(" - webstudio list-breakpoints --json");
- expect(output).toContain(
- 'MCP tool: update-project-settings {"meta":{"siteName":"Acme"}}'
- );
- expect(output).toContain("Manage marketplace metadata");
- expect(output).toContain("Create records with semantic operations");
- expect(output).toContain(
- "Do not create generated records, replace generated record collections, replace records with different ids, or mutate record id fields with raw patch"
- );
- for (const { cliCommand } of cliCommandMetadata) {
- expect(output).toContain(`### ${cliCommand}`);
- }
- expect(output).not.toContain("### list-domains\n");
- expect(output).toContain("Operation: list-domains");
- expect(output).not.toContain("### update-props\n");
- expect(output).toContain("- update-props:");
- expect(output).not.toContain("append-instance");
- expect(output).not.toContain("children.json contents");
-});
-
test("prints api manual as json", () => {
vi.spyOn(console, "info").mockImplementation(() => undefined);
@@ -171,28 +101,7 @@ test("prints api manual as json", () => {
const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
expect(output.topic).toBe("api");
- expect(output.workflows).toContain("webstudio permissions --json");
- expect(output.workflows).toContain("webstudio mcp");
- expect(output.workflows).not.toContain(
- "webstudio snapshot --include pages,instances,props,styles,styleSources,styleSourceSelections,dataSources,resources,assets --json"
- );
expect(output.mutationNamespaces).toContain("instances");
- expect(output.sessionBehavior.refreshFlag).toContain("--refresh");
- expect(output.sessionBehavior.metadata).toContain("meta.session");
- expect(output.knownGaps).toEqual(
- expect.arrayContaining([
- expect.objectContaining({
- capability: "Generate from design input",
- }),
- ])
- );
- expect(output.knownGaps).not.toEqual(
- expect.arrayContaining([
- expect.objectContaining({
- capability: "Save and manage page templates",
- }),
- ])
- );
expect(
output.topLevelCommands.map(({ command }: { command: string }) => command)
).toEqual([
@@ -267,20 +176,6 @@ test("prints api manual as json", () => {
({ useCase }: { useCase: string }) => useCase
);
expect(new Set(useCaseTitles).size).toBe(useCaseTitles.length);
- expect(useCaseTitles.at(0)).toBe("Link/configure one project");
- expect(useCaseTitles.at(-1)).toBe("Cross-project maintenance");
- expect(useCaseTitles).toEqual(
- expect.arrayContaining([
- "Visually verify rendered work with AI vision",
- "Create page",
- "Insert authored JSX or one component template",
- "Create resource",
- "Upload one asset",
- "Publish project",
- "Make arbitrary store-level changes",
- "Generate from design input",
- ])
- );
const documentedCommands = new Set([
...output.commands.map(
(command: { operation?: string; command: string }) =>
@@ -341,80 +236,6 @@ test("prints api manual as json", () => {
expect(documentedVisibleCommands).not.toContain("append-instance");
});
-test("prints llm manual with discovery rules", () => {
- vi.spyOn(console, "info").mockImplementation(() => undefined);
-
- man({ topic: "llm", json: false, verbose: true });
-
- const output = vi.mocked(console.info).mock.calls.at(-1)?.[0];
- expect(output).toContain("webstudio schema api");
- expect(output).toContain("webstudio man --json");
- expect(output).toContain("webstudio permissions --json");
- expect(output).toContain("## MCP Argument Examples");
- expect(output).toContain("### insert-fragment\n\n```json\n{");
- expect(output).not.toContain("append-instance");
- expect(output).not.toContain("children.json contents");
- expect(output).toContain('"updates"');
- expect(output).toContain('"instanceId": "instance-id"');
- expect(output).toContain("Never guess ids");
- expect(output).toContain("--refresh");
- expect(output).toContain("## LLM Implementation Process");
- expect(output).toContain("## Visual Design Workflow");
- expect(output).toContain("## Generated Files Guardrails");
- expect(output).toContain("## Values vs Bindings");
- expect(output).toContain("Use `ws:style={css\\`...\\`}`");
- expect(output).toContain("style={{ padding: 24 }}");
- expect(output).toContain("Use Webstudio prop names in JSX");
- expect(output).toContain("Do not wrap the CLI call in `pwd && ...`");
- expect(output).toContain("`node packages/cli/local.js ...`");
- expect(output).toContain(
- "Do not take a broad task such as creating a full design-system page as one execution unit"
- );
- expect(output).toContain('workflow.next {"goal":"design-system-page"}');
- expect(output).toContain("one dry-run JSX section");
- expect(output).toContain("components.coverage-insert-next");
- expect(output).toContain("Phase commands do not include nextPhase");
- expect(output).toContain("`className` or `htmlFor`");
- expect(output).toContain(
- "<radix.Switch><radix.SwitchThumb /></radix.Switch>"
- );
- expect(output).toContain("Use `insert-component` when you want");
- expect(output).toContain("Do not pass `detail` to `list-pages`");
- expect(output).toContain("components.coverage-plan");
- expect(output).toContain(
- "Use `bind-props` only when the prop must stay dynamic"
- );
- expect(output).toContain(
- '{"pageId":"page-id","values":{"title":"Pricing | Acme","meta":{"description":"Plans for teams"}}}'
- );
- expect(output).toContain(
- '{"resourceId":"resource-id","values":{"url":"https://api.example.com/items"}}'
- );
- expect(output).toContain(
- "Make edits through Webstudio semantic commands/MCP tools"
- );
- expect(output).toContain(
- "Do not edit `app/__generated__`, generated route files"
- );
- expect(output).toContain("inspect it with vision");
- expect(output).toContain(
- "Pass --json only to commands whose help/schema documents it"
- );
- expect(output).toContain("## Known Gaps");
- expect(output).toContain("Provider-specific authenticated pages");
-});
-
-test("prints project-editing manual as llm alias", () => {
- vi.spyOn(console, "info").mockImplementation(() => undefined);
-
- man({ topic: "project-editing", json: false, verbose: true });
-
- const output = vi.mocked(console.info).mock.calls.at(-1)?.[0];
- expect(output).toContain("## LLM Implementation Process");
- expect(output).toContain('workflow.next {"goal":"design-system-page"}');
- expect(output).toContain("Use `ws:style={css\\`...\\`}`");
-});
-
test("prints project-editing manual as json alias", () => {
vi.spyOn(console, "info").mockImplementation(() => undefined);
@@ -423,118 +244,6 @@ test("prints project-editing manual as json alias", () => {
const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
expect(output.topic).toBe("project-editing");
expect(output.aliasOf).toBe("llm");
- expect(output.implementationProcess).toEqual(
- expect.arrayContaining([
- expect.stringContaining("webstudio man --json"),
- expect.stringContaining("inspect it with vision"),
- ])
- );
-});
-
-test("prints llm manual as json with implementation process", () => {
- vi.spyOn(console, "info").mockImplementation(() => undefined);
-
- man({ topic: "llm", json: true, verbose: true });
-
- const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
- expect(output.topic).toBe("llm");
- expect(output.implementationProcess).toEqual(
- expect.arrayContaining([
- expect.stringContaining("webstudio man --json"),
- expect.stringContaining("inspect it with vision"),
- ])
- );
- expect(output.visualDesignWorkflow).toEqual(
- expect.arrayContaining([
- expect.stringContaining("Read editable Webstudio structure first"),
- expect.stringContaining(
- "Make edits through Webstudio semantic commands/MCP tools"
- ),
- ])
- );
- expect(output.responsiveVerification).toEqual(
- expect.arrayContaining([
- expect.stringContaining("Read breakpoints with list-breakpoints"),
- expect.stringContaining("viewport"),
- expect.stringContaining("Inspect every viewport screenshot with vision"),
- ])
- );
- expect(output.generatedFileGuardrails).toEqual(
- expect.arrayContaining([
- expect.stringContaining("Do not edit app/__generated__"),
- expect.stringContaining("Generated files are build artifacts"),
- ])
- );
- expect(output.valuesVsBindings).toEqual(
- expect.arrayContaining([
- expect.stringContaining("Use direct value tools for fixed content"),
- expect.stringContaining(
- "Use bind-props only when the prop must stay dynamic"
- ),
- expect.stringContaining("Page metadata fields"),
- ])
- );
- expect(output.rules).toContain(
- "Pass --json only to commands whose help/schema documents it. Do not add --json to top-level commands such as sync unless supported."
- );
- expect(output.rules).toContain(
- "Never run visual verification automatically. Ask first unless the user explicitly requested screenshots, visual verification, or a rendered audit; if they do not opt in, use focused non-visual assertions."
- );
- expect(output.rules).toContain(
- "Use direct values for static strings and bindings only for dynamic expressions/resources/actions."
- );
- expect(output.rules).toContain(
- "Use plain fixed text where documented. Only encode a quoted JavaScript string literal when a field is explicitly documented as an expression-only value."
- );
- expect(output.visionVerificationLoop).toContain(
- getVisionVerificationLoop({ includeDiff: true })[1]
- );
- expect(output.visionVerificationLoop).toEqual(
- expect.arrayContaining([
- expect.stringContaining("list-breakpoints"),
- expect.stringContaining("viewport"),
- ])
- );
- expect(output.screenshotVerification).toContain("screenshot.diff");
- expect(output.screenshotVerification).toContain("list-breakpoints");
-});
-
-test("prints mcp manual with startup and JSON argument examples", () => {
- vi.spyOn(console, "info").mockImplementation(() => undefined);
-
- man({ topic: "mcp", json: false, verbose: true });
-
- const output = vi.mocked(console.info).mock.calls.at(-1)?.[0];
- expect(output).toContain("# Webstudio MCP Manual");
- expect(output).toContain("stdout is reserved for MCP JSON-RPC");
- expect(output).toContain("meta.get-more-tools");
- expect(output).toContain("webstudio://project/tools");
- expect(output).toContain("## MCP SDK Client Imports");
- expect(output).toContain(
- 'import { Client } from "@modelcontextprotocol/sdk/client/index.js";'
- );
- expect(output).toContain(
- 'import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";'
- );
- expect(output).toContain(
- 'import { LoggingMessageNotificationSchema } from "@modelcontextprotocol/sdk/types.js";'
- );
- expect(output).toContain('args: ["packages/cli/local.js", "mcp"]');
- expect(output).toContain("Use `node packages/cli/local.js mcp`");
- expect(output).toContain("## Vision Verification Loop");
- expect(output).toContain("screenshot.diff");
- expect(output).toContain("Read screenshot.diff textAnalysis");
- expect(output).toContain("vision.install-ocr");
- expect(output).toContain('"parentInstanceId": "parent-id"');
- expect(output).toContain("For tools with no required arguments, pass `{}`.");
- expect(output).not.toContain("```json\n{}\n```");
- expect(output).not.toContain("### inspect-auth-context\n");
- expect(output).toContain("### components.coverage-plan\n");
- expect(output).toContain('"documentType": "html"');
- expect(output).toContain(
- "Copying a `.webstudio` folder is not an isolated project clone"
- );
- expect(output).toContain("Use `--dry-run` with local-capable mutation tools");
});
test("prints mcp manual as json", () => {
@@ -544,35 +253,7 @@ test("prints mcp manual as json", () => {
const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
expect(output.topic).toBe("mcp");
- expect(output.discovery).toContain("meta.index");
expect(output.resources).toContain("webstudio://project/tools");
- expect(output.rules).toContain(
- "Never run visual verification automatically. Ask first unless the user explicitly requested screenshots, visual verification, or a rendered audit; if they do not opt in, use focused non-visual assertions."
- );
- expect(output.visionVerificationLoop).toContain(
- getVisionVerificationLoop({ includeDiff: true })[1]
- );
- expect(output.visionVerificationLoop).toContain(
- generatedAppDependencyNotes[0]
- );
- expect(output.visionVerificationLoop).toEqual(
- expect.arrayContaining([
- expect.stringContaining(
- 'Call screenshot with { path: "/" } or the changed page path and viewport'
- ),
- expect.stringContaining("list-breakpoints"),
- expect.stringContaining("viewport"),
- ])
- );
- expect(output.visionVerificationLoop).toEqual(
- expect.arrayContaining([
- expect.stringContaining(
- "Add expectedText when a specific visible phrase must be present"
- ),
- ])
- );
- expect(output.screenshotVerification).toContain("screenshot.diff");
- expect(output.screenshotVerification).toContain("OCR textAnalysis");
expect(output.mcpArgumentExamples["vision.install-ocr"]).toEqual([
{ confirm: true },
]);
@@ -639,15 +320,3 @@ test("prints mcp manual as json", () => {
},
]);
});
-
-test("prints available topics for unknown manual topic", () => {
- vi.spyOn(console, "info").mockImplementation(() => undefined);
-
- man({ topic: "missing", json: false });
-
- expect(vi.mocked(console.info).mock.calls.at(-1)?.[0]).toContain(
- "Available topics"
- );
- expect(vi.mocked(console.info).mock.calls.at(-1)?.[0]).toContain("- all");
- expect(vi.mocked(console.info).mock.calls.at(-1)?.[0]).toContain("- mcp");
-});
diff --git a/packages/cli/src/commands/mcp.test.ts b/packages/cli/src/commands/mcp.test.ts
index f954cc9156..0dd3f07bb5 100644
--- a/packages/cli/src/commands/mcp.test.ts
+++ b/packages/cli/src/commands/mcp.test.ts
@@ -232,7 +232,7 @@ const getArraySchemasWithoutItems = (schema: unknown): unknown[] => {
];
};
-test("documents MCP stdio startup and discovery tools", () => {
+test("configures MCP commands and options", () => {
const yargs = {
command: vi.fn(() => yargs),
option: vi.fn(() => yargs),
@@ -254,13 +254,9 @@ test("documents MCP stdio startup and discovery tools", () => {
})
);
- expect(yargs.example).toHaveBeenCalledWith(
- "$0 mcp",
- "Run a local MCP server over stdio for the configured Webstudio project"
- );
expect(yargs.command).toHaveBeenCalledWith(
["single-op-call <tool> [input]"],
- "Call one MCP tool in a fresh CLI process for debugging",
+ expect.any(String),
expect.any(Function),
expect.any(Function)
);
@@ -276,9 +272,7 @@ test("documents MCP stdio startup and discovery tools", () => {
singleOpBuilder?.(singleOpYargs as never);
expect(singleOpYargs.positional).toHaveBeenCalledWith(
"tool",
- expect.objectContaining({
- describe: expect.stringContaining("insert-fragment"),
- })
+ expect.any(Object)
);
const runBuilder = commandCalls.find(
(call) => call[0][0] === "run <input>"
@@ -288,12 +282,7 @@ test("documents MCP stdio startup and discovery tools", () => {
option: vi.fn(() => runYargs),
};
runBuilder?.(runYargs as never);
- expect(runYargs.option).toHaveBeenCalledWith(
- "dry-run",
- expect.objectContaining({
- describe: "Run local-capable mutation tools without committing",
- })
- );
+ expect(runYargs.option).toHaveBeenCalledWith("dry-run", expect.any(Object));
expect(runYargs.option).toHaveBeenCalledWith(
"approve-mutations",
expect.objectContaining({ default: false })
@@ -308,68 +297,28 @@ test("documents MCP stdio startup and discovery tools", () => {
);
expect(yargs.command).toHaveBeenCalledWith(
["run <input>"],
- "Run an MCP workflow manifest for one or more linked projects",
+ expect.any(String),
expect.any(Function),
expect.any(Function)
);
expect(yargs.command).toHaveBeenCalledWith(
["list-tools"],
- "Print the concise MCP tool catalog as JSON",
+ expect.any(String),
expect.any(Function),
expect.any(Function)
);
expect(yargs.command).toHaveBeenCalledWith(
["list-resources"],
- "List the MCP resources available for the configured project",
+ expect.any(String),
expect.any(Function),
expect.any(Function)
);
expect(yargs.command).toHaveBeenCalledWith(
["read-resource <uri>"],
- "Read one MCP resource by URI",
+ expect.any(String),
expect.any(Function),
expect.any(Function)
);
- expect(yargs.example).toHaveBeenCalledWith(
- "$0 mcp single-op-call meta.index",
- "Debug one MCP tool without writing a stdio client script"
- );
- expect(yargs.example).toHaveBeenCalledWith(
- "$0 mcp list-tools",
- "Print the concise MCP tool catalog"
- );
- expect(yargs.example).toHaveBeenCalledWith(
- "$0 mcp list-resources",
- "List available MCP resources"
- );
- expect(yargs.example).toHaveBeenCalledWith(
- "$0 mcp read-resource webstudio://project/guide",
- "Read the project MCP guide"
- );
- expect(yargs.example).toHaveBeenCalledWith(
- '$0 mcp run \'[{"tool":"components.search","input":{"brief":"button"}}]\'',
- "Run a small multi-step MCP workflow from inline JSON"
- );
- expect(yargs.example).toHaveBeenCalledWith(
- "$0 mcp run .temp/mcp-calls.json",
- "Run a larger bounded multi-step MCP workflow from a file"
- );
- expect(yargs.example).toHaveBeenCalledWith(
- "MCP tool: meta.index",
- "Discover the concise capability catalog after the server starts"
- );
- expect(yargs.epilogue).toHaveBeenCalledWith(
- expect.stringContaining("tools/list")
- );
- expect(yargs.epilogue).toHaveBeenCalledWith(
- expect.stringContaining("current Builder dev build")
- );
- expect(yargs.epilogue).toHaveBeenCalledWith(
- expect.stringContaining("linked Webstudio project root")
- );
- expect(yargs.epilogue).toHaveBeenCalledWith(
- expect.stringContaining("webstudio://project/guide")
- );
});
test("preserves an existing local snapshot before serving MCP tools", async () => {
@@ -643,38 +592,6 @@ 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("checks persisted checkpoints before every MCP run call", async () => {
const dir = await mkdtemp(
path.join(tmpdir(), "webstudio-mcp-run-checkpoint-")
diff --git a/packages/cli/src/commands/preview.test.ts b/packages/cli/src/commands/preview.test.ts
index 67fb4e9d93..3899ba4d0e 100644
--- a/packages/cli/src/commands/preview.test.ts
+++ b/packages/cli/src/commands/preview.test.ts
@@ -24,9 +24,7 @@ import {
preparePreviewProject,
preview,
previewDefaultTemplate,
- previewOptions,
} from "./preview";
-import type { CommonYargsArgv } from "./yargs-types";
import { generatedFilesManifest } from "../prebuild";
const readWindowsPackageFile = (path: string) => {
@@ -922,26 +920,6 @@ test("keeps the standalone React Router preview template", async () => {
});
});
-test("documents generated app dependency setup", () => {
- const yargs = {
- option: () => yargs,
- example: () => yargs,
- epilogue: (text: string) => {
- epilogueText = text;
- return yargs;
- },
- } as unknown as CommonYargsArgv;
- let epilogueText = "";
-
- previewOptions(yargs);
-
- expect(epilogueText).toContain("isolated under .webstudio/preview");
- expect(epilogueText).toContain("reused across regenerations");
- expect(epilogueText).toContain("Do not add generated-preview dependencies");
- expect(epilogueText).not.toContain("WEBSTUDIO_PREVIEW_PACKAGE_MANAGER");
- expect(epilogueText).toContain("reported package-manager path");
-});
-
test("reports the locked preview path, owned PID, and scoped recovery", async () => {
const error = await createPreviewCleanupError({
previewProjectDir: "/project/.webstudio/preview",
diff --git a/packages/cli/src/commands/schema.test.ts b/packages/cli/src/commands/schema.test.ts
index e3ab0f0a99..803592f12a 100644
--- a/packages/cli/src/commands/schema.test.ts
+++ b/packages/cli/src/commands/schema.test.ts
@@ -21,7 +21,6 @@ test("prints api command schema as json", () => {
schema({ topic: "api", json: true, verbose: true, limit: 200 });
const output = JSON.parse(vi.mocked(console.info).mock.calls.at(-1)?.[0]);
- expect(output.projectScope).toContain("single project");
expect(
output.topLevelCommands.map((command: { name: string }) => command.name)
).toEqual(topLevelCliCommandMetadata.map(({ command }) => command));
@@ -85,13 +84,8 @@ test("prints api command schema as json", () => {
])
);
expect(output.mcp.toolCount).toBe(apiCommandMetadata.length);
- expect(output.mcp.discovery).toContain("meta.get-more-tools");
expect(output.mcp.resources).toContain("webstudio://project/tools");
expect(output.mcp.resources).toContain("webstudio://project/components");
- expect(output.mcp.capabilities).toEqual(
- expect.arrayContaining([expect.stringContaining("Instances/components")])
- );
- expect(output.mcp.boundary).toContain("MCP-level");
expect(output.mcp).not.toHaveProperty("commands");
expect(output.mcp).not.toHaveProperty("argumentExamples");
for (const command of output.commands) {
@@ -116,8 +110,6 @@ test("prints api command schema as json", () => {
])
);
expect(output.patch.namespaces).toContain("dataSources");
- expect(output.session.refreshFlag).toContain("--refresh");
- expect(output.session.resultMetadata).toContain("meta.session");
});
test("prints api command schema as json by default", () => {
@@ -148,17 +140,6 @@ test("prints compact mcp tool summaries as json by default", () => {
expect(output.name).toBe("webstudio-mcp");
expect(output.detail).toBe("compact");
expect(output).not.toHaveProperty("callCommand");
- expect(output.singleOpCallCommand).toContain("webstudio mcp single-op-call");
- expect(output.usage).toContain("--verbose");
- expect(output.discovery).toContain(
- `webstudio mcp single-op-call meta.get-more-tools '{"tools":["insert-fragment"]}'`
- );
- expect(output.discovery).toEqual(
- expect.arrayContaining([
- "webstudio mcp single-op-call meta.index",
- expect.stringContaining("components.coverage-plan"),
- ])
- );
expect(output.resources).toEqual(listProjectSessionMcpResources());
expect(output.toolCount).toBe(expectedTools.length);
const handshakePayload = expectedTools.map(
@@ -254,13 +235,6 @@ test("prints full mcp tool input schemas when requested", () => {
]);
const fragmentSchema = insertFragmentTool.inputSchema.properties.fragment;
expect(fragmentSchema.type).toBe("string");
- const jsxDescription = fragmentSchema.description;
- expect(jsxDescription).toContain("not React aliases className or htmlFor");
- expect(jsxDescription).toContain("Use ws:style");
- expect(jsxDescription).toContain("style={{ padding: 24 }}");
- expect(jsxDescription).toContain("include required child/part components");
- expect(jsxDescription).toContain("same parent structure");
- expect(jsxDescription).toContain("use insert-component");
expect(insertFragmentTool.inputSchema.properties).not.toHaveProperty(
"source"
);
diff --git a/packages/cli/src/mcp-guidance.test.ts b/packages/cli/src/mcp-guidance.test.ts
index 1fd2fea39e..2e4cd447a2 100644
--- a/packages/cli/src/mcp-guidance.test.ts
+++ b/packages/cli/src/mcp-guidance.test.ts
@@ -1,66 +1,24 @@
import { expect, test } from "vitest";
import {
- generatedAppDependencyNotes,
getVisionVerificationLoop,
getVisionWorkflowSummary,
- screenshotVerificationSummary,
- visualVerificationRule,
} from "./mcp-guidance";
-test("documents generated app setup for visual verification", () => {
- expect(getVisionVerificationLoop({ includeDiff: false })).toEqual(
- expect.arrayContaining(generatedAppDependencyNotes)
- );
- expect(visualVerificationRule).toContain(
- "generated project files are current"
- );
- expect(visualVerificationRule).toContain(
- "Ask the user whether they want visual verification"
- );
- expect(screenshotVerificationSummary).toContain("preview.start");
- expect(screenshotVerificationSummary).toContain(
- "Iterative mode is the default"
- );
- expect(screenshotVerificationSummary).not.toContain("production-like");
- expect(screenshotVerificationSummary).not.toContain(
- "path screenshots restart preview"
- );
- expect(screenshotVerificationSummary).toContain("list-breakpoints");
- expect(screenshotVerificationSummary).toContain("viewport");
-});
-
-test("builds vision loop with optional screenshot diff guidance", () => {
+test("includes additional vision steps when diff guidance is enabled", () => {
+ const visionLoopWithoutDiff = getVisionVerificationLoop({
+ includeDiff: false,
+ });
const visionLoopWithDiff = getVisionVerificationLoop({ includeDiff: true });
- expect(visionLoopWithDiff[0]).toContain(
- "Ask the user whether they want visual verification"
- );
-
- expect(getVisionVerificationLoop({ includeDiff: false })).not.toEqual(
- expect.arrayContaining([expect.stringContaining("screenshot.diff")])
- );
- expect(visionLoopWithDiff).toEqual(
- expect.arrayContaining([expect.stringContaining("screenshot.diff")])
- );
- expect(visionLoopWithDiff).toEqual(
- expect.arrayContaining([expect.stringContaining("vision.install-ocr")])
- );
- expect(visionLoopWithDiff).toEqual(
- expect.arrayContaining([expect.stringContaining("expectedText")])
- );
- expect(visionLoopWithDiff).toEqual(
- expect.arrayContaining([expect.stringContaining("expectedVisual")])
- );
- expect(visionLoopWithDiff).toEqual(
- expect.arrayContaining([
- expect.stringContaining("list-breakpoints"),
- expect.stringContaining("viewport"),
- ])
- );
- expect(getVisionWorkflowSummary({ includeDiff: false })).not.toContain(
- "screenshot.diff"
- );
- expect(getVisionWorkflowSummary({ includeDiff: true })).toContain(
- "screenshot.diff"
+ expect(visionLoopWithDiff.length).toBeGreaterThan(
+ visionLoopWithoutDiff.length
+ );
+ expect(
+ visionLoopWithDiff.filter(
+ (step) => visionLoopWithoutDiff.includes(step) === false
+ )
+ ).toHaveLength(visionLoopWithDiff.length - visionLoopWithoutDiff.length);
+ expect(getVisionWorkflowSummary({ includeDiff: false })).not.toBe(
+ getVisionWorkflowSummary({ includeDiff: true })
);
});
diff --git a/packages/project-build/src/contracts/builder-runtime.test.ts b/packages/project-build/src/contracts/builder-runtime.test.ts
index 9982ab22c0..3e1d8c3e0f 100644
--- a/packages/project-build/src/contracts/builder-runtime.test.ts
+++ b/packages/project-build/src/contracts/builder-runtime.test.ts
@@ -4,13 +4,6 @@ import {
runtimeOperationContracts,
type RuntimeOperationId,
} from "./builder-runtime";
-import {
- pageDraftFieldHint,
- pageExpressionFieldHint,
- pageStatusFieldHint,
- pagePathFieldHint,
-} from "../runtime/pages";
-import { pageDraftOutputHint } from "../runtime/output-schemas";
import { getBuilderRuntimeOperationInputSchema } from "../runtime/registry";
const knownOperationId: RuntimeOperationId = "pages.list";
@@ -27,7 +20,6 @@ const getSchemaItems = (schema: unknown) =>
const expectPageStatusInputSchema = (schema: unknown) => {
expect(schema).toMatchObject({
- description: pageStatusFieldHint,
anyOf: expect.arrayContaining([
expect.objectContaining({ type: "number" }),
expect.objectContaining({ type: "string" }),
@@ -115,7 +107,7 @@ describe("builder runtime operation contracts", () => {
).not.toContain("pageId");
});
- test("describes page expression inputs in generated contracts", () => {
+ test("exposes page expression inputs in generated contracts", () => {
const createPageInputSchema = getContract("pages.create").inputSchema;
const createPageProperties = getSchemaProperties(createPageInputSchema);
const createPageMetaProperties = getSchemaProperties(
@@ -130,16 +122,13 @@ describe("builder runtime operation contracts", () => {
expect(createPageProperties.title).toMatchObject({
type: "string",
- description: pageExpressionFieldHint,
});
expect(createPageMetaProperties.description).toMatchObject({
type: "string",
- description: pageExpressionFieldHint,
});
expectPageStatusInputSchema(createPageMetaProperties.status);
expect(createPageCustomItemProperties.content).toMatchObject({
type: "string",
- description: pageExpressionFieldHint,
});
const updatePageInputSchema = getContract("pages.update").inputSchema;
@@ -153,11 +142,9 @@ describe("builder runtime operation contracts", () => {
expect(updatePageValueProperties.title).toMatchObject({
type: "string",
- description: pageExpressionFieldHint,
});
expect(updatePageMetaProperties.description).toMatchObject({
type: "string",
- description: pageExpressionFieldHint,
});
expectPageStatusInputSchema(updatePageMetaProperties.status);
});
@@ -186,13 +173,12 @@ describe("builder runtime operation contracts", () => {
});
});
- test("describes page path inputs in generated contracts", () => {
+ test("exposes page path inputs in generated contracts", () => {
const createPageInputSchema = getContract("pages.create").inputSchema;
const createPageProperties = getSchemaProperties(createPageInputSchema);
expect(createPageProperties.path).toMatchObject({
type: "string",
- description: pagePathFieldHint,
});
const updatePageInputSchema = getContract("pages.update").inputSchema;
@@ -202,11 +188,13 @@ describe("builder runtime operation contracts", () => {
);
expect(updatePageValueProperties.path).toMatchObject({
- description: pagePathFieldHint,
+ anyOf: expect.arrayContaining([
+ expect.objectContaining({ type: "string" }),
+ ]),
});
});
- test("explains draft-page behavior in generated MCP contracts", () => {
+ test("exposes draft-page fields in generated MCP contracts", () => {
const updatePageInputSchema = getContract("pages.update").inputSchema;
const updatePageProperties = getSchemaProperties(updatePageInputSchema);
const updatePageValueProperties = getSchemaProperties(
@@ -215,7 +203,6 @@ describe("builder runtime operation contracts", () => {
expect(updatePageValueProperties.isDraft).toMatchObject({
type: "boolean",
- description: pageDraftFieldHint,
});
const listPagesOutputSchema = getContract("pages.list").outputSchema;
@@ -224,7 +211,6 @@ describe("builder runtime operation contracts", () => {
const listPageProperties = getSchemaProperties(listPageItems);
expect(listPageProperties.isDraft).toMatchObject({
type: "boolean",
- description: pageDraftOutputHint,
});
});
diff --git a/packages/project-build/src/mcp.test.ts b/packages/project-build/src/mcp.test.ts
index 07d7ae4c8e..d2f07d377f 100644
--- a/packages/project-build/src/mcp.test.ts
+++ b/packages/project-build/src/mcp.test.ts
@@ -14,7 +14,6 @@ import { componentMetas } from "@webstudio-is/sdk-components-registry/metas";
import { builderPatchTransactionSchema } from "./contracts/patch";
import { runtimeOperationContracts } from "./contracts/builder-runtime";
import { getInputSchemaMetadata } from "./contracts/input-schema";
-import { pageExpressionFieldHint, pageStatusFieldHint } from "./runtime/pages";
import { imageDescriptionsSetInput } from "./runtime/assets";
import { BuilderRuntimeError } from "./runtime/errors";
import {
@@ -94,7 +93,6 @@ const getSchemaProperties = (schema: unknown) =>
const expectPageStatusInputSchema = (schema: unknown) => {
expect(schema).toMatchObject({
- description: pageStatusFieldHint,
anyOf: expect.arrayContaining([
expect.objectContaining({ type: "number" }),
expect.objectContaining({ type: "string" }),
@@ -856,7 +854,6 @@ describe("project session mcp adapter", () => {
expect(
assetOperationTools.find(({ name }) => name === "duplicate-asset-folder")
).toMatchObject({
- description: expect.stringContaining("Recursively duplicate"),
inputSchema: expect.objectContaining({ required: ["folderId"] }),
});
expect(
@@ -881,9 +878,6 @@ describe("project session mcp adapter", () => {
(tool) => tool.name === "set-image-descriptions"
);
expect(imageDescriptionsTool).toMatchObject({
- description: expect.stringContaining(
- "agent-generated image descriptions"
- ),
inputSchema: expect.objectContaining({
required: ["updates"],
}),
@@ -1050,27 +1044,10 @@ describe("project session mcp adapter", () => {
]);
const fragmentSchema = insertFragmentTool?.inputSchema.properties?.fragment;
expect(fragmentSchema).toEqual(expect.objectContaining({ type: "string" }));
- const detailedFragmentSchema =
- insertFragmentTool === undefined
- ? undefined
- : getDetailedProjectSessionMcpInputSchema(insertFragmentTool).properties
- ?.fragment;
expect(
tools.find((tool) => tool.name === "insert-fragment-verified")
?.inputSchema.required
).toEqual(["parentInstanceId", "fragment", "pagePath"]);
- const jsxDescription =
- typeof detailedFragmentSchema === "object" &&
- "description" in detailedFragmentSchema &&
- typeof detailedFragmentSchema.description === "string"
- ? detailedFragmentSchema.description
- : undefined;
- expect(jsxDescription).toContain("not React aliases className or htmlFor");
- expect(jsxDescription).toContain("Use ws:style");
- expect(jsxDescription).toContain("style={{ padding: 24 }}");
- expect(jsxDescription).toContain("include required child/part components");
- expect(jsxDescription).toContain("same parent structure");
- expect(jsxDescription).toContain("use insert-component");
expect(insertFragmentTool?.inputSchema.properties).not.toHaveProperty(
"source"
);
@@ -1223,52 +1200,6 @@ describe("project session mcp adapter", () => {
expect(tool?.inputSchema.properties).not.toHaveProperty("runtime");
});
- test("documents the queried Assets result shape in focused tools", () => {
- const contracts = runtimeOperationContracts.filter(({ id }) =>
- ["assetsResources.create", "assetsResources.update"].includes(id)
- );
- const tools = listProjectSessionMcpTools(
- contracts.map((contract) =>
- publicOperation({
- command: contract.command,
- id: contract.id,
- method: "mutation",
- permit: "build",
- description: contract.command,
- inputSchema: contract.inputSchema,
- readNamespaces: contract.readNamespaces,
- writeNamespaces: contract.writeNamespaces,
- invalidatesNamespaces: contract.invalidatesNamespaces,
- retryOnConflict: contract.retryOnConflict,
- })
- )
- );
-
- const assetsResourceTools = tools.filter(({ name }) =>
- ["create-assets-resource", "update-assets-resource"].includes(name)
- );
- expect(assetsResourceTools).toHaveLength(2);
-
- for (const tool of assetsResourceTools) {
- expect(tool.description).toContain("structured tool input");
- expect(tool.description).toContain("Webstudio JavaScript expression");
- expect(tool.description).toContain("<dataSourceName>.data");
- expect(tool.description).toContain("<dataSourceName>.meta");
- expect(tool.description).toContain("markdown-body-ref");
- expect(tool.description).toContain("document reference");
- expect(tool.description).toContain("content.text");
- expect(tool.description).toContain("result one");
- expect(tool.description).toContain(
- "one final resource per rendered query"
- );
- expect(tool.description).toContain(
- "static filters, limits, and offsets literal"
- );
- expect(tool.description).toContain("remove obsolete duplicates");
- expect(getSchemaProperties(tool.inputSchema)).not.toEqual({});
- }
- });
-
test("defers oversized input schemas until focused discovery", async () => {
const description = "x".repeat(25_000);
const operation = publicOperation({
@@ -1299,9 +1230,9 @@ describe("project session mcp adapter", () => {
name: "meta.get-more-tools",
input: { tools: ["large-input"] },
});
- expect(JSON.stringify(details.structuredContent.data)).toContain(
- description
- );
+ expect(
+ JSON.stringify(details.structuredContent.data).length
+ ).toBeGreaterThan(JSON.stringify(tool?.inputSchema).length);
});
test("keeps array items valid when deferring an oversized schema", () => {
@@ -1409,7 +1340,7 @@ describe("project session mcp adapter", () => {
});
});
- test("exposes page expression input descriptions to MCP clients", async () => {
+ test("exposes page expression inputs to MCP clients", async () => {
const createPageContract = runtimeOperationContracts.find(
(contract) => contract.id === "pages.create"
);
@@ -1434,11 +1365,9 @@ describe("project session mcp adapter", () => {
expect(toolProperties.title).toMatchObject({
type: "string",
- description: pageExpressionFieldHint,
});
expect(toolMetaProperties.description).toMatchObject({
type: "string",
- description: pageExpressionFieldHint,
});
expectPageStatusInputSchema(toolMetaProperties.status);
@@ -1463,11 +1392,9 @@ describe("project session mcp adapter", () => {
expect(toolDetailsProperties.title).toMatchObject({
type: "string",
- description: pageExpressionFieldHint,
});
expect(toolDetailsMetaProperties.description).toMatchObject({
type: "string",
- description: pageExpressionFieldHint,
});
expectPageStatusInputSchema(toolDetailsMetaProperties.status);
});
@@ -2893,7 +2820,7 @@ describe("project session mcp adapter", () => {
captureScreenshot: vi.fn(),
});
- const result = await adapter.callTool({
+ await adapter.callTool({
name: "insert-component",
input: {
parentInstanceId: "body",
@@ -2912,38 +2839,6 @@ describe("project session mcp adapter", () => {
},
})
);
- expect(result.structuredContent.meta).toMatchObject({
- next: [
- expect.stringContaining("Run audit when the change is structural"),
- expect.stringContaining(
- "Ask whether the user wants visual verification"
- ),
- ],
- });
- });
-
- test("requires binding verification after binding-related mutations", async () => {
- const operation = publicOperation({
- command: "bind-props",
- id: "props.bind",
- method: "mutation",
- permit: "edit",
- description: "Bind props",
- writeNamespaces: ["props"],
- invalidatesNamespaces: ["props"],
- });
- const adapter = createProjectSessionMcpCore({
- operations: [operation],
- createProjectSession: createSessionFactory(),
- executeOperation: createExecuteOperation(),
- });
-
- const result = await adapter.callTool({ name: operation.command });
-
- expect(result.structuredContent.meta.next).toEqual([
- expect.stringContaining("run verify-bindings"),
- expect.stringContaining("Run audit when the change is structural"),
- ]);
});
test("normalizes create-page description and preserves basic auth", async () => {
@@ -4180,10 +4075,6 @@ describe("project session mcp adapter", () => {
name: "meta.get-more-tools",
input: { tools: '["insert-fragment"]' },
});
- const insertFragmentDetails = await adapter.callTool({
- name: "meta.get-more-tools",
- input: { tools: ["insert-fragment"] },
- });
const fuzzyDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "styles" },
@@ -4208,27 +4099,7 @@ describe("project session mcp adapter", () => {
);
expect(index.structuredContent.data).toEqual(
expect.objectContaining({
- readThisFirst: expect.stringContaining(
- "first call meta.guide with the user's objective"
- ),
- delegatedAgentRule: expect.stringContaining(
- "shortcut command such as webstudio meta.index"
- ),
startHere: expect.arrayContaining(["meta.guide", "workflow.next"]),
- discovery: expect.objectContaining({
- overview: expect.stringContaining(
- "Do not call every discovery tool up front"
- ),
- tools: expect.stringContaining('"tools"'),
- insertFragment: expect.stringContaining("parentInstanceId"),
- components: expect.stringContaining('"brief"'),
- workflow: expect.stringContaining("workflow.next"),
- }),
- rules: expect.arrayContaining([
- expect.stringContaining(
- "Use direct value tools for fixed text/props"
- ),
- ]),
capabilities: expect.arrayContaining([
expect.objectContaining({
area: "publish",
@@ -4237,63 +4108,6 @@ describe("project session mcp adapter", () => {
]),
})
);
- const indexData = index.structuredContent.data as { readThisFirst: string };
- expect(indexData.readThisFirst).toContain(
- "Never start preview, screenshots, diffs, OCR, or rendered audits automatically"
- );
- expect(indexData.readThisFirst).toEqual(
- expect.stringContaining("delegated or non-streaming agent")
- );
- expect(indexData.readThisFirst).toEqual(
- expect.stringContaining(
- "Copying a `.webstudio` folder is not an isolated project clone"
- )
- );
- expect(indexData.readThisFirst).toEqual(
- expect.stringContaining("pass `--dry-run` to local-capable mutations")
- );
- expect(indexData.readThisFirst).toEqual(
- expect.stringContaining('components.coverage-plan {"detail":"roots"}')
- );
- expect(indexData.readThisFirst).toEqual(
- expect.stringContaining("`list-pages` does not accept `detail`")
- );
- expect(indexData.readThisFirst).toEqual(
- expect.stringContaining(
- "Do not take a broad task such as creating a full design-system page as one execution unit"
- )
- );
- expect(indexData.readThisFirst).toEqual(
- expect.stringContaining('workflow.next {"goal":"design-system-page"}')
- );
- expect(indexData.readThisFirst).toEqual(
- expect.stringContaining("one dry-run JSX section")
- );
- expect(indexData.readThisFirst).toEqual(
- expect.stringContaining("components.coverage-insert-next")
- );
- expect(indexData.readThisFirst).toEqual(
- expect.stringContaining("Phase commands do not include nextPhase")
- );
- expect(indexData.readThisFirst).not.toContain("Page details with");
- const discovery = (
- index.structuredContent.data as {
- discovery: { insertFragment: string };
- }
- ).discovery;
- expect(discovery.insertFragment).toContain("insert-fragment");
- expect(discovery.insertFragment).toContain("parentInstanceId");
- expect(discovery.insertFragment).toContain("not parentId");
- expect(discovery.insertFragment).toContain("ws:style={css`...`}");
- expect(discovery.insertFragment).toContain("style={{ padding: 24 }}");
- expect(discovery.insertFragment).toContain("--input-file");
- expect(discovery.insertFragment).not.toContain('ws:tag=\\"');
- expect(JSON.stringify(index.structuredContent.data)).not.toContain(
- "{ brief }"
- );
- expect(JSON.stringify(index.structuredContent.data)).not.toContain(
- "({ brief })"
- );
expect(index.structuredContent.data).not.toEqual(
expect.objectContaining({
capabilities: expect.arrayContaining([
@@ -4325,13 +4139,7 @@ describe("project session mcp adapter", () => {
goal: "design-system-page",
phase: "discovery",
mustReturnAfter: true,
- parentVisibleCheckpoint: expect.stringContaining(
- "acknowledge this checkpoint first"
- ),
- checkpoint: expect.objectContaining({
- required: true,
- instruction: expect.stringContaining("Stop after this workflow.next"),
- }),
+ checkpoint: expect.objectContaining({ required: true }),
allowedTools: ["components.coverage-plan"],
nextPhase: "page-creation",
})
@@ -4355,10 +4163,6 @@ describe("project session mcp adapter", () => {
fragment: expect.stringContaining("ws:tag='h2'"),
}),
}),
- constraints: expect.arrayContaining([
- expect.stringContaining("Keep the dry-run fragment tiny"),
- expect.stringContaining("do not use deprecated $.Box"),
- ]),
nextPhase: "commit-section",
})
);
@@ -4366,28 +4170,18 @@ describe("project session mcp adapter", () => {
expect.objectContaining({
goal: "design-system-page",
phase: "page-creation",
- purpose: expect.stringContaining("Create it only if lookup proves"),
allowedTools: expect.arrayContaining(["list-pages"]),
commandPattern: expect.stringMatching(/list-pages.*limit/),
fallbackCommandPattern: expect.stringMatching(
/create-page.*\/design-system/
),
- expectedReturn: expect.arrayContaining([
- "whether /design-system already exists",
- "if missing, report that create-page is the next phase action",
- ]),
})
);
expect(workflowPresentationPhase.structuredContent.data).toEqual(
expect.objectContaining({
goal: "design-system-page",
phase: "presentation-pass",
- purpose: expect.stringContaining("real design-system page"),
allowedTools: expect.arrayContaining(["update-styles"]),
- constraints: expect.arrayContaining([
- expect.stringContaining("Do not treat coverage 72/72 as completion"),
- expect.stringContaining("Keep every covered component"),
- ]),
})
);
expect(details.structuredContent.data).toEqual(
@@ -4402,9 +4196,6 @@ describe("project session mcp adapter", () => {
inputSchema: expect.any(Object),
inputFields: ["target", "domains"],
mcpExamples: [{ target: "production" }],
- inputNote: expect.stringContaining(
- "Use direct value tools for fixed text/props"
- ),
}),
],
})
@@ -4416,34 +4207,8 @@ describe("project session mcp adapter", () => {
tools: [expect.objectContaining({ name: "meta.get-more-tools" })],
})
);
- const [publishDetails] = (
- details.structuredContent.data as {
- tools: { inputNote: string }[];
- }
- ).tools;
- expect(publishDetails?.inputNote).toContain(
- "MCP tool arguments are JSON objects, not CLI flags"
- );
- expect(publishDetails?.inputNote).toContain(
- "prefer insert-fragment so JSX is converted locally"
- );
- const [insertFragmentToolDetails] = (
- insertFragmentDetails.structuredContent.data as {
- tools: { mcpExamples: unknown[] }[];
- }
- ).tools;
- const insertFragmentExamples = JSON.stringify(
- insertFragmentToolDetails?.mcpExamples
- );
- expect(insertFragmentExamples).toContain("ws:style={css`");
- expect(insertFragmentExamples).toContain("ws:tag='section'");
- expect(insertFragmentExamples).toContain("style={{ padding: 32");
- expect(insertFragmentExamples).toContain("ws:tokens");
- expect(insertFragmentExamples).toContain("ActionValue");
- expect(insertFragmentExamples).toContain("radix.SwitchThumb");
expect(fuzzyDetails.structuredContent.data).toEqual(
expect.objectContaining({
- usage: expect.stringContaining("capped"),
count: expect.any(Number),
omittedCount: expect.any(Number),
tools: expect.any(Array),
@@ -4788,13 +4553,6 @@ describe("project session mcp adapter", () => {
workflow: "markdown-blog",
},
});
- const expressionGuide = await adapter.callTool({
- name: "meta.guide",
- input: {
- brief: "Bind a dynamic expression to a prop",
- workflow: "expression",
- },
- });
const authenticatedPageGuide = await adapter.callTool({
name: "meta.guide",
input: {
@@ -4823,33 +4581,6 @@ describe("project session mcp adapter", () => {
workflow: "craft",
},
});
- const expectConsentBeforeVisualVerification = (
- guide: typeof markdownBlogGuide
- ) => {
- const workflow = (guide.structuredContent.data as { workflow: string[] })
- .workflow;
- const consentIndex = workflow.findIndex(
- (step) =>
- step.toLocaleLowerCase().includes("ask") &&
- step.toLocaleLowerCase().includes("user wants visual verification")
- );
- const verificationIndex = workflow.findIndex((step) =>
- workflow.some((candidate) =>
- candidate.includes("verify-page-responsive")
- )
- ? step.includes("verify-page-responsive")
- : step.includes("preview")
- );
- expect(consentIndex).toBeGreaterThanOrEqual(0);
- expect(verificationIndex).toBeGreaterThanOrEqual(consentIndex);
- expect(workflow[consentIndex]?.toLocaleLowerCase()).toContain(
- "if they decline"
- );
- };
- expectConsentBeforeVisualVerification(markdownBlogGuide);
- expectConsentBeforeVisualVerification(expressionGuide);
- expectConsentBeforeVisualVerification(authenticatedPageGuide);
- expectConsentBeforeVisualVerification(designInputGuide);
const authenticatedPageGuideTools = (
authenticatedPageGuide.structuredContent.data as {
tools: Array<Record<string, unknown>>;
@@ -4952,12 +4683,6 @@ describe("project session mcp adapter", () => {
});
expect(collectionGuide.structuredContent.data).toEqual(
expect.objectContaining({
- workflow: expect.arrayContaining([
- expect.stringContaining("complete nested array/object"),
- expect.stringContaining("insert-collection"),
- expect.stringContaining("private parameters atomically"),
- expect.stringContaining("stable unique id or slug"),
- ]),
tools: expect.arrayContaining([
expect.objectContaining({ name: "insert-collection" }),
]),
@@ -5003,18 +4728,6 @@ describe("project session mcp adapter", () => {
}),
}),
}),
- workflow: expect.arrayContaining([
- expect.stringContaining("meta.get-more-tools once"),
- expect.stringContaining('"format":"md"'),
- expect.stringContaining("do not create companion files"),
- expect.stringContaining('"/blog/:slug"'),
- expect.stringContaining("create one page per post"),
- expect.stringContaining("exactly one scoped Assets resource"),
- expect.stringContaining("only dynamic value"),
- expect.stringContaining("without a Collection"),
- expect.stringContaining("page settings"),
- expect.stringContaining("Assets-backed content"),
- ]),
tools: expect.arrayContaining([
expect.objectContaining({ name: "upload-assets" }),
expect.objectContaining({ name: "list-pages" }),
@@ -5025,16 +4738,6 @@ describe("project session mcp adapter", () => {
]),
})
);
- expect(expressionGuide.structuredContent.data).toEqual(
- expect.objectContaining({
- workflow: expect.arrayContaining([
- expect.stringContaining("webstudio://project/expressions"),
- expect.stringContaining("do not guess scoped identifier names"),
- expect.stringContaining("one expression rather than a statement"),
- expect.stringContaining("successful syntax validation"),
- ]),
- })
- );
expect(authenticatedPageGuide.structuredContent.data).toEqual(
expect.objectContaining({
recipe: {
@@ -5050,43 +4753,6 @@ describe("project session mcp adapter", () => {
},
},
},
- workflow: expect.arrayContaining([
- expect.stringContaining("existing auth resources"),
- expect.stringContaining("Call inspect-auth-context exactly once"),
- expect.stringContaining(
- "Do not call get-page-by-path to confirm that /account is absent"
- ),
- expect.stringContaining("Do not call meta.index after this guide"),
- expect.stringContaining("Never place credentials"),
- expect.stringContaining(
- "exact terms signed-out, loading, signed-in, and failed-auth"
- ),
- expect.stringContaining("not an authorization boundary"),
- expect.stringContaining(
- "Use create-page's returned rootInstanceId directly"
- ),
- expect.stringContaining(
- "Do not repeat list-variables when the fixture variable is not referenced"
- ),
- expect.stringContaining("recipe.createResourceInput"),
- expect.stringContaining("entire create-resource tool input"),
- expect.stringContaining(
- "Do not call selector-based structural tools"
- ),
- expect.stringContaining("one expression-free semantic fragment"),
- expect.stringContaining("Use that exact fragment verbatim"),
- expect.stringContaining(
- "Do not bind that server-only resource into local preview rendering"
- ),
- expect.stringContaining("insert-fragment-verified"),
- expect.stringContaining(
- "If they opt in, call verify-page-responsive once"
- ),
- expect.stringContaining(
- "Do not call preview.start, screenshot, screenshot.responsive, or audit separately"
- ),
- expect.stringContaining("bundled audit is the static evidence"),
- ]),
tools: expect.arrayContaining([
expect.objectContaining({ name: "list-instances" }),
expect.objectContaining({ name: "insert-fragment-verified" }),
@@ -5096,14 +4762,6 @@ describe("project session mcp adapter", () => {
);
expect(fontAssetGuide.structuredContent.data).toEqual(
expect.objectContaining({
- workflow: expect.arrayContaining([
- expect.stringContaining("returned asset ids directly"),
- expect.stringContaining("without re-uploading"),
- expect.stringContaining("verify-font-assets exactly once"),
- expect.stringContaining(
- "do not call refresh or get-asset separately"
- ),
- ]),
tools: expect.arrayContaining([
expect.objectContaining({ name: "verify-font-assets" }),
]),
@@ -5121,35 +4779,6 @@ describe("project session mcp adapter", () => {
}
expect(designInputGuide.structuredContent.data).toEqual(
expect.objectContaining({
- workflow: expect.arrayContaining([
- expect.stringContaining("Interpret the supplied design"),
- expect.stringContaining(
- "Before the first mutation, call inspect-design-context exactly once"
- ),
- expect.stringContaining(
- "instead of calling list-pages, list-breakpoints"
- ),
- expect.stringContaining("Do not call meta.index"),
- expect.stringContaining("Call create-page exactly once"),
- expect.stringContaining(
- "Do not call list-instances after the first mutation"
- ),
- expect.stringContaining("Do not call get-styles"),
- expect.stringContaining("call verify-page-responsive once"),
- expect.stringContaining("Call insert-fragment-verified exactly once"),
- expect.stringContaining('{"pagePath":"/summer"}'),
- expect.stringContaining("exactly the two supplied viewports"),
- expect.stringContaining("bundled audit is the static evidence"),
- expect.stringContaining("parallel design system"),
- expect.stringContaining("semantic editable structure"),
- expect.stringContaining("actual breakpoint ranges"),
- expect.stringContaining(
- 'Represent literal CSS values as {"type":"keyword","value":"..."}'
- ),
- expect.stringContaining(
- "Do not call preview.start, screenshot, screenshot.responsive, or audit separately"
- ),
- ]),
tools: expect.arrayContaining([
expect.objectContaining({ name: "inspect-design-context" }),
expect.objectContaining({ name: "components.search" }),
@@ -5162,12 +4791,6 @@ describe("project session mcp adapter", () => {
);
expect(craftGuide.structuredContent.data).toEqual(
expect.objectContaining({
- workflow: expect.arrayContaining([
- expect.stringContaining('"scopes":["craft"]'),
- expect.stringContaining("do not add Craft"),
- expect.stringContaining("only the first reported"),
- expect.stringContaining("templateCompatibility"),
- ]),
tools: expect.arrayContaining([
expect.objectContaining({ name: "audit" }),
]),
@@ -5477,7 +5100,6 @@ describe("project session mcp adapter", () => {
expect(session.initialize).not.toHaveBeenCalled();
expect(summary.structuredContent.data).toEqual(
expect.objectContaining({
- usage: expect.stringContaining("Default summary is compact"),
total: expect.any(Number),
templateCount: expect.any(Number),
standaloneInsertableCount: expect.any(Number),
@@ -5518,7 +5140,6 @@ describe("project session mcp adapter", () => {
);
expect(componentRegistry.structuredContent.data).toEqual(
expect.objectContaining({
- usage: expect.stringContaining("compact metadata"),
source: "all",
documentType: "html",
items: expect.arrayContaining([
@@ -5574,13 +5195,8 @@ describe("project session mcp adapter", () => {
).toBeLessThan(50_000);
expect(coveragePlan.structuredContent.data).toEqual(
expect.objectContaining({
- usage: expect.stringContaining("intentionally compact"),
checkpoint: expect.objectContaining({
required: true,
- instruction: expect.stringContaining(
- "Stop after this coverage-plan response"
- ),
- nextAllowedAfterReport: expect.stringContaining("create the page"),
}),
total: expect.any(Number),
rootCount: expect.any(Number),
@@ -5644,7 +5260,6 @@ describe("project session mcp adapter", () => {
);
expect(fullCoveragePlan.structuredContent.data).toEqual(
expect.objectContaining({
- usage: expect.stringContaining("design-system coverage"),
documentType: "html",
total: expect.any(Number),
rootCount: expect.any(Number),
@@ -5715,7 +5330,6 @@ describe("project session mcp adapter", () => {
);
expect(find.structuredContent.data).toEqual(
expect.objectContaining({
- usage: expect.stringContaining("compact, and paged"),
count: expect.any(Number),
totalCount: expect.any(Number),
pagination: expect.objectContaining({
@@ -5808,9 +5422,6 @@ describe("project session mcp adapter", () => {
standaloneInsertable: false,
contentModel: expect.any(Object),
props: expect.any(Object),
- usage: expect.stringContaining(
- "Do not insert this component standalone"
- ),
})
);
expect(buttonDetails.structuredContent.data).toEqual(
@@ -5841,53 +5452,42 @@ describe("project session mcp adapter", () => {
templateRootComponents: [
"@webstudio-is/sdk-components-react-radix:Label",
],
- usage: expect.stringContaining("templateRootComponents"),
})
);
expect(animationGroupDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "@webstudio-is/sdk-components-animation:AnimateChildren",
- animationUsage: expect.stringContaining(
- "Animation Group is the root animation controller"
- ),
props: expect.objectContaining({
action: expect.objectContaining({ type: "animationAction" }),
}),
- usage: expect.stringContaining('fill:"backwards"'),
})
);
expect(textAnimationDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "@webstudio-is/sdk-components-animation:AnimateText",
- animationUsage: expect.stringContaining("splitBy"),
props: expect.objectContaining({
slidingWindow: expect.objectContaining({ defaultValue: 5 }),
splitBy: expect.objectContaining({
options: expect.arrayContaining(["char", "space"]),
}),
}),
- usage: expect.stringContaining("direct child of Animation Group"),
})
);
expect(staggerAnimationDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "@webstudio-is/sdk-components-animation:StaggerAnimation",
- animationUsage: expect.stringContaining("direct children"),
props: expect.objectContaining({
slidingWindow: expect.objectContaining({ defaultValue: 1 }),
}),
- usage: expect.stringContaining("slidingWindow 0"),
})
);
expect(videoAnimationDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "@webstudio-is/sdk-components-animation:VideoAnimation",
hasTemplate: true,
- animationUsage: expect.stringContaining("Video child template"),
props: expect.objectContaining({
timeline: expect.objectContaining({ type: "boolean" }),
}),
- usage: expect.stringContaining("seek-friendly videos"),
})
);
expect(selectDetails.structuredContent.data).toEqual(
@@ -5905,9 +5505,6 @@ describe("project session mcp adapter", () => {
"@webstudio-is/sdk-components-react-radix:SelectItemIndicator",
},
]),
- usage: expect.stringContaining(
- "nest them according to templateRequiredEdges"
- ),
})
);
expect(jsonLdDetails.structuredContent.data).toEqual(
@@ -5925,11 +5522,6 @@ describe("project session mcp adapter", () => {
expect.objectContaining({
component: "ws:collection",
jsxElement: "<ws.collection />",
- description: expect.stringContaining("array or object"),
- collectionUsage: expect.stringMatching(
- /insert-collection.*private item\/itemKey parameters.*atomically/
- ),
- usage: expect.stringContaining("internal Collection parameter"),
props: expect.objectContaining({
data: expect.objectContaining({ type: "json", required: true }),
item: expect.objectContaining({ type: "string" }),
@@ -7924,7 +7516,6 @@ describe("project session mcp adapter", () => {
expect((tools.contents[0]?.text ?? "").length).toBeLessThan(16_000);
expect(JSON.parse(toolsOverview.contents[0]?.text ?? "{}")).toEqual(
expect.objectContaining({
- usage: expect.stringContaining("Short tool overview"),
count: expect.any(Number),
capabilities: expect.arrayContaining([
expect.objectContaining({
@@ -7937,59 +7528,24 @@ describe("project session mcp adapter", () => {
expect(toolsOverview.contents[0]?.text).not.toContain("inputSchema");
expect(JSON.parse(guide.contents[0]?.text ?? "{}")).toEqual(
expect.objectContaining({
- readThisFirst: expect.stringContaining(
- "do one small discovery step, then act"
- ),
- delegatedAgentRule: expect.stringContaining(
- "shortcut command such as webstudio meta.index"
- ),
startHere: expect.arrayContaining(["meta.index"]),
- discovery: expect.objectContaining({
- overview: expect.stringContaining(
- "Do not call every discovery tool up front"
- ),
- components: expect.stringContaining("components.summary"),
- }),
- rules: expect.arrayContaining([
- expect.stringContaining(
- "Use direct value tools for fixed text/props"
- ),
- ]),
})
);
expect(accessibilityReview.contents[0]).toEqual(
expect.objectContaining({
mimeType: "text/markdown",
- text: expect.stringContaining("# Webstudio Accessibility Review"),
})
);
- expect(accessibilityReview.contents[0]?.text).toContain(
- "Community-Access/accessibility-agents"
- );
expect(expressions.contents[0]).toEqual(
expect.objectContaining({
mimeType: "text/markdown",
- text: expect.stringContaining("# Webstudio Expressions"),
})
);
- expect(expressions.contents[0]?.text).toContain("Supported string methods");
- expect(expressions.contents[0]?.text).toContain("- `toLowerCase`");
- expect(expressions.contents[0]?.text).toContain("- `join`");
- expect(expressions.contents[0]?.text).toContain(
- "leave identifier property names unquoted"
- );
- expect(expressions.contents[0]?.text).not.toContain(
- "{{allowedStringMethods}}"
- );
- expect(expressions.contents[0]?.text).toContain(
- "Collection creates internal `collectionItem` and `collectionItemKey`"
- );
const componentOverviewData = JSON.parse(
componentsOverview.contents[0]?.text ?? "{}"
);
expect(componentOverviewData).toEqual(
expect.objectContaining({
- usage: expect.stringContaining("components.list"),
count: expect.any(Number),
namespaces: expect.objectContaining({
"@webstudio-is/sdk-components-react-radix": expect.any(Number),
diff --git a/packages/project-build/src/runtime/craft-profile.test.ts b/packages/project-build/src/runtime/craft-profile.test.ts
index 58b4b22883..038f38d59b 100644
--- a/packages/project-build/src/runtime/craft-profile.test.ts
+++ b/packages/project-build/src/runtime/craft-profile.test.ts
@@ -82,11 +82,7 @@ describe("Craft authoring profile", () => {
status: "compatible",
satisfiedRequiredChecks: 2,
totalRequiredChecks: 2,
- nextAction: "No Craft profile change is required.",
templateCompatibility: { status: "compatible" },
- guidance: expect.arrayContaining([
- expect.stringContaining("Preserve existing project-specific values"),
- ]),
});
expect(result.matches).toEqual([]);
});
@@ -111,7 +107,6 @@ describe("Craft authoring profile", () => {
expect(result.status).toMatchObject({
status: "partial",
satisfiedRequiredChecks: 0,
- nextAction: expect.stringContaining("--foreground-muted"),
templateCompatibility: { status: "requires-review" },
});
expect(result.matches).toEqual(
diff --git a/packages/project-build/src/runtime/pages.test.ts b/packages/project-build/src/runtime/pages.test.ts
index 4df2c88927..99dfad8191 100644
--- a/packages/project-build/src/runtime/pages.test.ts
+++ b/packages/project-build/src/runtime/pages.test.ts
@@ -782,7 +782,6 @@ describe("serialized page helpers", () => {
status: "404",
},
},
- guidance: expect.stringContaining("No exact page exists"),
});
});
diff --git a/packages/project-build/src/runtime/props.test.ts b/packages/project-build/src/runtime/props.test.ts
index 515a76c48d..78d6ec9e07 100644
--- a/packages/project-build/src/runtime/props.test.ts
+++ b/packages/project-build/src/runtime/props.test.ts
@@ -148,14 +148,12 @@ describe("findProp", () => {
});
test("defines show attribute metadata in runtime", () => {
- expect(showAttributeMeta).toEqual({
+ expect(showAttributeMeta).toMatchObject({
label: "Show",
required: false,
control: "boolean",
type: "boolean",
defaultValue: true,
- description:
- "Removes the instance from the DOM. Breakpoints have no effect on this setting.",
});
});
diff --git a/packages/project-build/src/runtime/registry.test.ts b/packages/project-build/src/runtime/registry.test.ts
index 3363cdf5b2..b4cf2fe6b4 100644
--- a/packages/project-build/src/runtime/registry.test.ts
+++ b/packages/project-build/src/runtime/registry.test.ts
@@ -2187,7 +2187,7 @@ describe("builder runtime registry", () => {
}
});
- test("publishes truthful inputs for asset, page-copy, style-source, and resource operations", () => {
+ test("publishes truthful inputs for asset and page-copy operations", () => {
const addAssetOperation = getBuilderRuntimeOperation("assets.add");
const addAssetSchema = toInputJsonSchemaObject(
addAssetOperation.inputJsonSchema
@@ -2197,44 +2197,16 @@ describe("builder runtime registry", () => {
);
expect(JSON.stringify(assetSchema)).not.toContain("projectId");
- for (const operationId of [
- "resources.create",
- "resources.update",
- ] as const) {
- const operation = getBuilderRuntimeOperation(operationId);
- const schema = toInputJsonSchemaObject(operation.inputJsonSchema);
- expect(
- toInputJsonSchemaObject(schema?.properties?.exposeAsDataSource)
- ?.description
- ).toContain("write resources default to false");
- }
-
const copyPageOperation = getBuilderRuntimeOperation("pages.copy");
const copyPageSchema = toInputJsonSchemaObject(
copyPageOperation.inputJsonSchema
);
expect(copyPageSchema?.required).toContain("sourceData");
- expect(
- toInputJsonSchemaObject(copyPageSchema?.properties?.sourceData)
- ?.description
- ).toContain("use duplicate-page");
expectRuntimeValidationError(
"pages.copy",
{ pageId: "home" },
{ path: ["sourceData"] }
);
-
- const duplicateStyleSourceOperation = getBuilderRuntimeOperation(
- "styleSources.duplicate"
- );
- const duplicateStyleSourceSchema = toInputJsonSchemaObject(
- duplicateStyleSourceOperation.inputJsonSchema
- );
- expect(
- toInputJsonSchemaObject(
- duplicateStyleSourceSchema?.properties?.styleSourceId
- )?.description
- ).toContain("Local style sources cannot be duplicated");
});
test("publishes Content Block replacement confirmation", () => {
diff --git a/packages/project-build/src/runtime/styles.test.ts b/packages/project-build/src/runtime/styles.test.ts
index 0f588f7ecb..624870ca72 100644
--- a/packages/project-build/src/runtime/styles.test.ts
+++ b/packages/project-build/src/runtime/styles.test.ts
@@ -2214,7 +2214,6 @@ describe("style declaration helpers", () => {
expect(
getInputSchemaMetadata(styleUpdateInput).inputJsonSchema.properties?.value
).toMatchObject({
- description: "Typed CSS StyleValue object.",
examples: [{ type: "keyword", value: "red" }],
type: "object",
properties: {
diff --git a/packages/protocol/src/asset-resource-api.test.ts b/packages/protocol/src/asset-resource-api.test.ts
index 1010dbbe35..cc98b3763b 100644
--- a/packages/protocol/src/asset-resource-api.test.ts
+++ b/packages/protocol/src/asset-resource-api.test.ts
@@ -335,7 +335,7 @@ describe("Assets OpenAPI description", () => {
expect(
document.paths[assetResourceApiOperations.deleteAsset.path].delete
.responses[204]
- ).toEqual({ description: "Asset deleted" });
+ ).toBeDefined();
expect(
document.paths[assetResourceApiOperations.downloadAssetContent.path].get
.responses[206]
@@ -439,9 +439,6 @@ describe("Assets OpenAPI description", () => {
{ value: "last", label: "Last" },
],
});
- expect(definition.description).toMatch(
- /^Autocomplete includes \d+ of 4096 observed content fields/
- );
expect(definition.fields.length).toBeGreaterThan(
assetQueryStandardFields.length
);
diff --git a/packages/protocol/src/builder-api/operation-docs.test.ts b/packages/protocol/src/builder-api/operation-docs.test.ts
index 2754bec556..55c223715f 100644
--- a/packages/protocol/src/builder-api/operation-docs.test.ts
+++ b/packages/protocol/src/builder-api/operation-docs.test.ts
@@ -16,7 +16,7 @@ const getSourceOperationCommands = () => [
const sortCommands = (commands: readonly string[]) =>
[...commands].sort((left, right) => left.localeCompare(right));
-test("documents every public API command with examples", () => {
+test("keeps public API operation coverage aligned", () => {
expect(
sortCommands(publicApiOperationDocumentation.map(({ command }) => command))
).toEqual(sortCommands(getSourceOperationCommands()));
@@ -28,118 +28,4 @@ test("documents every public API command with examples", () => {
expect(publicApiOperations.map(({ command }) => command)).toEqual(
publicApiOperationDocumentation.map(({ command }) => command)
);
-
- for (const item of publicApiOperationDocumentation) {
- expect(item.description).not.toBe("");
- expect(item.description).not.toContain("MCP/public API operation");
- expect(item.examples.length).toBeGreaterThan(0);
- }
-});
-
-test("documents update-text mode without suggesting replace", () => {
- const docs = publicApiOperationDocumentation.find(
- ({ command }) => command === "update-text"
- );
-
- expect(docs).toEqual(
- expect.objectContaining({
- description: expect.stringContaining(
- 'mode must be "text" or "expression"'
- ),
- examples: [
- expect.stringContaining("--mode text"),
- expect.stringContaining("--mode expression"),
- ],
- })
- );
- expect(`${docs?.description}\n${docs?.examples.join("\n")}`).not.toContain(
- "--mode replace"
- );
-});
-
-test("documents default instance props and opt-in details", () => {
- const docs = publicApiOperationDocumentation.find(
- ({ command }) => command === "inspect-instance"
- );
- const text = `${docs?.description}\n${docs?.examples.join("\n")}`;
-
- expect(text).toContain("classes and custom attributes by default");
- expect(text).toContain("styles,children,ancestors");
-});
-
-test("documents set-text-content discriminators", () => {
- const docs = publicApiOperationDocumentation.find(
- ({ command }) => command === "set-text-content"
- );
- const text = `${docs?.description}\n${docs?.examples.join("\n")}`;
-
- expect(text).toContain('"operation":"set"');
- expect(text).toContain('"operation":"reset"');
-});
-
-test("documents direct string props for update-props", () => {
- const docs = publicApiOperationDocumentation.find(
- ({ command }) => command === "update-props"
- );
-
- expect(docs?.description).toContain('"name": "placeholder"');
- expect(docs?.description).toContain('"type": "string"');
-});
-
-test("guides agents to keep Assets content databases small", () => {
- const getDescription = (command: string) =>
- publicApiOperationDocumentation.find((item) => item.command === command)
- ?.description ?? "";
-
- expect(getDescription("create-assets-resource")).toContain(
- "selecting only fields the page renders"
- );
- expect(getDescription("create-assets-resource")).toContain(
- "content mode none"
- );
- expect(getDescription("update-assets-resource")).toContain(
- "only rendered fields"
- );
- for (const command of ["create-assets-resource", "update-assets-resource"]) {
- expect(getDescription(command)).toContain("$ref");
- expect(getDescription(command)).toContain("#body");
- expect(getDescription(command)).toContain("content mode none");
- }
- expect(getDescription("preview-asset-query")).toContain("usedBytes");
- expect(getDescription("preview-asset-query")).toContain("truncated");
-});
-
-test("documents JSX insertion through the fragment field", () => {
- const docs = publicApiOperationDocumentation.find(
- ({ command }) => command === "insert-fragment"
- );
- const text = `${docs?.description}\n${docs?.examples.join("\n")}`;
-
- expect(text).toContain("Webstudio JSX");
- expect(text).toContain("CLI converts the JSX string");
- expect(text).toContain('"fragment":"<ws.element ws:tag=\'section\' />"');
- expect(text).not.toContain("Internal low-level");
- 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/operations.test.ts b/packages/protocol/src/builder-api/operations.test.ts
index ce69a957e5..0f63ab0f29 100644
--- a/packages/protocol/src/builder-api/operations.test.ts
+++ b/packages/protocol/src/builder-api/operations.test.ts
@@ -26,15 +26,7 @@ describe("public api operation catalog", () => {
expect(new Set(ids).size).toBe(ids.length);
});
- test("owns documentation metadata for every command", () => {
- for (const operation of publicApiOperations) {
- expect(operation.description).not.toBe("");
- expect(operation.examples.length).toBeGreaterThan(0);
- expect(Array.isArray(operation.inputFields)).toBe(true);
- }
- });
-
- test("keeps documentation in sync with implemented commands", () => {
+ test("keeps the public operation catalog aligned with implemented commands", () => {
const implementedCommands = [
...publicRuntimeOperationContracts.map((operation) => operation.command),
...Object.values(serverOnlyRouterOperationMetadata).map(
@@ -141,7 +133,6 @@ describe("public api operation catalog", () => {
).toMatchObject({
type: "string",
enum: ["text", "expression"],
- description: expect.stringContaining('There is no "replace" mode.'),
});
const resourceInputSchema =
getPublicApiOperation("create-resource").inputSchema?.properties
diff --git a/scripts/docs/generate-content-engine-docs.test.ts b/scripts/docs/generate-content-engine-docs.test.ts
deleted file mode 100644
index 9cbb587c6f..0000000000
--- a/scripts/docs/generate-content-engine-docs.test.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { renderContentEngineDocumentation } from "./generate-content-engine-docs.js";
-
-test("renders the shared reference inside a generated GitBook page", () => {
- const reference =
- "# Content Engine reference\n\n## Result modes\n\nReference body.\n";
- const generated = renderContentEngineDocumentation(reference);
-
- assert.ok(generated.startsWith("---\n"));
- assert.ok(generated.includes(reference.trim()));
- assert.equal(generated.includes("{{reference}}"), false);
-});
-
-test("rejects an unexpected CLI manual", () => {
- assert.throws(
- () => renderContentEngineDocumentation("# Different manual"),
- /Expected the CLI manual/
- );
-});
diff --git a/scripts/docs/generate-mcp-docs.test.ts b/scripts/docs/generate-mcp-docs.test.ts
deleted file mode 100644
index 69820b5d0e..0000000000
--- a/scripts/docs/generate-mcp-docs.test.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { renderMcpDocumentation } from "./generate-mcp-docs.js";
-
-test("renders GitBook metadata around the complete CLI manual", () => {
- const generated = renderMcpDocumentation(
- "# Webstudio MCP Manual\n\n## Startup\n\nStart here.\n",
- "1.2.3"
- );
-
- assert.match(generated, /^---\n/);
- assert.match(
- generated,
- /# Webstudio MCP\n\n\*\*Webstudio MCP v1\.2\.3\*\*\n/
- );
- assert.match(
- generated,
- /GitBook publishes it when that revision is successfully released/
- );
- assert.match(
- generated,
- /See \[CLI\]\(cli\.md\) for Node\.js and\s+`npx` setup/
- );
- assert.match(generated, /## Startup\n\nStart here\./);
- assert.match(generated, /## Related\n/);
- assert.equal(generated.includes("# Webstudio MCP Manual"), false);
-});
-
-test("rejects an unexpected CLI manual", () => {
- assert.throws(
- () => renderMcpDocumentation("# Different manual", "1.2.3"),
- /Expected the CLI manual/
- );
-});
-
-test("rejects a missing CLI version", () => {
- assert.throws(
- () => renderMcpDocumentation("# Webstudio MCP Manual\n\nBody", ""),
- /Expected a CLI version/
- );
-});
diff --git a/scripts/docs/mcp-page.md b/scripts/docs/mcp-page.md
index cb93d4c4a2..2e683b7aa2 100644
--- a/scripts/docs/mcp-page.md
+++ b/scripts/docs/mcp-page.md
@@ -11,6 +11,15 @@ icon: robot
**Webstudio MCP v{{version}}**
+## Introduction
+
+All you need to do is install the Codex desktop app or Claude Desktop and tell
+it:
+
+> Install Webstudio CLI and use MCP.
+
+---
+
{% hint style="info" %}
This reference is generated from the Webstudio CLI source in the same Builder
revision. GitBook publishes it when that revision is successfully released.