Skip to content

Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.

fix: support Cursor-compatible MCP tool names (#5961)

Oleg Isonene210fedc022f
diff --git a/packages/cli/src/commands/connect.test.ts b/packages/cli/src/commands/connect.test.ts
index 6c025bfeb5..710c295099 100644
--- a/packages/cli/src/commands/connect.test.ts
+++ b/packages/cli/src/commands/connect.test.ts
@@ -166,7 +166,24 @@ test("writes the cursor config into .cursor/mcp.json", async () => {
expect(dependencies.writeFileAtomic).toHaveBeenCalledWith(
join(cwd(), ".cursor", "mcp.json"),
- expect.stringContaining('"mcpServers"')
+ `${JSON.stringify(
+ {
+ mcpServers: {
+ webstudio: {
+ command: "npx",
+ args: [
+ "-y",
+ "webstudio@latest",
+ "mcp",
+ "--tool-name-format",
+ "underscores",
+ ],
+ },
+ },
+ },
+ null,
+ 2
+ )}\n`
);
});
diff --git a/packages/cli/src/commands/connect.ts b/packages/cli/src/commands/connect.ts
index 70e70aa84b..16de601bc7 100644
--- a/packages/cli/src/commands/connect.ts
+++ b/packages/cli/src/commands/connect.ts
@@ -68,6 +68,19 @@ const createServerEntry = (
serverFields?: Record<string, unknown>
) => ({ ...serverFields, ...serverCommand });
+const addClientServerArgs = (
+ client: ConnectClient,
+ serverCommand: ServerCommand
+): ServerCommand => {
+ if (client !== "cursor") {
+ return serverCommand;
+ }
+ return {
+ ...serverCommand,
+ args: [...serverCommand.args, "--tool-name-format", "underscores"],
+ };
+};
+
const getCodexRegistrationArgs = ({ command, args }: ServerCommand) => [
"mcp",
"add",
@@ -266,7 +279,10 @@ export const connect = async (
return;
}
- const parsedServerCommand = parseServerCommand(serverCommand);
+ const parsedServerCommand = addClientServerArgs(
+ client,
+ parseServerCommand(serverCommand)
+ );
if (client === "codex") {
if (options.print === true) {
diff --git a/packages/cli/src/commands/mcp.test.ts b/packages/cli/src/commands/mcp.test.ts
index 484c708c5e..5c3b639cb6 100644
--- a/packages/cli/src/commands/mcp.test.ts
+++ b/packages/cli/src/commands/mcp.test.ts
@@ -174,6 +174,13 @@ test("documents MCP stdio startup and discovery tools", () => {
"project",
expect.objectContaining({ type: "string" })
);
+ expect(yargs.option).toHaveBeenCalledWith(
+ "tool-name-format",
+ expect.objectContaining({
+ choices: ["canonical", "underscores"],
+ default: "canonical",
+ })
+ );
expect(yargs.example).toHaveBeenCalledWith(
"$0 mcp",
diff --git a/packages/cli/src/commands/mcp.ts b/packages/cli/src/commands/mcp.ts
index 972ee7fab7..c65bde9672 100644
--- a/packages/cli/src/commands/mcp.ts
+++ b/packages/cli/src/commands/mcp.ts
@@ -344,6 +344,13 @@ export const mcpOptions = (yargs: CommonYargsArgv) =>
describe:
"Saved project id to use without changing this directory's linked project",
})
+ .option("tool-name-format", {
+ type: "string",
+ choices: ["canonical", "underscores"] as const,
+ default: "canonical" as const,
+ describe:
+ "Format exposed MCP tool names for clients with stricter naming rules",
+ })
.command(
["list-tools"],
"Print the concise MCP tool catalog as JSON",
@@ -1638,7 +1645,12 @@ export const mcpReadResource = async (options: McpReadResourceOptions) => {
}
};
-export const mcp = async (options: { project?: string } = {}) => {
+export const mcp = async (
+ options: {
+ project?: string;
+ toolNameFormat?: "canonical" | "underscores";
+ } = {}
+) => {
const status = createMcpStatusReporter();
let didReportClose = false;
const reportClose = () => {
@@ -1659,6 +1671,7 @@ export const mcp = async (options: { project?: string } = {}) => {
status.ready(toolCount);
const server = await connectProjectSessionMcpServer({
...host,
+ toolNameFormat: options.toolNameFormat,
getErrorCode: getStableErrorCode,
reportLog: (_level, message) => {
reportLog(message);
diff --git a/packages/project-build/src/mcp.test.ts b/packages/project-build/src/mcp.test.ts
index 5fe43761dd..65b0a90463 100644
--- a/packages/project-build/src/mcp.test.ts
+++ b/packages/project-build/src/mcp.test.ts
@@ -7320,6 +7320,39 @@ describe("project session mcp adapter", () => {
}
});
+ 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",
diff --git a/packages/project-build/src/mcp.ts b/packages/project-build/src/mcp.ts
index 46fc72bd3b..6de3094a6e 100644
--- a/packages/project-build/src/mcp.ts
+++ b/packages/project-build/src/mcp.ts
@@ -7907,11 +7907,13 @@ export const createProjectSessionMcpServer = async <
restorePoints,
onProjectSessionChange,
onInitialized,
+ toolNameFormat = "canonical",
toolHeartbeatIntervalMs = 10_000,
}: Omit<ProjectSessionMcpCoreOptions<Command>, "reportToolProgress"> & {
getErrorCode?: McpErrorCodeResolver;
reportLog?: (level: McpLogLevel, message: string) => void;
onInitialized?: (clientName: string | undefined) => void;
+ toolNameFormat?: "canonical" | "underscores";
toolHeartbeatIntervalMs?: number;
}) => {
const server = new Server(
@@ -7953,6 +7955,27 @@ export const createProjectSessionMcpServer = async <
sendLog("info", message);
},
});
+ const exposedTools = core.listTools().map((tool) => ({
+ ...tool,
+ name:
+ toolNameFormat === "underscores"
+ ? tool.name.replace(/[^a-zA-Z0-9_]/g, "_")
+ : tool.name,
+ }));
+ const canonicalToolNameByExposedName = new Map<string, string>();
+ for (const [index, tool] of core.listTools().entries()) {
+ const exposedName = exposedTools[index]?.name;
+ if (exposedName === undefined) {
+ continue;
+ }
+ const existingName = canonicalToolNameByExposedName.get(exposedName);
+ if (existingName !== undefined && existingName !== tool.name) {
+ throw new Error(
+ `MCP tool names ${existingName} and ${tool.name} both map to ${exposedName}.`
+ );
+ }
+ canonicalToolNameByExposedName.set(exposedName, tool.name);
+ }
server.oninitialized = () => {
onInitialized?.(server.getClientVersion()?.name);
@@ -7963,7 +7986,7 @@ export const createProjectSessionMcpServer = async <
};
server.setRequestHandler(ListToolsRequestSchema, async () => ({
- tools: core.listTools().map(toSdkTool),
+ tools: exposedTools.map(toSdkTool),
}));
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
@@ -8006,7 +8029,8 @@ export const createProjectSessionMcpServer = async <
server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
const params = getRequestParams(request);
- const name = typeof params.name === "string" ? params.name : "";
+ const exposedName = typeof params.name === "string" ? params.name : "";
+ const name = canonicalToolNameByExposedName.get(exposedName) ?? exposedName;
const { input, dryRun } = getToolCallInput(params.arguments ?? {});
const startedAt = Date.now();
sendLog("info", `tool ${name} started${dryRun ? " (dry run)" : ""}`);