@probebrowser/trace-mcp 1.0.3 → 1.1.0

package/dist/server.js

@@ -3,16 +3,21 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { Trace, ALL_TOOLS } from '@probebrowser/sdk';
 import { TOOLS } from './tools.js';
+import { zodToJsonSchema as _zodToJsonSchema } from 'zod-to-json-schema';
 // Schema conversion helper
 function zodToJsonSchema(schema) {
+    const jsonSchema = _zodToJsonSchema(schema, { target: 'openApi3' });
+    // MCP expects { type: 'object', properties: {...}, required: [...] }
     return {
         type: 'object',
-        properties: {}, // Simplified
+        properties: jsonSchema.properties || {},
+        required: jsonSchema.required || [],
     };
 }
 export class TraceMcpServer {
     server;
     trace;
+    connected = false;
     constructor() {
         this.server = new Server({
             name: 'trace-mcp-server',
@@ -72,7 +77,7 @@ export class TraceMcpServer {
             }
             if (!method)
                 throw new Error(`Unknown tool: ${toolName}`);
-            const isConnected = !!this.trace.getCurrentUrl();
+            const isConnected = this.connected;
             try {
                 let result;
                 // 1. Handle Connect Tool
@@ -80,6 +85,7 @@ export class TraceMcpServer {
                     const url = String(request.params.arguments?.url);
                     // Re-init trace if headless mode changes? For now just connect.
                     await this.trace.connect(url);
+                    this.connected = true;
                     return { content: [{ type: 'text', text: `Connected to ${url}` }] };
                 }
                 if (!isConnected) {
@@ -92,17 +98,17 @@ export class TraceMcpServer {
                         return { content: [{ type: 'text', text: 'Error: TRACE_API_KEY is required for AI features.' }], isError: true };
                     }
                     const prompt = String(request.params.arguments?.prompt || request.params.arguments?.q || 'Analyze page');
-                    // Delegate to SDK's queryDeep which calls Azure /v1/agent-step
-                    const analysis = await this.trace.queryDeep(prompt);
+                    // Delegate to SDK's query which runs AI-powered deep debug
+                    const debugResult = await this.trace.query(prompt);
                     // Return the conclusion and steps
                     return {
                         content: [
-                            { type: 'text', text: `### Conclusion\n${analysis.conclusion}\n\n### Steps Taken\n${analysis.steps.map(s => `- ${s.tool}: ${s.success ? 'Success' : 'Failed'}`).join('\n')}` }
+                            { type: 'text', text: `### Summary\n${debugResult.analysis.summary}\n\n### Steps Taken\n${debugResult.execution.results.map((r) => `- ${r.tool}: ${r.success ? 'Success' : 'Failed'}`).join('\n')}` }
                         ]
                     };
                 }
                 // 3. Handle Standard SDK Tools
-                result = await this.trace.executeTool(toolDef.method, request.params.arguments);
+                result = await this.trace.tool(toolDef.method, (request.params.arguments || {}));
                 return {
                     content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                 };
@@ -161,12 +167,12 @@ export class TraceMcpServer {
         });
         this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             const uri = request.params.uri;
-            if (!this.trace.getCurrentUrl()) {
+            if (!this.connected) {
                 throw new Error('Not connected. Call trace_connect first.');
             }
             // --- Console ---
             if (uri === 'trace://console/errors') {
-                const logs = await this.trace.executeTool('get_console_errors', {});
+                const logs = await this.trace.tool('get_console_errors', {});
                 return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(logs, null, 2) }] };
             }
             if (uri === 'trace://console/logs') {
@@ -175,21 +181,21 @@ export class TraceMcpServer {
                 // For now, let's return the summary as it contains counts.
                 // Ideally SDK should expose 'get_all_logs'.
                 // Fallback: use get_console_errors
-                const logs = await this.trace.executeTool('get_console_summary', {});
+                const logs = await this.trace.tool('get_console_summary', {});
                 return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(logs, null, 2) }] };
             }
             // --- Network ---
             if (uri === 'trace://network/failed') {
-                const reqs = await this.trace.executeTool('get_network_failed', {});
+                const reqs = await this.trace.tool('get_network_failed', {});
                 return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(reqs, null, 2) }] };
             }
             if (uri === 'trace://network/all') {
-                const reqs = await this.trace.executeTool('get_network_summary', {});
+                const reqs = await this.trace.tool('get_network_summary', {});
                 return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(reqs, null, 2) }] };
             }
             // --- DOM ---
             if (uri === 'trace://dom/tree') {
-                const tree = await this.trace.executeTool('get_dom_tree', { depth: 2 });
+                const tree = await this.trace.tool('get_dom_tree', { depth: 2 });
                 return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(tree, null, 2) }] };
             }
             // --- Screenshot ---

