bitwrench 2.0.21 → 2.0.23

package/src/mcp/live.js

@@ -0,0 +1,226 @@
+/**
+ * MCP live rendering -- bwserve integration for render_live, screenshot, query_dom.
+ *
+ * Starts a bwserve instance that serves a shell page. The MCP agent pushes
+ * TACO to the browser via SSE, captures screenshots, and queries DOM state.
+ *
+ * @module mcp/live
+ */
+
+import bwserve from '../bwserve/index.js';
+
+var _app = null;
+
+/**
+ * Start the bwserve live rendering server.
+ *
+ * @param {Object} opts
+ * @param {number} [opts.port=7910]
+ * @param {string} [opts.theme]
+ * @param {boolean} [opts.open=false]
+ * @returns {Promise<Object>} The bwserve app instance
+ */
+export function startLive(opts) {
+  opts = opts || {};
+  var port = opts.port || 7910;
+
+  _app = bwserve.create({
+    port: port,
+    title: 'bwmcp',
+    allowScreenshot: true,
+    theme: opts.theme || null
+  });
+
+  // Register the default page handler
+  _app.page('/', function(client) {
+    // Render an initial placeholder
+    client.render('#app', {
+      t: 'div',
+      a: { class: 'bw_container', style: 'padding: 2rem; text-align: center; color: #888;' },
+      c: { t: 'p', c: 'bwmcp ready -- waiting for agent to render UI...' }
+    });
+  });
+
+  return new Promise(function(resolve, reject) {
+    try {
+      _app.listen(function() {
+        process.stderr.write('[bwmcp] bwserve listening on http://localhost:' + port + '\n');
+
+        // Open browser if requested
+        if (opts.open) {
+          import('child_process').then(function(cp) {
+            var url = 'http://localhost:' + port;
+            var cmd = process.platform === 'darwin' ? 'open'
+              : process.platform === 'win32' ? 'start' : 'xdg-open';
+            cp.exec(cmd + ' ' + url);
+          }).catch(function() { /* ignore open failures */ });
+        }
+
+        resolve(_app);
+      });
+    } catch (e) {
+      reject(e);
+    }
+  });
+}
+
+/**
+ * Get the current bwserve app instance (for testing).
+ */
+export function getApp() {
+  return _app;
+}
+
+/**
+ * Stop the live server.
+ */
+export function stopLive() {
+  if (_app) {
+    _app.close();
+    _app = null;
+  }
+}
+
+/**
+ * Get the first connected client, or null.
+ */
+function getClient() {
+  if (!_app) return null;
+  var clients = _app._clients;
+  if (!clients) return null;
+  // _clients is a Map in bwserve
+  for (var [, record] of clients) {
+    if (record && record.client && !record.client._closed) {
+      return record.client;
+    }
+  }
+  return null;
+}
+
+// -- Live tool definitions --
+
+export var liveToolDefs = [
+  {
+    name: 'render_live',
+    title: 'Render TACO Live in Browser',
+    description: 'Push a TACO to the connected browser window via bwserve SSE. The UI appears immediately. Use action "replace" (default), "append", "patch", or "remove".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'CSS selector of target element (default: "#app")' },
+        taco:   { type: 'object', description: 'TACO object to render' },
+        action: { type: 'string', enum: ['replace', 'append', 'patch', 'remove'], description: 'Render action (default: replace)' },
+        content: { type: 'string', description: 'For patch action: new text content' },
+        attr:   { type: 'object', description: 'For patch action: attributes to update' }
+      }
+    }
+  },
+  {
+    name: 'screenshot',
+    title: 'Capture Browser Screenshot',
+    description: 'Capture a screenshot of the live browser window. Returns a base64 PNG image. Useful for iterating on UI -- render, screenshot, evaluate, adjust.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: { type: 'string', description: 'CSS selector of element to capture (default: "body")' }
+      }
+    }
+  },
+  {
+    name: 'query_dom',
+    title: 'Query DOM State',
+    description: 'Execute JavaScript in the browser and return the result. Use this to inspect DOM state, read text content, count elements, etc.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        code: { type: 'string', description: 'JavaScript code to evaluate in the browser. The return value is sent back.' }
+      },
+      required: ['code']
+    }
+  }
+];
+
+// -- Live tool handlers --
+
+export var liveHandlers = {
+  render_live: function(args) {
+    if (!_app) {
+      return { content: [{ type: 'text', text: 'Error: bwserve not started. Live rendering not available.' }], isError: true };
+    }
+    var client = getClient();
+    var target = args.target || '#app';
+    var action = args.action || 'replace';
+
+    try {
+      if (action === 'replace' && args.taco) {
+        _app.broadcast({ type: 'replace', target: target, node: args.taco });
+      } else if (action === 'append' && args.taco) {
+        _app.broadcast({ type: 'append', target: target, node: args.taco });
+      } else if (action === 'patch') {
+        _app.broadcast({ type: 'patch', target: target, content: args.content || '', attr: args.attr || null });
+      } else if (action === 'remove') {
+        _app.broadcast({ type: 'remove', target: target });
+      } else {
+        return { content: [{ type: 'text', text: 'Error: invalid action or missing taco' }], isError: true };
+      }
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ status: 'rendered', action: action, target: target, clientCount: _app.clientCount || 0 }) }],
+        structuredContent: { status: 'rendered', action: action, target: target, clientCount: _app.clientCount || 0 }
+      };
+    } catch (e) {
+      return { content: [{ type: 'text', text: 'Error: ' + e.message }], isError: true };
+    }
+  },
+
+  screenshot: function(args) {
+    var client = getClient();
+    if (!client) {
+      return Promise.resolve({
+        content: [{ type: 'text', text: 'Error: no browser client connected. Open http://localhost:' + (_app ? _app._port : 7910) + ' in a browser.' }],
+        isError: true
+      });
+    }
+
+    var selector = (args && args.selector) || 'body';
+    return client.screenshot(selector, { timeout: 10000 })
+      .then(function(result) {
+        var base64 = result.data.toString('base64');
+        return {
+          content: [{
+            type: 'image',
+            data: base64,
+            mimeType: 'image/png'
+          }]
+        };
+      })
+      .catch(function(e) {
+        return {
+          content: [{ type: 'text', text: 'Screenshot error: ' + e.message }],
+          isError: true
+        };
+      });
+  },
+
+  query_dom: function(args) {
+    var client = getClient();
+    if (!client) {
+      return Promise.resolve({
+        content: [{ type: 'text', text: 'Error: no browser client connected.' }],
+        isError: true
+      });
+    }
+
+    return client.query(args.code, { timeout: 5000 })
+      .then(function(result) {
+        var text = typeof result === 'string' ? result : JSON.stringify(result);
+        return { content: [{ type: 'text', text: text }] };
+      })
+      .catch(function(e) {
+        return {
+          content: [{ type: 'text', text: 'Query error: ' + e.message }],
+          isError: true
+        };
+      });
+  }
+};

