blockwerk-mcp 0.1.0 → 0.1.1

package/dist/index.js

@@ -18,18 +18,21 @@ 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(/\/$/, '');
+let 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);
+    console.error('[BlockWerk MCP] Warning: No session ID provided at startup.\n' +
+        'Use the "configure_bridge" tool to set the session ID at runtime.');
 }
 // ── Relay communication ───────────────────────────────────────────────────────
 const MAX_WAIT_MS = 60000; // total wait before giving up
 async function callBlockWerk(name, input) {
+    if (!SESSION_ID) {
+        throw new Error('Session ID not configured. Please provide your BlockWerk Session ID first using the "configure_bridge" tool.');
+    }
     const requestId = crypto.randomUUID();
     // 1. Push command to relay
     const pushRes = await fetch(`${RELAY_URL}?session=${SESSION_ID}&type=command`, {
@@ -62,6 +65,19 @@ const server = new McpServer({
     version: '0.1.0',
 });
 // ── Tools ─────────────────────────────────────────────────────────────────────
+server.tool('configure_bridge', 'Connects this AI assistant to a specific BlockWerk browser session.', {
+    sessionId: z.string().describe('The Session ID from the BlockWerk UI (e.g. bw-a1b2c3d4)'),
+}, async ({ sessionId }) => {
+    SESSION_ID = sessionId;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Bridge configured successfully! Now connected to session: ${SESSION_ID}`,
+            },
+        ],
+    };
+});
 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', {}) }],
 }));
@@ -69,19 +85,37 @@ server.tool('get_available_blocks', 'Lists all available block types with their
     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']),
+    commands: z
+        .array(z.object({
+        type: z.enum([
+            'add_block',
+            'connect_blocks',
+            'update_params',
+            'delete_block',
+            'tidy_layout',
+            'clear_canvas',
+        ]),
         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'),
+        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'),
+        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 }) }],
 }));
@@ -104,7 +138,17 @@ server.tool('connect_blocks', 'Connects an output port of one block to an input
     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 }) }],
+    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'),
@@ -125,4 +169,4 @@ server.tool('load_diagram', 'Loads a complete BlockWerk project from a JSON stri
 // ── Start ─────────────────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error(`[BlockWerk MCP] Connected — session: ${SESSION_ID}, relay: ${RELAY_URL}`);
+console.error(`[BlockWerk MCP] Started — session: ${SESSION_ID || 'PENDING'}, relay: ${RELAY_URL}`);

package/package.json

@@ -1,26 +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"
-  }
-}
+{
+  "name": "blockwerk-mcp",
+  "version": "0.1.1",
+  "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

@@ -22,17 +22,19 @@ const getArg = (flag: string) => {
   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(/\/$/, '');
+let 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".',
+    '[BlockWerk MCP] Warning: No session ID provided at startup.\n' +
+      'Use the "configure_bridge" tool to set the session ID at runtime.'
   );
-  process.exit(1);
 }
 
 // ── Relay communication ───────────────────────────────────────────────────────
@@ -40,6 +42,11 @@ if (!SESSION_ID) {
 const MAX_WAIT_MS = 60000; // total wait before giving up
 
 async function callBlockWerk(name: string, input: Record<string, unknown>): Promise<string> {
+  if (!SESSION_ID) {
+    throw new Error(
+      'Session ID not configured. Please provide your BlockWerk Session ID first using the "configure_bridge" tool.'
+    );
+  }
   const requestId = crypto.randomUUID();
 
   // 1. Push command to relay
@@ -59,7 +66,7 @@ async function callBlockWerk(name: string, input: Record<string, unknown>): Prom
 
   while (Date.now() < deadline) {
     const pollRes = await fetch(
-      `${RELAY_URL}?session=${SESSION_ID}&type=result&requestId=${requestId}`,
+      `${RELAY_URL}?session=${SESSION_ID}&type=result&requestId=${requestId}`
     );
 
     if (!pollRes.ok) {
@@ -76,7 +83,7 @@ async function callBlockWerk(name: string, input: Record<string, unknown>): Prom
   }
 
   throw new Error(
-    'BlockWerk did not respond within 60 seconds. Is the browser tab open and the MCP bridge active?',
+    'BlockWerk did not respond within 60 seconds. Is the browser tab open and the MCP bridge active?'
   );
 }
 
@@ -89,13 +96,32 @@ const server = new McpServer({
 
 // ── Tools ─────────────────────────────────────────────────────────────────────
 
+server.tool(
+  'configure_bridge',
+  'Connects this AI assistant to a specific BlockWerk browser session.',
+  {
+    sessionId: z.string().describe('The Session ID from the BlockWerk UI (e.g. bw-a1b2c3d4)'),
+  },
+  async ({ sessionId }) => {
+    SESSION_ID = sessionId;
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Bridge configured successfully! Now connected to session: ${SESSION_ID}`,
+        },
+      ],
+    };
+  }
+);
+
 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(
@@ -104,30 +130,50 @@ server.tool(
   {},
   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'),
+    commands: z
+      .array(
+        z.object({
+          type: z.enum([
+            'add_block',
+            'connect_blocks',
+            'update_params',
+            'delete_block',
+            'tidy_layout',
+            'clear_canvas',
+          ]),
+          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(
@@ -136,7 +182,7 @@ server.tool(
   {},
   async () => ({
     content: [{ type: 'text', text: await callBlockWerk('tidy_layout', {}) }],
-  }),
+  })
 );
 
 server.tool(
@@ -145,7 +191,7 @@ server.tool(
   {},
   async () => ({
     content: [{ type: 'text', text: await callBlockWerk('clear_canvas', {}) }],
-  }),
+  })
 );
 
 server.tool(
@@ -158,7 +204,7 @@ server.tool(
   },
   async ({ type, x, y }) => ({
     content: [{ type: 'text', text: await callBlockWerk('add_block', { type, x, y }) }],
-  }),
+  })
 );
 
 server.tool(
@@ -171,8 +217,18 @@ server.tool(
     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 }) }],
-  }),
+    content: [
+      {
+        type: 'text',
+        text: await callBlockWerk('connect_blocks', {
+          fromBlockId,
+          fromPortId,
+          toBlockId,
+          toPortId,
+        }),
+      },
+    ],
+  })
 );
 
 server.tool(
@@ -184,7 +240,7 @@ server.tool(
   },
   async ({ blockId, params }) => ({
     content: [{ type: 'text', text: await callBlockWerk('update_params', { blockId, params }) }],
-  }),
+  })
 );
 
 server.tool(
@@ -195,7 +251,7 @@ server.tool(
   },
   async ({ blockId }) => ({
     content: [{ type: 'text', text: await callBlockWerk('delete_block', { blockId }) }],
-  }),
+  })
 );
 
 server.tool(
@@ -206,11 +262,11 @@ server.tool(
   },
   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}`);
+console.error(`[BlockWerk MCP] Started — session: ${SESSION_ID || 'PENDING'}, relay: ${RELAY_URL}`);

package/tsconfig.json

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