package/dist/tools.js

@@ -100,8 +100,37 @@ export const TOOLS = {
             requestId: z.string().describe('The ID of the request to replay'),
         }),
     },
+    trace_set_network_throttling: {
+        method: 'set_network_throttling',
+        description: 'Set network throttling to a preset (slow3G, fast3G, offline).',
+        schema: z.object({
+            preset: z.string().describe('Preset: slow3G, fast3G, or offline'),
+        }),
+    },
+    trace_set_custom_network_throttling: {
+        method: 'set_custom_network_throttling',
+        description: 'Set custom network throttling parameters.',
+        schema: z.object({
+            downloadThroughput: z.number().describe('Download speed in bytes/sec'),
+            uploadThroughput: z.number().describe('Upload speed in bytes/sec'),
+            latency: z.number().describe('Latency in ms'),
+        }),
+    },
+    trace_disable_network_throttling: {
+        method: 'disable_network_throttling',
+        description: 'Disable network throttling.',
+        schema: z.object({}),
+    },
+    // ============================================
+    // DIAGNOSTIC (1)
     // ============================================
-    // DOM & UI TOOLS (16)
+    trace_full_page_diagnostic: {
+        method: 'full_page_diagnostic',
+        description: 'COMPREHENSIVE page diagnostic that checks EVERYTHING: console errors, network failures (404s, 500s), slow requests, layout/overlap issues, hidden elements, CORS errors, mixed content. Use this FIRST when asked to find errors or debug a page.',
+        schema: z.object({}),
+    },
+    // ============================================
+    // DOM & UI TOOLS (22)
     // ============================================
     trace_inspect_element: {
         method: 'inspect_element',
@@ -117,6 +146,13 @@ export const TOOLS = {
             selector: z.string().describe('CSS selector'),
         }),
     },
+    trace_find_by_text: {
+        method: 'find_by_text',
+        description: 'Find elements containing specific visible text. Best for finding buttons, links, labels by their text content.',
+        schema: z.object({
+            text: z.string().describe('Text to search for (case-insensitive, partial match)'),
+        }),
+    },
     trace_get_element_styles: {
         method: 'get_element_styles',
         description: 'Get full computed style object.',
@@ -210,8 +246,28 @@ export const TOOLS = {
             selector: z.string().describe('CSS selector'),
         }),
     },
+    trace_check_layout_issues: {
+        method: 'check_layout_issues',
+        description: 'Find ALL layout issues: overlapping elements, hidden buttons/links, text overflow. Use when debugging visual bugs.',
+        schema: z.object({}),
+    },
+    trace_find_overlapping_elements: {
+        method: 'find_overlapping_elements',
+        description: 'Find elements that overlap and block each other (like invisible overlays covering buttons).',
+        schema: z.object({}),
+    },
+    trace_find_ghost_blockers: {
+        method: 'find_ghost_blockers',
+        description: 'Find INVISIBLE elements blocking user interaction! Detects: opacity:0 overlays, transparent full-screen blockers, modal backdrops left open, high z-index empty elements. Use when user says "why can\'t I click X?"',
+        schema: z.object({}),
+    },
+    trace_find_hidden_interactive_elements: {
+        method: 'find_hidden_interactive_elements',
+        description: 'Find buttons, links, inputs that are hidden but should be visible.',
+        schema: z.object({}),
+    },
     // ============================================
