what-devtools-mcp 0.6.0

package/README.md

@@ -0,0 +1,223 @@
+# what-devtools-mcp
+
+AI-powered debugging for What Framework apps. Lets Claude Code, Cursor, Windsurf, and other AI agents inspect your app's live state — signals, effects, components, errors — in real time.
+
+> **What is MCP?** [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that lets AI coding assistants call tools in external systems. This package exposes your app's runtime state as MCP tools that your AI assistant can call while helping you debug.
+
+## Architecture
+
+```
+Browser (What App + devtools)  ──WebSocket:9229──▶  Node.js Process
+                                                     ├── WS Bridge (state + events)
+                                                     └── MCP Server (stdio) ◀── Claude Code / Cursor
+```
+
+## Install
+
+```bash
+npm install --save-dev what-devtools what-devtools-mcp
+```
+
+## Setup
+
+### Step 1: Add the Vite plugin
+
+```js
+// vite.config.js
+import what from 'what-compiler/vite';
+import whatDevToolsMCP from 'what-devtools-mcp/vite-plugin';
+
+export default {
+  plugins: [what(), whatDevToolsMCP()],
+};
+```
+
+The plugin auto-injects the devtools client in dev mode only (`apply: 'serve'`). It never runs during `vite build`.
+
+### Step 2: Configure your AI tool
+
+**Claude Code** — add to `.claude/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "what-devtools": {
+      "command": "npx",
+      "args": ["what-devtools-mcp"]
+    }
+  }
+}
+```
+
+**Cursor** — add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "what-devtools": {
+      "command": "npx",
+      "args": ["what-devtools-mcp"]
+    }
+  }
+}
+```
+
+**Other MCP clients** — any client that supports stdio transport can connect with:
+
+```
+command: npx what-devtools-mcp
+```
+
+### Step 3: Start your app
+
+```bash
+npm run dev
+# In another terminal (or your AI tool starts it automatically):
+# The MCP server runs via your AI tool's MCP config — no manual start needed.
+```
+
+You should see in the browser console:
+```
+⚡ What DevTools MCP  Client v0.1.0
+MCP  Connecting to bridge on ws://localhost:9229
+MCP  🟢 Connected to bridge — AI agent can now inspect this app
+MCP  Sent initial snapshot — 5 signals, 3 effects, 2 components
+```
+
+## What Can Your AI Do Now?
+
+Here's a real debugging session with Claude Code:
+
+```
+You:    "The counter isn't updating when I click the button"
+
+Claude: Let me check your app's reactive state.
+        [calls what_signals { filter: "count" }]
+
+        I can see signal 'count' exists with value 0. Let me watch
+        what happens when you click.
+        [calls what_watch { duration: 5000, filter: "signal:updated" }]
+
+        No signal updates detected in 5 seconds. The click handler
+        isn't writing to the signal. Let me check the component.
+        [calls what_dom_inspect { componentId: 2 }]
+
+        Found it — the button's onclick calls increment() but that
+        function uses count.peek() instead of count.set(). peek()
+        reads without triggering reactivity. Here's the fix...
+```
+
+The AI sees your app's internals in real time — no console.log, no breakpoints, no guesswork.
+
+## Available Tools
+
+### Read Tools (inspect state)
+
+| Tool | Description |
+|------|-------------|
+| `what_connection_status` | Check if browser is connected, get counts |
+| `what_signals` | List signals with values. Filter by name regex or ID |
+| `what_effects` | List effects with deps, run counts, timing. Filter by name or dep signal |
+| `what_components` | List mounted components. Filter by name |
+| `what_snapshot` | Full state snapshot (signals + effects + components + errors) |
+| `what_errors` | Runtime errors with effect context and stack traces |
+| `what_cache` | SWR/useQuery cache entries. Filter by key |
+| `what_component_tree` | Hierarchical component tree with parent-child relationships |
+| `what_dependency_graph` | Reactive dependency graph — which signals feed which effects |
+| `what_dom_inspect` | See a component's rendered DOM output |
+| `what_route` | Current route info (path, params, query, matched pattern) |
+
+### Write Tools (modify state)
+
+| Tool | Description |
+|------|-------------|
+| `what_set_signal` | Set a signal's value and see what changes |
+| `what_invalidate_cache` | Force-refresh a cache key |
+| `what_eval` | Execute arbitrary JS in the browser context |
+| `what_navigate` | Navigate to a different route |
+
+### Observe Tools (watch changes)
+
+| Tool | Description |
+|------|-------------|
+| `what_watch` | Collect reactive events over a time window |
+| `what_diff_snapshot` | Save a baseline, take action, diff the changes |
+
+### Diagnostic Tools
+
+| Tool | Description |
+|------|-------------|
+| `what_diagnose` | Multi-check diagnostic — errors, performance, reactivity in one call |
+
+## Signal Debug Names
+
+For best debugging output, add names to your signals:
+
+```js
+// Without name: shows as "signal_1" in devtools
+const count = signal(0);
+
+// With name: shows as "count" in devtools
+const count = signal(0, 'count');
+```
+
+A compiler transform to auto-inject names from variable declarations is planned.
+
+## Manual Setup (without Vite plugin)
+
+```js
+import * as core from 'what-core';
+import { installDevTools } from 'what-devtools';
+import { connectDevToolsMCP } from 'what-devtools-mcp/client';
+
+installDevTools(core);
+connectDevToolsMCP({ port: 9229 });
+```
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `WHAT_MCP_PORT` env var | `9229` | WebSocket bridge port |
+| Vite plugin `{ port }` | `9229` | Same, via plugin option |
+
+Port 9229 matches Node.js `--inspect` convention. If you're also debugging Node.js, set a different port:
+
+```js
+whatDevToolsMCP({ port: 9230 })
+```
+
+```json
+{
+  "mcpServers": {
+    "what-devtools": {
+      "command": "npx",
+      "args": ["what-devtools-mcp"],
+      "env": { "WHAT_MCP_PORT": "9230" }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+**"No browser connected"**
+Your app isn't running or the Vite plugin isn't configured. Start your dev server and check the browser console for the MCP connection banner.
+
+**"No snapshot available"**
+The browser connected but hasn't sent state yet. Refresh the page.
+
+**WebSocket connection refused**
+Port 9229 may be in use. Check with `lsof -i :9229` and either kill the process or use a different port.
+
+**Multiple browser tabs**
+Only the most recently connected tab's state is tracked. Close extra tabs or use the one you're debugging.
+
+**Empty signal names (signal_1, signal_2)**
+Add debug names: `signal(0, 'count')`. See "Signal Debug Names" above.
+
+## WebMCP (Future)
+
+What Framework is designed to support WebMCP — running the MCP server directly in the browser, eliminating the WebSocket bridge entirely. The tool handlers are being built transport-agnostic so they can run in either Node.js or browser context.
+
+See `DESIGN.md` for the full WebMCP architecture plan.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "what-devtools-mcp",
+  "version": "0.6.0",
+  "description": "MCP server bridging AI agents to live What Framework app state via WebSocket",
+  "type": "module",
+  "bin": {
+    "what-devtools-mcp": "./src/index.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./vite-plugin": "./src/vite-plugin.js"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ws": "^8.0.0",
+    "zod": "^3.25.0"
+  },
+  "peerDependencies": {
+    "what-devtools": ">=0.6.0"
+  },
+  "keywords": [
+    "what-framework",
+    "devtools",
+    "mcp",
+    "model-context-protocol",
+    "ai-debugging"
+  ],
+  "license": "MIT"
+}

package/src/bridge.js

@@ -0,0 +1,171 @@
+/**
+ * Node.js WebSocket server + state bridge.
+ * Receives state snapshots and events from the browser client,
+ * provides query API for the MCP tools.
+ */
+
+import { WebSocketServer } from 'ws';
+
+const MAX_EVENT_LOG = 1000;
+const MAX_ERROR_LOG = 100;
+
+export function createBridge({ port = 9229 } = {}) {
+  let latestSnapshot = null;
+  const eventLog = [];
+  const errorLog = [];
+  let browserSocket = null;
+  let correlationCounter = 0;
+  const pendingCommands = new Map();
+
+  // Snapshot dedup cache (100ms)
+  let cachedSnapshot = null;
+  let cacheTime = 0;
+  const SNAPSHOT_CACHE_MS = 100;
+
+  // Baseline snapshot for diff tool
+  let baselineSnapshot = null;
+
+  const wss = new WebSocketServer({ port });
+
+  wss.on('connection', (ws) => {
+    browserSocket = ws;
+
+    ws.on('message', (raw) => {
+      let msg;
+      try { msg = JSON.parse(raw); } catch { return; }
+
+      switch (msg.type) {
+        case 'snapshot':
+          latestSnapshot = msg.data;
+          break;
+        case 'event':
+          eventLog.push({ event: msg.event, data: msg.data, timestamp: Date.now() });
+          if (eventLog.length > MAX_EVENT_LOG) eventLog.shift();
+          // Track errors separately
+          if (msg.event === 'error:captured') {
+            errorLog.push({ ...msg.data, timestamp: Date.now() });
+            if (errorLog.length > MAX_ERROR_LOG) errorLog.shift();
+          }
+          break;
+        case 'events':
+          for (const item of msg.batch || []) {
+            eventLog.push({ event: item.event, data: item.data, timestamp: Date.now() });
+            if (eventLog.length > MAX_EVENT_LOG) eventLog.shift();
+            if (item.event === 'error:captured') {
+              errorLog.push({ ...item.data, timestamp: Date.now() });
+              if (errorLog.length > MAX_ERROR_LOG) errorLog.shift();
+            }
+          }
+          break;
+        case 'response': {
+          const pending = pendingCommands.get(msg.correlationId);
+          if (pending) {
+            pendingCommands.delete(msg.correlationId);
+            pending.resolve(msg.data);
+          }
+          break;
+        }
+      }
+    });
+
+    ws.on('close', () => {
+      if (browserSocket === ws) browserSocket = null;
+      // Reject all pending commands
+      for (const [id, pending] of pendingCommands) {
+        pending.reject(new Error('Browser disconnected'));
+        pendingCommands.delete(id);
+      }
+    });
+  });
+
+  function isConnected() {
+    return browserSocket !== null && browserSocket.readyState === 1; // WebSocket.OPEN
+  }
+
+  function sendCommand(command, args = {}, timeout = 5000) {
+    return new Promise((resolve, reject) => {
+      if (!isConnected()) {
+        return reject(new Error('No browser connected'));
+      }
+      const correlationId = `cmd_${++correlationCounter}`;
+      const timer = setTimeout(() => {
+        pendingCommands.delete(correlationId);
+        reject(new Error(`Command '${command}' timed out after ${timeout}ms`));
+      }, timeout);
+
+      pendingCommands.set(correlationId, {
+        resolve: (data) => { clearTimeout(timer); resolve(data); },
+        reject: (err) => { clearTimeout(timer); reject(err); },
+      });
+
+      browserSocket.send(JSON.stringify({ command, correlationId, args }));
+    });
+  }
+
+  async function refreshSnapshot() {
+    const data = await sendCommand('get-snapshot');
+    latestSnapshot = data;
+    return data;
+  }
+
+  async function getOrRefreshSnapshot() {
+    const now = Date.now();
+    if (cachedSnapshot && now - cacheTime < SNAPSHOT_CACHE_MS) return cachedSnapshot;
+    try {
+      cachedSnapshot = await refreshSnapshot();
+      cacheTime = now;
+      return cachedSnapshot;
+    } catch {
+      return latestSnapshot;
+    }
+  }
+
+  async function getCacheSnapshot() {
+    return sendCommand('get-cache');
+  }
+
+  function getSnapshot() {
+    return latestSnapshot;
+  }
+
+  function saveBaseline() {
+    baselineSnapshot = latestSnapshot ? JSON.parse(JSON.stringify(latestSnapshot)) : null;
+    return !!baselineSnapshot;
+  }
+
+  function getBaseline() {
+    return baselineSnapshot;
+  }
+
+  function getEvents(since) {
+    if (since) return eventLog.filter(e => e.timestamp > since);
+    return eventLog.slice();
+  }
+
+  function getErrors(since) {
+    if (since) return errorLog.filter(e => e.timestamp > since);
+    return errorLog.slice();
+  }
+
+  function close() {
+    for (const [id, pending] of pendingCommands) {
+      pending.reject(new Error('Bridge closing'));
+      pendingCommands.delete(id);
+    }
+    wss.close();
+  }
+
+  return {
+    getSnapshot,
+    getOrRefreshSnapshot,
+    getEvents,
+    getErrors,
+    isConnected,
+    sendCommand,
+    refreshSnapshot,
+    getCacheSnapshot,
+    saveBaseline,
+    getBaseline,
+    close,
+  };
+}

package/src/client-commands.js

@@ -0,0 +1,206 @@
+/**
+ * Extended command handlers for the browser client.
+ * Handles: eval, dom-inspect, get-route, navigate
+ *
+ * Usage in client.js:
+ *   import { handleExtendedCommand } from './client-commands.js';
+ *
+ *   // Inside handleCommand(), before the default case:
+ *   const extResult = handleExtendedCommand(command, args, devtools);
+ *   if (extResult !== null) { result = extResult; break; }
+ */
+
+/**
+ * Handle extended commands sent from the MCP server via the bridge.
+ *
+ * @param {string} command - The command name
+ * @param {object} args - Command arguments
+ * @param {object|null} devtools - window.__WHAT_DEVTOOLS__ reference
+ * @returns {object|null} Result object, or null if command not handled
+ */
+export function handleExtendedCommand(command, args, devtools) {
+  switch (command) {
+
+    // -------------------------------------------------------------------------
+    // eval — Execute arbitrary JS in the browser context
+    // -------------------------------------------------------------------------
+    case 'eval': {
+      const start = performance.now();
+      try {
+        // Use Function constructor to execute in global scope
+        // eslint-disable-next-line no-new-func
+        const fn = new Function(args.code);
+        const raw = fn();
+        const elapsed = performance.now() - start;
+        return {
+          result: devtools?.safeSerialize ? devtools.safeSerialize(raw) : raw,
+          type: typeof raw,
+          executionTime: Math.round(elapsed * 100) / 100,
+        };
+      } catch (e) {
+        return {
+          error: e.message,
+          stack: e.stack,
+        };
+      }
+    }
+
+    // -------------------------------------------------------------------------
+    // dom-inspect — Serialize a component's rendered DOM
+    // -------------------------------------------------------------------------
+    case 'dom-inspect': {
+      const { componentId, depth = 3 } = args || {};
+      const registries = devtools?._registries;
+
+      if (!registries?.components) {
+        return { error: 'DevTools registries not available' };
+      }
+
+      const entry = registries.components.get(componentId);
+      if (!entry) {
+        return { error: `Component ${componentId} not found` };
+      }
+
+      const el = entry.element;
+      if (!el) {
+        return { error: `Component "${entry.name}" (id: ${componentId}) has no DOM element` };
+      }
+
+      /**
+       * Recursively serialize a DOM node into a plain object.
+       * Respects the max depth limit to avoid huge payloads.
+       */
+      function serializeDOM(node, currentDepth) {
+        if (currentDepth > depth) {
+          return { tag: '...', text: '(truncated)' };
+        }
+
+        // Text node
+        if (node.nodeType === 3) {
+          const text = node.textContent?.trim() || '';
+          if (!text) return null; // skip empty text nodes
+          return { text };
+        }
+
+        // Skip non-element, non-text nodes (comments, etc.)
+        if (node.nodeType !== 1) return null;
+
+        const result = {
+          tag: node.tagName.toLowerCase(),
+        };
+
+        // Include common identifying attributes
+        if (node.id) result.id = node.id;
+        if (node.className && typeof node.className === 'string') {
+          result.class = node.className;
+        }
+
+        // Include data attributes (often useful for debugging)
+        const dataAttrs = {};
+        for (const attr of node.attributes) {
+          if (attr.name.startsWith('data-')) {
+            dataAttrs[attr.name] = attr.value;
+          }
+        }
+        if (Object.keys(dataAttrs).length > 0) {
+          result.dataAttributes = dataAttrs;
+        }
+
+        // Recurse into children
+        const children = [];
+        for (const child of node.childNodes) {
+          const serialized = serializeDOM(child, currentDepth + 1);
+          if (serialized && (serialized.tag || serialized.text)) {
+            children.push(serialized);
+          }
+        }
+        if (children.length) result.children = children;
+
+        return result;
+      }
+
+      const structure = serializeDOM(el, 0);
+      // Cap HTML to 5000 chars to prevent huge payloads
+      const html = el.innerHTML?.substring(0, 5000) || '';
+
+      return {
+        componentName: entry.name,
+        componentId,
+        html,
+        structure,
+      };
+    }
+
+    // -------------------------------------------------------------------------
+    // get-route — Return current route information
+    // -------------------------------------------------------------------------
+    case 'get-route': {
+      const loc = typeof window !== 'undefined' ? window.location : {};
+      const result = {
+        path: loc.pathname || '/',
+        query: Object.fromEntries(new URLSearchParams(loc.search || '')),
+        hash: loc.hash || '',
+        fullUrl: loc.href || '',
+      };
+
+      // Try to get What Router state if available
+      try {
+        const core = window.__WHAT_CORE__;
+        if (core?.routerState) {
+          const state = typeof core.routerState === 'function'
+            ? core.routerState()
+            : core.routerState;
+          if (state) {
+            result.params = state.params || {};
+            result.matchedRoute = state.pattern || state.route || null;
+          }
+        }
+      } catch {
+        // Router state not available — that's fine, we have window.location
+      }
+
+      return result;
+    }
+
+    // -------------------------------------------------------------------------
+    // navigate — Programmatically change the route
+    // -------------------------------------------------------------------------
+    case 'navigate': {
+      const { path, replace } = args || {};
+
+      if (!path) {
+        return { error: 'No path provided' };
+      }
+
+      try {
+        // Prefer What Router's navigate() if available
+        const core = window.__WHAT_CORE__;
+        if (core?.navigate) {
+          core.navigate(path, { replace: !!replace });
+        } else if (replace) {
+          history.replaceState(null, '', path);
+          window.dispatchEvent(new PopStateEvent('popstate'));
+        } else {
+          history.pushState(null, '', path);
+          window.dispatchEvent(new PopStateEvent('popstate'));
+        }
+
+        return {
+          navigatedTo: path,
+          currentPath: window.location.pathname,
+          method: replace ? 'replaceState' : 'pushState',
+          usedWhatRouter: !!(core?.navigate),
+          success: true,
+        };
+      } catch (e) {
+        return { error: e.message };
+      }
+    }
+
+    // -------------------------------------------------------------------------
+    // Not handled — return null so caller falls through
+    // -------------------------------------------------------------------------
+    default:
+      return null;
+  }
+}