package/src/mcp/server.js

@@ -0,0 +1,216 @@
+/**
+ * bwmcp -- MCP server for bitwrench.
+ *
+ * JSON-RPC 2.0 dispatch: initialize, notifications/initialized,
+ * tools/list, tools/call. Wires knowledge tools, component tools,
+ * utility tools, and live rendering tools together.
+ *
+ * @module mcp/server
+ */
+
+import { VERSION } from '../version.js';
+import { createStdioTransport } from './transport.js';
+import { knowledgeToolDefs, knowledgeHandlers } from './knowledge.js';
+import { componentToolDefs, utilityToolDefs, toolHandlers } from './tools.js';
+import { liveToolDefs, liveHandlers, startLive, stopLive } from './live.js';
+
+var PROTOCOL_VERSION = '2024-11-05';
+
+// Ordered tool list: knowledge first (start_here at 0), then components, then utilities, then live
+var allToolDefs = [].concat(knowledgeToolDefs, componentToolDefs, utilityToolDefs, liveToolDefs);
+
+// Merge all handlers
+var allHandlers = Object.assign({}, knowledgeHandlers, toolHandlers, liveHandlers);
+
+/**
+ * Handle a single JSON-RPC 2.0 message. Returns a response object,
+ * or null for notifications (no id).
+ *
+ * @param {Object} msg - JSON-RPC message
+ * @returns {Object|Promise<Object>|null} Response or null for notifications
+ */
+export function handleMessage(msg) {
+  var id = msg.id;
+  var method = msg.method;
+  var params = msg.params || {};
+
+  // Notification (no id) -- no response expected
+  if (id === undefined || id === null) {
+    return null;
+  }
+
+  switch (method) {
+    case 'initialize':
+      return {
+        jsonrpc: '2.0',
+        id: id,
+        result: {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: {
+            tools: { listChanged: false }
+          },
+          serverInfo: {
+            name: 'bwmcp',
+            version: VERSION,
+            description: 'Bitwrench MCP server with live browser UI. Call bitwrench_start_here first.'
+          }
+        }
+      };
+
+    case 'tools/list':
+      return {
+        jsonrpc: '2.0',
+        id: id,
+        result: {
+          tools: allToolDefs
+        }
+      };
+
+    case 'tools/call': {
+      var toolName = params.name;
+      var toolArgs = params.arguments || {};
+      var handler = allHandlers[toolName];
+      if (!handler) {
+        return {
+          jsonrpc: '2.0',
+          id: id,
+          error: { code: -32602, message: 'Unknown tool: ' + toolName }
+        };
+      }
+      try {
+        var result = handler(toolArgs);
+        // Handle async tool results (screenshot, query_dom)
+        if (result && typeof result.then === 'function') {
+          return result.then(function(r) {
+            return { jsonrpc: '2.0', id: id, result: r };
+          }).catch(function(e) {
+            return {
+              jsonrpc: '2.0',
+              id: id,
+              result: { content: [{ type: 'text', text: 'Error: ' + e.message }], isError: true }
+            };
+          });
+        }
+        return { jsonrpc: '2.0', id: id, result: result };
+      } catch (e) {
+        return {
+          jsonrpc: '2.0',
+          id: id,
+          result: { content: [{ type: 'text', text: 'Error: ' + e.message }], isError: true }
+        };
+      }
+    }
+
+    default:
+      return {
+        jsonrpc: '2.0',
+        id: id,
+        error: { code: -32601, message: 'Method not found: ' + method }
+      };
+  }
+}
+
+/**
+ * Create an MCP server with the given options.
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.port=7910] - bwserve port
+ * @param {string} [opts.theme] - Default theme
+ * @param {boolean} [opts.open=false] - Open browser on start
+ * @param {boolean} [opts.noBrowser=false] - Skip starting bwserve
+ * @returns {{ listen: Function, close: Function }}
+ */
+export function createMcpServer(opts) {
+  opts = opts || {};
+  var transport = null;
+
+  function listen() {
+    transport = createStdioTransport(function(msg) {
+      var response = handleMessage(msg);
+      if (response === null) return; // notification, no response
+      if (response && typeof response.then === 'function') {
+        response.then(function(r) { transport.send(r); });
+      } else {
+        transport.send(response);
+      }
+    });
+
+    // Start bwserve unless disabled
+    if (!opts.noBrowser) {
+      startLive({
+        port: opts.port || 7910,
+        theme: opts.theme,
+        open: opts.open || false
+      });
+    }
+
+    process.stderr.write('[bwmcp] MCP server ready (stdio)\n');
+  }
+
+  function close() {
+    if (transport) transport.close();
+    stopLive();
+  }
+
+  return { listen: listen, close: close };
+}
+
+/**
+ * CLI entry point. Parse args and start the server.
+ *
+ * @param {string[]} argv - Command-line arguments (after node and script)
+ */
+export function run(argv) {
+  argv = argv || [];
+  var opts = {
+    port: 7910,
+    theme: null,
+    open: false,
+    noBrowser: false
+  };
+
+  for (var i = 0; i < argv.length; i++) {
+    switch (argv[i]) {
+      case '--port':
+        opts.port = parseInt(argv[++i], 10) || 7910;
+        break;
+      case '--theme':
+        opts.theme = argv[++i];
+        break;
+      case '--open':
+        opts.open = true;
+        break;
+      case '--no-browser':
+        opts.noBrowser = true;
+        break;
+      case '--help':
+      case '-h':
+        process.stderr.write([
+          'Usage: bwmcp [options]',
+          '',
+          'Options:',
+          '  --port <n>      bwserve port (default: 7910)',
+          '  --theme <name>  Default theme preset',
+          '  --open          Open browser on start',
+          '  --no-browser    Skip starting bwserve (testing mode)',
+          '  --help, -h      Show this help',
+          ''
+        ].join('\n'));
+        process.exit(0);
+        break;
+    }
+  }
+
+  var server = createMcpServer(opts);
+  server.listen();
+
+  // Clean shutdown
+  process.on('SIGINT', function() {
+    server.close();
+    process.exit(0);
+  });
+  process.on('SIGTERM', function() {
+    server.close();
+    process.exit(0);
+  });
+}