what-devtools-mcp 0.11.8 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-devtools-mcp",
-  "version": "0.11.8",
+  "version": "0.12.0",
   "description": "MCP server bridging AI agents to live What Framework app state via WebSocket",
   "type": "module",
   "bin": {

package/src/index.js

@@ -9,6 +9,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createBridge } from './bridge.js';
 import { registerTools } from './tools.js';
+import { instrumentServer } from './tool-registry.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
 
@@ -52,6 +53,10 @@ const server = new McpServer({
   version: pkg.version,
 });
 
+// Record every registration so what_connection_status can report the real
+// catalogue instead of a hand-maintained literal. Must run before any
+// register* call.
+instrumentServer(server);
 registerTools(server, bridge);
 
 // --- MCP Resources: static docs for agent context ---

package/src/tool-registry.js

@@ -0,0 +1,69 @@
+/**
+ * The single source of truth for what tools this MCP server actually exposes.
+ *
+ * `what_connection_status` is the tool CLAUDE.md tells every agent to call FIRST
+ * to orient, and it used to answer with a hand-maintained literal array of 17
+ * entries while 29 tools were registered. The product under-reported its own
+ * differentiator by 41% at the moment of first contact, and the same catalogue
+ * was hand-copied into CLAUDE.md, AGENTS.md and the docs, each free to drift.
+ *
+ * A framework whose thesis is machine-readable truth cannot hand-maintain its own
+ * machine-readable index, so the catalogue is now derived from registration by
+ * wrapping `server.tool` once before the three register* functions run.
+ */
+
+const registered = [];
+
+// Tools that answer with no browser attached. Everything else needs a live page
+// on the bridge, which is a stronger requirement than "the dev server is up" and
+// is the single most common reason an agent's first call comes back empty.
+const OFFLINE_TOOLS = new Set([
+  'what_connection_status',
+  'what_lint',
+  'what_validate',
+  'what_scaffold',
+  'what_fix',
+]);
+
+/**
+ * Wrap `server.tool` so every registration is recorded. Call once, before any
+ * register* function runs. Idempotent.
+ */
+export function instrumentServer(server) {
+  if (server.__whatToolRegistryInstalled) return server;
+  const original = server.tool.bind(server);
+  server.tool = (name, description, ...rest) => {
+    registered.push({ name, desc: description });
+    return original(name, description, ...rest);
+  };
+  server.__whatToolRegistryInstalled = true;
+  return server;
+}
+
+/** Every tool registered so far, in registration order. */
+export function getRegisteredTools() {
+  return registered.map((t) => ({ ...t }));
+}
+
+/**
+ * Split the catalogue by what can actually answer right now.
+ *
+ * No competitor's MCP server distinguishes "this tool exists" from "this tool can
+ * answer in this session", which is the distinction that actually costs an agent
+ * turns: it discovers the difference by calling and failing.
+ */
+export function describeToolAvailability(connected) {
+  const all = getRegisteredTools();
+  const offline = all.filter((t) => OFFLINE_TOOLS.has(t.name));
+  const needsBrowser = all.filter((t) => !OFFLINE_TOOLS.has(t.name));
+  return {
+    total: all.length,
+    available: connected ? all : offline,
+    requiresBrowser: connected ? [] : needsBrowser,
+  };
+}
+
+/** Test hook: drop the recorded registrations. @internal */
+export function __resetToolRegistry() {
+  registered.length = 0;
+}

package/src/tools.js

@@ -4,6 +4,7 @@
  */
 
 import { z } from 'zod';
+import { describeToolAvailability } from './tool-registry.js';
 
 export function registerTools(server, bridge) {
   // --- Helpers ---
@@ -112,26 +113,14 @@ export function registerTools(server, bridge) {
           'Make sure your app is running with the what-devtools-mcp Vite plugin',
           'Or manually call connectDevToolsMCP() in your browser console',
         ],
-        // Tool catalog so agents know what's available
-        tools: [
-          { name: 'what_components', desc: 'List mounted components with IDs' },
-          { name: 'what_signals', desc: 'List signals with values (use filter!)' },
-          { name: 'what_effects', desc: 'List effects with deps and run counts' },
-          { name: 'what_explain', desc: 'Everything about one component (signals + effects + DOM + errors)' },
-          { name: 'what_look', desc: 'Visual info without image: styles, layout, dimensions' },
-          { name: 'what_screenshot', desc: 'Cropped component screenshot (5-20KB)' },
-          { name: 'what_page_map', desc: 'Full page layout skeleton' },
-          { name: 'what_diagnose', desc: 'One-call health check (errors + perf + reactivity)' },
-          { name: 'what_errors', desc: 'Runtime errors with fix suggestions' },
-          { name: 'what_signal_trace', desc: 'Why did a signal change? Causal chain.' },
-          { name: 'what_dependency_graph', desc: 'Reactive dependency graph' },
-          { name: 'what_watch', desc: 'Observe events over a time window' },
-          { name: 'what_record_window', desc: 'Rank effects that re-ran during a recording window — what fired for this action?' },
-          { name: 'what_set_signal', desc: 'Change a signal value in the live app' },
-          { name: 'what_lint', desc: 'Static analysis for code (no browser needed)' },
-          { name: 'what_scaffold', desc: 'Generate boilerplate (no browser needed)' },
-          { name: 'what_fix', desc: 'Error diagnosis with code examples (no browser needed)' },
-        ],
+        // Tool catalogue, DERIVED from registration rather than hand-maintained.
+        // `tools` is every registered tool; `available` is the subset that can
+        // answer right now, which is the distinction that actually costs an
+        // agent turns when no browser is attached.
+        ...(() => {
+          const a = describeToolAvailability(connected);
+          return { toolCount: a.total, tools: a.available, requiresBrowser: a.requiresBrowser.map((t) => t.name) };
+        })(),
       };
 
       return {