-    // DEBUGGER TOOLS (24)
+    // DEBUGGER TOOLS (27)
     // ============================================
     trace_get_debugger_state: {
         method: 'get_debugger_state',
@@ -260,6 +316,15 @@ export const TOOLS = {
             expression: z.string().describe('JS code to evaluate'),
         }),
     },
+    trace_set_conditional_breakpoint: {
+        method: 'set_conditional_breakpoint',
+        description: 'Set a breakpoint that only triggers when a condition is met.',
+        schema: z.object({
+            url: z.string().describe('Script URL pattern'),
+            line: z.number().describe('Line number'),
+            condition: z.string().describe('JS condition expression'),
+        }),
+    },
     trace_set_exception_breakpoint: {
         method: 'set_exception_breakpoint',
         description: 'Pause on All or Uncaught exceptions.',
@@ -339,7 +404,7 @@ export const TOOLS = {
         description: 'Continue execution.',
         schema: z.object({}),
     },
-    trace_set_dom_breakpoint: {
+    trace_set_dom_breakpoint_by_selector: {
         method: 'set_dom_breakpoint_by_selector',
         description: 'Break on node modification.',
         schema: z.object({
@@ -361,8 +426,21 @@ export const TOOLS = {
             enable: z.boolean().describe('True to enable, false to disable'),
         }),
     },
+    trace_get_variable_preview: {
+        method: 'get_variable_preview',
+        description: 'Get current variable values while debugging.',
+        schema: z.object({}),
+    },
+    trace_debug_and_analyze: {
+        method: 'debug_and_analyze',
+        description: 'Combined tool: set breakpoint, capture state, and analyze.',
+        schema: z.object({
+            url: z.string().describe('Script URL'),
+            line: z.number().describe('Line number'),
+        }),
+    },
     // ============================================
-    // SOURCE TOOLS (8)
+    // SOURCE TOOLS (11)
     // ============================================
     trace_list_scripts: {
         method: 'list_scripts',
@@ -414,6 +492,23 @@ export const TOOLS = {
             scriptId: z.string().describe('Script ID'),
         }),
     },
+    trace_map_call_stack: {
+        method: 'map_call_stack',
+        description: 'Map the current call stack to original source locations using source maps.',
+        schema: z.object({}),
+    },
+    trace_list_blackbox_patterns: {
+        method: 'list_blackbox_patterns',
+        description: 'List current blackboxed script patterns (ignored during debugging).',
+        schema: z.object({}),
+    },
+    trace_analyze_fetch_origin: {
+        method: 'analyze_fetch_origin',
+        description: 'Analyze where a fetch/XHR request originated in the code.',
+        schema: z.object({
+            url: z.string().describe('URL pattern to match'),
+        }),
+    },
     // ============================================
     // PERFORMANCE TOOLS (4)
     // ============================================
@@ -583,6 +678,20 @@ export const TOOLS = {
             cacheName: z.string(),
         }),
     },
+    trace_clear_indexeddb: {
+        method: 'clear_indexeddb',
+        description: 'Clear an IndexedDB database.',
+        schema: z.object({
+            database: z.string().describe('Database name'),
+        }),
+    },
+    trace_delete_cache: {
+        method: 'delete_cache',
+        description: 'Delete a cache from Cache Storage.',
+        schema: z.object({
+            cacheName: z.string().describe('Cache name'),
+        }),
+    },
     // ============================================
     // SECURITY TOOLS (3)
     // ============================================
@@ -741,6 +850,89 @@ export const TOOLS = {
         }),
     },
     // ============================================
