what-devtools-mcp 0.6.0 → 0.7.0

package/src/tools-extended.js

@@ -1,7 +1,8 @@
 /**
  * Extended MCP tool definitions for what-devtools-mcp.
- * 8 tools: component tree, dependency graph, eval, DOM inspect,
- * route info, diagnostics, diff snapshot, navigate.
+ * 13 tools: component tree, dependency graph, eval, DOM inspect,
+ * route info, diagnostics, diff snapshot, navigate, explain, signal trace,
+ * visual inspect (what_look), page map (what_page_map), screenshot (what_screenshot).
  *
  * These supplement the 10 base tools in tools.js.
  */
@@ -114,6 +115,21 @@ export function registerExtendedTools(server, bridge) {
         byId.set(c.id, { ...c, children: [] });
       }
 
+      // Check if parentIds are available (framework may not track them)
+      const hasParentInfo = components.some(c => c.parentId != null);
+
+      if (!hasParentInfo && components.length > 1) {
+        // Framework doesn't track parent-child relationships.
+        // Infer: lowest-ID component is the root, all others are its children.
+        // This gives a 1-level tree which is better than a flat list.
+        const sorted = [...byId.values()].sort((a, b) => a.id - b.id);
+        const root = sorted[0];
+        for (let i = 1; i < sorted.length; i++) {
+          sorted[i].parentId = root.id;
+          root.children.push(sorted[i]);
+        }
+      }
+
       // Build parent-child links
       const roots = [];
       for (const node of byId.values()) {
@@ -123,6 +139,15 @@ export function registerExtendedTools(server, bridge) {
           roots.push(node);
         }
       }
+      // Deduplicate children (inferred path may have already added them)
+      for (const node of byId.values()) {
+        const seen = new Set();
+        node.children = node.children.filter(c => {
+          if (seen.has(c.id)) return false;
+          seen.add(c.id);
+          return true;
+        });
+      }
 
       // Attach signal/effect counts per component
       const signals = snapshot.signals || [];
