Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.
TypeScript accessibilityalternativecloudflarecloudflare-workersdesignfreefrontendopen-sourceradix-uireactremixweb-developmentwebflowwebsite-builderwebsite-developmentwebsiteswebstudio
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { PassThrough } from "node:stream";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { LoggingMessageNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
import { ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
import { parseExpressionAt } from "acorn";
import { describe, expect, test, vi } from "vitest";
import { z } from "zod";
import { parseDirectPathExpression } from "@webstudio-is/expression";
import type { WsComponentMeta } from "@webstudio-is/sdk";
import { componentMetas } from "@webstudio-is/sdk-components-registry/metas";
import { validateAssetQuery } from "@webstudio-is/content-engine";
import { builderPatchTransactionSchema } from "./contracts/patch";
import { runtimeOperationContracts } from "./contracts/builder-runtime";
import { getInputSchemaMetadata } from "./contracts/input-schema";
import { imageDescriptionsSetInput } from "./runtime/assets";
import { BuilderRuntimeError } from "./runtime/errors";
import { parseWebstudioJsxFragment } from "./runtime/jsx";
import {
createProjectSessionMcpCore,
createProjectSessionMcpServer,
createMcpStdioTransport,
getDetailedProjectSessionMcpInputSchema,
hiddenMcpOperationCommands,
isReadOnlyProjectSessionMcpTool,
listProjectSessionMcpResources,
listProjectSessionMcpTools,
type PublicMcpOperation,
type ProjectSessionMcpGuidance,
type ProjectSessionScreenshotInput,
} from "./mcp";
import { getComponentTemplates } from "./runtime/component-templates";
import { insertFragmentInput } from "./runtime/components";
import { createEmptyWebstudioFragment } from "./runtime/component-template";
import {
projectSessionBusyMessage,
type ProjectSessionEnvelope,
} from "./project-session";
import { diffPngFiles } from "@webstudio-is/vision/diff";
import {
createPng,
paintRect,
writePng,
} from "@webstudio-is/vision/test-utils";
type CreateProjectSession = NonNullable<
Parameters<typeof createProjectSessionMcpCore>[0]["createProjectSession"]
>;
type ExecuteOperation = NonNullable<
Parameters<typeof createProjectSessionMcpCore>[0]["executeOperation"]
>;
type TestSession = ReturnType<CreateProjectSession>;
type TestPublicMcpOperation = Pick<
PublicMcpOperation,
"command" | "id" | "description"
> &
Partial<PublicMcpOperation>;
const runtimeContractById = new Map<
string,
(typeof runtimeOperationContracts)[number]
>(runtimeOperationContracts.map((contract) => [contract.id, contract]));
const publicOperation = (
operation: TestPublicMcpOperation
): PublicMcpOperation => {
const { inputSchema = getTestInputSchema(z.object({})), ...operationFields } =
operation;
const merged: Omit<PublicMcpOperation, "inputSchema"> = {
method: "query",
permit: "view",
localCapable: true,
serverOnly: false,
readNamespaces: [],
writeNamespaces: [],
invalidatesNamespaces: [],
retryOnConflict: false,
requiresConfirm: false,
outputSchema: runtimeContractById.get(operation.id)?.outputSchema,
...operationFields,
};
return { ...merged, inputSchema };
};
const getTestInputSchema = (inputSchema: z.ZodTypeAny) =>
getInputSchemaMetadata(inputSchema).inputJsonSchema;
const getSchemaProperties = (schema: unknown) =>
(schema as { properties?: Record<string, unknown> }).properties ?? {};
const expectPageStatusInputSchema = (schema: unknown) => {
expect(schema).toMatchObject({
anyOf: expect.arrayContaining([
expect.objectContaining({ type: "number" }),
expect.objectContaining({ type: "string" }),
]),
});
};
const getSuccessfulOutputDataSchema = (schema: unknown) => {
const variants = (schema as { oneOf?: unknown[] }).oneOf ?? [];
const success = variants.find(
(variant) =>
getSchemaProperties(variant).ok !== undefined &&
(getSchemaProperties(variant).ok as { const?: unknown }).const === true
);
return getSchemaProperties(success).data;
};
const getUnresolvedLocalSchemaRefs = (
schema: unknown,
root = schema,
path: readonly string[] = []
): string[] => {
if (schema === null || typeof schema !== "object") {
return [];
}
const object = schema as Record<string, unknown>;
const ref = object.$ref;
const unresolved =
typeof ref === "string" && ref.startsWith("#/")
? ref
.slice(2)
.split("/")
.map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"))
.reduce<unknown>(
(value, segment) =>
value !== null && typeof value === "object"
? (value as Record<string, unknown>)[segment]
: undefined,
root
) === undefined
? [`${path.join(".")}: ${ref}`]
: []
: [];
return [
...unresolved,
...Object.entries(object).flatMap(([key, value]) =>
getUnresolvedLocalSchemaRefs(value, root, [...path, key])
),
];
};
const getArraySchemasWithoutItems = (
schema: unknown,
path: readonly string[] = []
): string[] => {
if (schema === null || typeof schema !== "object") {
return [];
}
if (Array.isArray(schema)) {
return schema.flatMap((value, index) =>
getArraySchemasWithoutItems(value, [...path, String(index)])
);
}
const object = schema as Record<string, unknown>;
const current =
object.type === "array" && object.items === undefined
? [path.join(".")]
: [];
return [
...current,
...Object.entries(object).flatMap(([name, value]) =>
getArraySchemasWithoutItems(value, [...path, name])
),
];
};
const optionalArrayFieldInputSchema = (field: string) =>
getTestInputSchema(
z.object({
[field]: z.array(z.unknown()).optional(),
})
);
const styleOperation = (
operation: TestPublicMcpOperation & {
readNamespaces: PublicMcpOperation["readNamespaces"];
}
): PublicMcpOperation =>
publicOperation({
method: "mutation",
permit: "edit",
writeNamespaces: ["styles"],
invalidatesNamespaces: ["styles"],
retryOnConflict: true,
...operation,
});
const publicMcpOperations: readonly PublicMcpOperation[] = [
publicOperation({
command: "list-pages",
id: "pages.list",
description: "List pages",
inputSchema: getTestInputSchema(
z.object({ includeFolders: z.boolean().optional() })
),
readNamespaces: ["pages"],
}),
publicOperation({
command: "get-page-by-path",
id: "pages.getByPath",
description: "Get page by path",
inputSchema: getTestInputSchema(z.object({ path: z.string() })),
readNamespaces: ["pages"],
}),
publicOperation({
command: "audit",
id: "project.audit",
description: "Audit project quality",
inputSchema: getTestInputSchema(
z.object({
scopes: z
.array(
z.enum([
"accessibility",
"security",
"seo",
"assets",
"styles",
"performance",
])
)
.optional(),
severities: z.array(z.enum(["error", "warning", "info"])).optional(),
pageId: z.string().optional(),
pagePath: z.string().optional(),
limit: z.number().int().min(1).max(200).optional(),
cursor: z.string().optional(),
verbose: z.boolean().optional(),
})
),
outputSchema: getTestInputSchema(
z.discriminatedUnion("verbose", [
z.object({
contractVersion: z.literal(2),
projectVersion: z.number(),
verbose: z.literal(false),
findings: z.array(z.unknown()),
renderedCheckCount: z.number(),
renderedIssueCount: z.number(),
renderedFailureCount: z.number(),
}),
z.object({
contractVersion: z.literal(2),
projectVersion: z.number(),
verbose: z.literal(true),
findings: z.array(z.unknown()),
renderedCheckCount: z.number(),
renderedIssueCount: z.number(),
renderedFailureCount: z.number(),
renderedChecks: z.array(z.unknown()),
renderedFailures: z.array(z.unknown()),
}),
])
),
readNamespaces: [
"pages",
"instances",
"props",
"styles",
"styleSources",
"styleSourceSelections",
"resources",
"dataSources",
"assets",
"breakpoints",
],
}),
publicOperation({
command: "verify-bindings",
id: "project.verifyBindings",
description: "Verify persisted bindings",
inputSchema: getTestInputSchema(
z.object({
pagePath: z.string().optional(),
instanceId: z.string().optional(),
limit: z.number().int().positive().optional(),
})
),
readNamespaces: ["pages", "instances", "props", "resources", "dataSources"],
}),
publicOperation({
command: "list-breakpoints",
id: "breakpoints.list",
description: "List breakpoints",
readNamespaces: ["breakpoints"],
}),
publicOperation({
command: "list-design-tokens",
id: "designTokens.list",
description: "List design tokens",
readNamespaces: ["styleSources", "styles"],
}),
publicOperation({
command: "whoami",
id: "auth.me",
description: "Identify token",
localCapable: false,
serverOnly: true,
}),
publicOperation({
command: "list-instances",
id: "instances.list",
description: "List instances",
inputSchema: getTestInputSchema(
z.object({
rootInstanceId: z.string().optional(),
maxDepth: z.number().int().nonnegative().optional(),
})
),
readNamespaces: ["pages", "instances", "props"],
}),
publicOperation({
command: "insert-fragment",
id: "instances.insertFragment",
method: "mutation",
permit: "edit",
description: "Insert fragment",
inputSchema: getTestInputSchema(insertFragmentInput),
readNamespaces: ["pages", "instances"],
writeNamespaces: ["instances", "props", "styles"],
invalidatesNamespaces: ["instances", "props", "styles"],
}),
publicOperation({
command: "insert-collection",
id: "instances.insertCollection",
method: "mutation",
permit: "build",
description: "Insert a semantic Collection",
readNamespaces: ["pages", "instances", "dataSources"],
writeNamespaces: ["instances", "props", "dataSources"],
invalidatesNamespaces: ["instances", "props", "dataSources"],
}),
publicOperation({
command: "list-texts",
id: "texts.list",
description: "List text children",
inputSchema: getTestInputSchema(
z.object({
pagePath: z.string().optional(),
})
),
readNamespaces: ["pages", "instances"],
}),
publicOperation({
command: "update-text",
id: "texts.update",
method: "mutation",
permit: "edit",
description: "Update text child",
inputSchema: getTestInputSchema(
z.object({
instanceId: z.string(),
childIndex: z.number(),
text: z.string(),
})
),
readNamespaces: ["instances"],
writeNamespaces: ["instances"],
invalidatesNamespaces: ["instances"],
}),
publicOperation({
command: "publish",
id: "build.publish",
method: "mutation",
permit: "build",
description: "Publish project",
inputSchema: getTestInputSchema(
z.object({
target: z.string().optional(),
domains: z.array(z.string()).optional(),
})
),
localCapable: false,
serverOnly: true,
}),
publicOperation({
command: "delete-instance",
id: "instances.delete",
method: "mutation",
permit: "edit",
description: "Delete instances",
inputSchema: getTestInputSchema(
z.object({
instanceIds: z.array(z.string()),
})
),
writeNamespaces: ["instances"],
invalidatesNamespaces: ["instances"],
requiresConfirm: true,
}),
publicOperation({
command: "move-instance",
id: "instances.move",
method: "mutation",
permit: "edit",
description: "Move instances",
inputSchema: getTestInputSchema(
z.object({
moves: z.array(z.unknown()),
})
),
readNamespaces: ["instances"],
writeNamespaces: ["instances"],
invalidatesNamespaces: ["instances"],
}),
publicOperation({
command: "clone-instance",
id: "instances.clone",
method: "mutation",
permit: "edit",
description: "Clone instance subtree",
inputSchema: getTestInputSchema(
z.object({
sourceInstanceId: z.string(),
targetParentInstanceId: z.string(),
})
),
readNamespaces: ["instances"],
writeNamespaces: ["instances"],
invalidatesNamespaces: ["instances"],
}),
publicOperation({
command: "update-page",
id: "pages.update",
method: "mutation",
permit: "edit",
description: "Update page",
inputSchema: getTestInputSchema(
z.object({
pageId: z.string(),
values: z.object({
title: z.string().optional(),
meta: z
.object({
description: z.string().optional(),
})
.optional(),
custom: z.record(z.string(), z.unknown()).optional(),
}),
})
),
writeNamespaces: ["pages"],
invalidatesNamespaces: ["pages"],
}),
styleOperation({
command: "update-styles",
id: "styles.updateDeclarations",
description: "Update styles",
readNamespaces: ["styles"],
inputSchema: getTestInputSchema(
z.object({
updates: z.array(
z.object({
instanceId: z.string(),
property: z.string(),
value: z.unknown(),
})
),
})
),
}),
styleOperation({
command: "attach-design-token",
id: "designTokens.attach",
description: "Attach a reusable style token",
readNamespaces: ["styleSources", "styleSourceSelections"],
writeNamespaces: ["styleSourceSelections"],
invalidatesNamespaces: ["styleSourceSelections"],
inputSchema: getTestInputSchema(
z.object({
designTokenId: z.string(),
instanceIds: z.array(z.string()).min(1),
position: z.enum(["before-local", "after-local"]).optional(),
})
),
}),
publicOperation({
command: "apply-patch",
id: "build.applyPatch",
method: "mutation",
permit: "build",
description: "Apply patch",
inputSchema: getTestInputSchema(
z.object({
transactions: z.array(builderPatchTransactionSchema),
})
),
localCapable: false,
serverOnly: true,
}),
publicOperation({
command: "set-image-descriptions",
id: "assets.setImageDescriptions",
method: "mutation",
permit: "edit",
description: "Save agent-generated image descriptions",
inputSchema: getTestInputSchema(imageDescriptionsSetInput),
readNamespaces: ["assets"],
writeNamespaces: ["assets"],
invalidatesNamespaces: ["assets"],
}),
publicOperation({
command: "replace-asset",
id: "assets.replace",
method: "mutation",
permit: "edit",
description: "Replace asset references",
inputSchema: getTestInputSchema(
z.object({
fromAssetId: z.string(),
toAssetId: z.string(),
})
),
readNamespaces: ["assets"],
writeNamespaces: ["assets", "props", "styles"],
invalidatesNamespaces: ["assets", "props", "styles"],
}),
styleOperation({
command: "delete-styles",
id: "styles.deleteDeclarations",
description: "Delete styles",
inputSchema: optionalArrayFieldInputSchema("deletions"),
readNamespaces: ["styles"],
}),
styleOperation({
command: "update-design-token-styles",
id: "designTokens.updateStyles",
description: "Update design token styles",
inputSchema: getTestInputSchema(
z.object({
designTokenId: z.string().optional(),
updates: z.array(z.unknown()).optional(),
})
),
readNamespaces: ["styleSources", "styles"],
}),
styleOperation({
command: "delete-design-token-styles",
id: "designTokens.deleteStyles",
description: "Delete design token styles",
inputSchema: getTestInputSchema(
z.object({
designTokenId: z.string().optional(),
deletions: z.array(z.unknown()).optional(),
})
),
readNamespaces: ["styleSources", "styles"],
}),
];
const testMcpGuidance: ProjectSessionMcpGuidance = {
visualVerificationRule:
"Ask before visual verification unless the user explicitly requested it.",
getVisionVerificationLoop: ({ includeDiff }) =>
[
"Ask whether the user wants visual verification and stop until they opt in.",
"Make focused changes.",
"Start preview.",
"Install dependencies if missing.",
'Call screenshot with { path: "/" } or the changed page path.',
includeDiff ? "Use screenshot.diff when a baseline exists." : undefined,
"Inspect the PNG with vision.",
].filter((step): step is string => step !== undefined),
getVisionWorkflowSummary: ({ includeDiff }) =>
includeDiff
? "Visual workflow with screenshot diff."
: "Visual workflow without screenshot diff.",
};
const tesseractInstallUrl =
"https://tesseract-ocr.github.io/tessdoc/Installation.html";
const createEnvelope = (
overrides: Partial<ProjectSessionEnvelope> & {
operationId: string;
result: unknown;
}
): ProjectSessionEnvelope => ({
projectId: "project-1",
buildId: "build-1",
version: 1,
source: "local",
state: { committed: false, freshness: {} },
namespaces: {
read: [],
write: [],
invalidated: [],
missing: [],
},
diagnostics: [],
...overrides,
});
const createSession = (overrides: Partial<TestSession> = {}): TestSession => ({
initialize: vi.fn(async () =>
createEnvelope({
operationId: "project-session.status",
result: { loaded: true },
})
),
refresh: vi.fn(async () =>
createEnvelope({
operationId: "project-session.refresh",
result: { refreshedNamespaces: [] },
})
),
reset: vi.fn(async () =>
createEnvelope({
operationId: "project-session.reset",
result: { loaded: false },
})
),
...overrides,
});
const createSessionFactory = (session = createSession()) =>
vi.fn(() => session) as CreateProjectSession;
const createExecuteOperation = (
implementation: ExecuteOperation = async () =>
createEnvelope({
operationId: "test.operation",
result: undefined,
})
): ExecuteOperation => vi.fn(implementation);
const createTestMcpCore = ({
operationId,
result,
session,
}: {
operationId: string;
result: unknown;
session?: TestSession;
}) => {
const executeOperation = createExecuteOperation(async () =>
createEnvelope({ operationId, result })
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(session),
executeOperation,
});
return { adapter, executeOperation };
};
const createConnectedClient = async (
server: Awaited<ReturnType<typeof createProjectSessionMcpServer>>
) => {
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
const client = new Client({ name: "test-client", version: "1.0.0" });
await Promise.all([
server.connect(serverTransport),
client.connect(clientTransport),
]);
return {
client,
close: async () => {
await client.close();
await server.close();
},
};
};
describe("project session mcp adapter", () => {
test("lists restore-point tools only when the host supports them", () => {
const restorePointToolNames = new Set([
"create-restore-point",
"list-restore-points",
"delete-restore-point",
"revert-to-restore-point",
]);
expect(
listProjectSessionMcpTools(publicMcpOperations).some((tool) =>
restorePointToolNames.has(tool.name)
)
).toBe(false);
expect(
listProjectSessionMcpTools(publicMcpOperations, {
includeRestorePoints: true,
})
.filter((tool) => restorePointToolNames.has(tool.name))
.map((tool) => tool.name)
).toEqual([
"create-restore-point",
"list-restore-points",
"delete-restore-point",
"revert-to-restore-point",
]);
});
test("requires explicit confirmation before deleting a restore point", async () => {
const deleteRestorePoint = vi.fn(async () => ({ deleted: true }));
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
restorePoints: {
create: vi.fn(),
list: vi.fn(),
delete: deleteRestorePoint,
revert: vi.fn(),
},
});
await expect(
adapter.callTool({
name: "delete-restore-point",
input: { id: "point-1" },
})
).rejects.toThrow();
const result = await adapter.callTool({
name: "delete-restore-point",
input: { id: "point-1", confirm: true },
});
expect(result.structuredContent).toMatchObject({
ok: true,
data: { deleted: true },
});
expect(deleteRestorePoint).toHaveBeenCalledWith({ id: "point-1" });
});
test("requires a matching confirmation token before reverting", async () => {
const revert = vi.fn(
async (_input: { id: string }, options: { dryRun: boolean }) =>
createEnvelope({
operationId: "project-session.restore-point.revert",
result: { restoredNamespaces: ["pages"] },
source: options.dryRun ? "dry-run" : "local",
state: { committed: options.dryRun === false, freshness: {} },
transaction: {
id: "restore",
payload: [
{
namespace: "pages",
patches: [{ op: "replace", path: [], value: {} }],
},
],
},
})
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
restorePoints: {
create: vi.fn(),
list: vi.fn(),
delete: vi.fn(),
revert,
},
});
const planned = await adapter.callTool({
name: "revert-to-restore-point",
input: { id: "point-1", dryRun: true },
});
const confirmation = planned.structuredContent.meta.confirmation as {
token: string;
};
expect(confirmation.token).toBeTypeOf("string");
const committed = await adapter.callTool({
name: "revert-to-restore-point",
input: {
id: "point-1",
confirmDestructive: true,
confirmationToken: confirmation.token,
},
});
expect(committed.structuredContent.ok).toBe(true);
expect(revert).toHaveBeenLastCalledWith(
{ id: "point-1" },
{ dryRun: false }
);
});
test("lists tools from the public operation catalog", () => {
const tools = listProjectSessionMcpTools(publicMcpOperations);
const toolNames = tools.map((tool) => tool.name);
expect(toolNames).toEqual([
...publicMcpOperations
.map((operation) => operation.command)
.filter((command) => hiddenMcpOperationCommands.has(command) === false),
"meta.index",
"meta.guide",
"workflow.next",
"meta.get-more-tools",
"checkpoint.ack",
"components.summary",
"components.list",
"components.coverage-plan",
"components.coverage-status",
"components.coverage-insert-next",
"components.find",
"components.search",
"components.get",
"templates.list",
"templates.get",
"status",
"refresh",
"reset-session",
"insert-fragment-verified",
]);
expect(toolNames).toContain("insert-fragment");
expect(toolNames).not.toContain("meta.get_more_tools");
const responseHeaderTools = listProjectSessionMcpTools(
runtimeOperationContracts
.filter(({ id }) => id.startsWith("responseHeaders."))
.map((contract) =>
publicOperation({
command: contract.command,
id: contract.id,
description: contract.command,
inputSchema: contract.inputSchema,
})
)
);
expect(responseHeaderTools.map(({ name }) => name)).toEqual(
expect.arrayContaining([
"list-response-headers",
"set-response-header",
"delete-response-header",
])
);
expect(
responseHeaderTools.find(({ name }) => name === "set-response-header")
?.inputSchema
).toMatchObject({
required: ["name", "value"],
properties: {
name: { pattern: expect.any(String) },
value: { minLength: 1, pattern: expect.any(String) },
},
});
const assetOperationTools = listProjectSessionMcpTools(
runtimeOperationContracts
.filter(
({ id }) =>
id.startsWith("assetFolders.") ||
id === "assets.get" ||
id === "assets.duplicate"
)
.map((contract) =>
publicOperation({
command: contract.command,
id: contract.id,
method: contract.kind === "read" ? "query" : "mutation",
permit: contract.kind === "read" ? "view" : "build",
description:
contract.id === "assetFolders.duplicate"
? "Recursively duplicate an asset folder"
: contract.command,
inputSchema: contract.inputSchema,
readNamespaces: contract.readNamespaces,
writeNamespaces: contract.writeNamespaces,
invalidatesNamespaces: contract.invalidatesNamespaces,
retryOnConflict: contract.retryOnConflict,
})
)
);
const assetOperationToolNames = assetOperationTools.map(({ name }) => name);
expect(assetOperationToolNames).toEqual(
expect.arrayContaining([
"list-asset-folders",
"create-asset-folder",
"update-asset-folder",
"duplicate-asset-folder",
"delete-asset-folder",
"get-asset",
"duplicate-asset",
])
);
expect(toolNames).not.toContain("copy-page");
expect(
assetOperationTools.find(({ name }) => name === "duplicate-asset-folder")
).toMatchObject({
inputSchema: expect.objectContaining({ required: ["folderId"] }),
});
expect(
JSON.stringify(
assetOperationTools.find(({ name }) => name === "update-asset-folder")
?.inputSchema
)
).toContain('"type":"null"');
for (const operation of publicMcpOperations) {
if (
hiddenMcpOperationCommands.has(operation.command) ||
runtimeContractById.has(operation.id) === false
) {
continue;
}
expect(
tools.find((tool) => tool.name === operation.command)?.outputSchema,
`Missing MCP output schema for ${operation.command}`
).toBeDefined();
}
const imageDescriptionsTool = tools.find(
(tool) => tool.name === "set-image-descriptions"
);
expect(imageDescriptionsTool).toMatchObject({
inputSchema: expect.objectContaining({
required: ["updates"],
}),
});
expect(JSON.stringify(imageDescriptionsTool?.inputSchema)).toContain(
"decorative"
);
expect(
getSchemaProperties(
tools.find((tool) => tool.name === "audit")?.inputSchema
)
).not.toHaveProperty("rendered");
const visualTools = listProjectSessionMcpTools(publicMcpOperations, {
includeScreenshot: true,
includePreview: true,
});
const completeTools = listProjectSessionMcpTools(publicMcpOperations, {
includeImport: true,
includeDownloadAsset: true,
includeScreenshot: true,
includeScreenshotDiff: true,
includeInstallOcr: true,
includePreview: true,
});
expect(completeTools.map(({ name }) => name)).toContain("download-asset");
for (const tool of completeTools) {
expect(
tool.inputSchema.additionalProperties,
`MCP input schema accepts unknown root fields for ${tool.name}`
).not.toBe(true);
expect(
getUnresolvedLocalSchemaRefs(tool.inputSchema),
`MCP input schema has unresolved local references for ${tool.name}`
).toEqual([]);
expect(
getArraySchemasWithoutItems(tool.inputSchema),
`MCP input schema has array parameters without items for ${tool.name}`
).toEqual([]);
if (tool.outputSchema !== undefined) {
expect(
tool.outputSchema.type,
`MCP output schema must be object-typed for ${tool.name}`
).toBe("object");
expect(
getUnresolvedLocalSchemaRefs(tool.outputSchema),
`MCP output schema has unresolved local references for ${tool.name}`
).toEqual([]);
}
}
expect(
getSchemaProperties(
visualTools.find((tool) => tool.name === "audit")?.inputSchema
)
).toHaveProperty("rendered", expect.objectContaining({ type: "boolean" }));
expect(JSON.stringify(imageDescriptionsTool?.inputSchema)).toContain(
"rendered image in context"
);
expect(
getSuccessfulOutputDataSchema(
tools.find((tool) => tool.name === "refresh")?.outputSchema
)
).toMatchObject({
type: "object",
required: ["refreshedNamespaces"],
properties: {
refreshedNamespaces: {
type: "array",
items: { type: "string", enum: expect.any(Array) },
},
},
});
const auditOutputSchema = tools.find(
(tool) => tool.name === "audit"
)?.outputSchema;
expect(auditOutputSchema).toEqual(
expect.objectContaining({
oneOf: [
expect.objectContaining({
required: ["ok", "data", "meta"],
properties: expect.objectContaining({
ok: { type: "boolean", const: true },
data: expect.objectContaining({ oneOf: expect.any(Array) }),
}),
}),
expect.objectContaining({
required: ["ok", "error", "meta"],
properties: expect.objectContaining({
ok: { type: "boolean", const: false },
data: expect.objectContaining({ oneOf: expect.any(Array) }),
error: expect.objectContaining({
required: ["code", "message"],
properties: expect.objectContaining({
issues: expect.objectContaining({ type: "array" }),
}),
}),
}),
}),
],
})
);
expect(() =>
ListToolsResultSchema.parse({
tools: tools.map(
({ name, description, inputSchema, outputSchema }) => ({
name,
description,
inputSchema,
...(outputSchema === undefined ? {} : { outputSchema }),
})
),
})
).not.toThrow();
for (const command of ["preview.start", "preview.status", "preview.stop"]) {
const outputSchema = getSuccessfulOutputDataSchema(
visualTools.find((tool) => tool.name === command)?.outputSchema
);
expect(
outputSchema,
`Missing MCP output schema for ${command}`
).toMatchObject({
type: "object",
required:
command === "preview.start" ? ["running", "mode"] : ["running"],
properties: {
url: { type: "string" },
pid: { type: "integer" },
running: { type: "boolean" },
},
});
}
for (const command of hiddenMcpOperationCommands) {
expect(toolNames).not.toContain(command);
}
const insertFragmentTool = tools.find(
(tool) => tool.name === "insert-fragment"
);
const runtimeInsertFragmentProperties = Object.keys(
getInputSchemaMetadata(insertFragmentInput).inputJsonSchema.properties ??
{}
);
expect(
Object.keys(
insertFragmentTool === undefined
? {}
: (getDetailedProjectSessionMcpInputSchema(insertFragmentTool)
.properties ?? {})
).filter((property) => property !== "dryRun")
).toEqual(runtimeInsertFragmentProperties);
expect(insertFragmentTool?.inputSchema.required).toEqual([
"parentInstanceId",
"fragment",
]);
expect(insertFragmentTool?.annotations.permit).toBe("edit");
expect(
Object.keys(insertFragmentTool?.inputSchema.properties ?? {})
).toEqual([
"parentInstanceId",
"fragment",
"conflictResolution",
"contentMode",
"mode",
"insertIndex",
"templateNameConfirmation",
"dryRun",
]);
const fragmentSchema = insertFragmentTool?.inputSchema.properties?.fragment;
expect(fragmentSchema).toEqual(expect.objectContaining({ type: "string" }));
expect(
tools.find((tool) => tool.name === "insert-fragment-verified")
?.inputSchema.required
).toEqual(["parentInstanceId", "fragment", "pagePath"]);
expect(insertFragmentTool?.inputSchema.properties).not.toHaveProperty(
"source"
);
expect(tools).toEqual(
expect.arrayContaining([
expect.objectContaining({
name: "list-pages",
inputSchema: expect.objectContaining({
required: [],
properties: {
includeFolders: { type: "boolean" },
},
}),
annotations: expect.objectContaining({
operationId: "pages.list",
inputFields: ["includeFolders"],
requiredInputFields: [],
localCapable: true,
serverOnly: false,
readNamespaces: ["pages"],
}),
}),
expect.objectContaining({
name: "whoami",
annotations: expect.objectContaining({
operationId: "auth.me",
localCapable: false,
serverOnly: true,
}),
}),
expect.objectContaining({
name: "meta.index",
inputSchema: expect.objectContaining({
additionalProperties: false,
properties: {},
required: [],
}),
annotations: expect.objectContaining({
operationId: "meta.index",
localCapable: true,
}),
}),
expect.objectContaining({
name: "refresh",
inputSchema: expect.objectContaining({
properties: expect.objectContaining({
namespaces: expect.objectContaining({
type: "array",
}),
}),
}),
annotations: expect.objectContaining({
operationId: "project-session.refresh",
requiredInputFields: [],
localCapable: true,
}),
}),
expect.objectContaining({
name: "reset-session",
annotations: expect.objectContaining({
operationId: "project-session.reset",
}),
}),
])
);
for (const [name, field] of [
["delete-instance", "instanceIds"],
["update-styles", "updates"],
["delete-styles", "deletions"],
["update-design-token-styles", "updates"],
["delete-design-token-styles", "deletions"],
]) {
expect(
tools.find((tool) => tool.name === name)?.inputSchema.properties?.[
field
]
).toMatchObject({ type: "array" });
}
expect(
tools.find((tool) => tool.name === "update-page")?.inputSchema.properties
?.values
).toMatchObject({
type: "object",
properties: expect.objectContaining({
meta: expect.objectContaining({ type: "object" }),
}),
});
expect(
tools.find((tool) => tool.name === "update-styles")?.inputSchema
.properties?.updates
).toMatchObject({
type: "array",
items: expect.objectContaining({
type: "object",
properties: expect.objectContaining({
instanceId: { type: "string" },
property: { type: "string" },
value: expect.objectContaining({
anyOf: expect.arrayContaining([
{ type: "string" },
{ type: "array", items: {} },
]),
}),
}),
}),
});
expect(
tools.find((tool) => tool.name === "delete-instance")?.inputSchema
.required
).toEqual(["instanceIds"]);
expect(
tools.find((tool) => tool.name === "delete-instance")?.annotations
.requiredInputFields
).toEqual(["instanceIds"]);
expect(
tools.find((tool) => tool.name === "delete-instance")?.inputSchema
.properties
).toEqual(
expect.objectContaining({
dryRun: expect.objectContaining({ type: "boolean" }),
confirmDestructive: expect.objectContaining({ type: "boolean" }),
confirmationToken: expect.objectContaining({ type: "string" }),
})
);
});
test("omits CLI-owned issue runtime from the MCP input schema", () => {
const [tool] = listProjectSessionMcpTools([
publicOperation({
command: "report-issue",
id: "reports.issue",
description: "Report an issue",
localCapable: false,
serverOnly: true,
inputSchema: getTestInputSchema(
z.object({
title: z.string(),
runtime: z
.object({ recentFailure: z.unknown().optional() })
.optional(),
})
),
}),
]);
expect(tool?.inputSchema.properties).toHaveProperty("title");
expect(tool?.inputSchema.properties).not.toHaveProperty("runtime");
});
test("defers oversized input schemas until focused discovery", async () => {
const description = "x".repeat(25_000);
const operation = publicOperation({
command: "large-input",
id: "test.largeInput",
description: "Accept a large structured input",
inputSchema: {
type: "object",
additionalProperties: false,
properties: {
targetId: { type: "string" },
payload: { type: "object", description },
},
required: ["targetId", "payload"],
},
});
const [tool] = listProjectSessionMcpTools([operation]);
expect(JSON.stringify(tool?.inputSchema).length).toBeLessThan(1_000);
expect(tool?.inputSchema.required).toEqual(["targetId", "payload"]);
const adapter = createProjectSessionMcpCore({
operations: [operation],
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
const details = await adapter.callTool({
name: "meta.get-more-tools",
input: { tools: ["large-input"] },
});
expect(
JSON.stringify(details.structuredContent.data).length
).toBeGreaterThan(JSON.stringify(tool?.inputSchema).length);
});
test("defers the nested Email Resource schema in upsert-resource-prop", async () => {
const contract = runtimeContractById.get("resources.upsertProp");
if (contract === undefined) {
throw new Error("Resource prop contract not found");
}
const operation = publicOperation({
command: contract.command,
id: contract.id,
description: contract.command,
inputSchema: contract.inputSchema,
});
const [tool] = listProjectSessionMcpTools([operation]);
expect(
JSON.stringify(tool?.inputSchema.properties?.resource).length
).toBeLessThan(500);
expect(
getDetailedProjectSessionMcpInputSchema(tool!).properties?.resource
).toHaveProperty("properties.email");
const adapter = createProjectSessionMcpCore({
operations: [operation],
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
const details = await adapter.callTool({
name: "meta.get-more-tools",
input: { tools: ["upsert-resource-prop"] },
});
expect(details.structuredContent.data).toEqual(
expect.objectContaining({
tools: [
expect.objectContaining({
inputSchema: expect.objectContaining({
properties: expect.objectContaining({
resource: expect.objectContaining({
properties: expect.objectContaining({
email: expect.any(Object),
}),
}),
}),
}),
}),
],
})
);
});
test("keeps array items valid when deferring an oversized schema", () => {
const operation = publicOperation({
command: "large-array-input",
id: "test.largeArrayInput",
description: "Accept a large structured array",
inputSchema: {
type: "object",
additionalProperties: false,
properties: {
updates: {
type: "array",
items: {
type: "object",
description: "x".repeat(25_000),
},
},
},
required: ["updates"],
},
});
const [tool] = listProjectSessionMcpTools([operation]);
const updates = tool?.inputSchema.properties?.updates as
| Record<string, unknown>
| undefined;
expect(JSON.stringify(tool?.inputSchema).length).toBeLessThan(1_000);
expect(updates).toMatchObject({
type: "array",
items: {},
});
});
test("adds items to tuple input schemas", () => {
const operation = publicOperation({
command: "tuple-input",
id: "test.tupleInput",
description: "Accept a structured tuple",
inputSchema: {
type: "object",
additionalProperties: false,
properties: {
coordinates: {
type: "array",
prefixItems: [{ type: "number" }, { type: "number" }],
},
},
required: ["coordinates"],
},
});
const [tool] = listProjectSessionMcpTools([operation]);
expect(tool?.inputSchema.properties?.coordinates).toMatchObject({
type: "array",
items: {},
prefixItems: [{ type: "number" }, { type: "number" }],
});
});
test("downloads assets through the MCP host", async () => {
const downloadAsset = vi.fn(async ({ assetId }: { assetId: string }) => ({
assetId,
path: `/workspace/.webstudio/assets/${assetId}.mdx`,
source: "# Kept\n\n{danger()}\n",
diagnostics: [
{
code: "unsafe-mdx" as const,
severity: "warning" as const,
message: "Executable MDX expressions are not supported",
sourceRange: {
start: { line: 3, column: 1, offset: 8 },
end: { line: 3, column: 11, offset: 18 },
},
},
{
code: "unresolved-template" as const,
severity: "warning" as const,
blockInstanceId: "content-block-1",
assetId,
contentRef: "asset:hero",
renderScope: "asset:hero:block:content-block-1",
templateName: "MissingCard",
},
],
}));
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
downloadAsset,
});
const result = await adapter.callTool({
name: "download-asset",
input: { assetId: "hero" },
});
expect(downloadAsset).toHaveBeenCalledWith({ assetId: "hero" });
expect(result.structuredContent).toMatchObject({
data: {
assetId: "hero",
path: "/workspace/.webstudio/assets/hero.mdx",
source: "# Kept\n\n{danger()}\n",
diagnostics: [
expect.objectContaining({
code: "unsafe-mdx",
severity: "warning",
}),
expect.objectContaining({
code: "unresolved-template",
severity: "warning",
blockInstanceId: "content-block-1",
assetId: "hero",
contentRef: "asset:hero",
renderScope: "asset:hero:block:content-block-1",
templateName: "MissingCard",
}),
],
},
});
});
test("exposes page expression inputs to MCP clients", async () => {
const createPageContract = runtimeOperationContracts.find(
(contract) => contract.id === "pages.create"
);
if (createPageContract === undefined) {
throw Error("Expected pages.create contract");
}
const createPageOperation = publicOperation({
command: createPageContract.command,
id: createPageContract.id,
method: "mutation",
permit: "build",
description: "Create page",
inputSchema: createPageContract.inputSchema,
readNamespaces: createPageContract.readNamespaces,
writeNamespaces: createPageContract.writeNamespaces,
invalidatesNamespaces: createPageContract.invalidatesNamespaces,
retryOnConflict: createPageContract.retryOnConflict,
});
const [tool] = listProjectSessionMcpTools([createPageOperation]);
const toolProperties = getSchemaProperties(tool?.inputSchema);
const toolMetaProperties = getSchemaProperties(toolProperties.meta);
expect(toolProperties.title).toMatchObject({ type: "string" });
expect(toolMetaProperties.description).toMatchObject({ type: "string" });
expectPageStatusInputSchema(toolMetaProperties.status);
const adapter = createProjectSessionMcpCore({
operations: [createPageOperation],
createProjectSession: createSessionFactory(createSession()),
executeOperation: createExecuteOperation(),
});
const details = await adapter.callTool({
name: "meta.get-more-tools",
input: { tools: ["create-page"] },
});
const [toolDetails] = (
details.structuredContent.data as {
tools: { inputSchema: PublicMcpOperation["inputSchema"] }[];
}
).tools;
const toolDetailsProperties = getSchemaProperties(toolDetails?.inputSchema);
const toolDetailsMetaProperties = getSchemaProperties(
toolDetailsProperties.meta
);
expect(toolDetailsProperties.title).toMatchObject({ type: "string" });
expect(toolDetailsMetaProperties.description).toMatchObject({
type: "string",
});
expectPageStatusInputSchema(toolDetailsMetaProperties.status);
});
test("lists OCR installer only when host provides installer", () => {
expect(
listProjectSessionMcpTools(publicMcpOperations).map((tool) => tool.name)
).not.toContain("vision.install-ocr");
expect(
listProjectSessionMcpTools(publicMcpOperations, {
includeInstallOcr: true,
}).map((tool) => tool.name)
).toContain("vision.install-ocr");
});
test("lists import only when host provides importer", () => {
expect(
listProjectSessionMcpTools(publicMcpOperations).map((tool) => tool.name)
).not.toContain("import");
const tools = listProjectSessionMcpTools(publicMcpOperations, {
includeImport: true,
});
const importTool = tools.find((tool) => tool.name === "import");
expect(importTool).toBeDefined();
expect(importTool?.annotations.invalidatesNamespaces).toEqual([]);
expect(tools.map((tool) => tool.name)).toContain("import");
});
test("keeps MCP input schemas and required annotations aligned", () => {
const tools = listProjectSessionMcpTools(publicMcpOperations, {
includeImport: true,
includeScreenshot: true,
includeScreenshotDiff: true,
includeInstallOcr: true,
includePreview: true,
});
for (const tool of tools) {
expect(tool.inputSchema.required ?? [], tool.name).toEqual(
tool.annotations.requiredInputFields
);
}
expect(tools.find((tool) => tool.name === "meta.guide")).toMatchObject({
inputSchema: expect.objectContaining({
required: ["brief"],
properties: expect.objectContaining({
taskScope: expect.objectContaining({
enum: expect.arrayContaining([
"read-only-audit",
"focused-page-change",
]),
}),
workflow: expect.objectContaining({
enum: expect.arrayContaining([
"general",
"markdown-blog",
"content-block-source",
"design-input",
]),
}),
authoredFragment: expect.objectContaining({ type: "boolean" }),
reuseDesignSystem: expect.objectContaining({ type: "boolean" }),
}),
}),
annotations: expect.objectContaining({ requiredInputFields: ["brief"] }),
});
expect(
tools.find((tool) => tool.name === "meta.get-more-tools")
).toMatchObject({
inputSchema: expect.objectContaining({
required: [],
properties: expect.objectContaining({
brief: expect.objectContaining({ type: "string" }),
tools: expect.objectContaining({ type: "array" }),
}),
}),
annotations: expect.objectContaining({ requiredInputFields: [] }),
});
expect(tools.find((tool) => tool.name === "screenshot.diff")).toMatchObject(
{
inputSchema: expect.objectContaining({
required: ["baselinePath", "currentPath"],
}),
annotations: expect.objectContaining({
requiredInputFields: ["baselinePath", "currentPath"],
}),
}
);
});
test("derives MCP required fields from branched input schemas", () => {
const operation = publicOperation({
command: "update-branched-settings",
id: "settings.updateBranched",
method: "mutation",
permit: "edit",
description: "Update branched settings",
inputSchema: {
allOf: [
{
properties: {
settings: { type: "object" },
},
required: ["settings"],
},
],
},
});
const [tool] = listProjectSessionMcpTools([operation]);
expect(tool?.inputSchema.required).toEqual(["settings"]);
expect(tool?.annotations).toMatchObject({
inputFields: ["dryRun", "settings"],
requiredInputFields: ["settings"],
});
});
test("does not expose CLI-only required options as MCP tool schemas", () => {
const operationWithCliOptions = {
...publicMcpOperations[0]!,
requiredOptions: ["page", "base-version", "json"],
};
expect(listProjectSessionMcpTools([operationWithCliOptions])).toEqual(
expect.arrayContaining([
expect.objectContaining({
name: "list-pages",
inputSchema: {
type: "object",
description:
"Pass this MCP tool's JSON arguments. Use meta.get-more-tools for examples and required fields. For authored content with styles, prefer insert-fragment so the CLI converts JSX into Webstudio data.",
additionalProperties: false,
required: [],
properties: {
includeFolders: { type: "boolean" },
},
},
}),
])
);
});
test("lists MCP resources for project status, tools, components, and accessibility review", () => {
expect(listProjectSessionMcpResources()).toEqual([
expect.objectContaining({ uri: "webstudio://project/status" }),
expect.objectContaining({ uri: "webstudio://project/tools-overview" }),
expect.objectContaining({ uri: "webstudio://project/tools" }),
expect.objectContaining({
uri: "webstudio://project/components-overview",
}),
expect.objectContaining({ uri: "webstudio://project/components" }),
expect.objectContaining({ uri: "webstudio://project/guide" }),
expect.objectContaining({
uri: "webstudio://project/expressions",
mimeType: "text/markdown",
}),
expect.objectContaining({
uri: "webstudio://project/accessibility-review",
mimeType: "text/markdown",
}),
]);
});
test("calls tools through project session operation executor", async () => {
const executeOperation: ExecuteOperation = vi.fn(async () =>
createEnvelope({
operationId: "pages.list",
result: [{ id: "home" }],
namespaces: {
read: ["pages"],
write: [],
invalidated: [],
missing: [],
},
})
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
const result = await adapter.callTool({
name: "list-pages",
input: { includeFolders: true },
});
expect(executeOperation).toHaveBeenCalledWith({
command: "list-pages",
input: { includeFolders: true },
dryRun: false,
});
expect(result.structuredContent).toEqual({
ok: true,
data: [{ id: "home" }],
meta: {
session: expect.objectContaining({
operationId: "pages.list",
source: "local",
namespaceCounts: {
read: 1,
write: 0,
invalidated: 0,
missing: 0,
},
diagnosticCount: 0,
}),
},
});
expect(result.structuredContent.meta.session).not.toHaveProperty(
"namespaces"
);
expect(result.structuredContent.meta.session).not.toHaveProperty(
"diagnostics"
);
});
test("exposes the audit input and structured result through MCP", async () => {
const auditResult = {
contractVersion: 2,
projectVersion: 7,
scopes: ["accessibility"],
pageFilter: null,
summary: {
total: 1,
bySeverity: { error: 1, warning: 0, info: 0 },
byScope: {
accessibility: 1,
security: 0,
seo: 0,
assets: 0,
styles: 0,
performance: 0,
},
},
verbose: false,
findings: [{ id: "accessibility/missing-alt/image" }],
skippedCheckCount: 0,
manualCheckCount: 3,
renderedCheckCount: 0,
renderedIssueCount: 0,
renderedFailureCount: 0,
nextCursor: null,
};
const executeOperation = createExecuteOperation(async () =>
createEnvelope({ operationId: "project.audit", result: auditResult })
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
const result = await adapter.callTool({
name: "audit",
input: {
scopes: ["accessibility"],
severities: ["error"],
limit: 10,
},
});
expect(executeOperation).toHaveBeenCalledWith({
command: "audit",
input: {
scopes: ["accessibility"],
severities: ["error"],
limit: 10,
},
dryRun: false,
});
expect(result.structuredContent).toEqual({
ok: true,
data: auditResult,
meta: {
session: expect.objectContaining({ operationId: "project.audit" }),
},
});
});
test("runs rendered responsive checks through the audit tool", async () => {
const executeOperation = createExecuteOperation(
async ({ command, input }) => {
if (command === "list-pages") {
return createEnvelope({
operationId: "pages.list",
result: {
pages: [
{ id: "home", path: "/" },
{ id: "dynamic", path: "/posts/:slug" },
],
},
});
}
if (command === "list-breakpoints") {
return createEnvelope({
operationId: "breakpoints.list",
result: {
breakpoints: [
{ id: "base", label: "Base" },
{ id: "tablet", label: "Tablet", minWidth: 768 },
],
},
});
}
const requestedScopes =
typeof input === "object" &&
input !== null &&
"scopes" in input &&
Array.isArray(input.scopes)
? input.scopes
: [
"accessibility",
"security",
"seo",
"assets",
"styles",
"performance",
];
return createEnvelope({
operationId: "project.audit",
result: {
contractVersion: 2,
projectVersion: 7,
scopes: requestedScopes,
pageFilter: null,
summary: {
total: 0,
bySeverity: { error: 0, warning: 0, info: 0 },
byScope: {
accessibility: 0,
security: 0,
seo: 0,
assets: 0,
styles: 0,
performance: 0,
},
},
verbose: true,
findings: [],
skippedCheckCount: 0,
skippedChecks: [],
manualCheckCount: 3,
manualChecks: [
{ checkId: "responsive-visual-review" },
{ checkId: "visual-contrast-review" },
{ checkId: "visual-hierarchy-review" },
],
renderedCheckCount: 0,
renderedIssueCount: 0,
renderedFailureCount: 0,
renderedChecks: [],
renderedFailures: [],
nextCursor: null,
},
});
}
);
const startPreview = vi.fn(async () => ({
url: "http://127.0.0.1:5177",
running: true,
mode: "production" as const,
}));
const stopPreview = vi.fn(async () => ({
url: "http://127.0.0.1:5173",
running: false,
mode: "production" as const,
}));
const captureScreenshot = vi.fn(async (input) => ({
output: `/tmp/${input.viewport.width}.png`,
browserPath: "/browser",
browser: "chromium" as const,
viewport: input.viewport,
fullPage: true,
elapsedMs: 1,
warnings: [],
navigation: {
requestedUrl: `http://127.0.0.1:5177${input.path}`,
finalUrl: `http://127.0.0.1:5177${input.path}`,
status: 200,
statusText: "OK",
mimeType: "text/html",
redirects: [],
documentReadyState: "complete",
generatedSiteRootPresent: true,
layoutStable: true,
},
layout: {
viewportWidth: input.viewport.width,
viewportHeight: input.viewport.height,
contentWidth:
input.viewport.width === 390
? input.viewport.width + 20
: input.viewport.width,
contentHeight: 1200,
horizontalOverflow: input.viewport.width === 390,
images:
input.viewport.width === 390
? [
{
instanceId: "broken",
loading: "eager",
complete: true,
naturalWidth: 0,
naturalHeight: 0,
renderedWidth: 200,
renderedHeight: 100,
top: 100,
},
{
instanceId: "below-fold",
loading: "eager",
complete: true,
naturalWidth: 800,
naturalHeight: 600,
renderedWidth: 400,
renderedHeight: 300,
top: 900,
},
{
instanceId: "oversized",
loading: "lazy",
complete: true,
naturalWidth: 2400,
naturalHeight: 1600,
renderedWidth: 600,
renderedHeight: 400,
top: 100,
},
]
: [],
resources:
input.viewport.width === 390
? [
{
pathname: "/styles.css",
initiatorType: "link",
transferSize: 12000,
encodedBodySize: 11000,
decodedBodySize: 40000,
duration: 25,
renderBlockingStatus: "blocking",
},
{
pathname: "/fonts/brand.ttf",
initiatorType: "css",
transferSize: 80000,
encodedBodySize: 79000,
decodedBodySize: 79000,
duration: 40,
},
]
: [],
},
}));
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
startPreview,
getPreviewStatus: vi.fn(),
stopPreview,
captureScreenshot,
});
const result = await adapter.callTool({
name: "audit",
input: { rendered: true, verbose: true },
});
expect(executeOperation).toHaveBeenCalledWith({
command: "audit",
input: { verbose: true },
dryRun: false,
});
expect(startPreview).toHaveBeenCalledTimes(1);
expect(stopPreview).toHaveBeenCalledTimes(1);
expect(captureScreenshot).toHaveBeenCalledTimes(2);
expect(captureScreenshot).toHaveBeenCalledWith(
expect.objectContaining({
path: "/",
timeout: 10_000,
viewport: { width: 390, height: 844 },
})
);
expect(result.structuredContent.data).toMatchObject({
renderedCheckCount: 2,
renderedIssueCount: 6,
renderedFailureCount: 0,
manualCheckCount: 3,
renderedChecks: [
expect.objectContaining({
pageId: "home",
viewport: { width: 390, height: 844 },
issues: [
"horizontal-overflow",
"broken-image",
"eager-below-fold-image",
"oversized-image",
"render-blocking-resource",
"legacy-font-format",
],
resourceIssues: [
expect.objectContaining({
kind: "render-blocking-resource",
pathname: "/styles.css",
}),
expect.objectContaining({
kind: "legacy-font-format",
pathname: "/fonts/brand.ttf",
}),
],
imageIssues: [
expect.objectContaining({
kind: "broken-image",
instanceId: "broken",
}),
expect.objectContaining({
kind: "eager-below-fold-image",
instanceId: "below-fold",
}),
expect.objectContaining({
kind: "oversized-image",
instanceId: "oversized",
}),
],
}),
expect.any(Object),
],
renderedFailures: [],
manualChecks: [
{ checkId: "responsive-visual-review" },
{ checkId: "visual-contrast-review" },
{ checkId: "visual-hierarchy-review" },
],
});
captureScreenshot.mockClear();
const accessibilityResult = await adapter.callTool({
name: "audit",
input: {
scopes: ["accessibility"],
rendered: true,
verbose: true,
},
});
expect(captureScreenshot).toHaveBeenCalledTimes(2);
expect(stopPreview).toHaveBeenCalledTimes(2);
expect(captureScreenshot).toHaveBeenCalledWith(
expect.objectContaining({
includeImageMetrics: false,
includeResourceMetrics: false,
})
);
expect(accessibilityResult.structuredContent.data).toMatchObject({
scopes: ["accessibility"],
renderedState: "complete",
renderedCheckCount: 2,
renderedIssueCount: 1,
renderedChecks: [
expect.objectContaining({
issues: ["horizontal-overflow"],
imageIssues: [],
resourceIssues: [],
}),
expect.any(Object),
],
});
await expect(
adapter.callTool({
name: "audit",
input: { rendered: true, cursor: "next" },
})
).rejects.toThrow(/cannot be combined with cursor pagination/);
});
test("returns static audit data with an error when rendered preview cannot start", async () => {
const executeOperation = createExecuteOperation(async ({ command }) => {
if (command === "list-pages") {
return createEnvelope({
operationId: "pages.list",
result: { pages: [{ id: "home", path: "/" }] },
});
}
if (command === "list-breakpoints") {
return createEnvelope({
operationId: "breakpoints.list",
result: { breakpoints: [] },
});
}
return createEnvelope({
operationId: "project.audit",
result: {
contractVersion: 2,
projectVersion: 7,
scopes: [],
pageFilter: null,
summary: {
total: 0,
bySeverity: { error: 0, warning: 0, info: 0 },
byScope: {},
},
verbose: true,
findings: [],
skippedCheckCount: 0,
skippedChecks: [],
manualCheckCount: 3,
manualChecks: [{ checkId: "responsive-visual-review" }],
renderedCheckCount: 0,
renderedIssueCount: 0,
renderedFailureCount: 0,
renderedChecks: [],
renderedFailures: [],
nextCursor: null,
},
});
});
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
startPreview: vi.fn(async () => {
throw new Error("preview build failed");
}),
getPreviewStatus: vi.fn(),
stopPreview: vi.fn(),
captureScreenshot: vi.fn(),
});
const result = await adapter.callTool({
name: "audit",
input: { rendered: true, verbose: true },
});
expect(result.isError).toBe(true);
expect(result.structuredContent).toMatchObject({
ok: false,
error: {
code: "RENDERED_AUDIT_FAILED",
message: expect.stringContaining("completed no rendered checks"),
},
});
expect(result.structuredContent.data).toMatchObject({
renderedState: "failed",
renderedCheckCount: 0,
renderedIssueCount: 0,
renderedFailureCount: 1,
renderedFailures: [
{
code: "RENDERED_AUDIT_PREVIEW_START_FAILED",
phase: "preview-start",
retryable: true,
remediation: expect.stringContaining("preview.start"),
message: "Rendered audit could not start: preview build failed",
},
],
manualCheckCount: 3,
manualChecks: [{ checkId: "responsive-visual-review" }],
});
});
test("includes actionable rendered failure summaries in compact output", async () => {
const executeOperation = createExecuteOperation(async ({ command }) => {
if (command === "list-pages") {
return createEnvelope({
operationId: "pages.list",
result: { pages: [{ id: "home", path: "/" }] },
});
}
if (command === "list-breakpoints") {
return createEnvelope({
operationId: "breakpoints.list",
result: { breakpoints: [] },
});
}
return createEnvelope({
operationId: "project.audit",
result: {
contractVersion: 2,
projectVersion: 1,
scopes: ["accessibility"],
pageFilter: null,
summary: {
total: 0,
selectedTotal: 0,
bySeverity: { error: 0, warning: 0, info: 0 },
byScope: {
accessibility: 0,
security: 0,
seo: 0,
assets: 0,
styles: 0,
performance: 0,
},
},
skippedCheckCount: 0,
manualCheckCount: 1,
renderedCheckCount: 0,
renderedIssueCount: 0,
renderedFailureCount: 0,
renderedFailureSummaries: [],
nextCursor: null,
verbose: false,
findings: [],
},
});
});
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
startPreview: vi.fn(async () => {
throw new Error("preview build failed");
}),
getPreviewStatus: vi.fn(),
stopPreview: vi.fn(),
captureScreenshot: vi.fn(),
});
const result = await adapter.callTool({
name: "audit",
input: { rendered: true },
});
expect(result.structuredContent.data).toMatchObject({
renderedState: "failed",
renderedFailureCount: 1,
renderedFailureSummaries: [
{
code: "RENDERED_AUDIT_PREVIEW_START_FAILED",
phase: "preview-start",
remediation: expect.stringContaining("preview.start"),
count: 1,
},
],
});
});
test("does not advertise or silently accept rendered audit without visual capabilities", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
const auditTool = adapter.listTools().find(({ name }) => name === "audit");
expect(auditTool?.inputSchema.properties).not.toHaveProperty("rendered");
await expect(
adapter.callTool({ name: "audit", input: { rendered: true } })
).rejects.toThrow(/does not provide preview and screenshot capabilities/);
await expect(
adapter.callTool({
name: "audit",
input: { confirmationToken: "not-rendered" },
})
).rejects.toThrow(/confirmationToken requires rendered: true/);
await expect(
adapter.callTool({ name: "audit", input: { rendered: false } })
).resolves.toMatchObject({
structuredContent: { ok: true },
});
});
test("returns a large rendered audit confirmation plan as a successful result", async () => {
const executeOperation = createExecuteOperation(async ({ command }) => {
if (command === "list-pages") {
return createEnvelope({
operationId: "pages.list",
result: {
pages: Array.from({ length: 121 }, (_, index) => ({
id: `page-${index}`,
path: `/page-${index}`,
})),
},
});
}
if (command === "list-breakpoints") {
return createEnvelope({
operationId: "breakpoints.list",
result: { breakpoints: [] },
});
}
return createEnvelope({
operationId: "project.audit",
result: {
contractVersion: 2,
projectVersion: 7,
scopes: [],
pageFilter: null,
summary: {
total: 0,
bySeverity: { error: 0, warning: 0, info: 0 },
byScope: {},
},
verbose: false,
findings: [],
skippedCheckCount: 0,
manualCheckCount: 0,
renderedCheckCount: 0,
renderedIssueCount: 0,
renderedFailureCount: 0,
nextCursor: null,
},
});
});
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
startPreview: vi.fn(),
getPreviewStatus: vi.fn(),
stopPreview: vi.fn(),
captureScreenshot: vi.fn(),
});
const result = await adapter.callTool({
name: "audit",
input: { rendered: true },
});
expect(result.isError).not.toBe(true);
expect(result.structuredContent).toMatchObject({
ok: true,
data: {
renderedState: "confirmation-required",
renderedPlan: {
captureCount: 121,
confirmationToken: expect.any(String),
},
renderedFailureCount: 1,
renderedFailureSummaries: [
{ code: "RENDERED_AUDIT_CONFIRMATION_REQUIRED", count: 1 },
],
},
});
});
test("returns the computed transaction for dry-run mutations", async () => {
const transaction = {
id: "dry-run-transaction",
payload: [
{
namespace: "pages" as const,
patches: [
{ op: "add" as const, path: ["pages", "draft"], value: {} },
],
},
],
};
const executeOperation = createExecuteOperation(async () =>
createEnvelope({
operationId: "folders.create",
source: "dry-run",
result: { folderId: "draft" },
transaction,
})
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
const result = await adapter.callTool({
name: "move-instance",
input: { moves: [], dryRun: true },
});
expect(result.structuredContent).toMatchObject({
data: { folderId: "draft" },
meta: {
session: {
source: "dry-run",
committed: false,
transaction,
},
},
});
});
test("plans and confirms destructive mutations without blind retries", async () => {
const transaction = {
id: "planned-delete",
payload: [
{
namespace: "instances" as const,
patches: [{ op: "remove" as const, path: ["target"] }],
},
],
};
const executeOperation = createExecuteOperation(async ({ dryRun }) =>
createEnvelope({
operationId: "instances.delete",
source: dryRun ? "dry-run" : "remote",
result: { deletedInstanceIds: ["target"] },
state: { committed: dryRun === false, freshness: {} },
...(dryRun ? { transaction } : {}),
})
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
const planned = await adapter.callTool({
name: "delete-instance",
input: { instanceIds: ["target"] },
});
expect(planned).toMatchObject({
isError: true,
structuredContent: {
ok: false,
error: { code: "DESTRUCTIVE_CONFIRMATION_REQUIRED" },
meta: {
session: { source: "dry-run", committed: false, transaction },
confirmation: {
required: true,
operation: "delete-instance",
token: expect.any(String),
summary: {
namespaces: ["instances"],
changeCount: 1,
patchCount: 1,
patchOperations: { remove: 1 },
},
},
},
},
});
expect(executeOperation).toHaveBeenCalledTimes(1);
const confirmation = planned.structuredContent.meta.confirmation;
if (confirmation === undefined) {
throw new Error("Expected destructive confirmation");
}
const altered = await adapter.callTool({
name: "delete-instance",
input: {
instanceIds: ["other"],
confirmDestructive: true,
confirmationToken: confirmation.token,
},
});
expect(altered).toMatchObject({
structuredContent: {
ok: false,
error: {
code: "DESTRUCTIVE_CONFIRMATION_INVALID",
issues: [
{
code: "DESTRUCTIVE_CONFIRMATION_MISMATCH",
path: ["confirmationToken"],
constraint: "unchanged_destructive_plan",
},
],
},
},
});
expect(executeOperation).toHaveBeenCalledTimes(2);
const committed = await adapter.callTool({
name: "delete-instance",
input: {
confirmationToken: confirmation.token,
instanceIds: ["target"],
confirmDestructive: true,
},
});
expect(committed).toMatchObject({
structuredContent: {
ok: true,
meta: { session: { committed: true } },
},
});
expect(executeOperation).toHaveBeenCalledTimes(4);
});
test("rejects unsupported operation input fields before execution", async () => {
const executeOperation: ExecuteOperation = vi.fn();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await expect(
adapter.callTool({
name: "list-instances",
input: { rootInstanceId: "body", depth: 1 },
})
).rejects.toThrow(
"list-instances input.depth is not supported. Expected one of: rootInstanceId, maxDepth. Did you mean maxDepth?"
);
await expect(
adapter.callTool({
name: "list-instances",
input: { instanceId: "body" },
})
).rejects.toThrow(
"list-instances input.instanceId is not supported. Expected one of: rootInstanceId, maxDepth. Did you mean rootInstanceId? Use rootInstanceId to list a subtree, or inspect-instance to inspect one element."
);
expect(executeOperation).not.toHaveBeenCalled();
});
test("reports unknown, missing, and wrong-type input fields together", async () => {
const createPageOperation = publicOperation({
command: "create-page",
id: "pages.create",
description: "Create a page",
method: "mutation",
inputSchema: getTestInputSchema(
z.object({ name: z.string(), path: z.string() })
),
});
const executeOperation: ExecuteOperation = vi.fn();
const adapter = createProjectSessionMcpCore({
operations: [...publicMcpOperations, createPageOperation],
createProjectSession: createSessionFactory(),
executeOperation,
});
let error: unknown;
try {
await adapter.callTool({
name: "create-page",
input: { name: 42, unexpected: true },
});
} catch (caught) {
error = caught;
}
expect(error).toMatchObject({
code: "INVALID_INPUT",
issues: [
expect.objectContaining({ path: ["path"], constraint: "required" }),
expect.objectContaining({ path: ["name"], constraint: "type:string" }),
expect.objectContaining({ path: ["unexpected"] }),
],
});
expect(executeOperation).not.toHaveBeenCalled();
});
test("uses the shared query validator and keeps root input errors", async () => {
const operation = publicOperation({
command: "validate-asset-query",
id: "assetQueries.validate",
description: "Validate an Asset query",
inputSchema: getTestInputSchema(z.object({ query: z.unknown() })),
});
const executeOperation: ExecuteOperation = vi.fn();
const adapter = createProjectSessionMcpCore({
operations: [operation],
createProjectSession: createSessionFactory(),
executeOperation,
});
const query = {
result: "first",
limit: -1,
output: { mode: "fields", includeMetadata: false, fields: [] },
content: { mode: "none" },
unexpected: true,
};
const sharedIssues = validateAssetQuery({ query })
.issues.filter(({ severity }) => severity === "error")
.map((issue) => ({ ...issue, constraint: issue.code }));
let error: unknown;
try {
await adapter.callTool({
name: "validate-asset-query",
input: { query, unexpectedRoot: true },
});
} catch (caught) {
error = caught;
}
expect(error).toMatchObject({
code: "INVALID_INPUT",
issues: [
...sharedIssues,
expect.objectContaining({ path: ["unexpectedRoot"] }),
],
});
expect(executeOperation).not.toHaveBeenCalled();
});
test("converts jsx fragments before executing insert operation", async () => {
const executeOperation = createExecuteOperation(async () =>
createEnvelope({
operationId: "instances.insertFragment",
result: {
rootInstanceIds: ["inserted"],
instanceIds: ["inserted"],
},
})
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
expect(
adapter.listTools().find(({ name }) => name === "insert-fragment")
?.inputSchema.properties?.conflictResolution
).toEqual({
type: "string",
enum: ["ours", "theirs", "merge"],
description: expect.any(String),
});
await adapter.callTool({
name: "insert-fragment",
input: {
parentInstanceId: "body",
fragment:
'<ws.element ws:tag="section"><ws.element ws:tag="h2">Title</ws.element></ws.element>',
conflictResolution: "ours",
contentMode: true,
},
});
const call = vi.mocked(executeOperation).mock.calls[0]?.[0];
expect(call).toEqual({
command: "insert-fragment",
input: {
parentInstanceId: "body",
fragment: expect.objectContaining({
instances: expect.arrayContaining([
expect.objectContaining({ component: "ws:element" }),
expect.objectContaining({ component: "ws:element" }),
]),
}),
conflictResolution: "ours",
contentMode: true,
mode: undefined,
insertIndex: undefined,
},
dryRun: false,
});
expect(call?.input).not.toHaveProperty("source");
});
test("inserts a fragment and verifies persisted bindings in one call", async () => {
const executeOperation = createExecuteOperation(async ({ command }) =>
command === "insert-fragment"
? createEnvelope({
operationId: "instances.insertFragment",
result: { instanceIds: ["section-id"] },
state: { committed: true, freshness: {} },
})
: createEnvelope({
operationId: "project.verifyBindings",
result: {
summary: { bindingsChecked: 2, findings: 0 },
findings: [],
},
})
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
startPreview: vi.fn(),
captureScreenshot: vi.fn(),
});
expect(adapter.listTools().map(({ name }) => name)).toContain(
"insert-fragment-verified"
);
expect(
adapter
.listTools()
.find(({ name }) => name === "insert-fragment-verified")?.inputSchema
.properties?.conflictResolution
).toEqual({
type: "string",
enum: ["ours", "theirs", "merge"],
description: expect.any(String),
});
const result = await adapter.callTool({
name: "insert-fragment-verified",
input: {
parentInstanceId: "root-id",
pagePath: "/account",
fragment: '<ws.element ws:tag="section" />',
conflictResolution: "merge",
},
});
expect(executeOperation).toHaveBeenNthCalledWith(
1,
expect.objectContaining({
command: "insert-fragment",
input: expect.objectContaining({ conflictResolution: "merge" }),
dryRun: false,
})
);
expect(executeOperation).toHaveBeenNthCalledWith(2, {
command: "verify-bindings",
input: { pagePath: "/account", limit: 200 },
dryRun: false,
});
expect(result.structuredContent).toMatchObject({
ok: true,
data: {
insertion: { instanceIds: ["section-id"] },
verification: {
summary: { bindingsChecked: 2, findings: 0 },
findings: [],
},
},
meta: {
session: {
operationId: "workflow.insert-fragment-verified",
committed: true,
},
},
});
expect(result.structuredContent.meta.next).toEqual(
expect.arrayContaining([
expect.stringContaining(
"Ask whether the user wants visual verification"
),
])
);
const failingVerification = createExecuteOperation(async ({ command }) => {
if (command === "verify-bindings") {
throw new Error("verification unavailable");
}
return createEnvelope({
operationId: "instances.insertFragment",
result: { instanceIds: ["committed-section-id"] },
state: { committed: true, freshness: {} },
});
});
const failureAdapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: failingVerification,
});
const failedVerificationResult = await failureAdapter.callTool({
name: "insert-fragment-verified",
input: {
parentInstanceId: "root-id",
pagePath: "/account",
fragment: '<ws.element ws:tag="section" />',
},
});
expect(failedVerificationResult).toMatchObject({
isError: true,
structuredContent: {
ok: false,
data: {
insertion: { instanceIds: ["committed-section-id"] },
verification: { status: "failed-after-commit" },
},
error: { code: "POST_COMMIT_VERIFICATION_FAILED" },
meta: { session: { committed: true } },
},
});
if (failedVerificationResult.structuredContent.ok !== false) {
throw new Error("Expected post-commit verification to fail");
}
expect(failedVerificationResult.structuredContent.error.message).toContain(
"Do not retry the insertion"
);
expect(failingVerification).toHaveBeenCalledTimes(2);
});
test("converts semantic Collection item jsx before executing one atomic operation", async () => {
const executeOperation = createExecuteOperation(async () =>
createEnvelope({
operationId: "instances.insertCollection",
result: {
rootInstanceIds: ["collection"],
instanceIds: ["collection", "item"],
collectionInstanceId: "collection",
itemRootInstanceId: "item",
itemParameterId: "item-parameter",
itemKeyParameterId: "item-key-parameter",
},
})
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await adapter.callTool({
name: "insert-collection",
input: {
parentInstanceId: "body",
data: { type: "expression", value: "Posts.data.items" },
itemFragment:
'<ws.element ws:tag="article"><ws.element ws:tag="h2">{expression`collectionItem.title`}</ws.element></ws.element>',
mode: "prepend",
insertIndex: 2,
},
});
expect(vi.mocked(executeOperation).mock.calls[0]?.[0]).toEqual({
command: "insert-collection",
input: {
parentInstanceId: "body",
data: { type: "expression", value: "Posts.data.items" },
itemFragment: expect.objectContaining({
instances: expect.arrayContaining([
expect.objectContaining({
component: "ws:element",
tag: "article",
}),
expect.objectContaining({ component: "ws:element", tag: "h2" }),
]),
}),
mode: "prepend",
insertIndex: 2,
},
dryRun: false,
});
});
test("rejects invalid semantic Collection data before execution", async () => {
const executeOperation = createExecuteOperation();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await expect(
adapter.callTool({
name: "insert-collection",
input: {
parentInstanceId: "body",
data: { type: "json", value: "not-an-array" },
itemFragment: '<ws.element ws:tag="article" />',
},
})
).rejects.toMatchObject({
issues: [
expect.objectContaining({
code: "invalid_union",
path: ["data", "value"],
}),
],
});
expect(executeOperation).not.toHaveBeenCalled();
});
test("rejects structured fragment objects at the mcp boundary", async () => {
const executeOperation = createExecuteOperation();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await expect(
adapter.callTool({
name: "insert-fragment",
input: {
parentInstanceId: "body",
fragment: { children: [], instances: [] },
},
})
).rejects.toThrow(
"insert-fragment requires fragment as a Webstudio JSX string"
);
expect(executeOperation).not.toHaveBeenCalled();
});
test("rejects deprecated source alias for fragment input", async () => {
const executeOperation = createExecuteOperation();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await expect(
adapter.callTool({
name: "insert-fragment",
input: {
parentInstanceId: "body",
source: '<ws.element ws:tag="section" />',
},
})
).rejects.toThrow(
"insert-fragment input.source is not supported. Put JSX in input.fragment instead."
);
expect(executeOperation).not.toHaveBeenCalled();
});
test("rejects top-level jsx alias for fragment input", async () => {
const executeOperation = createExecuteOperation();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await expect(
adapter.callTool({
name: "insert-fragment",
input: {
parentInstanceId: "body",
jsx: '<ws.element ws:tag="section" />',
},
})
).rejects.toThrow(
"insert-fragment input.jsx is not supported. Put JSX in input.fragment instead."
);
expect(executeOperation).not.toHaveBeenCalled();
});
test("explains parentId is not accepted for fragment insertion", async () => {
const executeOperation = createExecuteOperation();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await expect(
adapter.callTool({
name: "insert-fragment",
input: {
parentId: "body",
fragment: '<ws.element ws:tag="section" />',
},
})
).rejects.toThrow(
"insert-fragment input.parentId is not supported. Use input.parentInstanceId instead."
);
expect(executeOperation).not.toHaveBeenCalled();
});
test("names breakpoint when rejecting the breakpointId style field", async () => {
const executeOperation = createExecuteOperation();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await expect(
adapter.callTool({
name: "update-styles",
input: {
updates: [
{
instanceId: "body",
breakpointId: "mobile",
property: "display",
value: { type: "keyword", value: "block" },
},
],
},
})
).rejects.toThrow(
"update-styles input.updates[0].breakpointId is not supported. Use input.updates[0].breakpoint instead."
);
expect(executeOperation).not.toHaveBeenCalled();
});
test("normalizes insert-component position alias to mode", async () => {
const executeOperation = createExecuteOperation(async () =>
createEnvelope({
operationId: "components.insert",
result: {
rootInstanceIds: ["inserted"],
instanceIds: ["inserted"],
},
})
);
const operations = [
...publicMcpOperations,
publicOperation({
command: "insert-component",
id: "components.insert",
method: "mutation",
permit: "edit",
description: "Insert component",
inputSchema: getTestInputSchema(
z.object({
parentInstanceId: z.string(),
component: z.string(),
mode: z.enum(["append", "prepend", "replace"]).optional(),
insertIndex: z.number().int().nonnegative().optional(),
})
),
writeNamespaces: ["instances"],
invalidatesNamespaces: ["instances"],
}),
];
const adapter = createProjectSessionMcpCore({
operations,
createProjectSession: createSessionFactory(),
executeOperation,
startPreview: vi.fn(),
captureScreenshot: vi.fn(),
});
await adapter.callTool({
name: "insert-component",
input: {
parentInstanceId: "body",
component: "Box",
position: "append",
},
});
expect(executeOperation).toHaveBeenCalledWith(
expect.objectContaining({
command: "insert-component",
input: {
parentInstanceId: "body",
component: "Box",
mode: "append",
},
})
);
});
test("normalizes create-page description and preserves basic auth", async () => {
const executeOperation = createExecuteOperation(async () =>
createEnvelope({
operationId: "pages.create",
result: {
pageId: "page",
rootInstanceId: "root",
},
})
);
const operations = [
...publicMcpOperations,
publicOperation({
command: "create-page",
id: "pages.create",
method: "mutation",
permit: "edit",
description: "Create page",
inputSchema: getTestInputSchema(
z.object({
name: z.string(),
path: z.string(),
title: z.string().optional(),
parentFolderId: z.string().optional(),
meta: z
.object({
description: z.string().optional(),
auth: z
.object({
method: z.literal("basic"),
login: z.string(),
password: z.string(),
})
.optional(),
})
.optional(),
})
),
writeNamespaces: ["pages", "instances"],
invalidatesNamespaces: ["pages", "instances"],
}),
];
const adapter = createProjectSessionMcpCore({
operations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await adapter.callTool({
name: "create-page",
input: {
name: "Harbor Ops Design System",
path: "design-system",
title: "Harbor Ops Design System",
description:
"A realistic component coverage page for the Harbor Ops logistics product design system.",
meta: {
auth: {
method: "basic",
login: "editor",
password: "private-value",
},
},
},
});
expect(executeOperation).toHaveBeenCalledWith(
expect.objectContaining({
command: "create-page",
input: {
name: "Harbor Ops Design System",
path: "/design-system",
title: "Harbor Ops Design System",
meta: {
description:
"A realistic component coverage page for the Harbor Ops logistics product design system.",
auth: {
method: "basic",
login: "editor",
password: "private-value",
},
},
},
})
);
});
test("unwraps a redundantly nested create-resource input", async () => {
const executeOperation = createExecuteOperation();
const createResourceOperation = publicOperation({
command: "create-resource",
id: "resources.create",
method: "mutation",
permit: "edit",
description: "Create resource",
inputSchema: getTestInputSchema(
z.object({
scopeInstanceId: z.string(),
dataSourceName: z.string(),
resource: z.object({
name: z.string(),
method: z.enum(["get", "post"]),
url: z.string(),
headers: z.array(z.unknown()),
searchParams: z.array(z.unknown()).optional(),
}),
})
),
writeNamespaces: ["resources"],
invalidatesNamespaces: ["resources"],
});
const adapter = createProjectSessionMcpCore({
operations: [createResourceOperation],
createProjectSession: createSessionFactory(),
executeOperation,
});
const input = {
scopeInstanceId: "root",
dataSourceName: "accountSession",
resource: {
name: "Account session via server",
method: "get",
url: "/api/auth/session",
headers: [],
searchParams: [],
},
};
await adapter.callTool({
name: "create-resource",
input: { resource: input },
});
expect(executeOperation).toHaveBeenCalledWith(
expect.objectContaining({ command: "create-resource", input })
);
});
test("suggests page structure tools when page detail input is unsupported", async () => {
const executeOperation: ExecuteOperation = vi.fn();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await expect(
adapter.callTool({
name: "get-page-by-path",
input: { path: "/design-system", detail: "roots" },
})
).rejects.toThrow(
"Use get-page/get-page-by-path for page metadata, list-instances to inspect page root contents, and inspect-instance for props, styles, children, bindings, or sources."
);
expect(executeOperation).not.toHaveBeenCalled();
});
test("wraps bare array input for style operation tools", async () => {
const updates = [
{
instanceId: "instance-id",
property: "box-shadow",
value: { type: "keyword", value: "none" },
},
];
const { adapter, executeOperation } = createTestMcpCore({
operationId: "styles.updateDeclarations",
result: { styleKeys: [] },
});
await adapter.callTool({
name: "update-styles",
input: updates,
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-styles",
input: { updates },
dryRun: false,
});
});
test("bounds large style mutation results at the MCP boundary", async () => {
const styleKeys = Array.from(
{ length: 100 },
(_, index) => `instance:base:property-${index}:`
);
const { adapter } = createTestMcpCore({
operationId: "styles.updateDeclarations",
result: { styleKeys },
});
const result = await adapter.callTool({
name: "update-styles",
input: { updates: [] },
});
expect(result.structuredContent.data).toEqual({
styleKeys: styleKeys.slice(0, 20),
styleKeyCount: 100,
styleKeysTruncated: true,
});
expect(JSON.stringify(result.structuredContent).length).toBeLessThan(1500);
});
test("parses stringified structured fields using the MCP input schema", async () => {
const { adapter, executeOperation } = createTestMcpCore({
operationId: "pages.update",
result: { pageId: "page-id" },
});
await adapter.callTool({
name: "update-page",
input: {
pageId: "page-id",
values: JSON.stringify({
title: '"Pricing"',
meta: { description: '"Plans"' },
}),
},
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-page",
input: {
pageId: "page-id",
values: {
title: '"Pricing"',
meta: { description: '"Plans"' },
},
},
dryRun: false,
});
});
test("parses stringified single-array tool fields using the MCP input schema", async () => {
const updates = [
{
instanceId: "instance-id",
property: "color",
value: { type: "keyword", value: "red" },
},
];
const { adapter, executeOperation } = createTestMcpCore({
operationId: "styles.updateDeclarations",
result: { styleKeys: [] },
});
await adapter.callTool({
name: "update-styles",
input: { updates: JSON.stringify(updates) },
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-styles",
input: { updates },
dryRun: false,
});
});
test("parses stringified bare single-array tool input", async () => {
const updates = [
{
instanceId: "instance-id",
property: "color",
value: { type: "keyword", value: "red" },
},
];
const { adapter, executeOperation } = createTestMcpCore({
operationId: "styles.updateDeclarations",
result: { styleKeys: [] },
});
await adapter.callTool({
name: "update-styles",
input: JSON.stringify(updates),
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-styles",
input: { updates },
dryRun: false,
});
});
test("parses stringified nested object values for unconstrained schema fields", async () => {
const updates = [
{
instanceId: "instance-id",
property: "color",
value: JSON.stringify({ type: "keyword", value: "red" }),
},
];
const { adapter, executeOperation } = createTestMcpCore({
operationId: "styles.updateDeclarations",
result: { styleKeys: [] },
});
await adapter.callTool({
name: "update-styles",
input: { updates },
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-styles",
input: {
updates: [
{
instanceId: "instance-id",
property: "color",
value: { type: "keyword", value: "red" },
},
],
},
dryRun: false,
});
});
test("parses stringified nested array values for unconstrained schema fields", async () => {
const updates = [
{
instanceId: "instance-id",
property: "font-family",
value: JSON.stringify(["Inter", "sans-serif"]),
},
];
const { adapter, executeOperation } = createTestMcpCore({
operationId: "styles.updateDeclarations",
result: { styleKeys: [] },
});
await adapter.callTool({
name: "update-styles",
input: { updates },
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-styles",
input: {
updates: [
{
instanceId: "instance-id",
property: "font-family",
value: ["Inter", "sans-serif"],
},
],
},
dryRun: false,
});
});
test("normalizes primitive CSS values to typed keyword values", async () => {
const updates = [
{
instanceId: "instance-id",
property: "font-family",
value: "TokenFont",
},
];
const { adapter, executeOperation } = createTestMcpCore({
operationId: "styles.updateDeclarations",
result: { styleKeys: [] },
});
await adapter.callTool({
name: "update-styles",
input: { updates },
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-styles",
input: {
updates: [
{
instanceId: "instance-id",
property: "font-family",
value: { type: "keyword", value: "TokenFont" },
},
],
},
dryRun: false,
});
});
test("normalizes malformed typed CSS literals to keyword values", async () => {
const updates = [
{
instanceId: "spacing-instance",
property: "padding",
value: { type: "unit", value: "48px" },
},
{
instanceId: "gap-instance",
property: "gap",
value: { type: "length", value: "2rem" },
},
{
instanceId: "color-instance",
property: "color",
value: { type: "color", value: "#fff" },
},
{
instanceId: "structured-color-instance",
property: "color",
value: {
type: "color",
colorSpace: "srgb",
components: [1, 1, 1],
alpha: 1,
value: "#fff",
},
},
];
const { adapter, executeOperation } = createTestMcpCore({
operationId: "styles.updateDeclarations",
result: { styleKeys: [] },
});
await adapter.callTool({
name: "update-styles",
input: { updates },
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-styles",
input: {
updates: [
...updates.slice(0, 3).map((update) => ({
...update,
value: { type: "keyword", value: update.value.value },
})),
updates[3],
],
},
dryRun: false,
});
});
test("flattens grouped style declarations before validation", async () => {
const { adapter, executeOperation } = createTestMcpCore({
operationId: "styles.updateDeclarations",
result: { styleKeys: [] },
});
await adapter.callTool({
name: "update-styles",
input: {
updates: [
{
instanceId: "hero-instance",
breakpoint: "mobile-breakpoint",
styles: {
display: "grid",
gap: { type: "unit", value: "24px" },
},
},
{
instanceId: "title-instance",
declarations: { color: "#123456" },
},
],
},
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-styles",
input: {
updates: [
{
instanceId: "hero-instance",
breakpoint: "mobile-breakpoint",
property: "display",
value: { type: "keyword", value: "grid" },
},
{
instanceId: "hero-instance",
breakpoint: "mobile-breakpoint",
property: "gap",
value: { type: "keyword", value: "24px" },
},
{
instanceId: "title-instance",
property: "color",
value: { type: "keyword", value: "#123456" },
},
],
},
dryRun: false,
});
});
test("resolves discriminated input branches before parsing JSON-looking strings", async () => {
const operation = publicOperation({
command: "update-discriminated-value",
id: "test.updateDiscriminatedValue",
method: "mutation",
permit: "build",
description: "Update a discriminated value",
inputSchema: getTestInputSchema(
z.object({
updates: z.array(
z.discriminatedUnion("type", [
z.object({ type: z.literal("string"), value: z.string() }),
z.object({ type: z.literal("json"), value: z.unknown() }),
])
),
})
),
writeNamespaces: ["props"],
invalidatesNamespaces: ["props"],
});
const executeOperation = createExecuteOperation();
const adapter = createProjectSessionMcpCore({
operations: [operation],
createProjectSession: createSessionFactory(),
executeOperation,
});
const json = '{"@context":"https://schema.org","@type":1}';
await adapter.callTool({
name: operation.command,
input: {
updates: [
{ type: "string", value: json },
{ type: "json", value: json },
],
},
});
expect(executeOperation).toHaveBeenCalledWith({
command: operation.command,
input: {
updates: [
{ type: "string", value: json },
{ type: "json", value: JSON.parse(json) },
],
},
dryRun: false,
});
});
test("parses stringified record values through additionalProperties schemas", async () => {
const { adapter, executeOperation } = createTestMcpCore({
operationId: "pages.update",
result: { pageId: "page-id" },
});
await adapter.callTool({
name: "update-page",
input: {
pageId: "page-id",
values: {
custom: {
settings: JSON.stringify({ enabled: true }),
},
},
},
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-page",
input: {
pageId: "page-id",
values: {
custom: {
settings: { enabled: true },
},
},
},
dryRun: false,
});
});
test("keeps and uses root additionalProperties schemas from generated input schema", async () => {
const operation = publicOperation({
command: "update-settings",
id: "settings.update",
method: "mutation",
permit: "edit",
description: "Update settings",
inputSchema: getTestInputSchema(
z.object({ known: z.string() }).catchall(
z.object({
enabled: z.boolean(),
})
)
),
});
const executeOperation = createExecuteOperation(async () =>
createEnvelope({
operationId: "settings.update",
result: { ok: true },
})
);
const adapter = createProjectSessionMcpCore({
operations: [operation],
createProjectSession: createSessionFactory(),
executeOperation,
});
expect(listProjectSessionMcpTools([operation])[0]?.inputSchema).toEqual(
expect.objectContaining({
additionalProperties: expect.objectContaining({
type: "object",
properties: expect.objectContaining({
enabled: { type: "boolean" },
}),
}),
})
);
await adapter.callTool({
name: "update-settings",
input: {
known: "value",
custom: JSON.stringify({ enabled: true }),
},
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-settings",
input: {
known: "value",
custom: { enabled: true },
},
dryRun: false,
});
});
test("keeps allOf schema branches conjunctive when parsing stringified inputs", async () => {
const operation = publicOperation({
command: "update-conflicting",
id: "settings.updateConflicting",
method: "mutation",
permit: "edit",
description: "Update conflicting settings",
inputSchema: getTestInputSchema(
z.object({
settings: z
.object({
value: z.string(),
})
.and(
z.object({
value: z.object({
enabled: z.boolean(),
}),
})
),
})
),
});
const executeOperation = createExecuteOperation(async () =>
createEnvelope({
operationId: "settings.updateConflicting",
result: { ok: true },
})
);
const adapter = createProjectSessionMcpCore({
operations: [operation],
createProjectSession: createSessionFactory(),
executeOperation,
});
await adapter.callTool({
name: "update-conflicting",
input: {
settings: {
value: JSON.stringify({ enabled: true }),
},
},
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-conflicting",
input: {
settings: {
value: JSON.stringify({ enabled: true }),
},
},
dryRun: false,
});
});
test("parses nested fields from schemas with object keywords and no explicit type", async () => {
const operation = publicOperation({
command: "update-loose-schema",
id: "settings.updateLooseSchema",
method: "mutation",
permit: "edit",
description: "Update settings with loose schema",
inputSchema: {
properties: {
settings: {
properties: {
custom: {
properties: {
enabled: { type: "boolean" },
},
},
},
},
},
},
});
const executeOperation = createExecuteOperation(async () =>
createEnvelope({
operationId: "settings.updateLooseSchema",
result: { ok: true },
})
);
const adapter = createProjectSessionMcpCore({
operations: [operation],
createProjectSession: createSessionFactory(),
executeOperation,
});
await adapter.callTool({
name: "update-loose-schema",
input: {
settings: {
custom: JSON.stringify({ enabled: true }),
},
},
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-loose-schema",
input: {
settings: {
custom: { enabled: true },
},
},
dryRun: false,
});
});
test("parses tuple items with prefix item schemas", async () => {
const operation = publicOperation({
command: "update-range",
id: "settings.updateRange",
method: "mutation",
permit: "edit",
description: "Update range",
inputSchema: getTestInputSchema(
z.object({
range: z.tuple([
z.string(),
z.object({
enabled: z.boolean(),
}),
]),
})
),
});
const executeOperation = createExecuteOperation(async () =>
createEnvelope({
operationId: "settings.updateRange",
result: { ok: true },
})
);
const adapter = createProjectSessionMcpCore({
operations: [operation],
createProjectSession: createSessionFactory(),
executeOperation,
});
await adapter.callTool({
name: "update-range",
input: {
range: ["sm", JSON.stringify({ enabled: true })],
},
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-range",
input: {
range: ["sm", { enabled: true }],
},
dryRun: false,
});
});
test("parses stringified nested object values inside union schema fields", async () => {
const transactions = [
{
id: "transaction-id",
payload: [
{
namespace: "props",
patches: [
{
op: "add",
path: ["prop-id"],
value: JSON.stringify({
id: "prop-id",
name: "data",
type: "json",
value: { enabled: true },
}),
},
],
},
],
},
];
const { adapter, executeOperation } = createTestMcpCore({
operationId: "build.applyPatch",
result: { success: true },
});
await adapter.callTool({
name: "apply-patch",
input: { transactions },
});
expect(executeOperation).toHaveBeenCalledWith({
command: "apply-patch",
input: {
transactions: [
{
id: "transaction-id",
payload: [
{
namespace: "props",
patches: [
{
op: "add",
path: ["prop-id"],
value: {
id: "prop-id",
name: "data",
type: "json",
value: { enabled: true },
},
},
],
},
],
},
],
},
dryRun: false,
});
});
test("wraps bare array input for single-array operation tools", async () => {
const instanceIds = ["instance-id"];
const executeOperation: ExecuteOperation = vi.fn(async () =>
createEnvelope({
operationId: "instances.delete",
result: { instanceIds },
})
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await adapter.callTool({
name: "delete-instance",
input: instanceIds,
});
expect(executeOperation).toHaveBeenCalledWith({
command: "delete-instance",
input: { instanceIds },
dryRun: true,
});
});
test("does not wrap bare array input for unconstrained single-field tools", async () => {
const operation = publicOperation({
command: "update-anything",
id: "settings.updateAnything",
method: "mutation",
permit: "edit",
description: "Update anything",
inputSchema: getTestInputSchema(
z.object({
value: z.unknown(),
})
),
});
const executeOperation = createExecuteOperation(async () =>
createEnvelope({
operationId: "settings.updateAnything",
result: { ok: true },
})
);
const adapter = createProjectSessionMcpCore({
operations: [operation],
createProjectSession: createSessionFactory(),
executeOperation,
});
const value = ["not", "a", "root", "wrapper"];
await adapter.callTool({
name: "update-anything",
input: value,
});
expect(executeOperation).toHaveBeenCalledWith({
command: "update-anything",
input: value,
dryRun: false,
});
});
test("calls import through injected project importer", async () => {
const importProject = vi.fn(async () => ({ imported: true as const }));
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
importProject,
});
const result = await adapter.callTool({
name: "import",
input: {
to: "https://p-destination.wstd.dev/?authToken=token",
assetsDir: "assets",
ignoreVersionCheck: true,
skipAssets: true,
},
});
expect(importProject).toHaveBeenCalledWith({
to: "https://p-destination.wstd.dev/?authToken=token",
assetsDir: "assets",
ignoreVersionCheck: true,
skipAssets: true,
});
expect(result.structuredContent.data).toEqual({ imported: true });
});
test("includes import in capability index when importer is provided", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
importProject: vi.fn(async () => ({ imported: true as const })),
});
const index = await adapter.callTool({ name: "meta.index" });
const capabilities = (
index.structuredContent.data as {
capabilities: { tools: string[] }[];
}
).capabilities;
expect(capabilities.flatMap((capability) => capability.tools)).toContain(
"import"
);
});
test("categorizes text asset editing with asset capabilities", async () => {
const updateAssetContent = publicOperation({
command: "update-asset-content",
id: "assets.updateContent",
method: "mutation",
permit: "edit",
description: "Update text asset content",
inputSchema: getTestInputSchema(
z.object({
assetId: z.string(),
expectedName: z.string(),
content: z.string(),
})
),
readNamespaces: ["assets"],
writeNamespaces: ["assets"],
invalidatesNamespaces: ["assets"],
});
const adapter = createProjectSessionMcpCore({
operations: [...publicMcpOperations, updateAssetContent],
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
const index = await adapter.callTool({ name: "meta.index" });
const capabilities = (
index.structuredContent.data as {
capabilities: { area: string; tools: string[] }[];
}
).capabilities;
const assets = capabilities.find(({ area }) => area === "assets");
expect(assets?.tools).toContain("update-asset-content");
});
test("rejects import without destination share link", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
importProject: vi.fn(),
});
await expect(
adapter.callTool({ name: "import", input: {} })
).rejects.toThrow("import requires destination share link in to.");
});
test("delegates catalog operation tools without creating core session", async () => {
const createProjectSession = createSessionFactory();
const executeOperation: ExecuteOperation = vi.fn(async () =>
createEnvelope({
operationId: "pages.list",
result: [],
namespaces: {
read: ["pages"],
write: [],
invalidated: [],
missing: [],
},
})
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession,
executeOperation,
});
await adapter.callTool({ name: "list-pages" });
await adapter.callTool({ name: "list-pages" });
expect(createProjectSession).not.toHaveBeenCalled();
expect(executeOperation).toHaveBeenCalledTimes(2);
});
test("calls project session management tools directly", async () => {
const session = createSession({
initialize: vi.fn(async () =>
createEnvelope({
operationId: "project-session.status",
result: { loaded: true },
namespaces: {
read: ["pages"],
write: [],
invalidated: [],
missing: ["assets"],
},
diagnostics: [
{
level: "warning",
code: "STALE_ASSETS",
message: "Assets need refreshing.",
details: { namespace: "assets" },
},
],
state: {
committed: false,
freshness: {
pages: {
status: "fresh",
version: 1,
source: "remote",
loadedAt: "2026-07-10T12:00:00.000Z",
},
},
},
})
),
refresh: vi.fn(async () =>
createEnvelope({
operationId: "project-session.refresh",
version: 2,
source: "remote",
result: { refreshedNamespaces: ["pages"] },
namespaces: {
read: ["pages"],
write: [],
invalidated: [],
missing: [],
},
})
),
reset: vi.fn(async () =>
createEnvelope({
operationId: "project-session.reset",
buildId: undefined,
version: undefined,
result: { loaded: false },
})
),
});
const onProjectSessionChange = vi.fn();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(session),
executeOperation: createExecuteOperation(),
onProjectSessionChange,
});
const status = await adapter.callTool({ name: "status" });
const verboseStatus = await adapter.callTool({
name: "status",
input: { verbose: true },
});
const refresh = await adapter.callTool({
name: "refresh",
input: { namespaces: ["pages"] },
});
expect(session.initialize).toHaveBeenCalledTimes(3);
const reset = await adapter.callTool({ name: "reset-session" });
expect(status.structuredContent.data).toEqual({ loaded: true });
expect(status.structuredContent.meta.session).not.toHaveProperty(
"namespaces"
);
expect(verboseStatus.structuredContent.meta.session).toMatchObject({
namespaces: {
read: ["pages"],
missing: ["assets"],
},
diagnostics: [
{
code: "STALE_ASSETS",
details: { namespace: "assets" },
},
],
freshness: {
pages: {
status: "fresh",
source: "remote",
loadedAt: "2026-07-10T12:00:00.000Z",
},
},
});
expect(session.initialize).toHaveBeenCalledTimes(3);
expect(session.refresh).toHaveBeenCalledWith(["pages"]);
expect(refresh.structuredContent.meta.session).toEqual(
expect.objectContaining({ operationId: "project-session.refresh" })
);
expect(reset.structuredContent.meta.session).toEqual(
expect.objectContaining({ operationId: "project-session.reset" })
);
expect(onProjectSessionChange).toHaveBeenCalledTimes(2);
});
test("calls meta tools without initializing project session", async () => {
const session = createSession({
initialize: vi.fn(),
refresh: vi.fn(),
reset: vi.fn(),
});
const uploadAssetsOperation = {
...publicMcpOperations[0]!,
command: "upload-assets" as const,
description: "Upload multiple assets",
};
const contextOperations = [
"list-assets",
"list-variables",
"get-asset",
].map((command) =>
publicOperation({
command,
id: `test.${command}`,
description: command,
})
);
const adapter = createProjectSessionMcpCore({
operations: [
...publicMcpOperations,
uploadAssetsOperation,
...contextOperations,
],
createProjectSession: createSessionFactory(session),
executeOperation: createExecuteOperation(),
capturePageScreenshots: vi.fn(async () => []),
});
const index = await adapter.callTool({ name: "meta.index" });
const guide = await adapter.callTool({
name: "meta.guide",
input: { brief: "publish a site" },
});
const workflow = await adapter.callTool({
name: "workflow.next",
input: { goal: "design-system-page" },
});
const detailsWhileCheckpointed = await adapter.callTool({
name: "meta.get-more-tools",
input: { tools: ["publish"] },
});
await expect(
adapter.callTool({ name: "create-page", input: { name: "Blocked" } })
).rejects.toThrow("CHECKPOINT_REQUIRED");
const ackCheckpoint = () =>
adapter.callTool({
name: "checkpoint.ack",
input: {
reported: true,
continueAfterReport: true,
summary: "reported checkpoint",
},
});
await ackCheckpoint();
const workflowPhase = await adapter.callTool({
name: "workflow.next",
input: { goal: "design-system-page", phase: "dry-run-section" },
});
await ackCheckpoint();
const workflowPagePhase = await adapter.callTool({
name: "workflow.next",
input: { goal: "design-system-page", phase: "page-creation" },
});
await ackCheckpoint();
const workflowPresentationPhase = await adapter.callTool({
name: "workflow.next",
input: { goal: "design-system-page", phase: "presentation-pass" },
});
await ackCheckpoint();
const details = await adapter.callTool({
name: "meta.get-more-tools",
input: { tools: ["publish"] },
});
const legacyDetails = await adapter.callTool({
name: "meta.get_more_tools",
input: { tools: ["meta.get_more_tools", "meta.get-more-tools"] },
});
const underscoreToolDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { tools: ["insert_fragment"] },
});
const stringifiedToolDetails = 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" },
});
expect(session.initialize).not.toHaveBeenCalled();
expect(underscoreToolDetails.structuredContent.data).toEqual(
expect.objectContaining({
missingTools: [],
count: 1,
tools: expect.arrayContaining([
expect.objectContaining({ name: "insert-fragment" }),
]),
})
);
expect(stringifiedToolDetails.structuredContent.data).toEqual(
expect.objectContaining({
requestedTools: ["insert-fragment"],
missingTools: [],
count: 1,
})
);
expect(index.structuredContent.data).toEqual(
expect.objectContaining({
startHere: expect.arrayContaining(["meta.guide", "workflow.next"]),
capabilities: expect.arrayContaining([
expect.objectContaining({
area: "publish",
tools: ["publish"],
}),
]),
})
);
expect(index.structuredContent.data).not.toEqual(
expect.objectContaining({
capabilities: expect.arrayContaining([
expect.objectContaining({
tools: expect.arrayContaining(["create-page"]),
}),
]),
})
);
expect(guide.structuredContent.data).toEqual(
expect.objectContaining({
tools: expect.arrayContaining([
expect.objectContaining({ name: "publish" }),
]),
})
);
expect(guide.structuredContent.data).toEqual(
expect.objectContaining({
tools: expect.arrayContaining([
expect.objectContaining({
name: "publish",
mcpExamples: [{ target: "production" }],
}),
]),
})
);
expect(workflow.structuredContent.data).toEqual(
expect.objectContaining({
goal: "design-system-page",
phase: "discovery",
mustReturnAfter: true,
checkpoint: expect.objectContaining({ required: true }),
allowedTools: ["components.coverage-plan"],
nextPhase: "page-creation",
})
);
expect(detailsWhileCheckpointed.structuredContent.data).toEqual(
expect.objectContaining({ tools: expect.any(Array) })
);
expect(workflowPhase.structuredContent.data).toEqual(
expect.objectContaining({
goal: "design-system-page",
phase: "dry-run-section",
mustReturnAfter: true,
checkpoint: expect.objectContaining({ required: true }),
allowedTools: expect.arrayContaining(["insert-fragment"]),
commandPattern: expect.stringContaining(
"--input-file .temp/design-system-section.json"
),
inputFile: expect.objectContaining({
path: ".temp/design-system-section.json",
contents: expect.objectContaining({
fragment: expect.stringContaining("<h2>"),
}),
}),
nextPhase: "commit-section",
})
);
expect(workflowPagePhase.structuredContent.data).toEqual(
expect.objectContaining({
goal: "design-system-page",
phase: "page-creation",
allowedTools: expect.arrayContaining(["list-pages"]),
commandPattern: expect.stringMatching(/list-pages.*limit/),
fallbackCommandPattern: expect.stringMatching(
/create-page.*\/design-system/
),
})
);
expect(workflowPresentationPhase.structuredContent.data).toEqual(
expect.objectContaining({
goal: "design-system-page",
phase: "presentation-pass",
allowedTools: expect.arrayContaining(["update-styles"]),
})
);
expect(details.structuredContent.data).toEqual(
expect.objectContaining({
requestedTools: ["publish"],
missingTools: [],
count: 1,
omittedCount: 0,
tools: [
expect.objectContaining({
name: "publish",
inputSchema: expect.any(Object),
inputFields: ["target", "domains"],
mcpExamples: [{ target: "production" }],
}),
],
})
);
expect(legacyDetails.structuredContent.data).toEqual(
expect.objectContaining({
requestedTools: ["meta.get_more_tools", "meta.get-more-tools"],
missingTools: [],
tools: [expect.objectContaining({ name: "meta.get-more-tools" })],
})
);
expect(fuzzyDetails.structuredContent.data).toEqual(
expect.objectContaining({
count: expect.any(Number),
omittedCount: expect.any(Number),
tools: expect.any(Array),
})
);
expect(
(fuzzyDetails.structuredContent.data as { tools: unknown[] }).tools.length
).toBeLessThanOrEqual(12);
const insertDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "insert component" },
});
const insertToolNames = (
insertDetails.structuredContent.data as { tools: { name: string }[] }
).tools.map((tool) => tool.name);
expect(insertToolNames[0]).toBe("insert-fragment");
if (insertToolNames.includes("insert-component")) {
expect(insertToolNames.indexOf("insert-component")).toBeLessThan(
insertToolNames.indexOf("list-instances")
);
}
const styledSectionDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "create a styled section" },
});
const styledSectionToolNames = (
styledSectionDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
expect(styledSectionToolNames[0]).toBe("insert-fragment");
expect(styledSectionToolNames).not.toEqual(
expect.arrayContaining(["delete-folder", "import", "create-breakpoint"])
);
const heroSectionDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "style hero section" },
});
const heroSectionToolNames = (
heroSectionDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
expect(heroSectionToolNames[0]).toBe("insert-fragment");
expect(heroSectionToolNames).not.toEqual(
expect.arrayContaining([
"delete-page",
"delete-folder",
"delete-styles",
"delete-breakpoint",
])
);
const deleteStylesDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "delete unused styles" },
});
const deleteStylesToolNames = (
deleteStylesDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
expect(deleteStylesToolNames[0]).toBe("delete-styles");
expect(deleteStylesToolNames).not.toEqual(
expect.arrayContaining([
"delete-page",
"delete-folder",
"delete-redirect",
"insert-fragment",
"update-styles",
])
);
const deleteCssVariablesDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "delete CSS variables" },
});
const deleteCssVariablesToolNames = (
deleteCssVariablesDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (deleteCssVariablesToolNames.includes("delete-css-variable")) {
expect(deleteCssVariablesToolNames[0]).toBe("delete-css-variable");
}
expect(deleteCssVariablesToolNames).not.toEqual(
expect.arrayContaining(["delete-variable"])
);
const deleteVariablesDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "delete variables" },
});
const deleteVariablesToolNames = (
deleteVariablesDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (deleteVariablesToolNames.includes("delete-variable")) {
expect(deleteVariablesToolNames[0]).toBe("delete-variable");
}
const createCssVariableDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "create CSS variable" },
});
const createCssVariableToolNames = (
createCssVariableDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (createCssVariableToolNames.includes("define-css-variable")) {
expect(createCssVariableToolNames[0]).toBe("define-css-variable");
}
const createVariablesDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "create variables" },
});
const createVariablesToolNames = (
createVariablesDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (createVariablesToolNames.includes("create-variable")) {
expect(createVariablesToolNames[0]).toBe("create-variable");
}
const deleteDesignTokenDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "delete design token" },
});
const deleteDesignTokenToolNames = (
deleteDesignTokenDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
expect(deleteDesignTokenToolNames).not.toEqual(
expect.arrayContaining([
"delete-design-token-styles",
"detach-design-token",
])
);
const deleteDesignTokenStylesDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "delete design token styles" },
});
const deleteDesignTokenStylesToolNames = (
deleteDesignTokenStylesDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (
deleteDesignTokenStylesToolNames.includes("delete-design-token-styles")
) {
expect(deleteDesignTokenStylesToolNames[0]).toBe(
"delete-design-token-styles"
);
}
const detachDesignTokenDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "remove design token from component" },
});
const detachDesignTokenToolNames = (
detachDesignTokenDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (detachDesignTokenToolNames.includes("detach-design-token")) {
expect(detachDesignTokenToolNames[0]).toBe("detach-design-token");
}
const updateTextDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "update text" },
});
const updateTextToolNames = (
updateTextDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
expect(updateTextToolNames[0]).toBe("update-text");
expect(updateTextToolNames).not.toEqual(
expect.arrayContaining(["update-page", "update-styles"])
);
const deletePageDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "delete page" },
});
const deletePageToolNames = (
deletePageDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (deletePageToolNames.includes("delete-page")) {
expect(deletePageToolNames[0]).toBe("delete-page");
}
expect(deletePageToolNames).toEqual(expect.arrayContaining(["list-pages"]));
expect(deletePageToolNames).not.toEqual(
expect.arrayContaining([
"create-page",
"update-page",
"duplicate-page",
"delete-folder",
])
);
const deletePagesDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "delete pages" },
});
const deletePagesToolNames = (
deletePagesDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (deletePagesToolNames.includes("delete-page")) {
expect(deletePagesToolNames[0]).toBe("delete-page");
}
expect(deletePagesToolNames).not.toEqual(
expect.arrayContaining(["create-page", "update-page", "delete-folder"])
);
const componentTreeDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "insert styled component tree" },
});
const componentTreeToolNames = (
componentTreeDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
expect(componentTreeToolNames[0]).toBe("insert-fragment");
const replaceImageDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "replace image" },
});
const replaceImageToolNames = (
replaceImageDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (replaceImageToolNames.includes("replace-asset")) {
expect(replaceImageToolNames[0]).toBe("replace-asset");
}
const moveComponentDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "move component" },
});
const moveComponentToolNames = (
moveComponentDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (moveComponentToolNames.includes("move-instance")) {
expect(moveComponentToolNames[0]).toBe("move-instance");
}
const cloneSectionDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "clone section" },
});
const cloneSectionToolNames = (
cloneSectionDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (cloneSectionToolNames.includes("clone-instance")) {
expect(cloneSectionToolNames[0]).toBe("clone-instance");
}
const deleteComponentDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "delete component" },
});
const deleteComponentToolNames = (
deleteComponentDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (deleteComponentToolNames.includes("delete-instance")) {
expect(deleteComponentToolNames[0]).toBe("delete-instance");
}
const compareScreenshotsDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "compare screenshots" },
});
const compareScreenshotsToolNames = (
compareScreenshotsDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (compareScreenshotsToolNames.includes("screenshot.diff")) {
expect(compareScreenshotsToolNames[0]).toBe("screenshot.diff");
}
const findComponentDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "find component" },
});
const findComponentToolNames = (
findComponentDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (findComponentToolNames.includes("components.search")) {
expect(findComponentToolNames[0]).toBe("components.search");
}
const getComponentDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "get component details" },
});
const jsonLdGuide = await adapter.callTool({
name: "meta.guide",
input: {
brief: "Add JSON-LD structured data to the home page",
workflow: "json-ld",
},
});
const collectionGuide = await adapter.callTool({
name: "meta.guide",
input: {
brief: "Render an array of blog posts as repeated cards",
workflow: "collection",
},
});
const markdownBlogGuide = await adapter.callTool({
name: "meta.guide",
input: {
brief:
"Create a Markdown-based blog with overview and post pages from Assets",
workflow: "markdown-blog",
},
});
const contentBlockSourceGuide = await adapter.callTool({
name: "meta.guide",
input: {
brief: "Connect an MDX article and make its designed header editable",
workflow: "content-block-source",
},
});
const authenticatedPageGuide = await adapter.callTool({
name: "meta.guide",
input: {
brief: "Build a Supabase authenticated account page",
workflow: "authenticated-page",
},
});
const fontAssetGuide = await adapter.callTool({
name: "meta.guide",
input: {
brief: "Upload and correct two font assets",
workflow: "font-assets",
},
});
const designInputGuide = await adapter.callTool({
name: "meta.guide",
input: {
brief: "Recreate this Figma design as a responsive page",
workflow: "design-input",
},
});
const craftGuide = await adapter.callTool({
name: "meta.guide",
input: {
brief: "Add a section that preserves this Craft project",
workflow: "craft",
},
});
const authenticatedPageGuideTools = (
authenticatedPageGuide.structuredContent.data as {
tools: Array<Record<string, unknown>>;
}
).tools;
expect(
authenticatedPageGuideTools.every(
(tool) => Object.keys(tool).join(",") === "name"
)
).toBe(true);
const designInputGuideTools = (
designInputGuide.structuredContent.data as {
tools: Array<Record<string, unknown>>;
}
).tools;
expect(
designInputGuideTools.every(
(tool) => Object.keys(tool).join(",") === "name"
)
).toBe(true);
const getComponentToolNames = (
getComponentDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (getComponentToolNames.includes("components.get")) {
expect(getComponentToolNames[0]).toBe("components.get");
}
const coverageDetails = await adapter.callTool({
name: "meta.get-more-tools",
input: { brief: "check component coverage" },
});
const coverageToolNames = (
coverageDetails.structuredContent.data as {
tools: { name: string }[];
}
).tools.map((tool) => tool.name);
if (coverageToolNames.includes("components.coverage-status")) {
expect(coverageToolNames[0]).toBe("components.coverage-status");
}
const jsonLdGuideData = jsonLdGuide.structuredContent.data as {
recipe: {
fixedCodeUpdate: {
updates: Array<{
instanceId: string;
name: string;
type: string;
value: string;
}>;
};
dynamicCodeBinding: {
bindings: Array<{
instanceId: string;
name: string;
binding: { type: string; value: string };
}>;
};
};
tools: Array<{ name: string }>;
};
expect(jsonLdGuideData.tools.map(({ name }) => name)).toEqual(
expect.arrayContaining(["components.get", "audit"])
);
const fixedCode = jsonLdGuideData.recipe.fixedCodeUpdate.updates[0];
expect(fixedCode).toMatchObject({
instanceId: "<json-ld-instance-id>",
name: "code",
type: "string",
});
expect(JSON.parse(fixedCode?.value ?? "")).toEqual({
"@context": "https://schema.org",
"@type": "Organization",
name: "Acme",
});
const dynamicCodeInput =
jsonLdGuideData.recipe.dynamicCodeBinding.bindings[0];
expect(dynamicCodeInput).toMatchObject({
instanceId: "<json-ld-instance-id>",
name: "code",
binding: { type: "expression" },
});
const dynamicCodeExpression = parseExpressionAt(
dynamicCodeInput?.binding.value ?? "",
0,
{ ecmaVersion: "latest" }
);
expect(dynamicCodeExpression).toMatchObject({
type: "ObjectExpression",
properties: expect.arrayContaining([
expect.objectContaining({
key: expect.objectContaining({ name: "headline" }),
value: expect.objectContaining({
type: "MemberExpression",
object: expect.objectContaining({ name: "post" }),
property: expect.objectContaining({ name: "title" }),
}),
}),
]),
});
expect(collectionGuide.structuredContent.data).toEqual(
expect.objectContaining({
tools: expect.arrayContaining([
expect.objectContaining({ name: "insert-collection" }),
]),
})
);
expect(markdownBlogGuide.structuredContent.data).toEqual(
expect.objectContaining({
recipe: expect.objectContaining({
articleFormat: {
extension: "md",
editSurface: "asset-source-editor",
publishCompilation: false,
assetSyncDownloadsFiles: true,
visualAlternative: {
extension: "mdx",
editSurface: "content-block-canvas",
publishCompilation: true,
assetSyncDownloadsFiles: true,
workflow: "general",
tool: "connect-content-block-source",
},
},
executionOrder: [
{ tool: "create-asset-folder", calls: 1 },
{ tool: "upload-assets", calls: 1 },
{ tool: "create-page", calls: 2 },
{ tool: "validate-asset-query", calls: 2 },
{ tool: "preview-asset-query", calls: 1 },
{ tool: "meta.get-more-tools", calls: 1 },
{ tool: "create-assets-resource", calls: 2 },
{ tool: "insert-collection", calls: 1 },
{ tool: "insert-fragment", calls: 1 },
{ tool: "update-page", calls: 1 },
{
tool: "verify-page-responsive",
calls: 2,
terminal: true,
},
],
pages: [
{ path: "/blog", name: "Blog" },
{ path: "/blog/:slug", name: "Blog article" },
],
toolDiscovery: {
tool: "meta.get-more-tools",
when: "after-query-verification",
input: {
tools: ["create-assets-resource"],
},
},
overviewResource: expect.objectContaining({
dataSourceName: "posts",
query: expect.objectContaining({
result: "many",
limit: { type: "literal", value: 20 },
offset: { type: "literal", value: 0 },
}),
}),
overviewValidationQuery: expect.objectContaining({
where: {
all: expect.arrayContaining([
expect.objectContaining({ value: "md" }),
expect.objectContaining({ value: "<blog-folder-id>" }),
expect.objectContaining({ value: true }),
]),
},
limit: 20,
offset: 0,
}),
detailResource: expect.objectContaining({
dataSourceName: "post",
query: expect.objectContaining({
result: "one",
content: { mode: "markdown-body-ref" },
}),
}),
detailValidationQuery: expect.objectContaining({
result: "one",
where: {
all: expect.arrayContaining([
expect.objectContaining({ value: "md" }),
expect.objectContaining({ value: "<blog-folder-id>" }),
expect.objectContaining({ value: "aurora-trails" }),
expect.objectContaining({ value: true }),
]),
},
}),
overviewCollection: expect.objectContaining({
itemFragment: expect.stringContaining(
"collectionItem.properties.author.name"
),
}),
detailFragment: expect.objectContaining({
parentInstanceId: "<detail-root-id>",
fragment: expect.any(String),
}),
detailPageSettings: expect.objectContaining({
pageId: "<detail-page-id>",
values: expect.objectContaining({
title: expect.stringContaining("post.data.properties.title"),
meta: expect.objectContaining({
description: expect.stringContaining(
"post.data.properties.excerpt"
),
status: "post.data ? 200 : 404",
}),
}),
}),
}),
tools: expect.arrayContaining([
expect.objectContaining({ name: "upload-assets" }),
expect.objectContaining({ name: "list-pages" }),
expect.objectContaining({ name: "list-assets" }),
expect.objectContaining({ name: "insert-collection" }),
expect.objectContaining({ name: "insert-fragment" }),
expect.objectContaining({ name: "update-page" }),
]),
})
);
expect(contentBlockSourceGuide.structuredContent.data).toMatchObject({
routing: {
workflow: "content-block-source",
matchedBy: "explicit-workflow",
},
recipe: {
executionOrder: [
{ tool: "inspect-instance", calls: 1 },
{ tool: "connect-content-block-source", calls: 1 },
{ tool: "inspect-content-block-source", calls: 1 },
{
tool: "update-text",
calls: "once per requested designed text field",
},
{ tool: "update-content-block-frontmatter", calls: 1 },
{ tool: "reload-content-block-source", calls: 1 },
{ tool: "inspect-content-block-source", calls: 1 },
{ tool: "audit", calls: 1 },
],
connectSource: {
source: { type: "asset", assetId: "<md-or-mdx-asset-id>" },
},
designedTextBinding: {
tool: "update-text",
input: {
instanceId: "<designedTextInstanceId>",
childIndex: 0,
text: "<documentVariable>.frontmatter.<exactFieldPath>",
mode: "expression",
expressionBindingMode: "readwrite",
},
},
},
tools: expect.arrayContaining([
expect.objectContaining({ name: "update-text" }),
expect.objectContaining({ name: "audit" }),
]),
});
const markdownBlogRecipe = (
markdownBlogGuide.structuredContent.data as {
recipe: {
detailResource: {
query: {
output: { fields: string[][] };
};
};
detailFragment: { fragment: string };
detailPageSettings: {
values: {
meta: { socialImageUrl: string };
};
};
};
}
).recipe;
const detailFragment = await parseWebstudioJsxFragment(
markdownBlogRecipe.detailFragment.fragment
);
const markdownEmbedInstances = detailFragment.instances.filter(
(instance) => instance.component === "MarkdownEmbed"
);
const markdownCodeProps = detailFragment.props.filter(
(prop) =>
prop.instanceId === markdownEmbedInstances[0]?.id &&
prop.name === "code" &&
prop.type === "expression"
);
expect(markdownEmbedInstances).toHaveLength(1);
expect(markdownCodeProps).toHaveLength(1);
expect(
parseDirectPathExpression(String(markdownCodeProps[0]?.value))?.path
).toEqual(["post", "data", "content", "text"]);
expect(
markdownBlogRecipe.detailResource.query.output.fields
).toContainEqual(["properties", "featureImage", "src"]);
expect(
markdownBlogRecipe.detailResource.query.output.fields
).not.toContainEqual(["properties", "featureImage"]);
expect(
markdownBlogRecipe.detailPageSettings.values.meta.socialImageUrl
).toBe('post.data.properties.featureImage.src ?? ""');
expect(
(
markdownBlogGuide.structuredContent.data as {
recipe: Record<string, unknown>;
}
).recipe
).not.toHaveProperty("detailCollection");
expect(authenticatedPageGuide.structuredContent.data).toEqual(
expect.objectContaining({
recipe: {
createResourceInput: {
scopeInstanceId: "<account-root-id>",
dataSourceName: "accountSession",
resource: {
name: "Account session via server",
method: "get",
url: "/api/auth/session",
headers: [],
searchParams: [],
},
},
},
tools: expect.arrayContaining([
expect.objectContaining({ name: "list-instances" }),
expect.objectContaining({ name: "insert-fragment-verified" }),
expect.objectContaining({ name: "verify-page-responsive" }),
]),
})
);
expect(fontAssetGuide.structuredContent.data).toEqual(
expect.objectContaining({
tools: expect.arrayContaining([
expect.objectContaining({ name: "verify-font-assets" }),
]),
})
);
expect(fontAssetGuide.structuredContent.data).not.toHaveProperty("brief");
expect(fontAssetGuide.structuredContent.data).toEqual(
expect.objectContaining({
recipe: {
upload: {
tool: "upload-assets",
input: {
assetsDir: ".webstudio/assets",
assetFields: ["name", "type", "format", "meta"],
excludedAssetFields: ["path"],
},
},
audit: { tool: "audit", input: {} },
},
})
);
for (const tool of (
fontAssetGuide.structuredContent.data as {
tools: Array<Record<string, unknown>>;
}
).tools) {
expect(Object.keys(tool)).toEqual(
tool.name === "upload-assets" ? ["name", "mcpExamples"] : ["name"]
);
}
expect(designInputGuide.structuredContent.data).toEqual(
expect.objectContaining({
recipe: {
insertion: { includeStyles: false },
tokenReuse: {
minimumAttachments: 1,
source: "inspect-design-context",
},
responsiveStyles: {
tool: "update-styles",
breakpointSource: "inspect-design-context",
minimumBreakpointSpecificUpdates: 1,
},
},
tools: expect.arrayContaining([
expect.objectContaining({ name: "inspect-design-context" }),
expect.objectContaining({ name: "components.search" }),
expect.objectContaining({ name: "insert-fragment-verified" }),
expect.objectContaining({ name: "attach-design-token" }),
expect.objectContaining({ name: "verify-page-responsive" }),
expect.objectContaining({ name: "update-styles" }),
]),
})
);
expect(craftGuide.structuredContent.data).toEqual(
expect.objectContaining({
tools: expect.arrayContaining([
expect.objectContaining({ name: "audit" }),
]),
})
);
const specializedGuide = await adapter.callTool({
name: "meta.guide",
input: { brief: "Update one font asset reference" },
});
expect(specializedGuide.structuredContent.data).not.toHaveProperty(
"focusedCorrection"
);
});
test("rejects invalid focused discovery input with path-specific messages", async () => {
const session = createSession({
initialize: vi.fn(),
refresh: vi.fn(),
reset: vi.fn(),
});
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(session),
executeOperation: createExecuteOperation(),
});
await expect(
adapter.callTool({
name: "meta.guide",
input: { brief: true },
})
).rejects.toThrow(
"meta.guide input.brief must be a string when provided. Received boolean."
);
await expect(
adapter.callTool({
name: "meta.guide",
input: { brief: "Audit this page", taskScope: "audit" },
})
).rejects.toThrow(
"meta.guide input.taskScope must be one of read-only-audit, small-value-or-reference-correction, focused-page-change, visual-change, structural-project-change, project-wide-migration."
);
await expect(
adapter.callTool({
name: "meta.guide",
input: { brief: "Build a blog", workflow: "blog" },
})
).rejects.toThrow(
"meta.guide input.workflow must be one of general, markdown-blog, json-ld, collection, expression, authenticated-page, font-assets, design-input, content-block-source, craft."
);
await expect(
adapter.callTool({
name: "meta.guide",
input: { brief: "Insert a fragment", authoredFragment: "yes" },
})
).rejects.toThrow(
"meta.guide input.authoredFragment must be a boolean when provided. Received string."
);
await expect(
adapter.callTool({
name: "meta.get-more-tools",
input: { tools: "insert-component" },
})
).rejects.toThrow(
"meta.get-more-tools input.tools must be an array of strings when provided. Received string."
);
await expect(
adapter.callTool({
name: "components.get",
input: {},
})
).rejects.toThrow("components.get input.component is required.");
await expect(
adapter.callTool({
name: "meta.index",
input: { query: "create a styled section" },
})
).rejects.toThrow(
'meta.index does not accept input. Call meta.guide with {"brief":"..."} for goal-specific guidance.'
);
await expect(
adapter.callTool({
name: "workflow.next",
input: { goal: "full-site" },
})
).rejects.toThrow(
'workflow.next currently supports goal "design-system-page".'
);
await expect(
adapter.callTool({
name: "workflow.next",
input: { goal: "design-system-page", phase: "everything" },
})
).rejects.toThrow(
"workflow.next input.phase must be one of discovery, page-creation, dry-run-section, commit-section, coverage-batch, presentation-pass."
);
expect(session.initialize).not.toHaveBeenCalled();
});
test("gets metadata for a hidden required template child", async () => {
const session = createSession({
initialize: vi.fn(),
refresh: vi.fn(),
reset: vi.fn(),
});
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(session),
executeOperation: createExecuteOperation(),
});
const details = await adapter.callTool({
name: "components.get",
input: { component: "VimeoPreviewImage" },
});
const listing = await adapter.callTool({
name: "components.list",
input: { source: "all" },
});
expect(details.structuredContent.data).toEqual(
expect.objectContaining({
found: true,
component: "VimeoPreviewImage",
standaloneInsertable: false,
contentModel: expect.objectContaining({ category: "none" }),
})
);
expect(JSON.stringify(listing.structuredContent.data)).not.toContain(
"VimeoPreviewImage"
);
});
test("exposes structured component discovery without full resource parsing", async () => {
const session = createSession({
initialize: vi.fn(),
refresh: vi.fn(),
reset: vi.fn(),
});
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(session),
executeOperation: createExecuteOperation(),
});
const summary = await adapter.callTool({ name: "components.summary" });
const summaryDetails = await adapter.callTool({
name: "components.summary",
input: { detail: "components", limit: 100 },
});
const componentRegistry = await adapter.callTool({
name: "components.list",
input: { source: "all", limit: 200 },
});
const templateRegistry = await adapter.callTool({
name: "templates.list",
input: { limit: 200 },
});
const coveragePlan = await adapter.callTool({
name: "components.coverage-plan",
});
const checkpointedFind = await adapter.callTool({
name: "components.find",
input: { brief: "radix select" },
});
expect(checkpointedFind.structuredContent.data).toEqual(
expect.objectContaining({ components: expect.any(Array) })
);
await expect(
adapter.callTool({
name: "checkpoint.ack",
input: { reported: false },
})
).rejects.toThrow(
'checkpoint.ack requires {"reported":true,"continueAfterReport":true,"summary":"..."}'
);
await expect(
adapter.callTool({
name: "checkpoint.ack",
input: { reported: true },
})
).rejects.toThrow(
'checkpoint.ack requires {"reported":true,"continueAfterReport":true,"summary":"..."}'
);
await expect(
adapter.callTool({
name: "checkpoint.ack",
input: {
reported: true,
continueAfterReport: true,
summary: "reported checkpoint",
},
})
).resolves.toEqual(
expect.objectContaining({
structuredContent: expect.objectContaining({
data: expect.objectContaining({
acknowledged: true,
summary: "reported checkpoint",
}),
}),
})
);
const coveragePlanAlias = await adapter.callTool({
name: "get-component-coverage-plan",
});
await adapter.callTool({
name: "checkpoint.ack",
input: {
reported: true,
continueAfterReport: true,
summary: "reported checkpoint",
},
});
const fullCoveragePlan = await adapter.callTool({
name: "components.coverage-plan",
input: { detail: "full" },
});
await adapter.callTool({
name: "checkpoint.ack",
input: {
reported: true,
continueAfterReport: true,
summary: "reported checkpoint",
},
});
const rootCoveragePlan = await adapter.callTool({
name: "components.coverage-plan",
input: { detail: "roots", limit: 5 },
});
await adapter.callTool({
name: "checkpoint.ack",
input: {
reported: true,
continueAfterReport: true,
summary: "reported checkpoint",
},
});
const xmlCoveragePlan = await adapter.callTool({
name: "components.coverage-plan",
input: { documentType: "xml", detail: "roots", limit: 100 },
});
await adapter.callTool({
name: "checkpoint.ack",
input: {
reported: true,
continueAfterReport: true,
summary: "reported checkpoint",
},
});
const find = await adapter.callTool({
name: "components.find",
input: { brief: "radix select indicator" },
});
const search = await adapter.callTool({
name: "components.search",
input: { brief: "radix select indicator" },
});
const bodyFind = await adapter.callTool({
name: "components.find",
input: { brief: "body" },
});
const bodyDetails = await adapter.callTool({
name: "components.get",
input: { component: "Body" },
});
const broadFind = await adapter.callTool({
name: "components.find",
input: { brief: "radix tabs dialog select" },
});
const broadFindNextPage = await adapter.callTool({
name: "components.find",
input: { brief: "radix tabs dialog select", offset: 12, limit: 3 },
});
const details = await adapter.callTool({
name: "components.get",
input: {
component:
"@webstudio-is/sdk-components-react-radix:SelectItemIndicator",
},
});
const selectDetails = await adapter.callTool({
name: "components.get",
input: { component: "@webstudio-is/sdk-components-react-radix:Select" },
});
const selectTemplateDetails = await adapter.callTool({
name: "templates.get",
input: { component: "@webstudio-is/sdk-components-react-radix:Select" },
});
const buttonDetails = await adapter.callTool({
name: "components.get",
input: { component: "Button" },
});
const jsonLdDetails = await adapter.callTool({
name: "components.get",
input: { component: "JsonLd" },
});
const collectionDetails = await adapter.callTool({
name: "components.get",
input: { component: "ws:collection" },
});
const blockTemplateDetails = await adapter.callTool({
name: "components.get",
input: { component: "ws:block-template" },
});
const italicDetails = await adapter.callTool({
name: "components.get",
input: { component: "Italic" },
});
const animationGroupDetails = await adapter.callTool({
name: "components.get",
input: {
component: "@webstudio-is/sdk-components-animation:AnimateChildren",
},
});
const textAnimationDetails = await adapter.callTool({
name: "components.get",
input: {
component: "@webstudio-is/sdk-components-animation:AnimateText",
},
});
const staggerAnimationDetails = await adapter.callTool({
name: "components.get",
input: {
component: "@webstudio-is/sdk-components-animation:StaggerAnimation",
},
});
const videoAnimationDetails = await adapter.callTool({
name: "components.get",
input: {
component: "@webstudio-is/sdk-components-animation:VideoAnimation",
},
});
const coveragePlanData = coveragePlan.structuredContent.data as {
total: number;
rootCount: number;
partCount: number;
};
expect(session.initialize).not.toHaveBeenCalled();
expect(summary.structuredContent.data).toEqual(
expect.objectContaining({
total: expect.any(Number),
templateCount: expect.any(Number),
standaloneInsertableCount: expect.any(Number),
nonStandaloneCount: expect.any(Number),
})
);
expect(summary.structuredContent.data).not.toHaveProperty("components");
expect(JSON.stringify(summary.structuredContent.data).length).toBeLessThan(
1_000
);
expect(summaryDetails.structuredContent.data).toEqual(
expect.objectContaining({
detail: "components",
count: expect.any(Number),
pagination: { offset: 0, limit: 100, nextOffset: undefined },
components: expect.arrayContaining([
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Select",
hasTemplate: true,
standaloneInsertable: true,
}),
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Checkbox",
jsxName: "RadixCheckbox",
jsxElement: "<RadixCheckbox />",
hasTemplate: true,
templateRootComponents: [
"@webstudio-is/sdk-components-react-radix:Label",
],
}),
expect.objectContaining({
component:
"@webstudio-is/sdk-components-react-radix:SelectItemIndicator",
jsxName: "SelectItemIndicator",
jsxElement: "<SelectItemIndicator />",
standaloneInsertable: false,
}),
]),
})
);
expect(componentRegistry.structuredContent.data).toEqual(
expect.objectContaining({
source: "all",
documentType: "html",
items: expect.arrayContaining([
expect.objectContaining({
name: "component:HtmlEmbed",
type: "registry:ui",
meta: expect.objectContaining({
source: "meta",
component: "HtmlEmbed",
insert: expect.objectContaining({
component: "HtmlEmbed",
template: false,
}),
}),
}),
expect.objectContaining({
name: "template:@webstudio-is/sdk-components-react-radix:Select",
type: "registry:ui",
meta: expect.objectContaining({
source: "template",
component: "@webstudio-is/sdk-components-react-radix:Select",
insert: expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Select",
template: true,
}),
}),
}),
]),
})
);
expect(
JSON.stringify(componentRegistry.structuredContent.data)
).not.toContain('"files"');
expect(templateRegistry.structuredContent.data).toEqual(
expect.objectContaining({
source: "template",
items: expect.arrayContaining([
expect.objectContaining({
name: "template:@webstudio-is/sdk-components-react-radix:Select",
}),
]),
})
);
expect(templateRegistry.structuredContent.data).not.toEqual(
expect.objectContaining({
items: expect.arrayContaining([
expect.objectContaining({ name: "component:HtmlEmbed" }),
]),
})
);
expect(
JSON.stringify(templateRegistry.structuredContent.data).length
).toBeLessThan(50_000);
expect(coveragePlan.structuredContent.data).toEqual(
expect.objectContaining({
checkpoint: expect.objectContaining({
required: true,
}),
total: expect.any(Number),
rootCount: expect.any(Number),
partCount: expect.any(Number),
uncoveredPartCount: 0,
roots: expect.arrayContaining([
expect.objectContaining({
component: expect.any(String),
jsxElement: expect.stringMatching(/^<.+ \/>$/),
coveredCount: expect.any(Number),
}),
]),
})
);
expect(coveragePlanAlias.structuredContent.data).toEqual(
expect.objectContaining({
total: coveragePlanData.total,
rootCount: coveragePlanData.rootCount,
partCount: coveragePlanData.partCount,
})
);
expect(coveragePlan.structuredContent.data).not.toEqual(
expect.objectContaining({
partComponents: expect.any(Array),
})
);
expect(coveragePlan.structuredContent.data).not.toEqual(
expect.objectContaining({
roots: expect.arrayContaining([
expect.objectContaining({ sampleCovers: expect.any(Array) }),
]),
})
);
expect(rootCoveragePlan.structuredContent.data).toEqual(
expect.objectContaining({
documentType: "html",
roots: expect.arrayContaining([
expect.objectContaining({
sampleCovers: expect.any(Array),
}),
]),
})
);
for (const component of ["Body", "XmlNode", "XmlTime"]) {
expect(rootCoveragePlan.structuredContent.data).not.toEqual(
expect.objectContaining({
roots: expect.arrayContaining([
expect.objectContaining({ component }),
]),
})
);
}
expect(xmlCoveragePlan.structuredContent.data).toEqual(
expect.objectContaining({
documentType: "xml",
roots: expect.arrayContaining([
expect.objectContaining({ component: "XmlNode" }),
expect.objectContaining({ component: "XmlTime" }),
]),
})
);
expect(fullCoveragePlan.structuredContent.data).toEqual(
expect.objectContaining({
documentType: "html",
total: expect.any(Number),
rootCount: expect.any(Number),
partCount: expect.any(Number),
roots: expect.arrayContaining([
expect.objectContaining({
component: "@webstudio-is/sdk-components-animation:AnimateChildren",
covers: expect.arrayContaining([
// contentModel.children: direct child components count toward coverage.
"@webstudio-is/sdk-components-animation:AnimateText",
"@webstudio-is/sdk-components-animation:StaggerAnimation",
]),
}),
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Select",
hasTemplate: true,
insertWith: "@webstudio-is/sdk-components-react-radix:Select",
templateRootComponents: [
"@webstudio-is/sdk-components-react-radix:Select",
],
templateRequiredParts: expect.arrayContaining([
"@webstudio-is/sdk-components-react-radix:SelectItemIndicator",
]),
covers: expect.arrayContaining([
// contentModel.descendants: nested component parts count too.
"@webstudio-is/sdk-components-react-radix:SelectTrigger",
"@webstudio-is/sdk-components-react-radix:SelectContent",
]),
}),
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Checkbox",
hasTemplate: true,
insertWith: "@webstudio-is/sdk-components-react-radix:Checkbox",
templateRootComponents: [
"@webstudio-is/sdk-components-react-radix:Label",
],
}),
expect.objectContaining({
component: "HeadSlot",
covers: expect.arrayContaining([
"HeadLink",
"HeadMeta",
"HeadTitle",
]),
}),
expect.objectContaining({
component: "ws:block",
covers: expect.arrayContaining(["ws:block-template"]),
}),
]),
partComponents: expect.arrayContaining([
expect.objectContaining({
component: "@webstudio-is/sdk-components-animation:AnimateText",
coveredBy: expect.arrayContaining([
"@webstudio-is/sdk-components-animation:AnimateChildren",
]),
}),
expect.objectContaining({
component:
"@webstudio-is/sdk-components-react-radix:SelectItemIndicator",
coveredBy: expect.arrayContaining([
"@webstudio-is/sdk-components-react-radix:Select",
]),
}),
]),
uncoveredPartComponents: [],
})
);
expect(find.structuredContent.data).toEqual(
expect.objectContaining({
count: expect.any(Number),
totalCount: expect.any(Number),
pagination: expect.objectContaining({
offset: 0,
limit: 12,
}),
components: expect.arrayContaining([
expect.objectContaining({
component:
"@webstudio-is/sdk-components-react-radix:SelectItemIndicator",
}),
]),
})
);
expect(search.structuredContent.data).toEqual(
expect.objectContaining({
query: "radix select indicator",
components: expect.arrayContaining([
expect.objectContaining({
component:
"@webstudio-is/sdk-components-react-radix:SelectItemIndicator",
}),
]),
})
);
expect(bodyFind.structuredContent.data).toEqual(
expect.objectContaining({
count: 0,
components: [],
})
);
expect(bodyDetails.structuredContent.data).toEqual(
expect.objectContaining({
found: false,
component: "Body",
})
);
expect(broadFind.structuredContent.data).toEqual(
expect.objectContaining({
count: 12,
totalCount: expect.any(Number),
omittedCount: expect.any(Number),
pagination: expect.objectContaining({
offset: 0,
limit: 12,
nextOffset: 12,
}),
components: expect.arrayContaining([
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Tabs",
matchedTokens: expect.arrayContaining(["radix", "tabs"]),
}),
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Dialog",
matchedTokens: expect.arrayContaining(["radix", "dialog"]),
}),
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Select",
matchedTokens: expect.arrayContaining(["radix", "select"]),
}),
]),
})
);
const broadFindData = broadFind.structuredContent.data as {
components: Record<string, unknown>[];
count: number;
totalCount: number;
};
expect(broadFindData.totalCount).toBeGreaterThan(broadFindData.count);
for (const component of broadFindData.components) {
expect(Object.values(component)).not.toContain(undefined);
expect(component).not.toHaveProperty("templateRequiredParts");
expect(component).not.toHaveProperty("templateRequiredEdges");
expect(component).not.toHaveProperty("templateTextContent");
}
expect(broadFindNextPage.structuredContent.data).toEqual(
expect.objectContaining({
count: 3,
pagination: expect.objectContaining({
offset: 12,
limit: 3,
}),
})
);
expect(details.structuredContent.data).toEqual(
expect.objectContaining({
found: true,
component:
"@webstudio-is/sdk-components-react-radix:SelectItemIndicator",
standaloneInsertable: false,
contentModel: expect.any(Object),
props: expect.any(Object),
})
);
expect(buttonDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "Button",
found: false,
})
);
expect(italicDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "Italic",
found: false,
})
);
expect(
(
await adapter.callTool({
name: "components.get",
input: {
component: "@webstudio-is/sdk-components-react-radix:Checkbox",
},
})
).structuredContent.data
).toEqual(
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Checkbox",
hasTemplate: true,
templateRootComponents: [
"@webstudio-is/sdk-components-react-radix:Label",
],
})
);
expect(animationGroupDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "@webstudio-is/sdk-components-animation:AnimateChildren",
props: expect.objectContaining({
action: expect.objectContaining({ type: "animationAction" }),
}),
})
);
expect(textAnimationDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "@webstudio-is/sdk-components-animation:AnimateText",
props: expect.objectContaining({
slidingWindow: expect.objectContaining({ defaultValue: 5 }),
splitBy: expect.objectContaining({
options: expect.arrayContaining(["char", "space"]),
}),
}),
})
);
expect(staggerAnimationDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "@webstudio-is/sdk-components-animation:StaggerAnimation",
props: expect.objectContaining({
slidingWindow: expect.objectContaining({ defaultValue: 1 }),
}),
})
);
expect(videoAnimationDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "@webstudio-is/sdk-components-animation:VideoAnimation",
hasTemplate: true,
props: expect.objectContaining({
timeline: expect.objectContaining({ type: "boolean" }),
}),
})
);
expect(selectDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Select",
hasTemplate: true,
templateRequiredParts: expect.arrayContaining([
"@webstudio-is/sdk-components-react-radix:SelectItemIndicator",
]),
templateRequiredEdges: expect.arrayContaining([
{
parentComponent:
"@webstudio-is/sdk-components-react-radix:SelectItem",
childComponent:
"@webstudio-is/sdk-components-react-radix:SelectItemIndicator",
},
]),
})
);
expect(jsonLdDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "JsonLd",
props: expect.objectContaining({
code: expect.objectContaining({
control: "json-code",
type: "string",
}),
}),
})
);
expect(collectionDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "ws:collection",
props: expect.objectContaining({
data: expect.objectContaining({ type: "json", required: true }),
item: expect.objectContaining({ type: "string" }),
itemKey: expect.objectContaining({ type: "string" }),
}),
})
);
expect(collectionDetails.structuredContent.data).not.toHaveProperty(
"jsxElement"
);
expect(blockTemplateDetails.structuredContent.data).toEqual(
expect.objectContaining({
component: "ws:block-template",
standaloneInsertable: false,
})
);
expect(blockTemplateDetails.structuredContent.data).not.toHaveProperty(
"jsxElement"
);
expect(selectTemplateDetails.structuredContent.data).toEqual(
expect.objectContaining({
found: true,
name: "template:@webstudio-is/sdk-components-react-radix:Select",
type: "registry:ui",
template: expect.objectContaining({
instances: expect.any(Array),
}),
meta: expect.objectContaining({
insert: expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Select",
template: true,
}),
}),
})
);
});
test("searches registry-only templates without duplicating component templates", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
const formSearch = await adapter.callTool({
name: "components.search",
input: { brief: "Form (Beta)" },
});
expect(formSearch.structuredContent.data).toEqual(
expect.objectContaining({
usage: expect.stringContaining("templates.get"),
components: expect.arrayContaining([
expect.objectContaining({
component: "form",
label: "Form (Beta)",
template: "template:form",
hasTemplate: true,
standaloneInsertable: true,
insertWith: "form",
}),
]),
})
);
const formResults = (
formSearch.structuredContent.data as {
components: { component: string; template?: string }[];
}
).components;
expect(formResults[0]?.component).toBe("form");
const formResult = formResults.find(
({ template }) => template === "template:form"
);
expect(formResult).toBeDefined();
const formDetails = await adapter.callTool({
name: "templates.get",
input: { template: formResult?.template },
});
expect(formDetails.structuredContent.data).toEqual(
expect.objectContaining({
found: true,
name: "template:form",
meta: expect.objectContaining({
source: "template",
component: "form",
}),
})
);
const formIdSearch = await adapter.callTool({
name: "components.search",
input: { brief: "template:form" },
});
expect(formIdSearch.structuredContent.data).toEqual(
expect.objectContaining({
components: expect.arrayContaining([
expect.objectContaining({ template: "template:form" }),
]),
})
);
const broadFormSearch = await adapter.callTool({
name: "components.search",
input: { brief: "form", limit: 25 },
});
expect(broadFormSearch.structuredContent.data).toEqual(
expect.objectContaining({
components: expect.arrayContaining([
expect.objectContaining({ template: "template:form" }),
]),
})
);
const selectSearch = await adapter.callTool({
name: "components.search",
input: { brief: "radix select", limit: 25 },
});
const selectComponents = (
selectSearch.structuredContent.data as {
components: { component: string }[];
}
).components;
expect(
selectComponents.filter(
({ component }) =>
component === "@webstudio-is/sdk-components-react-radix:Select"
)
).toHaveLength(1);
});
test("omits the deprecated Webhook Form from MCP discovery", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
const search = await adapter.callTool({
name: "components.search",
input: { brief: "form", limit: 25 },
});
const matches = (
search.structuredContent.data as {
components: { component: string; template?: string }[];
}
).components;
expect(matches).toContainEqual(
expect.objectContaining({ template: "template:form" })
);
expect(matches.some(({ component }) => component === "WebhookForm")).toBe(
false
);
const formResult = matches.find(
({ template }) => template === "template:form"
);
expect(formResult?.component).toBe("form");
for (const component of [formResult!.component, "ResourceForm"]) {
const formDetails = await adapter.callTool({
name: "components.get",
input: { component },
});
expect(formDetails.structuredContent.data).toEqual(
expect.objectContaining({
found: true,
component: "ResourceForm",
props: expect.objectContaining({ action: expect.any(Object) }),
})
);
}
const formTemplate = await adapter.callTool({
name: "templates.get",
input: { template: formResult!.template },
});
expect(formTemplate.structuredContent.data).toEqual(
expect.objectContaining({ found: true })
);
const formTemplateByRoot = await adapter.callTool({
name: "templates.get",
input: { component: "ResourceForm" },
});
expect(formTemplateByRoot.structuredContent.data).toEqual(
expect.objectContaining({
found: true,
name: "template:form",
meta: expect.objectContaining({ component: "form" }),
})
);
const details = await adapter.callTool({
name: "components.get",
input: { component: "WebhookForm" },
});
const template = await adapter.callTool({
name: "templates.get",
input: { component: "WebhookForm" },
});
expect(details.structuredContent.data).toEqual(
expect.objectContaining({ found: false })
);
expect(template.structuredContent.data).toEqual(
expect.objectContaining({ found: false })
);
for (const name of ["components.list", "templates.list"] as const) {
let offset = 0;
do {
const result = await adapter.callTool({
name,
input: { offset, limit: 100 },
});
const data = result.structuredContent.data as {
items: { meta: { component: string } }[];
pagination: { nextOffset?: number };
};
expect(
data.items.every(({ meta }) => meta.component !== "WebhookForm")
).toBe(true);
offset = data.pagination.nextOffset ?? 0;
} while (offset !== 0);
}
let cursor: string | undefined;
do {
const query = new URLSearchParams({ limit: "100", verbose: "true" });
if (cursor !== undefined) {
query.set("cursor", cursor);
}
const resource = await adapter.readResource({
uri: `webstudio://project/components?${query}`,
});
const data = JSON.parse(resource.contents[0]?.text ?? "{}") as {
components: { component: string }[];
nextCursor?: string;
};
expect(
data.components.some(({ component }) => component === "WebhookForm")
).toBe(false);
cursor = data.nextCursor;
} while (cursor !== undefined);
});
test("rejects new deprecated Webhook Forms through MCP insertion paths", async () => {
const executeOperation = createExecuteOperation();
const operations = [
...publicMcpOperations,
...(["wrap-instance", "convert-instance"] as const).map((command) =>
publicOperation({
command,
id: `instances.${command}`,
description: command,
method: "mutation",
permit: "edit",
inputSchema: getTestInputSchema(
z.object({
instanceSelector: z.array(z.string()),
component: z.string(),
})
),
writeNamespaces: ["instances"],
})
),
publicOperation({
command: "update-text-tree",
id: "instances.updateTextTree",
description: "Update text tree",
method: "mutation",
permit: "edit",
inputSchema: getTestInputSchema(
z.object({ rootInstanceId: z.string(), instances: z.array(z.any()) })
),
writeNamespaces: ["instances"],
}),
publicOperation({
command: "integrate-runtime-ui",
id: "runtimeUi.integrate",
description: "Integrate runtime UI",
method: "mutation",
permit: "edit",
inputSchema: getTestInputSchema(
z.object({ parentInstanceId: z.string(), structure: z.any() })
),
writeNamespaces: ["instances"],
}),
...(
["insert-component", "insert-fragment", "insert-collection"] as const
).map((command) =>
publicOperation({
command,
id: `instances.${command}`,
description: command,
method: "mutation",
permit: "edit",
inputSchema: getTestInputSchema(
z.object({
parentInstanceId: z.string(),
component: z.string().optional(),
fragment: z.any().optional(),
itemFragment: z.any().optional(),
data: z.any().optional(),
})
),
writeNamespaces: ["instances"],
})
),
publicOperation({
command: "verify-bindings",
id: "project.verifyBindings",
description: "verify-bindings",
}),
];
const adapter = createProjectSessionMcpCore({
operations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await expect(
adapter.callTool({
name: "insert-component",
input: { parentInstanceId: "body", component: "WebhookForm" },
})
).rejects.toThrow("Webhook Form is deprecated");
for (const name of ["wrap-instance", "convert-instance"] as const) {
await expect(
adapter.callTool({
name,
input: {
instanceSelector: ["instance", "body"],
component: "WebhookForm",
},
})
).rejects.toThrow("Webhook Form is deprecated");
}
for (const id of ["new-form", "existing-rich-text-child"]) {
await expect(
adapter.callTool({
name: "update-text-tree",
input: {
rootInstanceId: "rich-text-root",
instances: [
{
type: "instance",
id,
component: "WebhookForm",
children: [],
},
],
},
})
).rejects.toThrow("Webhook Form is deprecated");
}
const deprecatedFormFragment =
await parseWebstudioJsxFragment("<WebhookForm />");
for (const structure of [
{ type: "fragment", fragment: deprecatedFormFragment },
{
type: "collection",
data: { type: "json", value: [{ name: "example" }] },
itemFragment: deprecatedFormFragment,
},
]) {
await expect(
adapter.callTool({
name: "integrate-runtime-ui",
input: { parentInstanceId: "body", structure },
})
).rejects.toThrow("Webhook Form is deprecated");
}
for (const name of [
"insert-fragment",
"insert-fragment-verified",
] as const) {
await expect(
adapter.callTool({
name,
input: {
parentInstanceId: "body",
...(name === "insert-fragment-verified"
? { pagePath: "/contact" }
: {}),
fragment: "<WebhookForm />",
},
})
).rejects.toThrow("Webhook Form is deprecated");
}
await expect(
adapter.callTool({
name: "insert-collection",
input: {
parentInstanceId: "body",
data: { type: "json", value: [{ name: "example" }] },
itemFragment: "<WebhookForm />",
},
})
).rejects.toThrow("Webhook Form is deprecated");
expect(executeOperation).not.toHaveBeenCalled();
});
test("rejects cloning a saved deprecated Webhook Form subtree through MCP", async () => {
const executeOperation = createExecuteOperation(async ({ command }) => {
if (command === "list-instances") {
return createEnvelope({
operationId: "instances.list",
result: { instances: [{ id: "legacy", component: "WebhookForm" }] },
});
}
throw new Error(`Unexpected mutation: ${command}`);
});
const adapter = createProjectSessionMcpCore({
operations: [
...publicMcpOperations,
publicOperation({
command: "duplicate-instance",
id: "instances.duplicateAfterItself",
description: "Duplicate instance",
method: "mutation",
permit: "edit",
inputSchema: getTestInputSchema(
z.object({
sourceInstanceId: z.string(),
parentInstanceId: z.string(),
})
),
writeNamespaces: ["instances"],
}),
],
createProjectSession: createSessionFactory(),
executeOperation,
});
for (const name of ["clone-instance", "duplicate-instance"] as const) {
await expect(
adapter.callTool({
name,
input: {
sourceInstanceId: "saved-form",
...(name === "clone-instance"
? { targetParentInstanceId: "body" }
: { parentInstanceId: "body" }),
},
})
).rejects.toThrow("Webhook Form is deprecated");
}
expect(executeOperation).toHaveBeenNthCalledWith(1, {
command: "list-instances",
input: {
rootInstanceId: "saved-form",
component: "WebhookForm",
limit: 1,
},
dryRun: false,
});
expect(executeOperation).toHaveBeenNthCalledWith(2, {
command: "list-instances",
input: {
rootInstanceId: "saved-form",
component: "WebhookForm",
limit: 1,
},
dryRun: false,
});
expect(executeOperation).toHaveBeenCalledTimes(2);
});
test("keeps Editor page-template copying available while guarding other deprecated-form copies", async () => {
const inputs = [
["insert-mdx-text", { parentInstanceId: "body", source: "<Contact />" }],
["duplicate-page", { projectId: "project", pageId: "page" }],
[
"duplicate-page-template",
{ projectId: "project", templateId: "template" },
],
[
"create-page-from-template",
{
projectId: "project",
templateId: "template",
name: "Contact copy",
path: "/contact-copy",
},
],
["duplicate-folder", { projectId: "project", folderId: "folder" }],
["insert-page-transfer-item", { projectId: "project" }],
] as const;
const operations = [
...publicMcpOperations,
...inputs.map(([command]) =>
publicOperation({
command,
id: `test.${command}`,
description: command,
method: "mutation",
permit: "edit",
inputSchema: getTestInputSchema(
z.object({
projectId: z.string().optional(),
parentInstanceId: z.string().optional(),
source: z.string().optional(),
pageId: z.string().optional(),
templateId: z.string().optional(),
folderId: z.string().optional(),
name: z.string().optional(),
path: z.string().optional(),
})
),
writeNamespaces: ["pages", "instances"],
})
),
];
const executeOperation = createExecuteOperation(
async ({ command, dryRun }) => {
if (command === "create-page-from-template" && dryRun === false) {
return createEnvelope({
operationId: command,
result: { pageId: "copied-page" },
});
}
if (dryRun === false) {
throw new Error(`Unexpected committed copy: ${command}`);
}
return createEnvelope({
operationId: command,
source: "dry-run",
result: {},
transaction: {
id: `planned-${command}`,
payload: [
{
namespace: "instances",
patches: [
{
op: "add",
path: ["copied-form"],
value: { id: "copied-form", component: "WebhookForm" },
},
],
},
],
},
});
}
);
const adapter = createProjectSessionMcpCore({
operations,
createProjectSession: createSessionFactory(),
executeOperation,
});
for (const [name, input] of inputs) {
if (name === "create-page-from-template") {
const result = await adapter.callTool({ name, input });
expect(result.structuredContent.data).toEqual({
pageId: "copied-page",
});
continue;
}
await expect(adapter.callTool({ name, input })).rejects.toThrow(
"Webhook Form is deprecated"
);
}
expect(executeOperation).toHaveBeenCalledTimes(inputs.length);
expect(
vi
.mocked(executeOperation)
.mock.calls.every(
([call]) =>
call.dryRun === (call.command !== "create-page-from-template")
)
).toBe(true);
});
test("rejects a copied deprecated Webhook Form in a root Map replacement", async () => {
const executeOperation = createExecuteOperation(async ({ dryRun }) => {
if (dryRun === false) {
throw new Error("Unexpected committed copy");
}
return createEnvelope({
operationId: "pages.duplicate",
source: "dry-run",
result: {},
transaction: {
id: "planned-page-copy",
payload: [
{
namespace: "instances",
patches: [
{
op: "replace",
path: [],
value: new Map([
[
"copied-form",
{ id: "copied-form", component: "WebhookForm" },
],
]),
},
],
},
],
},
});
});
const adapter = createProjectSessionMcpCore({
operations: [
...publicMcpOperations,
publicOperation({
command: "duplicate-page",
id: "pages.duplicate",
description: "Duplicate page",
method: "mutation",
permit: "edit",
inputSchema: getTestInputSchema(
z.object({ projectId: z.string(), pageId: z.string() })
),
writeNamespaces: ["pages", "instances"],
}),
],
createProjectSession: createSessionFactory(),
executeOperation,
});
await expect(
adapter.callTool({
name: "duplicate-page",
input: { projectId: "project", pageId: "source-page" },
})
).rejects.toThrow("Webhook Form is deprecated");
expect(executeOperation).toHaveBeenCalledTimes(1);
});
test("keeps copying pages without deprecated Webhook Forms available through MCP", async () => {
const executeOperation = createExecuteOperation(async ({ dryRun }) =>
createEnvelope({
operationId: "pages.duplicate",
source: dryRun ? "dry-run" : "remote",
result: { pageId: "copied-page" },
...(dryRun
? {
transaction: {
id: "planned-page-copy",
payload: [
{
namespace: "instances" as const,
patches: [
{
op: "add" as const,
path: ["copied-box"],
value: { id: "copied-box", component: "Box" },
},
],
},
],
},
}
: {}),
})
);
const adapter = createProjectSessionMcpCore({
operations: [
...publicMcpOperations,
publicOperation({
command: "duplicate-page",
id: "pages.duplicate",
description: "Duplicate page",
method: "mutation",
permit: "edit",
inputSchema: getTestInputSchema(
z.object({ projectId: z.string(), pageId: z.string() })
),
writeNamespaces: ["pages", "instances"],
}),
],
createProjectSession: createSessionFactory(),
executeOperation,
});
const result = await adapter.callTool({
name: "duplicate-page",
input: { projectId: "project", pageId: "source-page" },
});
expect(result.structuredContent.data).toEqual({ pageId: "copied-page" });
expect(
vi.mocked(executeOperation).mock.calls.map(([call]) => call.dryRun)
).toEqual([true, false]);
});
test("rejects raw MCP patches that create a deprecated Webhook Form", async () => {
const executeOperation = createExecuteOperation();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
for (const patch of [
{
op: "add",
path: ["legacy-form"],
value: { id: "legacy-form", component: "WebhookForm" },
},
{
op: "replace",
path: ["existing", "component"],
value: "WebhookForm",
},
{
op: "replace",
path: [],
value: {
"legacy-form": { id: "legacy-form", component: "WebhookForm" },
},
},
]) {
await expect(
adapter.callTool({
name: "apply-patch",
input: {
transactions: [
{
id: "legacy-form-insert",
payload: [{ namespace: "instances", patches: [patch] }],
},
],
},
})
).rejects.toThrow("Webhook Form is deprecated");
}
expect(executeOperation).not.toHaveBeenCalled();
});
test("hides explicit hidden component metas even when templates are visible", async () => {
const component = "test:ConcealedWidget";
const previousMeta = componentMetas.get(component);
const templates = getComponentTemplates();
const previousTemplate = templates.get(component);
componentMetas.set(component, {
category: "hidden",
label: "Concealed Widget",
contentModel: {
category: "instance",
children: ["instance"],
},
props: {},
} satisfies WsComponentMeta);
templates.set(component, {
category: "general",
template: {
...createEmptyWebstudioFragment(),
children: [{ type: "id", value: "template-root" }],
instances: [
{
type: "instance",
id: "template-root",
component,
children: [],
},
],
},
});
try {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
const summary = await adapter.callTool({
name: "components.summary",
input: { detail: "components", limit: 100 },
});
const find = await adapter.callTool({
name: "components.find",
input: { brief: "ConcealedWidget" },
});
const search = await adapter.callTool({
name: "components.search",
input: { brief: "ConcealedWidget" },
});
const details = await adapter.callTool({
name: "components.get",
input: { component },
});
expect(summary.structuredContent.data).toEqual(
expect.objectContaining({
components: expect.not.arrayContaining([
expect.objectContaining({ component }),
]),
})
);
expect(find.structuredContent.data).toEqual(
expect.objectContaining({
components: [],
count: 0,
})
);
expect(search.structuredContent.data).toEqual(
expect.objectContaining({
components: [],
count: 0,
})
);
expect(details.structuredContent.data).toEqual(
expect.objectContaining({
component,
found: false,
})
);
} finally {
if (previousMeta === undefined) {
componentMetas.delete(component);
} else {
componentMetas.set(component, previousMeta);
}
if (previousTemplate === undefined) {
templates.delete(component);
} else {
templates.set(component, previousTemplate);
}
}
});
test("reports page component coverage status from list-instances", async () => {
const executeOperation = createExecuteOperation(async () =>
createEnvelope({
operationId: "instances.list",
result: {
instances: [
{ id: "body", component: "ws:element", depth: 0 },
{
id: "switch",
component: "@webstudio-is/sdk-components-react-radix:Switch",
depth: 1,
},
],
},
namespaces: {
read: ["pages", "instances"],
write: [],
invalidated: [],
missing: [],
},
})
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
const status = await adapter.callTool({
name: "components.coverage-status",
input: { pagePath: "/design-system" },
});
expect(executeOperation).toHaveBeenCalledWith({
command: "list-instances",
input: {
pageId: undefined,
pagePath: "/design-system",
},
dryRun: false,
});
expect(status.structuredContent.data).toEqual(
expect.objectContaining({
pagePath: "/design-system",
documentType: "html",
coveredCount: expect.any(Number),
missingCount: expect.any(Number),
covered: expect.arrayContaining([
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Switch",
jsxElement: "<Switch />",
}),
]),
missing: expect.arrayContaining([
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Select",
jsxElement: "<RadixSelect />",
}),
]),
missingRoots: expect.arrayContaining([
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Select",
jsxElement: "<RadixSelect />",
}),
]),
missingParts: expect.arrayContaining([
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:AccordionItem",
jsxElement: "<AccordionItem />",
}),
]),
})
);
});
test("inserts one missing coverage component and returns before and after coverage", async () => {
const isTestRecord = (value: unknown): value is Record<string, unknown> =>
typeof value === "object" &&
value !== null &&
Array.isArray(value) === false;
const instances = [
{ id: "body", component: "ws:element", depth: 0 },
{
id: "switch",
component: "@webstudio-is/sdk-components-react-radix:Switch",
depth: 1,
},
];
const executeOperation = createExecuteOperation(
async ({ command, input }) => {
if (command === "list-instances") {
return createEnvelope({
operationId: "instances.list",
result: { instances },
namespaces: {
read: ["pages", "instances"],
write: [],
invalidated: [],
missing: [],
},
});
}
if (command === "insert-component") {
const component =
isTestRecord(input) && typeof input.component === "string"
? input.component
: "";
instances.push({
id: "inserted",
component,
depth: 1,
});
return createEnvelope({
operationId: "components.insert",
result: {
rootInstanceIds: ["inserted"],
instanceIds: ["inserted"],
parentInstanceId:
isTestRecord(input) &&
typeof input.parentInstanceId === "string"
? input.parentInstanceId
: undefined,
},
state: { committed: true, freshness: {} },
version: 2,
});
}
throw new Error(`Unexpected command ${command}`);
}
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
const result = await adapter.callTool({
name: "components.coverage-insert-next",
input: {
pagePath: "/design-system",
parentInstanceId: "root",
component: "@webstudio-is/sdk-components-react-radix:Select",
},
});
expect(executeOperation).toHaveBeenNthCalledWith(1, {
command: "list-instances",
input: {
pageId: undefined,
pagePath: "/design-system",
},
dryRun: false,
});
expect(executeOperation).toHaveBeenNthCalledWith(2, {
command: "insert-component",
input: {
parentInstanceId: "root",
component: "@webstudio-is/sdk-components-react-radix:Select",
},
dryRun: false,
});
expect(executeOperation).toHaveBeenNthCalledWith(3, {
command: "list-instances",
input: {
pageId: undefined,
pagePath: "/design-system",
},
dryRun: false,
});
expect(result.structuredContent.data).toEqual(
expect.objectContaining({
inserted: expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Select",
}),
before: expect.objectContaining({
coveredCount: expect.any(Number),
missingCount: expect.any(Number),
}),
after: expect.objectContaining({
coveredCount: expect.any(Number),
missingCount: expect.any(Number),
}),
})
);
const find = await adapter.callTool({
name: "components.find",
input: { brief: "button" },
});
expect(find.structuredContent.data).toEqual(
expect.objectContaining({ components: expect.any(Array) })
);
await expect(
adapter.callTool({
name: "components.coverage-insert-next",
input: { pagePath: "/design-system", parentInstanceId: "root" },
})
).rejects.toThrow("CHECKPOINT_REQUIRED");
});
test("keeps coverage reads active during a dry-run insertion", async () => {
const instances = [
{ id: "body", component: "ws:element", depth: 0 },
{
id: "switch",
component: "@webstudio-is/sdk-components-react-radix:Switch",
depth: 1,
},
];
const executeOperation = createExecuteOperation(
async ({ command, dryRun }) => {
if (command === "list-instances") {
if (dryRun) {
throw new Error("read operations do not accept dryRun");
}
return createEnvelope({
operationId: "instances.list",
result: { instances },
});
}
if (command === "insert-component") {
expect(dryRun).toBe(true);
return createEnvelope({
operationId: "components.insert",
result: {
rootInstanceIds: ["inserted"],
instanceIds: ["inserted"],
parentInstanceId: "root",
},
state: { committed: false, freshness: {} },
version: 1,
});
}
throw new Error(`Unexpected command ${command}`);
}
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await expect(
adapter.callTool({
name: "components.coverage-insert-next",
input: {
pagePath: "/design-system",
parentInstanceId: "root",
component: "@webstudio-is/sdk-components-react-radix:Select",
},
dryRun: true,
})
).resolves.toEqual(
expect.objectContaining({
structuredContent: expect.objectContaining({
data: expect.objectContaining({ committed: false }),
}),
})
);
expect(executeOperation).toHaveBeenNthCalledWith(1, {
command: "list-instances",
input: {
pageId: undefined,
pagePath: "/design-system",
},
dryRun: false,
});
expect(executeOperation).toHaveBeenNthCalledWith(
2,
expect.objectContaining({
command: "insert-component",
dryRun: true,
})
);
expect(executeOperation).toHaveBeenNthCalledWith(3, {
command: "list-instances",
input: {
pageId: undefined,
pagePath: "/design-system",
},
dryRun: false,
});
});
test("inserts uncovered non-standalone coverage parts under compatible parents", async () => {
const isTestRecord = (value: unknown): value is Record<string, unknown> =>
typeof value === "object" &&
value !== null &&
Array.isArray(value) === false;
const instances = [
{ id: "body", component: "ws:element", depth: 0 },
{
id: "animation-group",
component: "@webstudio-is/sdk-components-animation:AnimateChildren",
depth: 1,
},
];
const executeOperation = createExecuteOperation(
async ({ command, input }) => {
if (command === "list-instances") {
return createEnvelope({
operationId: "instances.list",
result: { instances },
});
}
if (command === "insert-component") {
expect(input).toEqual(
expect.objectContaining({
parentInstanceId: "animation-group",
component: "@webstudio-is/sdk-components-animation:AnimateText",
})
);
instances.push({
id: "animate-text",
component: "@webstudio-is/sdk-components-animation:AnimateText",
depth: 2,
});
return createEnvelope({
operationId: "instances.insertComponent",
result: {
instanceIds: ["animate-text"],
parentInstanceId:
isTestRecord(input) &&
typeof input.parentInstanceId === "string"
? input.parentInstanceId
: undefined,
},
state: { committed: true, freshness: {} },
version: 2,
});
}
throw new Error(`Unexpected command ${command}`);
}
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
const result = await adapter.callTool({
name: "components.coverage-insert-next",
input: {
pagePath: "/design-system",
parentInstanceId: "body",
component: "@webstudio-is/sdk-components-animation:AnimateText",
},
});
expect(executeOperation).toHaveBeenNthCalledWith(2, {
command: "insert-component",
input: expect.objectContaining({
parentInstanceId: "animation-group",
component: "@webstudio-is/sdk-components-animation:AnimateText",
}),
dryRun: false,
});
expect(result.structuredContent.data).toEqual(
expect.objectContaining({
inserted: expect.objectContaining({
component: "@webstudio-is/sdk-components-animation:AnimateText",
mode: "component",
}),
parentInstanceId: "animation-group",
})
);
});
test("exposes screenshot tools only when screenshot runners are injected", async () => {
const session = createSession({
initialize: vi.fn(),
refresh: vi.fn(),
reset: vi.fn(),
});
const captureScreenshot = vi.fn(async () => ({
output: "/tmp/current.png",
browserPath: "/usr/bin/chromium",
browser: "chromium" as const,
viewport: { width: 1440, height: 900 },
fullPage: true,
elapsedMs: 12,
warnings: [],
}));
const capturePageScreenshots = vi.fn(
async (inputs: readonly ProjectSessionScreenshotInput[]) =>
inputs.map((input) => ({
output: `/tmp/${input.viewport.width}.png`,
browserPath: "/usr/bin/chromium",
browser: "chromium" as const,
viewport: input.viewport,
fullPage: input.fullPage ?? false,
elapsedMs: 12,
warnings: [],
}))
);
const adapterWithoutScreenshot = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(session),
executeOperation: createExecuteOperation(),
});
const adapterWithScreenshot = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(session),
executeOperation: createExecuteOperation(),
captureScreenshot,
});
const adapterWithResponsiveScreenshot = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(session),
executeOperation: createExecuteOperation(),
capturePageScreenshots,
});
const adapterWithScreenshotDiff = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(session),
executeOperation: createExecuteOperation(),
diffScreenshots: diffPngFiles,
});
expect(
adapterWithoutScreenshot.listTools().map((tool) => tool.name)
).not.toContain("screenshot");
expect(
adapterWithoutScreenshot.listTools().map((tool) => tool.name)
).not.toContain("screenshot.diff");
expect(
adapterWithoutScreenshot.listTools().map((tool) => tool.name)
).not.toContain("screenshot.responsive");
expect(
adapterWithScreenshot.listTools().map((tool) => tool.name)
).toContain("screenshot");
expect(
adapterWithScreenshot.listTools().map((tool) => tool.name)
).not.toContain("screenshot.diff");
expect(
adapterWithScreenshotDiff.listTools().map((tool) => tool.name)
).toContain("screenshot.diff");
expect(
adapterWithResponsiveScreenshot.listTools().map((tool) => tool.name)
).toContain("screenshot.responsive");
expect(
adapterWithResponsiveScreenshot.listTools().map((tool) => tool.name)
).toContain("verify-page-responsive");
const result = await adapterWithScreenshot.callTool({
name: "screenshot",
input: {
url: "https://example.com",
output: "current.png",
viewport: { width: 1440, height: 900 },
fullPage: true,
browser: "auto",
waitUntil: "networkidle",
waitForSelector: "#ready",
waitForFonts: false,
waitForTimeout: 500,
timeout: 10_000,
},
});
expect(session.initialize).not.toHaveBeenCalled();
expect(captureScreenshot).toHaveBeenCalledWith(
{
url: "https://example.com",
baseUrl: undefined,
path: undefined,
output: "current.png",
host: undefined,
port: undefined,
imageDomains: undefined,
source: undefined,
viewport: { width: 1440, height: 900 },
fullPage: true,
includeImageMetrics: false,
includeResourceMetrics: false,
includeContrastMetrics: false,
browser: "auto",
browserPath: undefined,
waitUntil: "networkidle",
waitForSelector: "#ready",
waitForFonts: false,
waitForTimeout: 500,
timeout: 10_000,
},
expect.objectContaining({ report: expect.any(Function) })
);
expect(result.structuredContent).toEqual({
ok: true,
data: {
output: "/tmp/current.png",
browserPath: "/usr/bin/chromium",
browser: "chromium",
viewport: { width: 1440, height: 900 },
fullPage: true,
elapsedMs: 12,
warnings: [],
},
meta: {},
});
const responsiveResult = await adapterWithResponsiveScreenshot.callTool({
name: "screenshot.responsive",
input: {
path: "/pricing",
viewports: [
{ width: 1440, height: 900 },
{ width: 390, height: 844 },
],
fullPage: true,
source: "session",
waitForFonts: false,
},
});
expect(capturePageScreenshots).toHaveBeenCalledWith(
[
expect.objectContaining({
path: "/pricing",
viewport: { width: 1440, height: 900 },
fullPage: true,
source: "session",
waitForFonts: false,
}),
expect.objectContaining({
path: "/pricing",
viewport: { width: 390, height: 844 },
fullPage: true,
source: "session",
}),
],
expect.objectContaining({ report: expect.any(Function) })
);
expect(responsiveResult.structuredContent.data).toEqual({
screenshots: [
expect.objectContaining({ viewport: { width: 1440, height: 900 } }),
expect.objectContaining({ viewport: { width: 390, height: 844 } }),
],
});
const verificationResult = await adapterWithResponsiveScreenshot.callTool({
name: "verify-page-responsive",
input: {
path: "/pricing",
viewports: [
{ width: 1440, height: 900 },
{ width: 390, height: 844 },
],
source: "session",
},
});
expect(verificationResult.structuredContent.data).toEqual({
screenshots: [
expect.objectContaining({ viewport: { width: 1440, height: 900 } }),
expect.objectContaining({ viewport: { width: 390, height: 844 } }),
],
audit: undefined,
});
});
test("omits screenshot diff guidance when diff runner is not injected", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
captureScreenshot: vi.fn(async () => ({
output: "/tmp/current.png",
browserPath: "/usr/bin/chromium",
browser: "chromium" as const,
viewport: { width: 1440, height: 900 },
fullPage: false,
elapsedMs: 12,
warnings: [],
})),
startPreview: vi.fn(async () => ({
url: "http://127.0.0.1:5173/",
running: true,
mode: "iterative" as const,
})),
getPreviewStatus: vi.fn(async () => ({
url: "http://127.0.0.1:5173/",
running: true,
mode: "iterative" as const,
})),
guidance: testMcpGuidance,
});
const index = await adapter.callTool({ name: "meta.index" });
const guide = await adapter.callTool({
name: "meta.guide",
input: { brief: "visual verification", taskScope: "visual-change" },
});
expect(index.structuredContent.data).toEqual(
expect.objectContaining({
visionLoop: expect.not.arrayContaining([
expect.stringContaining("screenshot.diff"),
]),
})
);
expect(
(index.structuredContent.data as { visionLoop: string[] }).visionLoop[0]
).toBe(testMcpGuidance.getVisionVerificationLoop({ includeDiff: true })[0]);
expect(guide.structuredContent.data).toEqual(
expect.objectContaining({
workflow: expect.arrayContaining([
testMcpGuidance.getVisionWorkflowSummary({ includeDiff: false }),
]),
})
);
expect(guide.content[0].text).not.toContain("screenshot.diff");
});
test("rejects unsupported screenshot browser input", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
captureScreenshot: vi.fn(),
});
await expect(
adapter.callTool({
name: "screenshot",
input: {
url: "https://example.com",
browser: "firefox",
},
})
).rejects.toThrow(
"screenshot browser must be auto, chromium, chrome, edge, or brave."
);
});
test("rejects invalid screenshot readiness input", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
captureScreenshot: vi.fn(),
});
await expect(
adapter.callTool({
name: "screenshot",
input: {
url: "https://example.com",
waitUntil: "interactive",
},
})
).rejects.toThrow(
"screenshot waitUntil must be commit, domcontentloaded, load, or networkidle."
);
await expect(
adapter.callTool({
name: "screenshot",
input: {
url: "https://example.com",
waitForTimeout: -1,
},
})
).rejects.toThrow(
"screenshot waitForTimeout must be a non-negative integer."
);
await expect(
adapter.callTool({
name: "screenshot",
input: {
url: "https://example.com",
waitForTimeout: "500",
},
})
).rejects.toThrow(
"screenshot waitForTimeout must be a non-negative integer."
);
await expect(
adapter.callTool({
name: "screenshot",
input: {
url: "https://example.com",
waitForSelector: "",
},
})
).rejects.toThrow("screenshot waitForSelector must be a non-empty string.");
await expect(
adapter.callTool({
name: "screenshot",
input: {
url: "https://example.com",
waitForSelector: 1,
},
})
).rejects.toThrow("screenshot waitForSelector must be a non-empty string.");
await expect(
adapter.callTool({
name: "screenshot",
input: {
url: "https://example.com",
timeout: 0,
},
})
).rejects.toThrow("screenshot timeout must be a positive integer.");
await expect(
adapter.callTool({
name: "screenshot",
input: {
url: "https://example.com",
timeout: "10000",
},
})
).rejects.toThrow("screenshot timeout must be a positive integer.");
});
test("rejects empty screenshot url and path input", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
captureScreenshot: vi.fn(),
});
await expect(
adapter.callTool({
name: "screenshot",
input: {
url: "",
},
})
).rejects.toThrow("screenshot requires url or path.");
await expect(
adapter.callTool({
name: "screenshot",
input: {
path: "",
},
})
).rejects.toThrow("screenshot requires url or path.");
});
test("declares the screenshot target requirement in its MCP schema", () => {
const screenshotTool = listProjectSessionMcpTools(publicMcpOperations, {
includeScreenshot: true,
}).find((tool) => tool.name === "screenshot");
expect(screenshotTool?.inputSchema).toMatchObject({
oneOf: expect.arrayContaining([
expect.objectContaining({ required: ["url"] }),
expect.objectContaining({ required: ["path"] }),
]),
});
});
test("rejects ambiguous screenshot base URL input", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
captureScreenshot: vi.fn(),
});
await expect(
adapter.callTool({
name: "screenshot",
input: {
baseUrl: "http://127.0.0.1:5177",
},
})
).rejects.toThrow("screenshot requires url or path.");
await expect(
adapter.callTool({
name: "screenshot",
input: {
url: "https://example.com",
baseUrl: "http://127.0.0.1:5177",
path: "/design-system",
},
})
).rejects.toThrow(
"screenshot accepts either url or path/baseUrl, not both."
);
await expect(
adapter.callTool({
name: "screenshot",
input: {
baseUrl: "not-a-url",
path: "/design-system",
},
})
).rejects.toThrow("screenshot baseUrl must be an absolute URL.");
await expect(
adapter.callTool({
name: "screenshot",
input: {
baseUrl: "http://127.0.0.1:5177",
path: "/design-system",
source: "session",
},
})
).rejects.toThrow(
"screenshot baseUrl uses an existing preview/site and cannot be combined with source, mode, or imageDomains."
);
});
test("compares screenshot diffs with generated PNG files", async () => {
const tempDir = await mkdtemp(path.join(tmpdir(), "webstudio-mcp-diff-"));
try {
const baselinePath = path.join(tempDir, "baseline.png");
const currentPath = path.join(tempDir, "current.png");
const outputDir = path.join(tempDir, "diff");
await writePng(baselinePath, createPng(4, 4, { r: 255, g: 255, b: 255 }));
const current = createPng(4, 4, { r: 255, g: 255, b: 255 });
paintRect(
current,
{ x: 1, y: 1, width: 2, height: 1 },
{ r: 0, g: 0, b: 0 }
);
await writePng(currentPath, current);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
diffScreenshots: diffPngFiles,
});
const result = await adapter.callTool({
name: "screenshot.diff",
input: {
baselinePath,
currentPath,
outputDir,
},
});
expect(result.structuredContent.data).toEqual(
expect.objectContaining({
totalPixels: 16,
differentPixels: 2,
mismatchPercentage: 12.5,
regions: [
expect.objectContaining({
bounds: { x: 1, y: 1, width: 2, height: 1 },
pixelCount: 2,
}),
],
summary: expect.stringContaining("status: changed"),
diffPath: path.join(outputDir, "current-diff.png"),
contextDiffPath: path.join(outputDir, "current-context-diff.png"),
})
);
} finally {
await rm(tempDir, { recursive: true, force: true });
}
});
test("rejects invalid screenshot diff input", async () => {
const diffScreenshots = vi.fn(async () => ({
totalPixels: 0,
differentPixels: 0,
mismatchPercentage: 0,
summary: "Screenshot diff summary",
regions: [],
textAnalysis: {
status: "ok" as const,
provider: "tesseract" as const,
changes: [],
observedText: ["Pricing"],
},
warnings: [],
}));
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
diffScreenshots,
});
await expect(
adapter.callTool({
name: "screenshot.diff",
input: { baselinePath: "baseline.png" },
})
).rejects.toThrow("screenshot.diff requires baselinePath and currentPath.");
await expect(
adapter.callTool({
name: "screenshot.diff",
input: {
baselinePath: "baseline.png",
currentPath: "current.png",
threshold: 2,
},
})
).rejects.toThrow("screenshot.diff threshold must be between 0 and 1.");
await adapter.callTool({
name: "screenshot.diff",
input: {
baselinePath: "baseline.png",
currentPath: "current.png",
expectedText: ["Pricing"],
expectedVisual: { maxMismatchPercentage: 2, maxChangedRegions: 3 },
},
});
expect(diffScreenshots).toHaveBeenLastCalledWith(
expect.objectContaining({
expectedText: ["Pricing"],
expectedVisual: { maxMismatchPercentage: 2, maxChangedRegions: 3 },
})
);
await expect(
adapter.callTool({
name: "screenshot.diff",
input: {
baselinePath: "baseline.png",
currentPath: "current.png",
expectedText: [],
},
})
).rejects.toThrow(
"screenshot.diff expectedText must be a non-empty array of non-empty strings."
);
await expect(
adapter.callTool({
name: "screenshot.diff",
input: {
baselinePath: "baseline.png",
currentPath: "current.png",
expectedVisual: { minChangedRegions: 2, maxChangedRegions: 1 },
},
})
).rejects.toThrow("screenshot.diff expectedVisual must include valid");
await expect(
adapter.callTool({
name: "screenshot.diff",
input: {
baselinePath: "baseline.png",
currentPath: "current.png",
expectedVisual: {
dominantColorChange: {
channel: "purple",
direction: "increase",
},
},
},
})
).rejects.toThrow("screenshot.diff expectedVisual must include valid");
});
test("installs OCR only after explicit confirmation", async () => {
const installOcr = vi.fn(async () => ({
installed: true,
alreadyAvailable: false,
command: "sudo apt install -y tesseract-ocr",
tesseractPath: "/usr/bin/tesseract",
installUrl: tesseractInstallUrl,
warnings: [],
}));
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
installOcr,
});
await expect(
adapter.callTool({ name: "vision.install-ocr", input: {} })
).rejects.toThrow(
"vision.install-ocr requires confirm: true after explicit user consent."
);
await expect(
adapter.callTool({
name: "vision.install-ocr",
input: { confirm: true },
})
).resolves.toEqual(
expect.objectContaining({
structuredContent: expect.objectContaining({
data: expect.objectContaining({
installed: true,
tesseractPath: "/usr/bin/tesseract",
}),
}),
})
);
expect(installOcr).toHaveBeenCalledOnce();
});
test("exposes preview tools when preview runner is injected", async () => {
const captureScreenshot = vi.fn(async () => ({
output: "/tmp/current.png",
browserPath: "/usr/bin/chromium",
browser: "chromium" as const,
viewport: { width: 1440, height: 900 },
fullPage: false,
elapsedMs: 12,
warnings: [],
}));
const progressMessages: string[] = [];
const startPreview = vi.fn(
async (
_input: { host?: string; port?: number; source?: "local" | "session" },
progress?: { report: (message: string) => void }
) => {
progress?.report(
"tool preview.start preparing generated preview project"
);
return {
url: "http://127.0.0.1:5173/",
pid: 123,
running: true,
mode: "iterative" as const,
};
}
);
const getPreviewStatus = vi.fn(async () => ({
url: "http://127.0.0.1:5173/",
pid: 123,
running: true,
mode: "iterative" as const,
}));
const stopPreview = vi.fn(async () => ({
url: "http://127.0.0.1:5173/",
running: false,
mode: "iterative" as const,
}));
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
captureScreenshot,
diffScreenshots: diffPngFiles,
startPreview,
getPreviewStatus,
stopPreview,
guidance: testMcpGuidance,
reportToolProgress: (message) => {
progressMessages.push(message);
},
});
expect(adapter.listTools().map((tool) => tool.name)).toEqual(
expect.arrayContaining([
"preview.start",
"preview.status",
"preview.stop",
])
);
expect(
adapter.listTools().find((tool) => tool.name === "preview.start")
?.mcpExamples
).toEqual([{ source: "session" }]);
const started = await adapter.callTool({
name: "preview.start",
input: { source: "session" },
});
const status = await adapter.callTool({ name: "preview.status" });
const stopped = await adapter.callTool({ name: "preview.stop" });
const index = await adapter.callTool({ name: "meta.index" });
const guide = await adapter.callTool({
name: "meta.guide",
input: { brief: "visual verification", taskScope: "visual-change" },
});
expect(startPreview).toHaveBeenCalledWith(
{ source: "session" },
expect.objectContaining({ report: expect.any(Function) })
);
expect(getPreviewStatus).toHaveBeenCalledOnce();
expect(stopPreview).toHaveBeenCalledOnce();
expect(progressMessages).toEqual([
"tool preview.start preparing generated preview project",
]);
expect(started.structuredContent.data).toEqual({
url: "http://127.0.0.1:5173/",
pid: 123,
running: true,
mode: "iterative",
});
expect(status.structuredContent.data).toEqual({
url: "http://127.0.0.1:5173/",
pid: 123,
running: true,
mode: "iterative",
});
expect(stopped.structuredContent.data).toEqual({
url: "http://127.0.0.1:5173/",
running: false,
mode: "iterative",
});
expect(index.structuredContent.data).toEqual(
expect.objectContaining({
visionLoop: expect.arrayContaining([
...testMcpGuidance
.getVisionVerificationLoop({ includeDiff: true })
.slice(1, 3),
'Call screenshot with { path: "/" } or the changed page path.',
]),
capabilities: expect.arrayContaining([
expect.objectContaining({
area: "visual-verification",
tools: [
"preview.start",
"preview.status",
"preview.stop",
"screenshot",
"screenshot.diff",
],
}),
]),
})
);
expect(guide.structuredContent.data).toEqual(
expect.objectContaining({
workflow: expect.arrayContaining([
testMcpGuidance.getVisionWorkflowSummary({ includeDiff: true }),
]),
tools: expect.arrayContaining([
expect.objectContaining({ name: "preview.start" }),
expect.objectContaining({ name: "screenshot" }),
]),
})
);
});
test("does not include visual guidance without host-provided docs", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
captureScreenshot: vi.fn(),
startPreview: vi.fn(),
getPreviewStatus: vi.fn(),
});
const index = await adapter.callTool({ name: "meta.index" });
const guide = await adapter.callTool({
name: "meta.guide",
input: { brief: "visual verification" },
});
expect(index.structuredContent.data).toEqual(
expect.objectContaining({ visionLoop: [] })
);
expect(
(guide.structuredContent.data as { workflow: string[] }).workflow
).not.toContain(
testMcpGuidance.getVisionWorkflowSummary({ includeDiff: false })
);
});
test("exposes Preview form submission only with a handler and preserves repeated inputs", async () => {
const submitPreviewForm = vi.fn(async () => ({
status: "submitted" as const,
formState: "success",
results: [],
errors: [],
exchanges: [],
pageUrl: "http://127.0.0.1:5173/contact",
correlationId: "form-1",
}));
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
startPreview: vi.fn(),
getPreviewStatus: vi.fn(),
submitPreviewForm,
});
expect(adapter.listTools().map((tool) => tool.name)).toContain(
"preview.submit-form"
);
const result = await adapter.callTool({
name: "preview.submit-form",
input: {
path: "/contact",
selector: "form",
values: [
{ name: "tag", value: "first" },
{ name: "tag", value: "second" },
],
submitter: "button[type=submit]",
},
});
expect(submitPreviewForm).toHaveBeenCalledWith({
path: "/contact",
selector: "form",
values: [
{ name: "tag", value: "first" },
{ name: "tag", value: "second" },
],
submitter: "button[type=submit]",
});
expect(result.structuredContent.data).toMatchObject({
status: "submitted",
});
});
test("exposes server-side Form simulation only with a handler and preserves synthetic repeated fields", async () => {
const simulateForm = vi.fn(async () => ({
success: true,
status: 200,
results: [{ status: 201, resourceId: "receiver" }],
errors: [],
}));
const withoutHandler = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
expect(withoutHandler.listTools().map((tool) => tool.name)).not.toContain(
"forms.simulate-submission"
);
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
simulateForm,
});
expect(adapter.listTools().map((tool) => tool.name)).toContain(
"forms.simulate-submission"
);
const input = {
path: "/contact",
siteOrigin: "https://site.example",
formId: "saved-form",
values: [
{ name: "tag", value: "first" },
{ name: "tag", value: "second" },
],
};
const result = await adapter.callTool({
name: "forms.simulate-submission",
input,
});
expect(simulateForm).toHaveBeenCalledWith(input);
expect(result.structuredContent.data).toMatchObject({
success: true,
results: [{ resourceId: "receiver", status: 201 }],
});
});
test("uses proportional verification for small value corrections", async () => {
const searchOperation = publicOperation({
command: "search-project",
id: "project.search",
description: "Search project data",
inputSchema: getTestInputSchema(
z.object({
query: z.string(),
namespaces: z.array(z.string()).optional(),
})
),
readNamespaces: ["pages", "instances", "props"],
});
const adapter = createProjectSessionMcpCore({
operations: [...publicMcpOperations, searchOperation],
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
captureScreenshot: vi.fn(),
startPreview: vi.fn(),
getPreviewStatus: vi.fn(),
guidance: testMcpGuidance,
});
const guide = await adapter.callTool({
name: "meta.guide",
input: {
brief: "Correct one asset reference on the pricing page",
taskScope: "small-value-or-reference-correction",
},
});
expect(guide.structuredContent.data).toEqual(
expect.objectContaining({
taskScope: "small-value-or-reference-correction",
focusedCorrection: {
search: {
tool: "search-project",
requiredInput: ["query"],
calls: 1,
},
edit: { strategy: "smallest-semantic-mutation" },
verify: { strategy: "targeted-assertions" },
},
tools: expect.arrayContaining([
expect.objectContaining({
name: "search-project",
requiredInputFields: ["query"],
inputFields: expect.arrayContaining(["query", "namespaces"]),
}),
]),
visionLoop: [],
slowOperation: expect.objectContaining({
confirmationRequired: true,
operation: "full production preview",
}),
})
);
});
test("keeps explicit read-only custom-code audits read-only", async () => {
const readOnlyOperations = [
...publicMcpOperations,
publicOperation({
command: "search-project",
id: "project.search",
description: "Search project data for known values",
}),
publicOperation({
command: "inspect-instance",
id: "instances.inspect",
description: "Inspect one instance and its props",
}),
publicOperation({
command: "get-project-settings",
id: "project.getSettings",
description: "Read project settings",
}),
publicOperation({
command: "snapshot",
id: "project.snapshot",
description: "Read a bounded project snapshot",
}),
];
const adapter = createProjectSessionMcpCore({
operations: readOnlyOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
guidance: testMcpGuidance,
});
const guide = await adapter.callTool({
name: "meta.guide",
input: {
brief:
"Perform a read-only custom-code consolidation audit against the provided design for this existing page. Return an ordered inventory of HTML Embeds, CSS, scripts, selectors, and runtime dependencies. Do not mutate, create, insert, update, delete, rename, reorder, publish, or change project settings.",
taskScope: "read-only-audit",
},
});
const data = guide.structuredContent.data as {
taskScope: string;
routing: Record<string, unknown>;
constraints: Record<string, unknown>;
tools: Array<{ name: string }>;
};
const toolNames = data.tools.map(({ name }) => name);
const mutationToolNames = new Set(
readOnlyOperations
.filter(({ method }) => method === "mutation")
.map(({ command }) => command)
);
expect(data.taskScope).toBe("read-only-audit");
expect(data.routing).toEqual({
matchedBy: "explicit-read-only",
workflow: "read-only-discovery",
broadContextTools: [],
authoredFragment: false,
});
expect(data.constraints).toEqual({
readOnly: true,
mutationToolsExcluded: true,
});
expect(toolNames).toEqual(
expect.arrayContaining([
"search-project",
"list-instances",
"inspect-instance",
"get-project-settings",
"snapshot",
])
);
expect(toolNames.filter((name) => mutationToolNames.has(name))).toEqual([]);
expect(
data.tools.every(({ name }) => {
const tool = adapter
.listTools()
.find((candidate) => candidate.name === name);
return (
tool !== undefined &&
tool.annotations.method === "query" &&
isReadOnlyProjectSessionMcpTool(tool)
);
})
).toBe(true);
expect(
toolNames.filter((name) =>
[
"inspect-design-context",
"insert-fragment-verified",
"attach-design-token",
"update-styles",
"verify-page-responsive",
"preview.status",
"screenshot.diff",
].includes(name)
)
).toEqual([]);
});
test("does not infer task scope from brief prose", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
const guide = await adapter.callTool({
name: "meta.guide",
input: {
brief:
"Perform a read-only custom-code consolidation audit against the provided design for this existing page. Return an ordered inventory of HTML Embeds, CSS, scripts, selectors, and runtime dependencies. Do not mutate, create, insert, update, delete, rename, reorder, publish, or change project settings.",
},
});
expect(guide.structuredContent.data).toMatchObject({
taskScope: "focused-page-change",
routing: { workflow: "general" },
});
expect(guide.structuredContent.data).not.toHaveProperty("constraints");
});
test("routes an authored component insertion without broad discovery", async () => {
const operations = [
...publicMcpOperations,
publicOperation({
command: "create-variable",
id: "variables.create",
description: "Create a variable in a known container",
}),
publicOperation({
command: "bind-props",
id: "props.bind",
description: "Bind component interactions to variables",
}),
];
const adapter = createProjectSessionMcpCore({
operations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
guidance: testMcpGuidance,
});
const guide = await adapter.callTool({
name: "meta.guide",
input: {
brief:
"Insert an authored timer component with insert-fragment into the known container. Create variables and bind its interactions while keeping the existing design.",
taskScope: "structural-project-change",
authoredFragment: true,
},
});
const data = guide.structuredContent.data as {
taskScope: string;
routing?: Record<string, unknown>;
tools: Array<{ name: string }>;
};
const toolNames = data.tools.map(({ name }) => name);
expect(data.taskScope).toBe("structural-project-change");
expect(data.routing).toEqual({
matchedBy: "general-tool-ranking",
workflow: "general",
broadContextTools: [],
authoredFragment: true,
});
expect(toolNames).toEqual(
expect.arrayContaining([
"insert-fragment",
"create-variable",
"bind-props",
])
);
expect(toolNames).not.toContain("inspect-design-context");
expect(toolNames).not.toContain("components.search");
});
test("does not infer authored fragment routing from brief prose", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
const guide = await adapter.callTool({
name: "meta.guide",
input: {
brief: "Insert an authored fragment and reuse design system tokens",
},
});
expect(guide.structuredContent.data).toMatchObject({
routing: {
workflow: "general",
authoredFragment: false,
},
});
});
test("preflights production preview before starting slow work", async () => {
const startPreview = vi.fn(async () => ({
url: "http://127.0.0.1:5173/",
running: true,
mode: "production" as const,
}));
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
startPreview,
getPreviewStatus: vi.fn(),
});
const result = await adapter.callTool({
name: "preview.start",
input: { mode: "production", maxDurationMs: 10_000 },
});
expect(startPreview).not.toHaveBeenCalled();
expect(result.structuredContent.data).toEqual(
expect.objectContaining({
confirmationRequired: true,
operation: "production preview build",
estimatedDuration: "30–60 seconds",
confirmationToken: expect.any(String),
fasterAlternative: expect.objectContaining({
operation: "targeted route validation",
}),
})
);
const confirmationToken = (
result.structuredContent.data as { confirmationToken: string }
).confirmationToken;
const confirmed = await adapter.callTool({
name: "preview.start",
input: {
mode: "production",
maxDurationMs: 10_000,
confirmSlow: true,
confirmationToken,
},
});
expect(startPreview).toHaveBeenCalledOnce();
expect(confirmed.structuredContent.data).toEqual(
expect.objectContaining({ running: true, mode: "production" })
);
});
test.each([{ port: 5173 }, { host: "127.0.0.1" }])(
"keeps preview network binding under runner control for %o",
async (input) => {
const startPreview = vi.fn();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
startPreview,
getPreviewStatus: vi.fn(),
});
await expect(
adapter.callTool({ name: "preview.start", input })
).rejects.toThrow(
"preview.start does not accept host or port. The MCP runner selects an available local address and returns its URL."
);
expect(startPreview).not.toHaveBeenCalled();
}
);
test.each([{ port: 5173 }, { host: "127.0.0.1" }])(
"keeps screenshot network binding under runner control for %o",
async (networkInput) => {
const captureScreenshot = vi.fn();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
captureScreenshot,
});
await expect(
adapter.callTool({
name: "screenshot",
input: { path: "/", ...networkInput },
})
).rejects.toThrow(
"screenshot does not accept host or port. The MCP runner selects an available local address and returns its URL."
);
expect(captureScreenshot).not.toHaveBeenCalled();
}
);
test("does not advertise MCP network binding fields", () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
captureScreenshot: vi.fn(),
startPreview: vi.fn(),
getPreviewStatus: vi.fn(),
});
for (const name of ["preview.start", "screenshot"]) {
const tool = adapter
.listTools()
.find((candidate) => candidate.name === name);
expect(tool?.inputSchema.properties).not.toHaveProperty("host");
expect(tool?.inputSchema.properties).not.toHaveProperty("port");
}
});
test("uses discovery tools when meta guide has no brief", async () => {
const session = createSession({
initialize: vi.fn(),
refresh: vi.fn(),
reset: vi.fn(),
});
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(session),
executeOperation: createExecuteOperation(),
});
const guide = await adapter.callTool({ name: "meta.guide" });
expect(session.initialize).not.toHaveBeenCalled();
expect(guide.structuredContent.data).toEqual(
expect.objectContaining({
tools: expect.arrayContaining([
expect.objectContaining({ name: "status" }),
expect.objectContaining({ name: "whoami" }),
]),
})
);
});
test("bundles bounded authentication discovery into one focused call", async () => {
const commands = [
"get-project-settings",
"list-pages",
"list-resources",
"list-variables",
] as const;
const operations = [
...publicMcpOperations.filter(
(operation) => commands.includes(operation.command as never) === false
),
...commands.map((command) =>
publicOperation({
command,
id: `test.${command}`,
description: command,
})
),
];
const executeOperation = createExecuteOperation(
async ({ command, input }) =>
createEnvelope({
operationId: `test.${command}`,
result: { command, input },
})
);
const adapter = createProjectSessionMcpCore({
operations,
createProjectSession: createSessionFactory(),
executeOperation,
});
expect(adapter.listTools().map(({ name }) => name)).toContain(
"inspect-auth-context"
);
const guide = await adapter.callTool({
name: "meta.guide",
input: {
brief: "Create an authenticated page",
workflow: "authenticated-page",
},
});
const guideToolNames = (
guide.structuredContent.data as { tools: Array<{ name: string }> }
).tools.map(({ name }) => name);
expect(guideToolNames).toContain("inspect-auth-context");
expect(guideToolNames).not.toEqual(expect.arrayContaining([...commands]));
const result = await adapter.callTool({ name: "inspect-auth-context" });
expect(result.structuredContent.data).toEqual({
projectSettings: { command: "get-project-settings", input: {} },
pages: { command: "list-pages", input: { limit: 50 } },
resources: { command: "list-resources", input: { limit: 50 } },
variables: { command: "list-variables", input: { limit: 50 } },
});
expect(executeOperation).toHaveBeenCalledTimes(4);
});
test("bundles bounded design discovery into one focused call", async () => {
const commands = [
"list-pages",
"list-breakpoints",
"list-design-tokens",
"list-assets",
"list-variables",
] as const;
const operations = [
...publicMcpOperations.filter(
(operation) => commands.includes(operation.command as never) === false
),
...commands.map((command) =>
publicOperation({
command,
id: `test.${command}`,
description: command,
})
),
];
const executeOperation = createExecuteOperation(
async ({ command, input }) =>
createEnvelope({
operationId: `test.${command}`,
result: { command, input },
})
);
const adapter = createProjectSessionMcpCore({
operations,
createProjectSession: createSessionFactory(),
executeOperation,
});
expect(adapter.listTools().map(({ name }) => name)).toContain(
"inspect-design-context"
);
const guide = await adapter.callTool({
name: "meta.guide",
input: {
brief: "Recreate this design as a responsive page",
workflow: "design-input",
},
});
const guideToolNames = (
guide.structuredContent.data as { tools: Array<{ name: string }> }
).tools.map(({ name }) => name);
expect(guideToolNames).toContain("inspect-design-context");
expect(guideToolNames).not.toEqual(expect.arrayContaining([...commands]));
const result = await adapter.callTool({ name: "inspect-design-context" });
expect(result.structuredContent.data).toEqual({
pages: { command: "list-pages", input: { limit: 50 } },
breakpoints: { command: "list-breakpoints", input: {} },
designTokens: { command: "list-design-tokens", input: { limit: 50 } },
assets: { command: "list-assets", input: { limit: 50 } },
variables: { command: "list-variables", input: { limit: 50 } },
});
expect(executeOperation).toHaveBeenCalledTimes(5);
});
test("refreshes and verifies several font assets in one call", async () => {
const session = createSession({ refresh: vi.fn() });
const operations = [
...publicMcpOperations,
publicOperation({
command: "get-asset",
id: "assets.get",
description: "Get asset",
}),
];
const executeOperation = createExecuteOperation(
async ({ command, input }) =>
createEnvelope({
operationId: `test.${command}`,
result: { command, input },
})
);
const adapter = createProjectSessionMcpCore({
operations,
createProjectSession: createSessionFactory(session),
executeOperation,
});
expect(adapter.listTools().map(({ name }) => name)).toContain(
"verify-font-assets"
);
const guide = await adapter.callTool({
name: "meta.guide",
input: {
brief: "Upload and manage font assets",
workflow: "font-assets",
},
});
const guideToolNames = (
guide.structuredContent.data as { tools: Array<{ name: string }> }
).tools.map(({ name }) => name);
expect(guideToolNames).toContain("verify-font-assets");
expect(guideToolNames).not.toEqual(
expect.arrayContaining(["refresh", "get-asset"])
);
const result = await adapter.callTool({
name: "verify-font-assets",
input: { assetIds: ["asset-regular", "asset-bold"] },
});
expect(session.refresh).toHaveBeenCalledWith(["assets"]);
expect(result.structuredContent.data).toEqual({
assets: [
{ command: "get-asset", input: { assetId: "asset-regular" } },
{ command: "get-asset", input: { assetId: "asset-bold" } },
],
});
expect(executeOperation).toHaveBeenCalledTimes(2);
});
test("rejects unknown tools before calling the operation executor", async () => {
const createProjectSession = createSessionFactory();
const executeOperation = createExecuteOperation();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession,
executeOperation,
});
await expect(adapter.callTool({ name: "unknown-tool" })).rejects.toThrow(
'Unknown MCP tool "unknown-tool". Use meta.index to list available tools.'
);
await expect(adapter.callTool({ name: "updat_styles" })).rejects.toThrow(
'Unknown MCP tool "updat_styles". Did you mean "update-styles"? Use meta.index to list available tools.'
);
expect(createProjectSession).not.toHaveBeenCalled();
expect(executeOperation).not.toHaveBeenCalled();
});
test("accepts exposed underscore spellings in direct MCP calls", async () => {
const executeOperation = createExecuteOperation();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
await adapter.callTool({
name: "update_styles",
input: {
updates: [
{
instanceId: "body",
breakpoint: "base",
property: "display",
value: "grid",
},
],
},
});
expect(executeOperation).toHaveBeenCalledWith(
expect.objectContaining({ command: "update-styles" })
);
});
test.each([
{
command: "insert-fragment",
input: {
parentInstanceId: "body",
fragment: '<ws.element ws:tag="div" />',
},
},
{
command: "insert-collection",
input: {
parentInstanceId: "body",
data: { type: "json", value: [] },
itemFragment: '<ws.element ws:tag="article" />',
},
},
])(
"does not dispatch the $command adapter when the operation is unavailable",
async ({ command, input }) => {
const createProjectSession = createSessionFactory();
const executeOperation = createExecuteOperation();
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations.filter(
(operation) => operation.command !== command
),
createProjectSession,
executeOperation,
});
await expect(adapter.callTool({ name: command, input })).rejects.toThrow(
`Unknown MCP tool "${command}".`
);
expect(createProjectSession).not.toHaveBeenCalled();
expect(executeOperation).not.toHaveBeenCalled();
}
);
test("reads MCP resources from the long-lived project session", async () => {
const session = createSession({
initialize: vi.fn(async () =>
createEnvelope({
operationId: "project-session.status",
result: { loaded: true },
})
),
refresh: vi.fn(),
reset: vi.fn(),
});
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(session),
executeOperation: createExecuteOperation(),
});
const status = await adapter.readResource({
uri: "webstudio://project/status",
});
const toolsOverview = await adapter.readResource({
uri: "webstudio://project/tools-overview",
});
const tools = await adapter.readResource({
uri: "webstudio://project/tools",
});
const guide = await adapter.readResource({
uri: "webstudio://project/guide",
});
const expressions = await adapter.readResource({
uri: "webstudio://project/expressions",
});
const accessibilityReview = await adapter.readResource({
uri: "webstudio://project/accessibility-review",
});
const componentsOverview = await adapter.readResource({
uri: "webstudio://project/components-overview",
});
const components = await adapter.readResource({
uri: "webstudio://project/components",
});
const componentsVerbose = await adapter.readResource({
uri: "webstudio://project/components?verbose=true",
});
expect(JSON.parse(status.contents[0]?.text ?? "{}")).toEqual(
expect.objectContaining({
data: { loaded: true },
meta: expect.objectContaining({
session: expect.objectContaining({
operationId: "project-session.status",
}),
}),
})
);
expect(JSON.parse(tools.contents[0]?.text ?? "{}")).toEqual(
expect.objectContaining({
detail: "compact",
returnedCount: 20,
nextCursor: "20",
tools: expect.any(Array),
})
);
expect(tools.contents[0]?.text).not.toContain("inputSchema");
expect((tools.contents[0]?.text ?? "").length).toBeLessThan(16_000);
expect(JSON.parse(toolsOverview.contents[0]?.text ?? "{}")).toEqual(
expect.objectContaining({
count: expect.any(Number),
capabilities: expect.arrayContaining([
expect.objectContaining({
area: "content",
count: expect.any(Number),
}),
]),
})
);
expect(toolsOverview.contents[0]?.text).not.toContain("inputSchema");
expect(JSON.parse(guide.contents[0]?.text ?? "{}")).toEqual(
expect.objectContaining({
startHere: expect.arrayContaining(["meta.index"]),
})
);
expect(accessibilityReview.contents[0]).toEqual(
expect.objectContaining({
mimeType: "text/markdown",
})
);
expect(expressions.contents[0]).toEqual(
expect.objectContaining({
mimeType: "text/markdown",
})
);
const componentOverviewData = JSON.parse(
componentsOverview.contents[0]?.text ?? "{}"
);
expect(componentOverviewData).toEqual(
expect.objectContaining({
count: expect.any(Number),
namespaces: expect.objectContaining({
"@webstudio-is/sdk-components-react-radix": expect.any(Number),
}),
})
);
expect(componentOverviewData).not.toHaveProperty("components");
const compactComponents = JSON.parse(components.contents[0]?.text ?? "{}");
expect(compactComponents).toEqual(
expect.objectContaining({
detail: "compact",
returnedCount: 20,
nextCursor: "20",
components: expect.arrayContaining([
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Accordion",
namespace: "@webstudio-is/sdk-components-react-radix",
exportName: "Accordion",
category: expect.any(String),
}),
]),
})
);
for (const component of compactComponents.components) {
expect(component).not.toHaveProperty("contentModel");
expect(component).not.toHaveProperty("props");
expect(component).not.toHaveProperty("states");
}
expect((components.contents[0]?.text ?? "").length).toBeLessThan(16_000);
expect(JSON.parse(componentsVerbose.contents[0]?.text ?? "{}")).toEqual(
expect.objectContaining({
source: "@webstudio-is/sdk-components-registry/metas",
detail: "verbose",
returnedCount: 20,
components: expect.arrayContaining([
expect.objectContaining({
component: "@webstudio-is/sdk-components-react-radix:Accordion",
namespace: "@webstudio-is/sdk-components-react-radix",
exportName: "Accordion",
contentModel: expect.objectContaining({
children: expect.arrayContaining(["instance"]),
descendants: expect.arrayContaining([
"@webstudio-is/sdk-components-react-radix:AccordionItem",
]),
}),
initialProps: expect.arrayContaining(["value", "collapsible"]),
props: expect.objectContaining({
value: expect.any(Object),
collapsible: expect.any(Object),
}),
}),
]),
})
);
await expect(
adapter.readResource({ uri: "webstudio://project/unknown" })
).rejects.toThrow('Unknown MCP resource "webstudio://project/unknown".');
});
test("pages discovery resources without omissions or duplicate entries", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
const readCatalog = async (
resource: "tools" | "components",
verbose: boolean
) => {
const ids: string[] = [];
let cursor: string | undefined;
let total = 0;
do {
const query = new URLSearchParams({
limit: "13",
verbose: String(verbose),
...(cursor === undefined ? {} : { cursor }),
});
const result = await adapter.readResource({
uri: `webstudio://project/${resource}?${query}`,
});
const data = JSON.parse(result.contents[0]?.text ?? "{}");
const entries = data[resource] as Array<{
name?: string;
component?: string;
}>;
expect(data.returnedCount).toBe(entries.length);
expect(entries.length).toBeLessThanOrEqual(13);
ids.push(
...entries.map(({ name, component }) => name ?? component ?? "")
);
total = data.total;
cursor = data.nextCursor;
} while (cursor !== undefined);
expect(ids).toHaveLength(total);
expect(new Set(ids).size).toBe(ids.length);
return ids;
};
const compactTools = await readCatalog("tools", false);
const verboseTools = await readCatalog("tools", true);
const compactComponents = await readCatalog("components", false);
const verboseComponents = await readCatalog("components", true);
expect(compactTools).toEqual(verboseTools);
expect(compactTools).toEqual(adapter.listTools().map(({ name }) => name));
expect(compactComponents).toEqual(verboseComponents);
});
test("caps and validates discovery resource pagination", async () => {
const adapter = createProjectSessionMcpCore({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
const capped = await adapter.readResource({
uri: "webstudio://project/tools?limit=500",
});
const cappedData = JSON.parse(capped.contents[0]?.text ?? "{}");
expect(cappedData.returnedCount).toBeLessThanOrEqual(50);
await expect(
adapter.readResource({
uri: "webstudio://project/tools?cursor=invalid",
})
).rejects.toThrow("Invalid webstudio://project/tools cursor");
await expect(
adapter.readResource({
uri: "webstudio://project/components?limit=0",
})
).rejects.toThrow("limit must be at least 1");
});
test("connects through the official MCP SDK and exposes discovery", async () => {
const setTextContentOperation = publicOperation({
command: "set-text-content",
id: "instances.setTextContent",
method: "mutation",
permit: "edit",
description: "Set or reset text content",
inputSchema: getTestInputSchema(
z.discriminatedUnion("operation", [
z.object({
operation: z.literal("set"),
instanceId: z.string(),
text: z.string(),
}),
z.object({
operation: z.literal("reset"),
instanceId: z.string(),
}),
])
),
readNamespaces: ["instances"],
writeNamespaces: ["instances"],
invalidatesNamespaces: ["instances"],
});
const defineCssVariablesOperation = styleOperation({
command: "define-css-variable",
id: "cssVariables.define",
description: "Define CSS variables",
inputSchema: getTestInputSchema(
z.object({
vars: z.record(z.string(), z.string()),
overwrite: z.boolean().optional(),
})
),
readNamespaces: ["styles"],
});
const listCssVariablesOperation = publicOperation({
command: "list-css-variables",
id: "cssVariables.list",
method: "query",
permit: "view",
description: "List CSS variables",
inputSchema: getTestInputSchema(
z.object({
withUsage: z.boolean().optional(),
verbose: z.boolean().optional(),
})
),
readNamespaces: ["styles"],
writeNamespaces: [],
invalidatesNamespaces: [],
});
const deleteCssVariablesOperation = styleOperation({
command: "delete-css-variable",
id: "cssVariables.delete",
description: "Delete CSS variables",
inputSchema: getTestInputSchema(
z.object({
names: z.array(z.string()),
force: z.boolean().optional(),
})
),
readNamespaces: ["styles"],
});
const server = await createProjectSessionMcpServer({
operations: [
...publicMcpOperations,
setTextContentOperation,
listCssVariablesOperation,
defineCssVariablesOperation,
deleteCssVariablesOperation,
],
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
additionalInstructions:
"This MCP server runs CLI 0.299.0; CLI 0.301.0 is available.",
});
const { client, close } = await createConnectedClient(server);
try {
expect(client.getServerCapabilities()).toEqual({
tools: {},
resources: {},
logging: {},
});
expect(client.getServerVersion()).toEqual({
name: "webstudio",
version: "0.0.0",
});
expect(client.getInstructions()).toContain(
"This MCP server runs CLI 0.299.0; CLI 0.301.0 is available."
);
expect(client.getInstructions()).toContain(
"For any multi-step authoring task"
);
const listedTools = await client.listTools();
expect(
listedTools.tools.find(({ name }) => name === "list-pages")?.annotations
).toEqual({ readOnlyHint: true, openWorldHint: false });
expect(
listedTools.tools.find(({ name }) => name === "publish")?.annotations
).toEqual({ destructiveHint: false });
expect(
listedTools.tools.find(({ name }) => name === "list-pages")?.inputSchema
).toHaveProperty("additionalProperties", false);
expect(
listedTools.tools.find(({ name }) => name === "set-text-content")
?.inputSchema
).toMatchObject({
oneOf: [
{
properties: {
operation: { type: "string", const: "set" },
instanceId: { type: "string" },
text: { type: "string" },
},
required: ["operation", "instanceId", "text"],
},
{
properties: {
operation: { type: "string", const: "reset" },
instanceId: { type: "string" },
},
required: ["operation", "instanceId"],
},
],
});
expect(
listedTools.tools.find(({ name }) => name === "list-css-variables")
?.inputSchema.properties
).toMatchObject({
withUsage: { type: "boolean" },
verbose: { type: "boolean" },
});
expect(listedTools).toEqual({
tools: expect.arrayContaining([
expect.objectContaining({
name: "list-pages",
annotations: { readOnlyHint: true, openWorldHint: false },
}),
expect.objectContaining({
name: "publish",
annotations: { destructiveHint: false },
}),
expect.objectContaining({
name: "meta.index",
annotations: { readOnlyHint: true, openWorldHint: false },
}),
expect.objectContaining({
name: "components.coverage-status",
annotations: { readOnlyHint: true, openWorldHint: false },
}),
expect.objectContaining({
name: "refresh",
annotations: { destructiveHint: false, openWorldHint: false },
}),
expect.objectContaining({
name: "reset-session",
annotations: { destructiveHint: false, openWorldHint: false },
}),
expect.objectContaining({
name: "delete-instance",
annotations: { openWorldHint: false },
}),
]),
});
expect(
listedTools.tools.find(({ name }) => name === "list-pages")
).not.toHaveProperty("outputSchema");
expect(
listedTools.tools.find(({ name }) => name === "list-pages")
).not.toHaveProperty("_meta");
expect(
listedTools.tools.filter(
({ description }) =>
typeof description !== "string" || description.trim() === ""
)
).toEqual([]);
expect(
JSON.stringify(
listedTools.tools.find(({ name }) => name === "list-pages")
?.inputSchema
)
).not.toContain('"description"');
expect(
getSchemaProperties(
listedTools.tools.find(({ name }) => name === "list-pages")
?.inputSchema
).includeFolders
).toEqual({ type: "boolean" });
expect(
getSchemaProperties(
listedTools.tools.find(({ name }) => name === "audit")?.inputSchema
)
).toEqual({ verbose: { type: "boolean" } });
expect(
getSchemaProperties(
listedTools.tools.find(({ name }) => name === "define-css-variable")
?.inputSchema
).overwrite
).toEqual({ type: "boolean" });
expect(
getSchemaProperties(
listedTools.tools.find(({ name }) => name === "delete-css-variable")
?.inputSchema
).force
).toEqual({ type: "boolean" });
expect(
getSchemaProperties(
listedTools.tools.find(({ name }) => name === "list-instances")
?.inputSchema
).maxDepth
).toBeUndefined();
expect(
getSchemaProperties(
listedTools.tools.find(({ name }) => name === "publish")?.inputSchema
)
).toEqual({});
const updatePageInputSchema = listedTools.tools.find(
({ name }) => name === "update-page"
)?.inputSchema;
expect(getSchemaProperties(updatePageInputSchema).values).toEqual({
type: "object",
});
await expect(client.listResources()).resolves.toEqual({
resources: expect.arrayContaining([
expect.objectContaining({ uri: "webstudio://project/status" }),
expect.objectContaining({
uri: "webstudio://project/tools-overview",
}),
expect.objectContaining({ uri: "webstudio://project/tools" }),
expect.objectContaining({
uri: "webstudio://project/components-overview",
}),
expect.objectContaining({
uri: "webstudio://project/components",
}),
]),
});
} finally {
await close();
}
});
test("exposes underscore-only tool names and maps calls to canonical names", async () => {
const executeOperation = createExecuteOperation();
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
toolNameFormat: "underscores",
});
const { client, close } = await createConnectedClient(server);
try {
const listedTools = await client.listTools();
expect(listedTools.tools).toEqual(
expect.arrayContaining([
expect.objectContaining({ name: "meta_index" }),
expect.objectContaining({ name: "components_coverage_plan" }),
expect.objectContaining({ name: "list_pages" }),
])
);
expect(
listedTools.tools.every(({ name }) => /^[a-zA-Z0-9_]+$/.test(name))
).toBe(true);
await client.callTool({ name: "list_pages", arguments: {} });
expect(executeOperation).toHaveBeenCalledWith(
expect.objectContaining({ command: "list-pages" })
);
} finally {
await close();
}
});
test("exposes dry-run and destructive confirmation through stdio MCP", async () => {
const transaction = {
id: "stdio-delete-plan",
payload: [
{
namespace: "instances" as const,
patches: [{ op: "remove" as const, path: ["target"] }],
},
],
};
const executeOperation = createExecuteOperation(async ({ dryRun }) =>
createEnvelope({
operationId: "instances.delete",
source: dryRun ? "dry-run" : "remote",
result: { deletedInstanceIds: ["target"] },
state: { committed: dryRun === false, freshness: {} },
...(dryRun ? { transaction } : {}),
})
);
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
const { client, close } = await createConnectedClient(server);
try {
const tools = await client.listTools();
const deleteTool = tools.tools.find(
({ name }) => name === "delete-instance"
);
expect(deleteTool).toMatchObject({
inputSchema: {
properties: expect.objectContaining({
dryRun: expect.objectContaining({ type: "boolean" }),
confirmDestructive: expect.objectContaining({ type: "boolean" }),
confirmationToken: expect.objectContaining({ type: "string" }),
}),
},
});
expect(deleteTool?.annotations).toEqual({ openWorldHint: false });
expect(
tools.tools.find(({ name }) => name === "move-instance")
).toMatchObject({
inputSchema: {
properties: expect.objectContaining({
dryRun: expect.objectContaining({ type: "boolean" }),
}),
},
});
expect(
tools.tools.find(({ name }) => name === "move-instance")?.annotations
).toEqual({ destructiveHint: false, openWorldHint: false });
expect(
getSchemaProperties(
tools.tools.find(({ name }) => name === "publish")?.inputSchema
)
).not.toHaveProperty("dryRun");
const planned = await client.callTool({
name: "delete-instance",
arguments: { instanceIds: ["target"] },
});
const plannedContent = planned.structuredContent as
| {
ok: boolean;
error?: { code: string };
meta: { confirmation?: { token: string } };
}
| undefined;
expect(plannedContent).toMatchObject({
ok: false,
error: { code: "DESTRUCTIVE_CONFIRMATION_REQUIRED" },
});
const confirmation = plannedContent?.meta.confirmation;
if (confirmation === undefined) {
throw new Error("Expected stdio destructive confirmation");
}
const committed = await client.callTool({
name: "delete-instance",
arguments: {
instanceIds: ["target"],
confirmDestructive: true,
confirmationToken: confirmation.token,
},
});
expect(committed.structuredContent).toMatchObject({
ok: true,
meta: { session: { committed: true } },
});
} finally {
await close();
}
});
test("keeps one MCP SDK connection healthy across repeated reads and mutations", async () => {
const executeOperation = createExecuteOperation(async ({ command }) =>
createEnvelope({
operationId: command === "list-pages" ? "pages.list" : "pages.update",
result: command === "list-pages" ? { pages: [] } : { pageId: "home" },
})
);
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
});
const { client, close } = await createConnectedClient(server);
try {
for (let index = 0; index < 50; index += 1) {
const read = await client.callTool({
name: "list-pages",
arguments: {},
});
expect(read.isError).not.toBe(true);
const mutation = await client.callTool({
name: "update-page",
arguments: {
pageId: "home",
values: { title: `Session title ${index}` },
},
});
expect(mutation.isError).not.toBe(true);
}
expect(executeOperation).toHaveBeenCalledTimes(100);
} finally {
await close();
}
});
test("recovers stdio transport after an idle partial JSON-RPC frame", async () => {
const stdin = new PassThrough();
const stdout = new PassThrough();
const transport = await createMcpStdioTransport({
stdin,
stdout,
partialFrameTimeoutMs: 10,
});
const messages: unknown[] = [];
const errors: Error[] = [];
transport.onmessage = (message) => messages.push(message);
transport.onerror = (error) => errors.push(error);
await transport.start();
stdin.write('{"jsonrpc":"2.0","id":1,"method":"tools/call"');
await new Promise((resolve) => setTimeout(resolve, 20));
stdin.write(
`${JSON.stringify({ jsonrpc: "2.0", id: 2, method: "ping" })}\n`
);
await new Promise((resolve) => setTimeout(resolve, 0));
expect(messages).toEqual([{ jsonrpc: "2.0", id: 2, method: "ping" }]);
expect(errors).toEqual([]);
await transport.close();
});
test("sends sparse protocol-native startup logging after initialization", async () => {
const onInitialized = vi.fn();
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
onInitialized,
});
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
const client = new Client({ name: "test-client", version: "1.0.0" });
const logs: unknown[] = [];
client.setNotificationHandler(
LoggingMessageNotificationSchema,
(notification) => {
logs.push(notification.params);
}
);
await Promise.all([
server.connect(serverTransport),
client.connect(clientTransport),
]);
try {
expect(client.getServerCapabilities()).toEqual(
expect.objectContaining({ logging: {} })
);
expect(logs).toEqual([
{
level: "info",
logger: "webstudio",
data: expect.stringContaining("ready with"),
},
]);
expect(onInitialized).toHaveBeenCalledOnce();
expect(onInitialized).toHaveBeenCalledWith("test-client");
} finally {
await client.close();
await server.close();
}
});
test("sends sparse protocol-native tool lifecycle logging", async () => {
const onToolSuccess = vi.fn();
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(async () =>
createEnvelope({
operationId: "pages.list",
result: [{ id: "home" }],
})
),
onToolSuccess,
});
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
const client = new Client({ name: "test-client", version: "1.0.0" });
const logs: unknown[] = [];
client.setNotificationHandler(
LoggingMessageNotificationSchema,
(notification) => {
logs.push(notification.params);
}
);
await Promise.all([
server.connect(serverTransport),
client.connect(clientTransport),
]);
try {
await client.callTool({
name: "list-pages",
arguments: { includeFolders: true },
});
expect(logs).toEqual(
expect.arrayContaining([
{
level: "info",
logger: "webstudio",
data: "tool list-pages started",
},
{
level: "info",
logger: "webstudio",
data: expect.stringMatching(/^tool list-pages succeeded in \d+ms$/),
},
])
);
expect(onToolSuccess).toHaveBeenCalledWith("list-pages", {
includeFolders: true,
});
} finally {
await client.close();
await server.close();
}
});
test("returns schema-valid rendered failures and stores their artifact manifest through the server", async () => {
const onToolSuccess = vi.fn();
const onToolFailure = vi.fn();
const storeRenderedAuditArtifacts = vi.fn(async () => "/manifest.json");
const executeOperation = createExecuteOperation(async ({ command }) => {
if (command === "list-pages") {
return createEnvelope({
operationId: "pages.list",
result: { pages: [{ id: "home", path: "/" }] },
});
}
if (command === "list-breakpoints") {
return createEnvelope({
operationId: "breakpoints.list",
result: { breakpoints: [] },
});
}
return createEnvelope({
operationId: "project.audit",
result: {
contractVersion: 2,
projectVersion: 7,
scopes: ["accessibility"],
pageFilter: null,
summary: {
total: 0,
bySeverity: { error: 0, warning: 0, info: 0 },
byScope: { accessibility: 0 },
},
verbose: true,
findings: [],
skippedCheckCount: 0,
skippedChecks: [],
manualCheckCount: 1,
manualChecks: [{ checkId: "responsive-visual-review" }],
renderedCheckCount: 0,
renderedIssueCount: 0,
renderedFailureCount: 0,
renderedChecks: [],
renderedFailures: [],
nextCursor: null,
},
});
});
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
startPreview: vi.fn(async () => {
throw new Error("preview build failed");
}),
getPreviewStatus: vi.fn(),
stopPreview: vi.fn(),
captureScreenshot: vi.fn(),
storeRenderedAuditArtifacts,
onToolSuccess,
onToolFailure,
});
const { client, close } = await createConnectedClient(server);
try {
const result = await client.callTool({
name: "audit",
arguments: { rendered: true, verbose: true },
});
expect(onToolSuccess).not.toHaveBeenCalledWith(
"audit",
expect.anything()
);
expect(onToolFailure).toHaveBeenCalledWith(
"audit",
expect.objectContaining({ code: "RENDERED_AUDIT_FAILED" }),
expect.any(Number),
{ rendered: true, verbose: true }
);
expect(result).toMatchObject({
isError: true,
structuredContent: {
ok: false,
error: { code: "RENDERED_AUDIT_FAILED" },
data: { renderedFailureCount: 1 },
},
});
expect(storeRenderedAuditArtifacts).toHaveBeenCalledWith(
expect.objectContaining({
projectId: "project-1",
projectVersion: 1,
failures: [
expect.objectContaining({
code: "RENDERED_AUDIT_PREVIEW_START_FAILED",
}),
],
})
);
} finally {
await close();
}
});
test("sends visible fallback and heartbeat logs for long-running tools", async () => {
const reportLog = vi.fn();
const executeOperation = createExecuteOperation(
async () =>
await new Promise<ProjectSessionEnvelope>((resolve) => {
setTimeout(() => {
resolve(
createEnvelope({
operationId: "pages.list",
result: [{ id: "home" }],
})
);
}, 25);
})
);
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
reportLog,
toolHeartbeatIntervalMs: 5,
});
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
const client = new Client({ name: "test-client", version: "1.0.0" });
const logs: unknown[] = [];
client.setNotificationHandler(
LoggingMessageNotificationSchema,
(notification) => {
logs.push(notification.params);
}
);
await Promise.all([
server.connect(serverTransport),
client.connect(clientTransport),
]);
try {
await client.callTool({
name: "list-pages",
arguments: { includeFolders: true },
});
expect(logs).toEqual(
expect.arrayContaining([
{
level: "info",
logger: "webstudio",
data: expect.stringMatching(
/^tool list-pages still running after \d+ms$/
),
},
])
);
expect(reportLog).toHaveBeenCalledWith(
"info",
expect.stringMatching(/^tool list-pages still running after \d+ms$/)
);
expect(reportLog).toHaveBeenCalledWith(
"info",
expect.stringMatching(/^tool list-pages succeeded in \d+ms$/)
);
} finally {
await client.close();
await server.close();
}
});
test("does not crash when a tool heartbeat outlives its MCP connection", async () => {
let finishOperation: ((value: ProjectSessionEnvelope) => void) | undefined;
const reportLog = vi.fn();
const executeOperation = createExecuteOperation(
async () =>
await new Promise<ProjectSessionEnvelope>((resolve) => {
finishOperation = resolve;
})
);
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation,
reportLog,
toolHeartbeatIntervalMs: 5,
});
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
const client = new Client({ name: "test-client", version: "1.0.0" });
await Promise.all([
server.connect(serverTransport),
client.connect(clientTransport),
]);
try {
const pending = client
.callTool({ name: "list-pages", arguments: { includeFolders: true } })
.catch(() => undefined);
await vi.waitFor(() => expect(finishOperation).toBeTypeOf("function"));
const countHeartbeats = () =>
reportLog.mock.calls.filter(
([, message]) =>
typeof message === "string" &&
message.startsWith("tool list-pages still running after ")
).length;
const beforeDisconnect = countHeartbeats();
await client.close();
await vi.waitFor(() =>
expect(countHeartbeats()).toBeGreaterThan(beforeDisconnect)
);
finishOperation?.(
createEnvelope({ operationId: "pages.list", result: [] })
);
await pending;
} finally {
await server.close();
}
});
test("reports logging notification failure while MCP remains connected", async () => {
const reportLog = vi.fn();
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
reportLog,
});
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
const client = new Client({ name: "test-client", version: "1.0.0" });
await Promise.all([
server.connect(serverTransport),
client.connect(clientTransport),
]);
const sendLoggingMessage = vi
.spyOn(server, "sendLoggingMessage")
.mockRejectedValue(new Error("transport failed"));
try {
await client.callTool({
name: "list-pages",
arguments: { includeFolders: true },
});
await vi.waitFor(() =>
expect(reportLog).toHaveBeenCalledWith(
"error",
"MCP logging notification failed"
)
);
expect(sendLoggingMessage).toHaveBeenCalled();
} finally {
sendLoggingMessage.mockRestore();
await client.close();
await server.close();
}
});
test("marks visual verification tools with side-effect-aware SDK annotations", async () => {
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
startPreview: vi.fn(async () => ({
url: "http://127.0.0.1:5173/",
running: true,
mode: "iterative" as const,
})),
getPreviewStatus: vi.fn(async () => ({
url: "http://127.0.0.1:5173/",
running: true,
mode: "iterative" as const,
})),
captureScreenshot: vi.fn(async () => ({
output: "current.png",
browserPath: "/usr/bin/chromium",
browser: "chromium" as const,
viewport: { width: 1440, height: 900 },
fullPage: false,
elapsedMs: 1,
warnings: [],
})),
diffScreenshots: vi.fn(async () => ({
totalPixels: 0,
differentPixels: 0,
mismatchPercentage: 0,
summary: "Screenshot diff summary",
regions: [],
textAnalysis: {
status: "skipped" as const,
provider: "tesseract" as const,
changes: [],
},
warnings: [],
})),
installOcr: vi.fn(async () => ({
installed: false,
alreadyAvailable: true,
tesseractPath: "/usr/bin/tesseract",
installUrl: tesseractInstallUrl,
warnings: [],
})),
});
const { client, close } = await createConnectedClient(server);
try {
await expect(client.listTools()).resolves.toEqual({
tools: expect.arrayContaining([
expect.objectContaining({
name: "preview.start",
annotations: { destructiveHint: false },
}),
expect.objectContaining({
name: "preview.status",
annotations: {
readOnlyHint: true,
},
}),
expect.objectContaining({
name: "preview.stop",
annotations: { destructiveHint: false },
}),
expect.objectContaining({
name: "screenshot",
annotations: { destructiveHint: false },
}),
expect.objectContaining({
name: "screenshot.diff",
annotations: { destructiveHint: false },
}),
expect.objectContaining({
name: "vision.install-ocr",
annotations: { destructiveHint: false },
}),
]),
});
} finally {
await close();
}
});
test("handles SDK tool calls and resource reads", async () => {
const session = createSession({
initialize: vi.fn(async () =>
createEnvelope({
operationId: "project-session.status",
result: { loaded: true },
})
),
refresh: vi.fn(),
reset: vi.fn(),
});
const executeOperation: ExecuteOperation = vi.fn(async () =>
createEnvelope({
operationId: "pages.list",
result: [{ id: "home" }],
})
);
const importProject = vi.fn(async () => ({ imported: true as const }));
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(session),
executeOperation,
importProject,
});
const { client, close } = await createConnectedClient(server);
try {
await expect(
client.callTool({
name: "list-pages",
arguments: { includeFolders: true, dryRun: true },
})
).resolves.toEqual(
expect.objectContaining({
structuredContent: expect.objectContaining({
ok: true,
data: [{ id: "home" }],
}),
})
);
expect(executeOperation).toHaveBeenCalledWith({
command: "list-pages",
input: { includeFolders: true },
dryRun: true,
});
await client.callTool({
name: "list-pages",
arguments: { includeFolders: true, dryRun: false },
});
expect(executeOperation).toHaveBeenLastCalledWith({
command: "list-pages",
input: { includeFolders: true },
dryRun: false,
});
await expect(
client.callTool({
name: "import",
arguments: {
to: "https://p-destination.wstd.dev/?authToken=token",
},
})
).resolves.toEqual(
expect.objectContaining({
structuredContent: expect.objectContaining({
data: { imported: true },
}),
})
);
expect(importProject).toHaveBeenCalledWith({
to: "https://p-destination.wstd.dev/?authToken=token",
assetsDir: undefined,
ignoreVersionCheck: false,
skipAssets: false,
});
await expect(
client.readResource({ uri: "webstudio://project/status" })
).resolves.toEqual({
contents: [
expect.objectContaining({
uri: "webstudio://project/status",
mimeType: "application/json",
}),
],
});
} finally {
await close();
}
});
test("returns actionable structured screenshot failures", async () => {
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
captureScreenshot: vi.fn(async () => {
throw Object.assign(new Error("Chromium executable was not found"), {
issues: [
{
code: "browser_ipc_permission_denied",
path: [],
message:
"The operating system denied browser IPC or socket access.",
constraint: "stage:browser-startup",
},
],
});
}),
});
const { client, close } = await createConnectedClient(server);
try {
const result = await client.callTool({
name: "screenshot",
arguments: { url: "https://example.com" },
});
expect(result).toMatchObject({
isError: true,
structuredContent: {
ok: false,
error: {
code: "SCREENSHOT_CAPTURE_FAILED",
message: expect.stringContaining("preview.status"),
issues: [
{
code: "browser_ipc_permission_denied",
path: [],
constraint: "stage:browser-startup",
},
],
},
},
});
} finally {
await close();
}
});
test("returns stable SDK tool errors from resolver", async () => {
const error = new Error(
"Project session snapshot changed on disk."
) as Error & { code: string };
error.code = "PROJECT_SESSION_BUSY";
const onToolFailure = vi.fn();
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(async () => {
throw error;
}),
getErrorCode: (error) =>
typeof error === "object" && error !== null && "code" in error
? (error as { code?: string }).code
: undefined,
onToolFailure,
});
const { client, close } = await createConnectedClient(server);
try {
await expect(
client.callTool({
name: "list-pages",
arguments: {},
})
).resolves.toEqual(
expect.objectContaining({
isError: true,
structuredContent: {
ok: false,
error: {
message: projectSessionBusyMessage,
code: "PROJECT_SESSION_BUSY",
},
meta: {},
},
})
);
expect(onToolFailure).toHaveBeenCalledWith(
"list-pages",
error,
expect.any(Number),
{}
);
await client.callTool({
name: "list-instances",
arguments: { rootInstanceId: "instance-1" },
});
expect(onToolFailure).toHaveBeenCalledWith(
"list-instances",
error,
expect.any(Number),
{ rootInstanceId: "instance-1" }
);
await client.callTool({
name: "customer/project",
arguments: {},
});
expect(onToolFailure.mock.calls.at(-1)?.[0]).toBe("unknown");
} finally {
await close();
}
});
test("waits for failure diagnostics persistence before returning the tool error", async () => {
const error = new Error("operation failed");
let finishPersistence: () => void = () => undefined;
let callbackStarted = false;
let callbackFinished = false;
const persistence = new Promise<void>((resolve) => {
finishPersistence = resolve;
});
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(async () => {
throw error;
}),
onToolFailure: async () => {
callbackStarted = true;
await persistence;
callbackFinished = true;
},
});
const { client, close } = await createConnectedClient(server);
try {
let callFinished = false;
const call = client
.callTool({ name: "list-pages", arguments: {} })
.finally(() => {
callFinished = true;
});
await vi.waitFor(() => expect(callbackStarted).toBe(true));
expect(callbackFinished).toBe(false);
expect(callFinished).toBe(false);
finishPersistence();
await call;
expect(callbackFinished).toBe(true);
} finally {
finishPersistence();
await close();
}
});
test("returns expected input examples for SDK zod tool errors", async () => {
const inputSchema = z.object({
email: z.email(),
description: z.string().min(10),
});
const parseResult = inputSchema.safeParse({
email: "invalid",
description: "short",
});
if (parseResult.success) {
throw new Error("Expected invalid test input");
}
const server = await createProjectSessionMcpServer({
operations: [
...publicMcpOperations,
{
...publicMcpOperations[0]!,
command: "constrained-input",
inputSchema: getTestInputSchema(inputSchema),
},
],
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(async () => {
throw parseResult.error;
}),
});
const { client, close } = await createConnectedClient(server);
try {
const result = await client.callTool({
name: "constrained-input",
arguments: { email: "invalid", description: "short" },
});
expect(result).toEqual(
expect.objectContaining({
isError: true,
structuredContent: {
ok: false,
error: {
message: expect.stringContaining(
'email: Invalid email address (format:email). Example: "[email protected]".'
),
code: "INVALID_INPUT",
issues: expect.arrayContaining([
expect.objectContaining({
path: ["email"],
message: expect.any(String),
example: "[email protected]",
}),
expect.objectContaining({
path: ["description"],
message: expect.any(String),
example: "stringxxxx",
}),
]),
},
meta: {},
},
})
);
} finally {
await close();
}
});
test("returns all input shape errors through the MCP server", async () => {
const executeOperation = createExecuteOperation();
const createPageOperation = publicOperation({
command: "create-page",
id: "pages.create",
description: "Create a page",
method: "mutation",
inputSchema: getTestInputSchema(
z.object({ name: z.string(), path: z.string() })
),
});
const server = await createProjectSessionMcpServer({
operations: [...publicMcpOperations, createPageOperation],
createProjectSession: createSessionFactory(),
executeOperation,
});
const { client, close } = await createConnectedClient(server);
try {
const result = await client.callTool({
name: "create-page",
arguments: { name: 42, unexpected: true },
});
expect(result.structuredContent).toMatchObject({
ok: false,
error: {
code: "INVALID_INPUT",
issues: [
expect.objectContaining({ path: ["path"], constraint: "required" }),
expect.objectContaining({
path: ["name"],
constraint: "type:string",
}),
expect.objectContaining({ path: ["unexpected"] }),
],
},
});
expect(executeOperation).not.toHaveBeenCalled();
} finally {
await close();
}
});
test("returns every Markdown upload input error through the MCP server", async () => {
const executeOperation = createExecuteOperation();
const uploadAssetsOperation = publicOperation({
command: "upload-assets",
id: "assets.uploadMany",
description: "Upload Assets",
method: "mutation",
inputSchema: getTestInputSchema(
z.object({
assets: z.array(
z.object({
name: z.string(),
type: z.string(),
format: z.string().optional(),
})
),
assetsDir: z.string().optional(),
})
),
});
const server = await createProjectSessionMcpServer({
operations: [...publicMcpOperations, uploadAssetsOperation],
createProjectSession: createSessionFactory(),
executeOperation,
});
const { client, close } = await createConnectedClient(server);
try {
const result = await client.callTool({
name: "upload-assets",
arguments: {
assets: [
{ name: 42, type: "file", format: "md" },
{ name: "page.mdx", type: "image", format: "md" },
],
unexpected: true,
},
});
expect(result.structuredContent).toMatchObject({
ok: false,
error: {
code: "INVALID_INPUT",
issues: expect.arrayContaining([
expect.objectContaining({
path: ["assets", "0", "name"],
constraint: "type:string",
}),
expect.objectContaining({
path: ["assets", "1", "format"],
code: "asset_filename_format_mismatch",
}),
expect.objectContaining({
path: ["assets", "1", "type"],
code: "markdown_asset_type_mismatch",
}),
expect.objectContaining({ path: ["unexpected"] }),
]),
},
});
expect(executeOperation).not.toHaveBeenCalled();
} finally {
await close();
}
});
test("returns every Asset content update input error through the MCP server", async () => {
const executeOperation = createExecuteOperation();
const baseInputSchema = getTestInputSchema(
z.object({
assetId: z.string().min(1),
expectedName: z.string().min(1),
extension: z.string().min(1).optional(),
path: z.string().min(1).optional(),
content: z.string().optional(),
})
);
const updateAssetContentOperation = publicOperation({
command: "update-asset-content",
id: "assets.updateContent",
description: "Update Asset content",
method: "mutation",
inputSchema: {
...baseInputSchema,
oneOf: [{ required: ["path"] }, { required: ["content"] }],
},
});
const server = await createProjectSessionMcpServer({
operations: [...publicMcpOperations, updateAssetContentOperation],
createProjectSession: createSessionFactory(),
executeOperation,
});
const { client, close } = await createConnectedClient(server);
try {
const result = await client.callTool({
name: "update-asset-content",
arguments: {
assetId: 42,
expectedName: "",
path: "article.md",
content: "# Duplicate source",
unexpected: true,
},
});
expect(result.structuredContent).toMatchObject({
ok: false,
error: {
code: "INVALID_INPUT",
issues: expect.arrayContaining([
expect.objectContaining({
path: ["assetId"],
constraint: "type:string",
}),
expect.objectContaining({
path: ["expectedName"],
constraint: "minLength:1",
}),
expect.objectContaining({
path: [],
constraint: "exactly_one_of:path|content",
}),
expect.objectContaining({ path: ["unexpected"] }),
]),
},
});
expect(executeOperation).not.toHaveBeenCalled();
} finally {
await close();
}
});
test("returns equivalent structured runtime validation issues", async () => {
const issue = {
code: "invalid_expression",
path: ["values", "title"],
message: "Invalid Webstudio expression",
constraint: "valid_webstudio_expression",
example: 'pageTitle ?? "Pricing"',
detail: "Unexpected token at 1:4",
};
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(async () => {
throw new BuilderRuntimeError(
"INVALID_INPUT",
"Page input is invalid.",
{
issues: [issue],
}
);
}),
});
const { client, close } = await createConnectedClient(server);
try {
const result = await client.callTool({
name: "list-pages",
arguments: {},
});
expect(result.structuredContent).toEqual({
ok: false,
error: {
code: "INVALID_INPUT",
message:
'Page input is invalid.\nvalues.title: Invalid Webstudio expression (valid_webstudio_expression). Example: "pageTitle ?? \\"Pricing\\"". Detail: Unexpected token at 1:4',
issues: [issue],
},
meta: {},
});
} finally {
await close();
}
});
test("returns an INVALID_INPUT breakpoint hint through MCP", async () => {
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
});
const { client, close } = await createConnectedClient(server);
try {
const result = await client.callTool({
name: "update-styles",
arguments: {
updates: [
{
instanceId: "body",
breakpointId: "mobile",
property: "display",
value: { type: "keyword", value: "block" },
},
],
},
});
expect(result.structuredContent).toEqual({
ok: false,
error: {
code: "INVALID_INPUT",
message: expect.stringContaining("use breakpoint instead"),
issues: [
expect.objectContaining({
path: ["updates", "0", "breakpointId"],
constraint: "field:breakpoint",
}),
],
},
meta: {},
});
} finally {
await close();
}
});
test("allows reads but blocks mutations until a required checkpoint is acknowledged", async () => {
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(),
getErrorCode: (error) =>
typeof error === "object" && error !== null && "code" in error
? (error as { code?: string }).code
: undefined,
});
const { client, close } = await createConnectedClient(server);
try {
const coveragePlan = await client.callTool({
name: "components.coverage-plan",
arguments: {},
});
expect(coveragePlan.structuredContent).toEqual(
expect.objectContaining({
data: expect.objectContaining({
checkpoint: expect.objectContaining({ required: true }),
}),
})
);
await expect(
client.callTool({
name: "components.find",
arguments: { brief: "button" },
})
).resolves.toEqual(
expect.objectContaining({
structuredContent: expect.objectContaining({ ok: true }),
})
);
await expect(
client.callTool({
name: "create-page",
arguments: { name: "Blocked", path: "/blocked" },
})
).resolves.toEqual(
expect.objectContaining({
isError: true,
structuredContent: expect.objectContaining({
ok: false,
error: expect.objectContaining({
message: expect.stringContaining("CHECKPOINT_REQUIRED"),
code: "CHECKPOINT_REQUIRED",
}),
}),
})
);
await expect(
client.callTool({
name: "checkpoint.ack",
arguments: {
reported: true,
continueAfterReport: true,
summary: "reported checkpoint",
},
})
).resolves.toEqual(
expect.objectContaining({
structuredContent: expect.objectContaining({
data: {
acknowledged: true,
summary: "reported checkpoint",
nextCommand:
'node packages/cli/local.js workflow.next \'{"goal":"design-system-page","phase":"page-creation"}\'',
},
}),
})
);
await expect(
client.callTool({
name: "components.find",
arguments: { brief: "button" },
})
).resolves.toEqual(
expect.objectContaining({
structuredContent: expect.objectContaining({ ok: true }),
})
);
} finally {
await close();
}
});
test("creates a complete project session MCP server", async () => {
const server = await createProjectSessionMcpServer({
operations: publicMcpOperations,
createProjectSession: createSessionFactory(),
executeOperation: createExecuteOperation(async () =>
createEnvelope({
operationId: "pages.list",
result: [{ id: "home" }],
})
),
});
const { client, close } = await createConnectedClient(server);
try {
await expect(
client.callTool({
name: "list-pages",
arguments: {},
})
).resolves.toEqual(
expect.objectContaining({
structuredContent: expect.objectContaining({
data: [{ id: "home" }],
}),
})
);
} finally {
await close();
}
});
});