+    // FULLSTACK DEBUGGING TOOLS (4)
+    // ============================================
+    trace_test_api_endpoint: {
+        method: 'test_api_endpoint',
+        description: 'Make a request to the configured backend API. WARNING: may bypass CORS/auth restrictions.',
+        schema: z.object({
+            path: z.string().describe('API path (e.g., /users, /products/123)'),
+            method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).describe('HTTP method'),
+            body: z.any().optional().describe('Request body for POST/PUT/PATCH'),
+            headers: z.record(z.string()).optional().describe('Additional headers'),
+        }),
+    },
+    trace_replay_failed_api: {
+        method: 'replay_failed_api',
+        description: 'Replay a failed API request from the network log with optional modifications.',
+        schema: z.object({
+            requestId: z.string().describe('ID of the failed request to replay'),
+            modifications: z.any().optional().describe('Optional modifications: { headers, body, queryParams }'),
+        }),
+    },
+    trace_trace_request_flow: {
+        method: 'trace_request_flow',
+        description: 'Trace a request from frontend -> backend -> database. Correlates network request with API logs and DB queries.',
+        schema: z.object({
+            url: z.string().describe('URL pattern of the request to trace'),
+            correlationId: z.string().optional().describe('Optional X-Request-ID or correlation header'),
+        }),
+    },
+    trace_get_fullstack_config: {
+        method: 'get_fullstack_config',
+        description: 'Get the current full-stack debugging configuration (backend URL, DB type).',
+        schema: z.object({}),
+    },
+    // ============================================
+    // NODE.JS SERVER DEBUGGING TOOLS (7)
+    // ============================================
+    trace_connect_node_debugger: {
+        method: 'connect_node_debugger',
+        description: 'Connect to Node.js inspector (requires server started with --inspect). Auto-discovers on port 9229.',
+        schema: z.object({
+            port: z.number().optional().describe('Inspector port (default: 9229)'),
+        }),
+    },
+    trace_node_list_scripts: {
+        method: 'node_list_scripts',
+        description: 'List all server-side scripts loaded by Node.js (excludes node_modules and builtins).',
+        schema: z.object({}),
+    },
+    trace_node_get_source: {
+        method: 'node_get_source',
+        description: 'Read the source code of a server-side Node.js script.',
+        schema: z.object({
+            scriptId: z.string().describe('Script ID from node_list_scripts'),
+        }),
+    },
+    trace_node_set_breakpoint: {
+        method: 'node_set_breakpoint',
+        description: 'Set a breakpoint in server-side Node.js code.',
+        schema: z.object({
+            url: z.string().describe('Script URL or filename pattern'),
+            line: z.number().describe('Line number'),
+        }),
+    },
+    trace_node_get_variables: {
+        method: 'node_get_variables',
+        description: 'Get server-side variable values when Node.js debugger is paused.',
+        schema: z.object({}),
+    },
+    trace_node_step_debugger: {
+        method: 'node_step_debugger',
+        description: 'Step through server-side Node.js code.',
+        schema: z.object({
+            action: z.enum(['stepOver', 'stepInto', 'stepOut', 'resume']).describe('Step action'),
+        }),
+    },
+    trace_node_evaluate: {
+        method: 'node_evaluate',
+        description: 'Evaluate an expression in the Node.js server context.',
+        schema: z.object({
+            expression: z.string().describe('JavaScript expression to evaluate in Node.js'),
+        }),
+    },
+    // ============================================
     // CONNECTION & META (2)
     // ============================================
     trace_connect: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@probebrowser/trace-mcp",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Trace MCP - Bridge between AI Agents and Trace",
   "homepage": "https://trace.probebrowser.com/",
   "main": "dist/index.js",
@@ -11,6 +11,9 @@
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
@@ -20,11 +23,13 @@
     "@types/express": "^5.0.6",
     "cors": "^2.8.6",
     "express": "^5.2.1",
