@yusufffararatt/dombridge-mcp 2.7.5

package/src/tools/analyze-page.js

@@ -0,0 +1,247 @@
+/**
+ * Analyze Page Tool
+ * Sayfanın yapısını, framework'ünü ve veri kaynaklarını analiz eder.
+ *
+ * Phase 2.4: Refactored from (args, extensionData, httpPort) to (args, bridgeClient).
+ * All HTTP communication now goes through BridgeClient.
+ */
+
+import { softGuardAnalyzePage, formatSoftGuard } from '../utils/workflow-helper.js';
+import { enrichProfile } from '../profiles/profile-enricher.js';
+import { extractDomain } from '../profiles/profile-manager.js';
+
+export const analyzePageTool = {
+    name: 'analyze_page',
+    description: `This is a tool from the dombridge MCP server.
+Analyze the current page's structure, frameworks, data containers, and SSR data — NO element selection needed.
+
+WORKFLOW POSITION: 🟢 First Step - Run before anything else to understand the page.
+
+RETURNS (default: summary):
+- Detected frameworks, SSR markers, page title/URL
+- Interactive element counts (forms, buttons, inputs)
+- Data source signal (SSR / API-driven / unknown)
+- DOM stats
+- Top 3 captured API calls (when includeApis: true)
+
+Use verbose: true for full detail: headings, all data containers, storageKeys, ssrData detail.
+
+PARAMETERS:
+- includeApis (optional, default: false): Also return top 3 captured API calls inline.
+- verbose (optional, default: false): Return full detail instead of summary.
+- tabId (optional): Target a specific tab by ID. Get IDs from debug_mcp_state().
+
+MULTI-TAB: Call debug_mcp_state() first to get tab IDs, then pass tabId to analyze a specific tab.
+Example: analyze_page({ tabId: 142, includeApis: true })
+
+AUTONOMOUS WORKFLOW:
+1. analyze_page({ includeApis: true }) → page structure + API snapshot in one call
+2. get_element({ selectorInfo: { css: 'SELECTOR' } }) → pick a data element
+3. get_network_trace() → find matching API
+`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            includeApis: {
+                type: 'boolean',
+                description: 'Also return top 3 captured API calls inline (default: false). Saves a separate discover_apis call.'
+            },
+            verbose: {
+                type: 'boolean',
+                description: 'Return full detail: headings, all data containers, storageKeys, ssrData (default: false)'
+            },
+            tabId: {
+                type: 'number',
+                description: 'Target tab ID (optional). Omit to use active tab. Get IDs from debug_mcp_state().'
+            }
+        }
+    },
+    handler: async (args, bridgeClient) => {
+        if (!bridgeClient.isConnected) {
+            return {
+                content: [{
+                    type: 'text',
+                    text: `❌ Error: Extension not connected.
+REQUIRED STEPS:
+1. Reload webpage
+2. Ensure the Chrome extension is active`
+                }],
+                isError: true
+            };
+        }
+
+        const { includeApis = false, verbose = false, tabId } = args || {};
+        const requestId = `analyze-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+
+        // Soft guard: very recent scan on this tab — append hint to output, don't block
+        const softHints = softGuardAnalyzePage({ tabId });
+
+        try {
+            // Queue analyze-page request via bridge daemon
+            await bridgeClient.queueRequest('analyze-page', {
+                id: requestId,
+                ...(tabId !== undefined ? { tabId } : {})
+            });
+
+            // Wait for result (max 12 seconds + buffer)
+            const timeout = 12000;
+            const resultItem = await bridgeClient.waitForResult('analyze-page', requestId, timeout + 3000);
+
+            if (!resultItem) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: `❌ Timeout: Page analysis did not complete within ${timeout}ms.`
+                    }],
+                    isError: true
+                };
+            }
+
+            const r = resultItem.result;
+
+            // Auto-save: profil'e framework + page karakteristiklerini kaydet
+            if (r && !r.error && r.meta?.url) {
+                const domain = extractDomain(r.meta.url);
+                if (domain) enrichProfile(domain, 'analyze_page', r);
+            }
+
+            if (r && r.error) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: `❌ Analysis failed: ${r.error}`
+                    }],
+                    isError: true
+                };
+            }
+            if (!r) {
+                return {
+                    content: [{
+                        type: 'text',
+                        text: `❌ Analysis failed: Script returned no data. The page may still be navigating or Chrome could not access the tab contents yet.`
+                    }],
+                    isError: true
+                };
+            }
+
+            // Format output
+            const lines = [
+                `🔍 **Page Analysis: ${r.meta?.title || r.meta?.url || 'Unknown Page'}**`,
+                `URL: ${r.meta?.url || 'N/A'}`,
+                ''
+            ];
+
+            // ── Summary mode (default) ───────────────────────────────
+            const hasSSR = r.ssrData && Object.keys(r.ssrData).length > 0;
+            const ssrKeys = hasSSR ? Object.keys(r.ssrData) : [];
+            const dataSignal = hasSSR ? `SSR (${ssrKeys.join(', ')})` : (r.dataContainers?.length > 0 ? 'API-driven' : 'unknown');
+
+            lines.push(`**🧩 Frameworks:** ${r.frameworks?.length ? r.frameworks.join(', ') : 'none / vanilla'}`);
+            lines.push(`**📦 Data source:** ${dataSignal}`);
+
+            if (r.elements) {
+                lines.push(`**🎯 Elements:** forms ${r.elements.forms} | inputs ${r.elements.inputs} | buttons ${r.elements.buttons} | links ${r.elements.links}`);
+            }
+
+            if (r.domStats) {
+                lines.push(`**🌳 DOM:** ${r.domStats.totalElements} elements, depth ${r.domStats.maxDepth}`);
+            }
+
+            // ── Verbose extras ───────────────────────────────────────
+            if (verbose) {
+                if (hasSSR) {
+                    lines.push(`\n**📦 SSR Detail:** ${Object.entries(r.ssrData).map(([k, v]) => `${k}${typeof v === 'object' ? ': ' + JSON.stringify(v) : ''}`).join(', ')}`);
+                }
+
+                if (r.dataContainers?.length > 0) {
+                    const ECOMMERCE_DOMAINS = ['trendyol', 'amazon', 'hepsiburada', 'shopify', 'etsy', 'ebay', 'n11', 'gittigidiyor', 'ciceksepeti'];
+                    const pageHost = r.meta?.url || '';
+                    const isEcommerce = ECOMMERCE_DOMAINS.some(d => pageHost.includes(d));
+                    lines.push(`\n**📋 Data Containers:**`);
+                    r.dataContainers.forEach(c => {
+                        const isProductSelector = c.selector === '[class*="product"]';
+                        const note = (isProductSelector && !isEcommerce) ? ' _(generic match — verify for non-ecommerce pages)_' : '';
+                        lines.push(`- \`${c.selector}\`: ${c.count} elements${note}`);
+                    });
+                }
+
+                if (r.headings?.length > 0) {
+                    lines.push(`\n**📝 Headings:**`);
+                    r.headings.forEach(h => lines.push(`- ${h.tag}: "${h.text}"`));
+                }
+
+                if (r.storageKeys?.local?.length > 0) {
+                    lines.push(`\n**🗄️ LocalStorage:** ${r.storageKeys.local.join(', ')}`);
+                }
+            }
+
+            lines.push(`\n---\n💡 **Next steps:**`);
+            if (hasSSR) {
+                lines.push(`- SSR data detected! Use \`execute_js\` to read \`window.__NEXT_DATA__\` or \`window.__INITIAL_STATE__\` directly.`);
+            }
+            lines.push(`- \`get_element({ selectorInfo: { css: 'SELECTOR' } })\` → select a data element`);
+            lines.push(`- \`get_network_trace()\` → find matching API`);
+
+            // Inline API discovery when includeApis: true
+            if (includeApis) {
+                const apiLines = await fetchTopApis(bridgeClient, tabId);
+                lines.push(...apiLines);
+            }
+
+            // Soft guard hint (appended after content, non-blocking)
+            const softNote = formatSoftGuard(softHints);
+            if (softNote) lines.push(softNote);
+
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }]
+            };
+
+        } catch (e) {
+            return {
+                content: [{ type: 'text', text: `❌ Error: ${e.message}` }],
+                isError: true
+            };
+        }
+    }
+};
+
+/**
+ * Fetch top 3 captured API calls inline (for includeApis: true)
+ * Uses BridgeClient for HTTP communication.
+ */
+async function fetchTopApis(bridgeClient, tabId) {
+    const requestId = `raw-net-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+    const lines = [];
+
+    try {
+        await bridgeClient.queueRequest('raw-network-requests', {
+            method: 'all',
+            limit: 3,
+            includeBody: false,
+            id: requestId,
+            ...(tabId !== undefined ? { tabId } : {})
+        });
+
+        const resultItem = await bridgeClient.waitForResult('raw-network', requestId, 6000 + 2000);
+
+        if (!resultItem) {
+            // Bug #1 fix: be explicit about empty/no response
+            return ['\n**📡 API Discovery:** No network data available yet. Try `discover_apis()` after page interaction.'];
+        }
+
+        const requests = resultItem.requests || [];
+        if (requests.length === 0) {
+            return [`\n**📡 API Discovery:** No network requests captured for this tab (0 calls). Try \`discover_apis()\` after page interaction.`];
+        }
+
+        lines.push(`\n**📡 Top API Calls (${requests.length} of ${resultItem.total || requests.length} captured):**`);
+        requests.forEach((req, i) => {
+            lines.push(`- ${i + 1}. \`${req.method}\` ${req.url.length > 80 ? req.url.substring(0, 80) + '…' : req.url} ${req.status ? `[${req.status}]` : ''}`);
+        });
+        lines.push(`_Use \`discover_apis()\` for full list with filtering._`);
+        return lines;
+    } catch (e) {
+        // Non-critical — but report the error
+        return [`\n**📡 API Discovery:** Failed to fetch — ${e.message}`];
+    }
+}