@@ -328,7 +353,17 @@ export function registerExtendedTools(server, bridge) {
         const id = Number(idStr);
         if (type === 'signal') {
           const s = signalMap.get(id);
-          nodes.push({ type: 'signal', id, name: s?.name || `signal_${id}`, value: s?.value });
+          // Truncate values to avoid token waste — graph topology is what matters
+          const raw = s?.value;
+          let value;
+          if (raw == null) value = raw;
+          else if (typeof raw === 'string') value = raw.length > 80 ? raw.slice(0, 80) + '…' : raw;
+          else if (Array.isArray(raw)) value = `Array(${raw.length})`;
+          else if (typeof raw === 'object') {
+            const json = JSON.stringify(raw);
+            value = json.length > 80 ? json.slice(0, 80) + '…' : raw;
+          } else value = raw;
+          nodes.push({ type: 'signal', id, name: s?.name || `signal_${id}`, value });
         } else {
           const e = effectMap.get(id);
           nodes.push({ type: 'effect', id, name: e?.name || `effect_${id}`, runCount: e?.runCount });
@@ -352,14 +387,39 @@ export function registerExtendedTools(server, bridge) {
   // Tool 3 — what_eval
   // ---------------------------------------------------------------------------
 
+  // Guard: eval only works when explicitly enabled via --unsafe-eval flag or
+  // WHAT_UNSAFE_EVAL=1 environment variable. Disabled by default.
+  const unsafeEvalEnabled = process.argv.includes('--unsafe-eval') ||
+    process.env.WHAT_UNSAFE_EVAL === '1' ||
+    process.env.WHAT_UNSAFE_EVAL === 'true';
+
   server.tool(
     'what_eval',
-    'Execute JavaScript in the browser context. Has access to window, document, __WHAT_DEVTOOLS__, and __WHAT_CORE__. Use for debugging scenarios not covered by other tools. Dev-only.',
+    'WARNING: Executes ARBITRARY JavaScript in the browser context. This is a security-sensitive tool that can run any code with full access to window, document, __WHAT_DEVTOOLS__, and __WHAT_CORE__. Disabled by default — must be explicitly enabled with --unsafe-eval flag or WHAT_UNSAFE_EVAL=1 env var. Use for debugging scenarios not covered by other tools. Dev-only.',
     {
       code: z.string().describe('JavaScript code to execute in the browser. Return a value to see it in the response.'),
       timeout: z.number().optional().default(5000).describe('Max execution time in ms (default: 5000, max: 30000)'),
     },
     async ({ code, timeout }) => {
+      // Allow safe read-only property access without the unsafe flag
+      const trimmed = (code || '').trim();
+      const isSafeRead = /^[\w.[\]'"]+$/.test(trimmed) && !trimmed.includes('=') ||
+        /^document\.(title|URL|readyState|visibilityState|characterSet|contentType)$/.test(trimmed) ||
+        /^window\.(innerWidth|innerHeight|devicePixelRatio|outerWidth|outerHeight)$/.test(trimmed) ||
+        /^navigator\.(userAgent|language|platform|onLine|hardwareConcurrency)$/.test(trimmed) ||
+        /^location\.(href|hostname|pathname|protocol|port|origin)$/.test(trimmed) ||
+        /^screen\.(width|height|availWidth|availHeight|colorDepth)$/.test(trimmed);
+
+      if (!unsafeEvalEnabled && !isSafeRead) {
+        return errorResponse(
+          'what_eval is disabled for arbitrary code. Safe read-only expressions (document.title, window.innerWidth, etc.) work without the flag.',
+          [
+            'Safe expressions: document.title, window.innerWidth, navigator.userAgent, location.href, screen.width',
+            'For full eval, start the MCP server with --unsafe-eval or WHAT_UNSAFE_EVAL=1',
+          ]
+        );
+      }
+
       if (!bridge.isConnected()) return noConnection('what_eval');
 
       const clampedTimeout = Math.min(Math.max(timeout || 5000, 100), 30000);
@@ -735,16 +795,23 @@ export function registerExtendedTools(server, bridge) {
         ? 'No changes detected since baseline.'
         : parts.join(', ') + '.';
 
+      // Cap large lists to save tokens — show count + sample
+      const cap = (arr, limit = 10) => arr.length <= limit ? arr : {
+        count: arr.length,
+        sample: arr.slice(0, limit),
+        truncated: arr.length - limit,
+      };
+
       return ok({
         action: 'diff',
         signalsChanged,
-        signalsAdded,
-        signalsRemoved,
+        signalsAdded: cap(signalsAdded),
+        signalsRemoved: cap(signalsRemoved),
         effectsTriggered,
-        effectsAdded,
-        effectsRemoved,
-        componentsAdded,
-        componentsRemoved,
+        effectsAdded: cap(effectsAdded),
+        effectsRemoved: cap(effectsRemoved),
+        componentsAdded: cap(componentsAdded),
+        componentsRemoved: cap(componentsRemoved),
         errorsNew: errorsNew.length,
         totalChanges,
         summary,
@@ -786,4 +853,335 @@ export function registerExtendedTools(server, bridge) {
       }
     }
   );
+
+  // ---------------------------------------------------------------------------
+  // Tool 9 — what_explain
+  // ---------------------------------------------------------------------------
+
+  server.tool(
+    'what_explain',
+    'Get a complete picture of a component: its signals with values, effects with deps and run counts, rendered DOM, and any errors. The "tell me everything about this component" tool.',
+    {
+      componentId: z.number().describe('Component ID to explain (from what_components)'),
+      includeDOM: z.boolean().optional().default(true).describe('Include rendered DOM output (default: true)'),
+      domDepth: z.number().optional().default(2).describe('Max DOM depth if includeDOM is true (default: 2)'),
+    },
+    async ({ componentId, includeDOM, domDepth }) => {
+      const { snapshot, err } = await freshSnapshot('what_explain');
+      if (err) return err;
+
+      const components = snapshot.components || [];
+      const comp = components.find(c => c.id === componentId);
+      if (!comp) {
+        return errorResponse(`Component ${componentId} not found.`, ['Use what_components to list available IDs.']);
+      }
+
+      // Signals belonging to this component
+      const signals = (snapshot.signals || []).filter(s => s.componentId === componentId);
+
+      // Effects belonging to this component
+      const signalMap = new Map((snapshot.signals || []).map(s => [s.id, s]));
+      const effects = (snapshot.effects || []).filter(e => e.componentId === componentId).map(e => ({
+        ...e,
+        depSignalNames: (e.depSignalIds || []).map(sid => signalMap.get(sid)?.name || `signal_${sid}`),
+      }));
+
+      // DOM output (if requested and bridge connected)
+      let dom = null;
+      if (includeDOM) {
+        try {
+          const domResult = await bridge.sendCommand('dom-inspect', { componentId, depth: domDepth || 2 });
+          if (!domResult.error) dom = { html: (domResult.html || '').substring(0, 2000), structure: domResult.structure };
+        } catch {}
+      }
+
+      // Errors associated with this component
+      const errors = bridge.getErrors().filter(e => e.componentId === componentId || e.component === comp.name);
+
+      // Build summary
+      const sigPreview = signals.slice(0, 5).map(s => {
+        const val = JSON.stringify(s.value);
+        return `${s.name}=${val && val.length > 30 ? val.slice(0, 27) + '...' : val}`;
+      }).join(', ');
+      const effPreview = effects.slice(0, 3).map(e => `${e.name || 'effect_' + e.id} (ran ${e.runCount || 0}x)`).join(', ');
+
+      // Add source file hint based on component name
+      const sourceHint = `Component source files are typically in the same directory as the app entry point. Use file search to find: ${comp.name}`;
+
+      const summary = `${comp.name}: ${signals.length} signals (${sigPreview || 'none'}), ` +
+        `${effects.length} effects (${effPreview || 'none'})` +
+        (errors.length ? `, ${errors.length} errors` : '') +
+        (dom ? `, DOM: ${(dom.html || '').substring(0, 80)}...` : '') +
+        `. ${sourceHint}`;
+
+      return ok({
+        summary,
+        component: { id: comp.id, name: comp.name, parentId: comp.parentId },
+        sourceHint,
+        signals,
+        effects,
+        dom,
+        errors: errors.length > 0 ? errors : [],
+        counts: { signals: signals.length, effects: effects.length, errors: errors.length },
+      });
+    }
+  );
+
+  // ---------------------------------------------------------------------------
+  // Tool 10 — what_signal_trace
+  // ---------------------------------------------------------------------------
+
+  server.tool(
+    'what_signal_trace',
+    'Trace why a signal changed. Shows which effects wrote to this signal and the causal chain of signal dependencies. The debugging question every developer asks: "why did this value change?"',
+    {
+      signalId: z.number().describe('Signal ID to trace (from what_signals)'),
+      depth: z.number().optional().default(2).describe('Causal chain depth — how many levels of effect->signal->effect to trace (default: 2)'),
+    },
+    async ({ signalId, depth }) => {
+      const { snapshot, err } = await freshSnapshot('what_signal_trace');
+      if (err) return err;
+
+      const signals = snapshot.signals || [];
+      const effects = snapshot.effects || [];
+      const signalMap = new Map(signals.map(s => [s.id, s]));
+      const effectMap = new Map(effects.map(e => [e.id, e]));
+
+      const sig = signalMap.get(signalId);
+      if (!sig) {
+        return errorResponse(`Signal ${signalId} not found.`, ['Use what_signals to list available signal IDs.']);
+      }
+
+      // Get writer info from browser
+      let writers = { recentWrites: [], totalWrites: 0 };
+      try {
+        writers = await bridge.sendCommand('get-signal-writers', { signalId }, 5000);
+        if (writers.error) writers = { recentWrites: [], totalWrites: 0, note: writers.error };
+      } catch {}
+
+      // Build causal chain
+      // For each writer effect, find what signals it depends on
+      const chain = [];
+      const visited = new Set();
+
+      function traceEffect(effectId, currentDepth) {
+        if (currentDepth > (depth || 2) || visited.has(`effect:${effectId}`)) return null;
+        visited.add(`effect:${effectId}`);
+
+        const eff = effectMap.get(effectId);
+        if (!eff) return null;
+
+        const deps = (eff.depSignalIds || []).map(sid => {
+          const depSig = signalMap.get(sid);
+          return { id: sid, name: depSig?.name || `signal_${sid}`, value: depSig?.value };
+        });
+
+        return {
+          effectId: eff.id,
+          effectName: eff.name || `effect_${eff.id}`,
+          runCount: eff.runCount,
+          dependsOn: deps,
+        };
+      }
+
+      // Trace from recent writes
+      for (const write of (writers.recentWrites || []).slice(-5)) {
+        const entry = {
+          timestamp: write.timestamp,
+          previousValue: write.previousValue,
+          newValue: write.newValue,
+        };
+        if (write.writerEffect) {
+          entry.causedBy = traceEffect(write.writerEffect.id, 1);
+        }
+        chain.push(entry);
+      }
+
+      // Also show which effects READ this signal (downstream)
+      const downstream = effects
+        .filter(e => (e.depSignalIds || []).includes(signalId))
+        .map(e => ({ id: e.id, name: e.name || `effect_${e.id}`, runCount: e.runCount }));
+
+      // Build summary
+      const writerNames = chain
+        .filter(c => c.causedBy)
+        .map(c => c.causedBy.effectName)
+        .filter((v, i, a) => a.indexOf(v) === i); // unique
+
+      const summary = writerNames.length > 0
+        ? `Signal "${sig.name}" (current: ${JSON.stringify(sig.value)}) was written by: ${writerNames.join(', ')}. ` +
+          `${downstream.length} effect${downstream.length !== 1 ? 's' : ''} read this signal.`
+        : `Signal "${sig.name}" (current: ${JSON.stringify(sig.value)}). No recent write events captured. ` +
+          `${downstream.length} effect${downstream.length !== 1 ? 's' : ''} read this signal.`;
+
+      return ok({
+        summary,
+        signalId,
+        signalName: sig.name,
+        currentValue: sig.value,
+        recentWrites: chain,
+        downstream,
+        totalWritesCaptured: writers.totalWrites || 0,
+        nextSteps: [
+          chain.length === 0 ? 'Use what_watch to capture events, then call what_signal_trace again.' : null,
+          downstream.length > 0 ? `Use what_dependency_graph with signalId=${signalId} to see the full reactive graph.` : null,
+          'Use what_set_signal to test what happens when this signal changes.',
+        ].filter(Boolean),
+      });
+    }
+  );
+
+  // ---------------------------------------------------------------------------
+  // Tool 11 — what_look (visual inspection without image)
+  // ---------------------------------------------------------------------------
+
+  server.tool(
+    'what_look',
+    'Get computed visual info about a component WITHOUT an image: bounding rect, key CSS styles, text content, child element types, accessibility info, and layout classification. Much cheaper than a screenshot (~300-500 tokens). Use this first before what_screenshot.',
+    {
+      componentId: z.number().describe('Component ID (from what_components)'),
+    },
+    async ({ componentId }) => {
+      if (!bridge.isConnected()) return noConnection('what_look');
+
+      try {
+        const result = await bridge.sendCommand('visual-inspect', { componentId }, 5000);
+        if (result.error) {
+          return errorResponse(result.error, ['Use what_components to list available IDs.']);
+        }
+
+        const { componentName, boundingRect, styles, textContent, childElements, totalChildren, layout, viewport, accessibility } = result;
+
+        const styleDesc = Object.entries(styles || {}).map(([k, v]) => `${k}: ${v}`).join(', ');
+        const childDesc = Object.entries(childElements || {}).map(([k, v]) => `${v} ${k}${v > 1 ? 's' : ''}`).join(', ');
+
+        const summary = `${componentName}: ${boundingRect.width}×${boundingRect.height}px at (${boundingRect.x},${boundingRect.y}). ` +
+          `Layout: ${layout}. ` +
+          (childDesc ? `Contains: ${childDesc}. ` : '') +
+          (textContent && textContent !== '(empty)' ? `Text: "${textContent.substring(0, 80)}${textContent.length > 80 ? '...' : ''}"` : 'No text content.');
+
+        return ok({
+          summary,
+          component: componentName,
+          boundingRect,
+          layout,
+          styles,
+          textContent,
+          childElements,
+          totalChildren,
+          accessibility,
+          viewport,
+        });
+      } catch (e) {
+        return errorResponse(`Failed: ${e.message}`, ['Check what_connection_status']);
+      }
+    }
+  );
+
+  // ---------------------------------------------------------------------------
+  // Tool 12 — what_page_map (full page layout skeleton)
+  // ---------------------------------------------------------------------------
+
+  server.tool(
+    'what_page_map',
+    'Get a structured map of the entire visible page: landmarks, interactive elements, headings, and WhatFW component boundaries with positions. No image — pure structured text (~500-1000 tokens). Use this to understand the full page layout.',
+    {
+      maxElements: z.number().optional().default(200).describe('Max elements to include (default: 200)'),
+    },
+    async ({ maxElements }) => {
+      if (!bridge.isConnected()) return noConnection('what_page_map');
+
+      try {
+        const result = await bridge.sendCommand('page-map', { maxElements: maxElements || 200 }, 5000);
+        if (result.error) {
+          return errorResponse(result.error);
+        }
+
+        const { viewport, landmarks, interactives, headings, components, totalElements } = result;
+
+        const summary = `Page map: ${viewport.width}×${viewport.height} viewport. ` +
+          `${landmarks?.length || 0} landmarks, ` +
+          `${interactives?.length || 0} interactive elements, ` +
+          `${headings?.length || 0} headings, ` +
+          `${components?.length || 0} WhatFW components. ` +
+          `${totalElements} total elements mapped.`;
+
+        return ok({
+          summary,
+          viewport,
+          landmarks: landmarks || [],
+          interactives: interactives || [],
+          headings: headings || [],
+          components: components || [],
+          totalElements,
+        });
+      } catch (e) {
+        return errorResponse(`Failed: ${e.message}`, ['Check what_connection_status']);
+      }
+    }
+  );
+
+  // ---------------------------------------------------------------------------
+  // Tool 13 — what_screenshot (component-level screenshot via foreignObject SVG)
+  // ---------------------------------------------------------------------------
+
+  server.tool(
+    'what_screenshot',
+    'Capture a component-level screenshot. Returns a base64-encoded image cropped to JUST the component bounding box (5-20KB, not a full page screenshot). Use what_look first for cheaper text-based inspection.',
+    {
+      componentId: z.number().describe('Component ID (from what_components)'),
+      maxWidth: z.number().optional().default(400).describe('Max image width in px — smaller = faster + cheaper (default: 400)'),
+      quality: z.number().optional().default(0.7).describe('JPEG quality 0.1-1.0 (default: 0.7)'),
+      format: z.enum(['jpeg', 'png']).optional().default('jpeg').describe('Image format — jpeg is smaller (default: jpeg)'),
+    },
+    async ({ componentId, maxWidth, quality, format }) => {
+      if (!bridge.isConnected()) return noConnection('what_screenshot');
+
+      try {
+        const result = await bridge.sendCommand('component-screenshot', {
+          componentId,
+          maxWidth: maxWidth || 400,
+          quality: quality || 0.7,
+          format: format || 'jpeg',
+        }, 10000); // 10s timeout for rendering
+
+        if (result.error) {
+          return errorResponse(result.error, [
+            result.fallback || 'Use what_look for text-based visual info.',
+            'Use what_dom_inspect for HTML structure.',
+          ]);
+        }
+
+        const sizeKB = Math.round(result.sizeBytes / 1024);
+        const summary = `Screenshot of "${result.componentName}": ${result.width}x${result.height}px, ${sizeKB}KB ${result.format.toUpperCase()}`;
+
+        // Return MCP image content block + metadata text
+        return {
+          content: [
+            {
+              type: 'image',
+              data: result.base64,
+              mimeType: result.mimeType || (result.format === 'png' ? 'image/png' : 'image/jpeg'),
+            },
+            {
+              type: 'text',
+              text: JSON.stringify({
+                summary,
+                componentName: result.componentName,
+                width: result.width,
+                height: result.height,
+                sizeKB,
+                format: result.format,
+              }, null, 2),
+            },
+          ],
+        };
+      } catch (e) {
+        return errorResponse(`Screenshot failed: ${e.message}`, [
+          'Use what_look for text-based visual info without an image.',
+          'Use what_dom_inspect for HTML structure.',
+        ]);
+      }
+    }
+  );
 }

package/src/tools.js

@@ -52,7 +52,7 @@ export function registerTools(server, bridge) {
 
   server.tool(
     'what_connection_status',
-    'Check if a What Framework app is connected via WebSocket',
+    'Bootstrap endpoint: check connection, get app info, see available tools and recommended workflow',
     {},
     async () => {
       const connected = bridge.isConnected();
@@ -61,31 +61,77 @@ export function registerTools(server, bridge) {
       const effectCount = snapshot?.effects?.length || 0;
       const componentCount = snapshot?.components?.length || 0;
 
+      // Try to get app metadata from the browser
+      let appInfo = null;
+      if (connected) {
+        try {
+          appInfo = await bridge.sendCommand('get-app-info');
+          // If the client doesn't support this command, appInfo may be null or have an error
+          if (appInfo?.error) appInfo = null;
+        } catch {
+          // Old client without get-app-info support — skip gracefully
+          appInfo = null;
+        }
+      }
+
       let summary;
       if (!connected) {
         summary = 'No browser connected. Start your app with the what-devtools-mcp Vite plugin and refresh the page.';
       } else if (!snapshot) {
         summary = 'Browser connected but no snapshot received yet. Try refreshing the page.';
       } else {
-        summary = `Connected. App has ${signalCount} signals, ${effectCount} effects, ${componentCount} components.`;
+        summary = `Connected to ${appInfo?.title || 'app'} at ${appInfo?.url || 'unknown URL'}. ${signalCount} signals, ${effectCount} effects, ${componentCount} components.`;
       }
 
       const result = {
         summary,
         connected,
         hasSnapshot: snapshot !== null,
+        // App info (from browser)
+        app: appInfo ? {
+          url: appInfo.url,
+          title: appInfo.title,
+          viewport: appInfo.viewport,
+          version: appInfo.version,
+          entryPoint: appInfo.entryPoint,
+        } : null,
+        // Counts
         signalCount,
         effectCount,
         componentCount,
-      };
-
-      if (!connected) {
-        result.nextSteps = [
+        // Framework primer for agents that don't know WhatFW
+        framework: 'What Framework: signal-based reactivity. Components run ONCE (not like React). signal(val) for state — read with sig(), write with sig(newVal). effect() for side effects. computed() for derived values. Import from "what-framework".',
+        // Recommended next steps
+        workflow: connected ? [
+          'what_components — see component tree and IDs',
+          'what_signals {filter: "yourSignalName"} — check specific state (always filter!)',
+          'what_diagnose — one-call health check',
+          'what_look {componentId: N} — visual info without screenshot',
+          'what_errors — check for runtime errors',
+        ] : [
           'Make sure your app is running with the what-devtools-mcp Vite plugin',
-          'Check that the MCP bridge server is running (npx what-devtools-mcp)',
-          'Try refreshing the browser page',
-        ];
-      }
+          '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_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)' },
+        ],
+      };
 
       return {
         content: [{
@@ -98,12 +144,14 @@ export function registerTools(server, bridge) {
 
   server.tool(
     'what_signals',
-    'List all reactive signals with current values. Filter by name regex or ID.',
+    'List all reactive signals with current values. Filter by name regex or ID. Named signals are sorted first for relevance.',
     {
       filter: z.string().optional().describe('Regex to filter signal names (ignored if id is set)'),
       id: z.number().optional().describe('Get a specific signal by ID (takes precedence over filter)'),
+      limit: z.number().optional().default(20).describe('Max signals to return (default: 20, max: 100)'),
+      named_only: z.boolean().optional().default(false).describe('If true, only return signals with debug names (filters out anonymous internal signals)'),
     },
-    async ({ filter, id }) => {
+    async ({ filter, id, limit, named_only }) => {
       if (!bridge.isConnected()) {
         return noConnection('what_signals');
       }
@@ -124,6 +172,40 @@ export function registerTools(server, bridge) {
         }
       }
 
+      // Sort: named signals first (more useful), then by ID
+      signals.sort((a, b) => {
+        const aHasName = a.name && !a.name.startsWith('signal_');
+        const bHasName = b.name && !b.name.startsWith('signal_');
+        if (aHasName && !bHasName) return -1;
+        if (!aHasName && bHasName) return 1;
+        return a.id - b.id;
+      });
+
+      // Filter to named-only if requested
+      if (named_only) {
+        signals = signals.filter(s => s.name && !s.name.startsWith('signal_') && !s.name.startsWith('effect_'));
+      }
+
+      // Clean up circular references in values
+      signals = signals.map(s => {
+        const val = s.value;
+        if (val === '[Circular]' || (typeof val === 'string' && val.includes('[Circular]'))) {
+          return { ...s, value: '[ref]', _circular: true };
+        }
+        // Truncate large array/object values
+        if (typeof val === 'object' && val !== null) {
+          const str = JSON.stringify(val);
+          if (str && str.length > 200) {
+            return { ...s, value: str.substring(0, 197) + '...', _truncated: true };
+          }
+        }
+        return s;
+      });
+
+      // Apply limit AFTER sorting and filtering
+      const totalBeforeLimit = signals.length;
+      signals = signals.slice(0, Math.min(limit || 20, 100));
+
       // Build summary
       const valuePreviews = signals.slice(0, 5).map(s => {
         const val = typeof s.value === 'string' ? `'${s.value}'` : JSON.stringify(s.value);
@@ -133,7 +215,8 @@ export function registerTools(server, bridge) {
       const filterNote = id != null ? ` 1 matched id=${id}.` : filter ? ` ${signals.length} match filter '${filter}'.` : '';
       const valuesNote = valuePreviews.length > 0 ? ` Values: ${valuePreviews.join(', ')}` : '';
       const moreNote = signals.length > 5 ? `, ... (${signals.length - 5} more)` : '';
-      const summary = `${totalCount} signals total.${filterNote}${valuesNote}${moreNote}`;
+      const limitNote = totalBeforeLimit > signals.length ? ` Showing ${signals.length} of ${totalBeforeLimit} (use limit param for more).` : '';
+      const summary = `${totalCount} signals total.${filterNote}${valuesNote}${moreNote}${limitNote}`;
 
       return {
         content: [{
@@ -225,7 +308,12 @@ export function registerTools(server, bridge) {
 
       // Build tree summary
       const { tree, depth } = buildComponentTreeSummary(components);
-      const summary = `${totalCount} components mounted. Tree depth: ${depth}. Root: ${tree}`;
+
+      // Add source file hint based on component names
+      const sourceHint = 'Component source files are typically in the same directory as the app entry point. Use file search to find: ' +
+        components.slice(0, 5).map(c => c.name).filter(Boolean).join(', ');
+
+      const summary = `${totalCount} components mounted. Tree depth: ${depth}. Root: ${tree}. ${sourceHint}`;
 
       return {
         content: [{
@@ -233,6 +321,7 @@ export function registerTools(server, bridge) {
           text: JSON.stringify({
             summary,
             count: components.length,
+            sourceHint,
             components,
           }, null, 2),
         }],