blockwerk-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * BlockWerk MCP Server
+ *
+ * Bridges an external AI client (Claude Desktop, Cursor) to a live BlockWerk
+ * browser tab via the Netlify relay.
+ *
+ * Usage:
+ *   npx @blockwerk/mcp --session bw-a1b2c3d4
+ *   npx @blockwerk/mcp --session bw-a1b2c3d4 --relay https://blockwerk.tech
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+// ── Config ────────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const getArg = (flag) => {
+    const i = args.indexOf(flag);
+    return i !== -1 ? args[i + 1] : undefined;
+};
+const SESSION_ID = getArg('--session') ?? process.env.BLOCKWERK_SESSION;
+const RELAY_BASE = (getArg('--relay') ?? process.env.BLOCKWERK_RELAY ?? 'https://blockwerk.tech').replace(/\/$/, '');
+const RELAY_URL = `${RELAY_BASE}/api/mcp-relay`;
+if (!SESSION_ID) {
+    console.error('Error: session ID required.\n' +
+        'Usage: npx @blockwerk/mcp --session <session-id>\n\n' +
+        'Get your session ID from blockwerk.tech → AI panel → "Connect external AI".');
+    process.exit(1);
+}
+// ── Relay communication ───────────────────────────────────────────────────────
+const MAX_WAIT_MS = 60000; // total wait before giving up
+async function callBlockWerk(name, input) {
+    const requestId = crypto.randomUUID();
+    // 1. Push command to relay
+    const pushRes = await fetch(`${RELAY_URL}?session=${SESSION_ID}&type=command`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ requestId, name, input }),
+    });
+    if (!pushRes.ok) {
+        throw new Error(`Relay rejected command: ${pushRes.status} ${await pushRes.text()}`);
+    }
+    // 2. Poll for result — relay returns after ~7s if not yet ready (pending: true)
+    //    We retry until MAX_WAIT_MS is exceeded.
+    const deadline = Date.now() + MAX_WAIT_MS;
+    while (Date.now() < deadline) {
+        const pollRes = await fetch(`${RELAY_URL}?session=${SESSION_ID}&type=result&requestId=${requestId}`);
+        if (!pollRes.ok) {
+            throw new Error(`Relay poll failed: ${pollRes.status}`);
+        }
+        const data = (await pollRes.json());
+        if (!data.pending) {
+            return typeof data.result === 'string' ? data.result : JSON.stringify(data.result);
+        }
+        // pending: true — relay timed out but result not yet ready, retry immediately
+    }
+    throw new Error('BlockWerk did not respond within 60 seconds. Is the browser tab open and the MCP bridge active?');
+}
+// ── MCP server ────────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: 'blockwerk',
+    version: '0.1.0',
+});
+// ── Tools ─────────────────────────────────────────────────────────────────────
+server.tool('describe_canvas', 'Returns a structured text description of all blocks and connections on the BlockWerk canvas.', {}, async () => ({
+    content: [{ type: 'text', text: await callBlockWerk('describe_canvas', {}) }],
+}));
+server.tool('get_available_blocks', 'Lists all available block types with their port IDs and configurable parameters.', {}, async () => ({
+    content: [{ type: 'text', text: await callBlockWerk('get_available_blocks', {}) }],
+}));
+server.tool('batch_commands', 'Executes multiple canvas operations in a single round-trip. Use handles (temporary IDs) to reference newly added blocks within the same batch. This is the preferred tool for building diagrams.', {
+    commands: z.array(z.object({
+        type: z.enum(['add_block', 'connect_blocks', 'update_params', 'delete_block', 'tidy_layout']),
+        blockType: z.string().optional().describe('Block type for add_block, e.g. PIDController'),
+        x: z.number().optional().describe('X position in pixels'),
+        y: z.number().optional().describe('Y position in pixels'),
+        handle: z.string().optional().describe('Temporary ID for this block, usable in the same batch'),
+        fromBlockId: z.string().optional().describe('Block ID or handle for connect_blocks'),
+        fromPortId: z.string().optional().describe('Output port, e.g. "out"'),
+        toBlockId: z.string().optional().describe('Block ID or handle for connect_blocks'),
+        toPortId: z.string().optional().describe('Input port, e.g. "in"'),
+        blockId: z.string().optional().describe('Block ID or handle for update_params / delete_block'),
+        params: z.record(z.unknown()).optional().describe('Parameter key-value pairs for update_params'),
+    })).describe('Ordered list of commands to execute'),
+}, async ({ commands }) => ({
+    content: [{ type: 'text', text: await callBlockWerk('batch_commands', { commands }) }],
+}));
+server.tool('tidy_layout', 'Automatically rearranges all blocks into a clean left-to-right signal flow layout.', {}, async () => ({
+    content: [{ type: 'text', text: await callBlockWerk('tidy_layout', {}) }],
+}));
+server.tool('clear_canvas', 'Removes all blocks and connections from the canvas.', {}, async () => ({
+    content: [{ type: 'text', text: await callBlockWerk('clear_canvas', {}) }],
+}));
+server.tool('add_block', 'Adds a single block to the canvas. Prefer batch_commands when adding multiple blocks.', {
+    type: z.string().describe('Block type, e.g. Integrator, PIDController, Scope'),
+    x: z.number().describe('X position in pixels (0–2000)'),
+    y: z.number().describe('Y position in pixels (0–2000)'),
+}, async ({ type, x, y }) => ({
+    content: [{ type: 'text', text: await callBlockWerk('add_block', { type, x, y }) }],
+}));
+server.tool('connect_blocks', 'Connects an output port of one block to an input port of another.', {
+    fromBlockId: z.string().describe('Source block ID'),
+    fromPortId: z.string().describe('Output port name, e.g. "out"'),
+    toBlockId: z.string().describe('Target block ID'),
+    toPortId: z.string().describe('Input port name, e.g. "in"'),
+}, async ({ fromBlockId, fromPortId, toBlockId, toPortId }) => ({
+    content: [{ type: 'text', text: await callBlockWerk('connect_blocks', { fromBlockId, fromPortId, toBlockId, toPortId }) }],
+}));
+server.tool('update_params', 'Updates parameters of a block.', {
+    blockId: z.string().describe('Block ID to update'),
+    params: z.record(z.unknown()).describe('Parameter key-value pairs, e.g. { "value": 1.0 }'),
+}, async ({ blockId, params }) => ({
+    content: [{ type: 'text', text: await callBlockWerk('update_params', { blockId, params }) }],
+}));
+server.tool('delete_block', 'Deletes a block and all its connections.', {
+    blockId: z.string().describe('Block ID to delete'),
+}, async ({ blockId }) => ({
+    content: [{ type: 'text', text: await callBlockWerk('delete_block', { blockId }) }],
+}));
+server.tool('load_diagram', 'Loads a complete BlockWerk project from a JSON string.', {
+    json: z.string().describe('JSON project data (from exportJson or a saved file)'),
+}, async ({ json }) => ({
+    content: [{ type: 'text', text: await callBlockWerk('load_diagram', { json }) }],
+}));
+// ── Start ─────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`[BlockWerk MCP] Connected — session: ${SESSION_ID}, relay: ${RELAY_URL}`);

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "blockwerk-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for BlockWerk — lets Claude Desktop and Cursor control a live BlockWerk browser tab",
+  "type": "module",
+  "bin": {
+    "blockwerk-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.15.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "~5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.ts

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * BlockWerk MCP Server
+ *
+ * Bridges an external AI client (Claude Desktop, Cursor) to a live BlockWerk
+ * browser tab via the Netlify relay.
+ *
+ * Usage:
+ *   npx @blockwerk/mcp --session bw-a1b2c3d4
+ *   npx @blockwerk/mcp --session bw-a1b2c3d4 --relay https://blockwerk.tech
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+// ── Config ────────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const getArg = (flag: string) => {
+  const i = args.indexOf(flag);
+  return i !== -1 ? args[i + 1] : undefined;
+};
+
+const SESSION_ID = getArg('--session') ?? process.env.BLOCKWERK_SESSION;
+const RELAY_BASE = (getArg('--relay') ?? process.env.BLOCKWERK_RELAY ?? 'https://blockwerk.tech').replace(/\/$/, '');
+const RELAY_URL = `${RELAY_BASE}/api/mcp-relay`;
+
+if (!SESSION_ID) {
+  console.error(
+    'Error: session ID required.\n' +
+    'Usage: npx @blockwerk/mcp --session <session-id>\n\n' +
+    'Get your session ID from blockwerk.tech → AI panel → "Connect external AI".',
+  );
+  process.exit(1);
+}
+
+// ── Relay communication ───────────────────────────────────────────────────────
+
+const MAX_WAIT_MS = 60000; // total wait before giving up
+
+async function callBlockWerk(name: string, input: Record<string, unknown>): Promise<string> {
+  const requestId = crypto.randomUUID();
+
+  // 1. Push command to relay
+  const pushRes = await fetch(`${RELAY_URL}?session=${SESSION_ID}&type=command`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ requestId, name, input }),
+  });
+
+  if (!pushRes.ok) {
+    throw new Error(`Relay rejected command: ${pushRes.status} ${await pushRes.text()}`);
+  }
+
+  // 2. Poll for result — relay returns after ~7s if not yet ready (pending: true)
+  //    We retry until MAX_WAIT_MS is exceeded.
+  const deadline = Date.now() + MAX_WAIT_MS;
+
+  while (Date.now() < deadline) {
+    const pollRes = await fetch(
+      `${RELAY_URL}?session=${SESSION_ID}&type=result&requestId=${requestId}`,
+    );
+
+    if (!pollRes.ok) {
+      throw new Error(`Relay poll failed: ${pollRes.status}`);
+    }
+
+    const data = (await pollRes.json()) as { pending?: boolean; result?: unknown };
+
+    if (!data.pending) {
+      return typeof data.result === 'string' ? data.result : JSON.stringify(data.result);
+    }
+
+    // pending: true — relay timed out but result not yet ready, retry immediately
+  }
+
+  throw new Error(
+    'BlockWerk did not respond within 60 seconds. Is the browser tab open and the MCP bridge active?',
+  );
+}
+
+// ── MCP server ────────────────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: 'blockwerk',
+  version: '0.1.0',
+});
+
+// ── Tools ─────────────────────────────────────────────────────────────────────
+
+server.tool(
+  'describe_canvas',
+  'Returns a structured text description of all blocks and connections on the BlockWerk canvas.',
+  {},
+  async () => ({
+    content: [{ type: 'text', text: await callBlockWerk('describe_canvas', {}) }],
+  }),
+);
+
+server.tool(
+  'get_available_blocks',
+  'Lists all available block types with their port IDs and configurable parameters.',
+  {},
+  async () => ({
+    content: [{ type: 'text', text: await callBlockWerk('get_available_blocks', {}) }],
+  }),
+);
+
+server.tool(
+  'batch_commands',
+  'Executes multiple canvas operations in a single round-trip. Use handles (temporary IDs) to reference newly added blocks within the same batch. This is the preferred tool for building diagrams.',
+  {
+    commands: z.array(z.object({
+      type: z.enum(['add_block', 'connect_blocks', 'update_params', 'delete_block', 'tidy_layout']),
+      blockType: z.string().optional().describe('Block type for add_block, e.g. PIDController'),
+      x: z.number().optional().describe('X position in pixels'),
+      y: z.number().optional().describe('Y position in pixels'),
+      handle: z.string().optional().describe('Temporary ID for this block, usable in the same batch'),
+      fromBlockId: z.string().optional().describe('Block ID or handle for connect_blocks'),
+      fromPortId: z.string().optional().describe('Output port, e.g. "out"'),
+      toBlockId: z.string().optional().describe('Block ID or handle for connect_blocks'),
+      toPortId: z.string().optional().describe('Input port, e.g. "in"'),
+      blockId: z.string().optional().describe('Block ID or handle for update_params / delete_block'),
+      params: z.record(z.unknown()).optional().describe('Parameter key-value pairs for update_params'),
+    })).describe('Ordered list of commands to execute'),
+  },
+  async ({ commands }) => ({
+    content: [{ type: 'text', text: await callBlockWerk('batch_commands', { commands }) }],
+  }),
+);
+
+server.tool(
+  'tidy_layout',
+  'Automatically rearranges all blocks into a clean left-to-right signal flow layout.',
+  {},
+  async () => ({
+    content: [{ type: 'text', text: await callBlockWerk('tidy_layout', {}) }],
+  }),
+);
+
+server.tool(
+  'clear_canvas',
+  'Removes all blocks and connections from the canvas.',
+  {},
+  async () => ({
+    content: [{ type: 'text', text: await callBlockWerk('clear_canvas', {}) }],
+  }),
+);
+
+server.tool(
+  'add_block',
+  'Adds a single block to the canvas. Prefer batch_commands when adding multiple blocks.',
+  {
+    type: z.string().describe('Block type, e.g. Integrator, PIDController, Scope'),
+    x: z.number().describe('X position in pixels (0–2000)'),
+    y: z.number().describe('Y position in pixels (0–2000)'),
+  },
+  async ({ type, x, y }) => ({
+    content: [{ type: 'text', text: await callBlockWerk('add_block', { type, x, y }) }],
+  }),
+);
+
+server.tool(
+  'connect_blocks',
+  'Connects an output port of one block to an input port of another.',
+  {
+    fromBlockId: z.string().describe('Source block ID'),
+    fromPortId: z.string().describe('Output port name, e.g. "out"'),
+    toBlockId: z.string().describe('Target block ID'),
+    toPortId: z.string().describe('Input port name, e.g. "in"'),
+  },
+  async ({ fromBlockId, fromPortId, toBlockId, toPortId }) => ({
+    content: [{ type: 'text', text: await callBlockWerk('connect_blocks', { fromBlockId, fromPortId, toBlockId, toPortId }) }],
+  }),
+);
+
+server.tool(
+  'update_params',
+  'Updates parameters of a block.',
+  {
+    blockId: z.string().describe('Block ID to update'),
+    params: z.record(z.unknown()).describe('Parameter key-value pairs, e.g. { "value": 1.0 }'),
+  },
+  async ({ blockId, params }) => ({
+    content: [{ type: 'text', text: await callBlockWerk('update_params', { blockId, params }) }],
+  }),
+);
+
+server.tool(
+  'delete_block',
+  'Deletes a block and all its connections.',
+  {
+    blockId: z.string().describe('Block ID to delete'),
+  },
+  async ({ blockId }) => ({
+    content: [{ type: 'text', text: await callBlockWerk('delete_block', { blockId }) }],
+  }),
+);
+
+server.tool(
+  'load_diagram',
+  'Loads a complete BlockWerk project from a JSON string.',
+  {
+    json: z.string().describe('JSON project data (from exportJson or a saved file)'),
+  },
+  async ({ json }) => ({
+    content: [{ type: 'text', text: await callBlockWerk('load_diagram', { json }) }],
+  }),
+);
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`[BlockWerk MCP] Connected — session: ${SESSION_ID}, relay: ${RELAY_URL}`);

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}