-    "zod": "^3.23.0"
+    "zod": "^3.23.0",
+    "zod-to-json-schema": "^3.25.1"
   },
   "devDependencies": {
     "@types/node": "^20.12.0",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
   },
   "publishConfig": {
     "access": "public"

package/src/server.ts

@@ -12,18 +12,23 @@ import {
 import { Trace, ALL_TOOLS } from '@probebrowser/sdk';
 import { TOOLS } from './tools.js';
 import { z } from 'zod';
+import { zodToJsonSchema as _zodToJsonSchema } from 'zod-to-json-schema';
 
 // Schema conversion helper
 function zodToJsonSchema(schema: z.ZodType<any>): any {
+    const jsonSchema = _zodToJsonSchema(schema, { target: 'openApi3' }) as any;
+    // MCP expects { type: 'object', properties: {...}, required: [...] }
     return {
         type: 'object',
-        properties: {}, // Simplified
+        properties: jsonSchema.properties || {},
+        required: jsonSchema.required || [],
     };
 }
 
 export class TraceMcpServer {
     private server: Server;
     private trace: Trace;
+    private connected = false;
 
     constructor() {
         this.server = new Server(
@@ -97,7 +102,7 @@ export class TraceMcpServer {
 
             if (!method) throw new Error(`Unknown tool: ${toolName}`);
 
-            const isConnected = !!this.trace.getCurrentUrl();
+            const isConnected = this.connected;
 
             try {
                 let result;
@@ -107,6 +112,7 @@ export class TraceMcpServer {
                     const url = String(request.params.arguments?.url);
                     // Re-init trace if headless mode changes? For now just connect.
                     await this.trace.connect(url);
+                    this.connected = true;
                     return { content: [{ type: 'text', text: `Connected to ${url}` }] };
                 }
 
@@ -123,19 +129,19 @@ export class TraceMcpServer {
 
                     const prompt = String(request.params.arguments?.prompt || request.params.arguments?.q || 'Analyze page');
 
-                    // Delegate to SDK's queryDeep which calls Azure /v1/agent-step
-                    const analysis = await this.trace.queryDeep(prompt);
+                    // Delegate to SDK's query which runs AI-powered deep debug
+                    const debugResult = await this.trace.query(prompt);
 
                     // Return the conclusion and steps
                     return {
                         content: [
-                            { type: 'text', text: `### Conclusion\n${analysis.conclusion}\n\n### Steps Taken\n${analysis.steps.map(s => `- ${s.tool}: ${s.success ? 'Success' : 'Failed'}`).join('\n')}` }
+                            { type: 'text', text: `### Summary\n${debugResult.analysis.summary}\n\n### Steps Taken\n${debugResult.execution.results.map((r: any) => `- ${r.tool}: ${r.success ? 'Success' : 'Failed'}`).join('\n')}` }
                         ]
                     };
                 }
 
                 // 3. Handle Standard SDK Tools
-                result = await this.trace.executeTool(toolDef.method, request.params.arguments as any);
+                result = await this.trace.tool(toolDef.method, (request.params.arguments || {}) as Record<string, unknown>);
 
                 return {
                     content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -196,13 +202,13 @@ export class TraceMcpServer {
 
         this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             const uri = request.params.uri;
-            if (!this.trace.getCurrentUrl()) {
+            if (!this.connected) {
                 throw new Error('Not connected. Call trace_connect first.');
             }
 
             // --- Console ---
             if (uri === 'trace://console/errors') {
-                const logs = await this.trace.executeTool('get_console_errors', {});
+                const logs = await this.trace.tool('get_console_errors', {});
                 return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(logs, null, 2) }] };
             }
             if (uri === 'trace://console/logs') {
@@ -211,23 +217,23 @@ export class TraceMcpServer {
                 // For now, let's return the summary as it contains counts.
                 // Ideally SDK should expose 'get_all_logs'.
                 // Fallback: use get_console_errors
-                const logs = await this.trace.executeTool('get_console_summary', {});
+                const logs = await this.trace.tool('get_console_summary', {});
                 return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(logs, null, 2) }] };
             }
 
             // --- Network ---
             if (uri === 'trace://network/failed') {
-                const reqs = await this.trace.executeTool('get_network_failed', {});
+                const reqs = await this.trace.tool('get_network_failed', {});
                 return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(reqs, null, 2) }] };
             }
             if (uri === 'trace://network/all') {
-                const reqs = await this.trace.executeTool('get_network_summary', {});
+                const reqs = await this.trace.tool('get_network_summary', {});
                 return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(reqs, null, 2) }] };
             }
 
             // --- DOM ---
             if (uri === 'trace://dom/tree') {
-                const tree = await this.trace.executeTool('get_dom_tree', { depth: 2 });
+                const tree = await this.trace.tool('get_dom_tree', { depth: 2 });
                 return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(tree, null, 2) }] };
             }