package/src/tools/debug-mcp-state.js

@@ -0,0 +1,172 @@
+/**
+ * Tool: debug_mcp_state
+ * MCP server's internal state for debugging — enriched with connection health
+ */
+
+import { readFileSync } from 'fs';
+import { RateLimiter } from '../utils/rate-limiter.js';
+import { circuitBreakers } from '../utils/circuit-breaker.js';
+
+export const debugMcpStateTool = {
+  name: 'debug_mcp_state',
+  description: `Show MCP server's internal state for debugging. Also lists open browser tabs for multi-tab targeting.
+
+WORKFLOW POSITION: 🔧 Debug/Setup Tool
+
+WHEN TO CALL:
+- Extension appears disconnected or tools are timing out
+- Circuit breakers showing OPEN state
+- BEFORE using tabId parameter in execute_js / execute_action / capture_screenshot / discover_apis
+  → This tool shows all open tab IDs so you can target the right one
+
+RETURNS:
+- Connection status + heartbeat health
+- Open browser tabs: ID, URL, title (use these IDs for tabId parameter)
+- Selected element state
+- Circuit breaker states (CLOSED/OPEN/HALF_OPEN)
+- Pending request queue
+
+⚠️  Do NOT call during normal single-tab workflows — use only when needed.`,
+  inputSchema: {
+    type: 'object',
+    properties: {},
+    required: []
+  },
+  handler: async (args, bridgeClient) => {
+    return await RateLimiter.executeWithRetry(
+      'debug_mcp_state',
+      async () => {
+        const health = bridgeClient._connectionHealth
+          ? (typeof bridgeClient._connectionHealth.getStatus === 'function'
+              ? bridgeClient._connectionHealth.getStatus()
+              : bridgeClient._connectionHealth)
+          : { connected: bridgeClient.isConnected, stale: false };
+
+        const uptimeSeconds = Math.floor(process.uptime());
+
+        // Get version from package.json
+        let version = 'unknown';
+        try {
+          const pkgPath = new URL('../../package.json', import.meta.url);
+          const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+          version = pkg.version;
+        } catch {
+          // Fallback if file read fails
+          version = '2.6.3'; 
+        }
+
+        // Fetch tab list from extension via bridge daemon (best-effort with 3s timeout)
+        let tabList = null;
+        try {
+          const tabRequestId = `tabs-debug-${Date.now()}`;
+          await bridgeClient.queueRequest('tabs', { id: tabRequestId });
+          const tabResult = await bridgeClient.waitForResult('tabs', tabRequestId, 3000);
+          if (tabResult && tabResult.tabs) {
+            tabList = tabResult.tabs;
+          }
+        } catch { /* ignore — tab list is best-effort */ }
+
+        let output = `## MCP Server Internal State\n\n`;
+        output += `Server Version: ${version}\n`;
+        output += `HTTP Port: ${bridgeClient.port}\n`;
+        output += `Process Uptime: ${uptimeSeconds}s\n\n`;
+
+        // Open Tabs (for multi-tab targeting)
+        output += `## OPEN TABS\n\n`;
+        if (tabList && tabList.length > 0) {
+          output += `_Pass tabId to execute_js / execute_action / capture_screenshot / discover_apis to target a specific tab._\n\n`;
+          tabList.forEach(t => {
+            const activeFlag = t.active ? ' ← active' : '';
+            const title = t.title ? ` "${t.title.substring(0, 50)}"` : '';
+            output += `- [${t.id}] ${t.url}${title}${activeFlag}\n`;
+          });
+        } else if (!bridgeClient.isConnected) {
+          output += `_(Extension not connected — connect first to see tabs)_\n`;
+        } else {
+          output += `_(No tabs found or extension did not respond in time)_\n`;
+        }
+        output += `\n`;
+
+        // Connection Health
+        output += `## CONNECTION HEALTH\n\n`;
+        output += `Status: ${health.connected ? '🟢 Connected' : '🔴 Disconnected'}\n`;
+        output += `Stale: ${health.stale ? '⚠️ Yes (no heartbeat)' : '✅ No'}\n`;
+        output += `Last Heartbeat: ${health.lastHeartbeat || 'Never'}\n`;
+        output += `Heartbeat Count: ${health.heartbeatCount || 0}\n`;
+        output += `Connection Uptime: ${health.uptimeHuman || 'N/A'}\n`;
+        const reconnectCount = health.reconnectCount || 0;
+        const knownSessions = health.knownSessionCount || 0;
+        output += `Reconnect Count: ${reconnectCount}`;
+        if (knownSessions > 1) {
+          output += ` (${knownSessions} tabs/sessions detected — normal for multi-tab browsing)`;
+        }
+        output += `\n\n`;
+
+        // State Details
+        output += `## STATE DETAILS\n\n`;
+        const sel = bridgeClient.selectedElement;
+        if (sel) {
+          output += `Selected Element: Yes\n`;
+          output += `  CSS: ${sel.cssSelector}\n`;
+          if (sel.stableSelector) {
+            const meta = sel.stableSelectorMeta;
+            const conf = meta?.confidence ? ` (${meta.confidence} — ${meta.reason})` : '';
+            output += `  Stable: ${sel.stableSelector}${conf}\n`;
+          } else {
+            output += `  Stable: ⚠️ none — element has no stable attribute (data-testid/data-cy/data-qa-id/aria-label/id)\n`;
+          }
+        } else {
+          output += `Selected Element: No\n`;
+        }
+        output += `Network Trace Matches: ${bridgeClient.networkTrace.totalMatches || 0}\n`;
+        output += `WebSocket Matches: ${bridgeClient.websocketTrace?.totalMatches || 0}\n`;
+        output += `Element Value: ${bridgeClient.networkTrace.elementValue || 'N/A'}\n\n`;
+
+        // Pending Requests
+        output += `## PENDING REQUESTS\n\n`;
+        output += `JS Execution: ${bridgeClient.jsExecutionRequest ? '⏳ Pending' : '✅ None'}\n`;
+        output += `Action Queue: ${bridgeClient.actionExecutionRequest ? '⏳ Pending' : '✅ None'}\n`;
+        output += `Screenshot: ${bridgeClient.captureScreenshotRequest ? '⏳ Pending' : '✅ None'}\n`;
+        output += `Raw Network: ${(bridgeClient.rawNetworkRequests?.length || 0) > 0 ? `⏳ ${bridgeClient.rawNetworkRequests.length} pending` : '✅ None'}\n`;
+        output += `Analyze Page: ${(bridgeClient.analyzePageRequests?.length || 0) > 0 ? `⏳ ${bridgeClient.analyzePageRequests.length} pending` : '✅ None'}\n`;
+        output += `Select Element: ${bridgeClient.selectElementRequest ? '⏳ Pending' : '✅ None'}\n\n`;
+
+        // Circuit Breaker Status
+        output += `## CIRCUIT BREAKERS\n\n`;
+        Object.values(circuitBreakers).forEach(cb => {
+          const s = cb.getStatus();
+          const icon = s.state === 'CLOSED' ? '🟢' : s.state === 'OPEN' ? '🔴' : '🟡';
+          output += `${icon} ${s.name}: ${s.state} (failures: ${s.failures})\n`;
+        });
+        output += '\n';
+
+        // Recent Events
+        if (health.recentEvents && health.recentEvents.length > 0) {
+          output += `## RECENT EVENTS\n\n`;
+          health.recentEvents.forEach(event => {
+            output += `- ${event.time}: ${event.type}\n`;
+          });
+          output += '\n';
+        }
+
+        // Connection Info
+        output += `## CONNECTION INFO\n\n`;
+        output += `Extension → MCP Bridge: http://localhost:${bridgeClient.port}\n`;
+        output += `Heartbeat Endpoint: POST /api/heartbeat\n`;
+        output += `Health Check: GET /health`;
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: output
+            }
+          ]
+        };
+      },
+      {
+        maxRetries: 1
+      }
+    );
+  }
+};

