@probebrowser/trace-mcp 1.0.2 → 1.1.0

package/src/tools.ts

@@ -102,9 +102,39 @@ 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({}),
+    },
 
     // ============================================
-    // DOM & UI TOOLS (16)
+    // DIAGNOSTIC (1)
+    // ============================================
+    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',
@@ -120,6 +150,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.',
@@ -213,9 +250,29 @@ 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',
@@ -264,6 +321,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.',
@@ -343,7 +409,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({
@@ -365,9 +431,22 @@ 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',
@@ -419,6 +498,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)
@@ -591,6 +687,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)
@@ -753,6 +863,91 @@ 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)
     // ============================================

package/tests/resources.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect } from 'vitest';
+
+// Test the Resources definitions that the server exposes
+describe('MCP Resources', () => {
+    const EXPECTED_RESOURCES = [
+        {
+            uri: 'trace://console/errors',
+            name: 'Console Errors',
+            mimeType: 'application/json',
+        },
+        {
+            uri: 'trace://console/logs',
+            name: 'All Console Logs',
+            mimeType: 'application/json',
+        },
+        {
+            uri: 'trace://network/failed',
+            name: 'Failed Network Requests',
+            mimeType: 'application/json',
+        },
+        {
+            uri: 'trace://network/all',
+            name: 'All Network Traffic',
+            mimeType: 'application/json',
+        },
+        {
+            uri: 'trace://dom/tree',
+            name: 'DOM Tree',
+            mimeType: 'application/json',
+        },
+        {
+            uri: 'trace://screenshot',
+            name: 'Page Screenshot',
+            mimeType: 'image/png',
+        },
+    ];
+
+    describe('Resource URIs', () => {
+        it('should define console/errors resource', () => {
+            const resource = EXPECTED_RESOURCES.find(r => r.uri === 'trace://console/errors');
+            expect(resource).toBeDefined();
+            expect(resource?.name).toBe('Console Errors');
+            expect(resource?.mimeType).toBe('application/json');
+        });
+
+        it('should define console/logs resource', () => {
+            const resource = EXPECTED_RESOURCES.find(r => r.uri === 'trace://console/logs');
+            expect(resource).toBeDefined();
+            expect(resource?.name).toBe('All Console Logs');
+        });
+
+        it('should define network/failed resource', () => {
+            const resource = EXPECTED_RESOURCES.find(r => r.uri === 'trace://network/failed');
+            expect(resource).toBeDefined();
+            expect(resource?.mimeType).toBe('application/json');
+        });
+
+        it('should define network/all resource', () => {
+            const resource = EXPECTED_RESOURCES.find(r => r.uri === 'trace://network/all');
+            expect(resource).toBeDefined();
+            expect(resource?.name).toBe('All Network Traffic');
+        });
+
+        it('should define dom/tree resource', () => {
+            const resource = EXPECTED_RESOURCES.find(r => r.uri === 'trace://dom/tree');
+            expect(resource).toBeDefined();
+            expect(resource?.mimeType).toBe('application/json');
+        });
+
+        it('should define screenshot resource', () => {
+            const resource = EXPECTED_RESOURCES.find(r => r.uri === 'trace://screenshot');
+            expect(resource).toBeDefined();
+            expect(resource?.mimeType).toBe('image/png');
+        });
+    });
+
+    describe('Resource Schema', () => {
+        it('should have 6 resources defined', () => {
+            expect(EXPECTED_RESOURCES.length).toBe(6);
+        });
+
+        it('all resources should have uri, name, and mimeType', () => {
+            for (const resource of EXPECTED_RESOURCES) {
+                expect(resource.uri).toBeDefined();
+                expect(resource.uri.startsWith('trace://')).toBe(true);
+                expect(resource.name).toBeDefined();
+                expect(resource.name.length).toBeGreaterThan(0);
+                expect(resource.mimeType).toBeDefined();
+            }
+        });
+
+        it('all URIs should use trace:// protocol', () => {
+            for (const resource of EXPECTED_RESOURCES) {
+                expect(resource.uri).toMatch(/^trace:\/\//);
+            }
+        });
+    });
+});
+
+describe('MCP Prompts', () => {
+    const EXPECTED_PROMPTS = [
+        {
+            name: 'debug_error',
+            description: 'Analyze the most recent error and suggest a fix',
+        },
+        {
+            name: 'audit_performance',
+            description: 'Check metrics and run a quick profile',
+        },
+        {
+            name: 'verify_security',
+            description: 'Check security headers and SSL status',
+        },
+    ];
+
+    describe('Prompt Definitions', () => {
+        it('should define debug_error prompt', () => {
+            const prompt = EXPECTED_PROMPTS.find(p => p.name === 'debug_error');
+            expect(prompt).toBeDefined();
+            expect(prompt?.description).toContain('error');
+        });
+
+        it('should define audit_performance prompt', () => {
+            const prompt = EXPECTED_PROMPTS.find(p => p.name === 'audit_performance');
+            expect(prompt).toBeDefined();
+            expect(prompt?.description).toContain('metrics');
+        });
+
+        it('should define verify_security prompt', () => {
+            const prompt = EXPECTED_PROMPTS.find(p => p.name === 'verify_security');
+            expect(prompt).toBeDefined();
+            expect(prompt?.description).toContain('security');
+        });
+    });
+
+    describe('Prompt Schema', () => {
+        it('should have 3 prompts defined', () => {
+            expect(EXPECTED_PROMPTS.length).toBe(3);
+        });
+
+        it('all prompts should have name and description', () => {
+            for (const prompt of EXPECTED_PROMPTS) {
+                expect(prompt.name).toBeDefined();
+                expect(prompt.name.length).toBeGreaterThan(0);
+                expect(prompt.description).toBeDefined();
+                expect(prompt.description.length).toBeGreaterThan(0);
+            }
+        });
+    });
+});

package/tests/server.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+
+// We need to mock BEFORE importing the server
+// Create a proper mock of the Server class
+const mockSetRequestHandler = vi.fn();
+const mockConnect = vi.fn().mockResolvedValue(undefined);
+
+vi.mock('@modelcontextprotocol/sdk/server/index.js', () => ({
+    Server: vi.fn().mockImplementation(() => ({
+        setRequestHandler: mockSetRequestHandler,
+        connect: mockConnect,
+    })),
+}));
+
+vi.mock('@modelcontextprotocol/sdk/server/stdio.js', () => ({
+    StdioServerTransport: vi.fn(),
+}));
+
+vi.mock('@modelcontextprotocol/sdk/types.js', () => ({
+    ListToolsRequestSchema: 'ListToolsRequestSchema',
+    CallToolRequestSchema: 'CallToolRequestSchema',
+    ListResourcesRequestSchema: 'ListResourcesRequestSchema',
+    ReadResourceRequestSchema: 'ReadResourceRequestSchema',
+    ListPromptsRequestSchema: 'ListPromptsRequestSchema',
+    GetPromptRequestSchema: 'GetPromptRequestSchema',
+}));
+
+// Mock the SDK
+vi.mock('@probebrowser/sdk', () => ({
+    Trace: vi.fn().mockImplementation(() => ({
+        connect: vi.fn().mockResolvedValue(undefined),
+        getCurrentUrl: vi.fn().mockReturnValue(null),
+        executeTool: vi.fn().mockResolvedValue({ success: true, data: {} }),
+        queryDeep: vi.fn().mockResolvedValue({
+            conclusion: 'Test conclusion',
+            steps: [{ tool: 'test', success: true }],
+        }),
+    })),
+    ALL_TOOLS: [
+        'get_console_errors',
+        'get_network_summary',
+        'get_dom_tree',
+        'click',
+        'type',
+    ],
+}));
+
+// Now import the server
+import { TraceMcpServer } from '../src/server.js';
+
+describe('TraceMcpServer', () => {
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+
+    describe('Initialization', () => {
+        it('should create server instance', () => {
+            const server = new TraceMcpServer();
+            expect(server).toBeDefined();
+            expect(server).toBeInstanceOf(TraceMcpServer);
+        });
+
+        it('should call setRequestHandler during initialization', () => {
+            new TraceMcpServer();
+            // Should be called 6 times: ListTools, CallTool, ListResources, ReadResource, ListPrompts, GetPrompt
+            expect(mockSetRequestHandler).toHaveBeenCalled();
+            expect(mockSetRequestHandler.mock.calls.length).toBeGreaterThanOrEqual(6);
+        });
+
+        it('should initialize with default headless mode', () => {
+            const server = new TraceMcpServer();
+            expect(server).toBeDefined();
+        });
+    });
+
+    describe('Server Configuration', () => {
+        it('should have start method', () => {
+            const server = new TraceMcpServer();
+            expect(typeof server.start).toBe('function');
+        });
+
+        it('should have connect method', () => {
+            const server = new TraceMcpServer();
+            expect(typeof server.connect).toBe('function');
+        });
+
+        it('should set up tool handlers', () => {
+            new TraceMcpServer();
+            // Find the ListToolsRequestSchema handler
+            const listToolsCall = mockSetRequestHandler.mock.calls.find(
+                ([schema]) => schema === 'ListToolsRequestSchema'
+            );
+            expect(listToolsCall).toBeDefined();
+        });
+
+        it('should set up resource handlers', () => {
+            new TraceMcpServer();
+            const listResourcesCall = mockSetRequestHandler.mock.calls.find(
+                ([schema]) => schema === 'ListResourcesRequestSchema'
+            );
+            expect(listResourcesCall).toBeDefined();
+        });
+
+        it('should set up prompt handlers', () => {
+            new TraceMcpServer();
+            const listPromptsCall = mockSetRequestHandler.mock.calls.find(
+                ([schema]) => schema === 'ListPromptsRequestSchema'
+            );
+            expect(listPromptsCall).toBeDefined();
+        });
+    });
+});
+
+describe('Server Environment Configuration', () => {
+    const originalEnv = { ...process.env };
+
+    afterEach(() => {
+        process.env = { ...originalEnv };
+        vi.clearAllMocks();
+    });
+
+    it('should default to headless true when env not set', () => {
+        delete process.env.TRACE_HEADLESS;
+        const server = new TraceMcpServer();
+        expect(server).toBeDefined();
+    });
+
+    it('should set headless to false when explicitly specified', () => {
+        process.env.TRACE_HEADLESS = 'false';
+        const server = new TraceMcpServer();
+        expect(server).toBeDefined();
+    });
+
+    it('should enable verbose mode when specified', () => {
+        process.env.TRACE_VERBOSE = 'true';
+        const server = new TraceMcpServer();
+        expect(server).toBeDefined();
+    });
+
+    it('should use TRACE_API_KEY from environment', () => {
+        process.env.TRACE_API_KEY = 'test-api-key';
+        const server = new TraceMcpServer();
+        expect(server).toBeDefined();
+    });
+});
+
+describe('Handler Registration', () => {
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it('should register all 6 required handlers', () => {
+        new TraceMcpServer();
+        expect(mockSetRequestHandler).toHaveBeenCalledTimes(6);
+    });
+
+    it('handlers should be functions', () => {
+        new TraceMcpServer();
+        for (const [, handler] of mockSetRequestHandler.mock.calls) {
+            expect(typeof handler).toBe('function');
+        }
+    });
+});