what-devtools-mcp 0.11.7 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "what-devtools-mcp",
-  "version": "0.11.7",
+  "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-agent.js

@@ -119,6 +119,34 @@ effect(() => {
 
 // Good — stable key:
 <For each={items()}>{item => <li key={item.id}>{item.name}</li>}</For>`,
+  },
+  ERR_UNSAFE_REDIRECT: {
+    code: 'ERR_UNSAFE_REDIRECT',
+    severity: 'error',
+    diagnosis: 'redirect() was given a target that can leave your origin: a protocol-relative ("//host"), backslash-smuggled ("/\\host") or javascript:/data: URL. Reaching it from user input is an open redirect.',
+    suggestedFix: 'redirect() accepts same-origin paths and http:, https:, mailto: or tel: URLs only. Check a user-supplied target against an allowlist before passing it.',
+    codeExample: `// Bad - a user-controlled target can leave your origin:
+redirect(query.next);
+
+// Fix - allowlist the target first:
+redirect(ALLOWED.has(query.next) ? query.next : '/');`,
+  },
+  ERR_REDIRECT_NOT_CAUGHT: {
+    code: 'ERR_REDIRECT_NOT_CAUGHT',
+    severity: 'error',
+    diagnosis: 'A redirect() navigation signal surfaced as an uncaught error, so nothing performed the navigation. redirect() is caught in two places only: route middleware, and a component body. An event handler, a promise callback or a timer runs long after both, and a try/catch around the call swallows the signal.',
+    suggestedFix: 'From an event handler, a promise callback or a timer, call navigate(to) instead. If the call is inside a try/catch, rethrow anything whose name is RouterRedirect.',
+    codeExample: `// Bad - an event handler runs after the render the Router caught:
+<button onclick={() => redirect('/login')}>Sign in</button>
+
+// Fix - navigate() from a handler:
+<button onclick={() => navigate('/login')}>Sign in</button>
+
+// Fix - redirect() from a component body, which the Router catches:
+function Private() {
+  if (!user()) redirect('/login');
+  return <Secret />;
+}`,
   },
   HINT_PREFER_COMPUTED: {
     code: 'HINT_PREFER_COMPUTED',
@@ -1063,9 +1091,25 @@ export function registerAgentTools(server, bridge) {
     'what_fix',
     'Given a What Framework error code, get diagnosis, suggested fix, and code example. Works offline — no browser needed.',
     {
-      error: z.string().describe('Error code (e.g., "ERR_INFINITE_EFFECT") or error message text'),
+      error: z.string().optional().describe('Error code (e.g., "ERR_INFINITE_EFFECT") or error message text'),
+      // `errorCode` is an accepted alias, not a second parameter. Every CLAUDE.md
+      // this project has ever scaffolded documents `what_fix {errorCode}` while
+      // the schema only accepted `error`, so the tool the guide calls a "hidden
+      // gem" and tells agents to reach for FIRST returned a hard validation
+      // error. The docs are fixed, but those CLAUDE.md files are already sitting
+      // in users' repos, so the alias stays permanently.
+      errorCode: z.string().optional().describe('Alias for `error`, accepted for compatibility with older scaffolded CLAUDE.md files'),
     },
-    async ({ error: errorInput }) => {
+    async ({ error, errorCode }) => {
+      const errorInput = error ?? errorCode;
+      if (!errorInput) {
+        return {
+          content: [{
+            type: 'text',
+            text: 'what_fix needs an error code or message. Example: what_fix({ error: "ERR_INFINITE_EFFECT" }).',
+          }],
+        };
+      }
       // Try exact code match first
       let entry = ERROR_DATABASE[errorInput];
 

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 {