package/src/tools/discover-apis.js

@@ -0,0 +1,186 @@
+/**
+ * Discover APIs Tool
+ * Lists captured network calls and saves scraper-relevant metadata to the site profile.
+ */
+
+import { circuitBreakers } from '../utils/circuit-breaker.js';
+import { softGuardDiscoverApis, formatSoftGuard } from '../utils/workflow-helper.js';
+import { resolveActiveDomain } from '../utils/tab-resolver.js';
+
+export const discoverApisTool = {
+    name: 'discover_apis',
+    description: `This is a tool from the dombridge MCP server.
+List all captured API calls on the current page WITHOUT requiring element selection.
+
+WORKFLOW POSITION: First Step - use when you need live API discovery or want to refresh saved endpoint intelligence.
+
+NOTE:
+- Successful responses are auto-saved into the site profile.
+- Use manage_site_profile({ action: 'load', domain: '...' }) to inspect the saved endpoint dossier afterward.
+
+MULTI-TAB: Call debug_mcp_state() first to get tab IDs, then pass tabId to discover APIs on a specific tab.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            urlPattern: {
+                type: 'string',
+                description: 'URL substring or regex pattern to filter results (e.g. "/api/", "graphql", "product")'
+            },
+            method: {
+                type: 'string',
+                enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'all'],
+                description: 'HTTP method filter. Default: "all"'
+            },
+            limit: {
+                type: 'number',
+                description: 'Max number of results to return. Default: 3, max: 20.',
+                default: 3,
+                maximum: 20
+            },
+            includeBody: {
+                type: 'boolean',
+                description: 'Include request/response bodies in verbose mode. Default: false.'
+            },
+            verbose: {
+                type: 'boolean',
+                description: 'Return full detail: contentType, timestamp, request/response bodies (default: false)',
+                default: false
+            },
+            tabId: {
+                type: 'number',
+                description: 'Target tab ID (optional). Omit to use active tab.'
+            },
+            force: {
+                type: 'boolean',
+                description: 'Skip soft guard hint about a fresh profile and run discovery anyway.',
+                default: false
+            }
+        }
+    },
+    handler: async (args, bridgeClient) => {
+        if (!bridgeClient.isConnected) {
+            return {
+                content: [{
+                    type: 'text',
+                    text: 'Error: Extension not connected.\nREQUIRED STEPS:\n1. Reload webpage\n2. Ensure the Chrome extension is active'
+                }],
+                isError: true
+            };
+        }
+
+        const requestId = `raw-net-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+        const { urlPattern, method = 'all', includeBody = false, verbose = false, tabId, force = false } = args || {};
+        const limit = Math.min(args?.limit ?? 3, 20);
+        const domain = await resolveActiveDomain(bridgeClient, tabId);
+        const softHints = softGuardDiscoverApis(bridgeClient, { domain, force });
+
+        try {
+            await circuitBreakers.discoverApis.execute(() =>
+                bridgeClient.queueRequest('raw-network-requests', { urlPattern, method, limit, includeBody, id: requestId, ...(tabId !== undefined ? { tabId } : {}) })
+            );
+
+            const timeout = 20000;
+            const resultItem = await bridgeClient.waitForResult('raw-network', requestId, timeout);
+
+            if (resultItem) {
+
+                    const allRequests = (resultItem.requests || []).sort((a, b) => {
+                        const aOk = a.status >= 200 && a.status < 300 ? 0 : 1;
+                        const bOk = b.status >= 200 && b.status < 300 ? 0 : 1;
+                        if (aOk !== bOk) return aOk - bOk;
+                        return (b.timestamp || 0) - (a.timestamp || 0);
+                    });
+                    const requests = allRequests.slice(0, limit);
+
+                    if (requests.length === 0) {
+                        return {
+                            content: [{
+                                type: 'text',
+                                text: `No API calls captured yet${urlPattern ? ` matching "${urlPattern}"` : ''}.\n\nTIPS:\n- Interact with the page first (scroll, click)\n- Use execute_action to trigger lazy-loaded requests\n- Try without urlPattern to see the full capture`
+                            }]
+                        };
+                    }
+
+                    // Push captures to bridge state via HTTP POST (process boundary)
+                    // so manage_site_profile (running in this same MCP process) can read
+                    // them back via bridgeClient.getCapturedEndpoints(domain).
+                    if (domain) {
+                        for (const req of allRequests) {
+                            try {
+                                await bridgeClient.addCapturedEndpoint(domain, {
+                                    method: req.method,
+                                    url: req.url,
+                                    status: req.status,
+                                    contentType: req.contentType
+                                });
+                            } catch (_) {
+                                // best-effort — don't fail the whole discovery
+                            }
+                        }
+                    }
+
+                    const lines = [
+                        `API discovery: ${requests.length} call${requests.length !== 1 ? 's' : ''} shown (total captured: ${resultItem.total})`,
+                        urlPattern ? `Filter: "${urlPattern}"` : '',
+                        ''
+                    ].filter(Boolean);
+
+                    requests.forEach((request, index) => {
+                        const urlDisplay = request.url.length > 80 ? `${request.url.substring(0, 80)}...` : request.url;
+                        lines.push(`**${index + 1}. ${request.method} ${urlDisplay}** ${request.status ? `[${request.status}]` : ''}`);
+
+                        if (verbose) {
+                            if (request.contentType) lines.push(`   Content-Type: ${request.contentType}`);
+                            if (request.timestamp) lines.push(`   Time: ${new Date(request.timestamp).toLocaleTimeString()}`);
+                            if (includeBody && request.requestBody) {
+                                const body = typeof request.requestBody === 'string'
+                                    ? request.requestBody
+                                    : JSON.stringify(request.requestBody, null, 2);
+                                lines.push(`   Request Body: ${body.substring(0, 500)}${body.length > 500 ? '...' : ''}`);
+                            }
+                            if (includeBody && request.responseBody) {
+                                const body = typeof request.responseBody === 'string'
+                                    ? request.responseBody
+                                    : JSON.stringify(request.responseBody, null, 2);
+                                lines.push(`   Response: ${body.substring(0, 500)}${body.length > 500 ? '...' : ''}`);
+                            }
+                        }
+
+                        lines.push('');
+                    });
+
+                    if (domain) {
+                        lines.push(`Captured ${allRequests.length} endpoint${allRequests.length !== 1 ? 's' : ''}. Inspect: \`manage_site_profile({ action: "load", domain: "${domain}" })\``);
+                    }
+                    if (verbose && !includeBody) {
+                        lines.push('💡 Add `includeBody: true` to see request/response bodies.');
+                    }
+                    lines.push('---');
+                    lines.push('Next steps:');
+                    lines.push('- `get_element({ css: "SELECTOR" })` -> pick the field you want to scrape');
+                    lines.push('- `get_network_trace()` -> connect that field to the correct API response');
+                    lines.push('- `discover_apis({ limit: 20 })` -> inspect more captured calls');
+
+                    const softNote = formatSoftGuard(softHints);
+                    if (softNote) lines.push(softNote);
+
+                    return {
+                        content: [{ type: 'text', text: lines.join('\n') }]
+                    };
+                }
+
+            return {
+                content: [{
+                    type: 'text',
+                    text: `Timeout: Extension did not respond within ${timeout}ms. Check if the extension is active and the page has finished loading.`
+                }],
+                isError: true
+            };
+        } catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error: ${e.message}` }],
+                isError: true
+            };
+        }
+    }
+};