mcp-web-inspector 0.1.0

package/dist/tools/api/base.d.ts

@@ -0,0 +1,33 @@
+import type { APIRequestContext } from 'playwright';
+import { ToolHandler, ToolContext, ToolResponse } from '../common/types.js';
+/**
+ * Base class for all API-based tools
+ * Provides common functionality and error handling
+ */
+export declare abstract class ApiToolBase implements ToolHandler {
+    protected server: any;
+    constructor(server: any);
+    /**
+     * Main execution method that all tools must implement
+     */
+    abstract execute(args: any, context: ToolContext): Promise<ToolResponse>;
+    /**
+     * Ensures an API context is available and returns it
+     * @param context The tool context containing apiContext
+     * @returns The apiContext or null if not available
+     */
+    protected ensureApiContext(context: ToolContext): APIRequestContext | null;
+    /**
+     * Validates that an API context is available and returns an error response if not
+     * @param context The tool context
+     * @returns Either null if apiContext is available, or an error response
+     */
+    protected validateApiContextAvailable(context: ToolContext): ToolResponse | null;
+    /**
+     * Safely executes an API operation with proper error handling
+     * @param context The tool context
+     * @param operation The async operation to perform
+     * @returns The tool response
+     */
+    protected safeExecute(context: ToolContext, operation: (apiContext: APIRequestContext) => Promise<ToolResponse>): Promise<ToolResponse>;
+}

package/dist/tools/api/base.js

@@ -0,0 +1,49 @@
+import { createErrorResponse } from '../common/types.js';
+/**
+ * Base class for all API-based tools
+ * Provides common functionality and error handling
+ */
+export class ApiToolBase {
+    constructor(server) {
+        this.server = server;
+    }
+    /**
+     * Ensures an API context is available and returns it
+     * @param context The tool context containing apiContext
+     * @returns The apiContext or null if not available
+     */
+    ensureApiContext(context) {
+        if (!context.apiContext) {
+            return null;
+        }
+        return context.apiContext;
+    }
+    /**
+     * Validates that an API context is available and returns an error response if not
+     * @param context The tool context
+     * @returns Either null if apiContext is available, or an error response
+     */
+    validateApiContextAvailable(context) {
+        if (!this.ensureApiContext(context)) {
+            return createErrorResponse("API context not initialized");
+        }
+        return null;
+    }
+    /**
+     * Safely executes an API operation with proper error handling
+     * @param context The tool context
+     * @param operation The async operation to perform
+     * @returns The tool response
+     */
+    async safeExecute(context, operation) {
+        const apiError = this.validateApiContextAvailable(context);
+        if (apiError)
+            return apiError;
+        try {
+            return await operation(context.apiContext);
+        }
+        catch (error) {
+            return createErrorResponse(`API operation failed: ${error.message}`);
+        }
+    }
+}

package/dist/tools/api/index.d.ts

@@ -0,0 +1,2 @@
+export * from './base.js';
+export * from './requests.js';

package/dist/tools/api/index.js

@@ -0,0 +1,3 @@
+export * from './base.js';
+export * from './requests.js';
+// TODO: Add exports for other API tools as they are implemented 

package/dist/tools/api/requests.d.ts

@@ -0,0 +1,47 @@
+import { ApiToolBase } from './base.js';
+import { ToolContext, ToolResponse } from '../common/types.js';
+/**
+ * Tool for making GET requests
+ */
+export declare class GetRequestTool extends ApiToolBase {
+    /**
+     * Execute the GET request tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}
+/**
+ * Tool for making POST requests
+ */
+export declare class PostRequestTool extends ApiToolBase {
+    /**
+     * Execute the POST request tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}
+/**
+ * Tool for making PUT requests
+ */
+export declare class PutRequestTool extends ApiToolBase {
+    /**
+     * Execute the PUT request tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}
+/**
+ * Tool for making PATCH requests
+ */
+export declare class PatchRequestTool extends ApiToolBase {
+    /**
+     * Execute the PATCH request tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}
+/**
+ * Tool for making DELETE requests
+ */
+export declare class DeleteRequestTool extends ApiToolBase {
+    /**
+     * Execute the DELETE request tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/api/requests.js

@@ -0,0 +1,168 @@
+import { ApiToolBase } from './base.js';
+import { createSuccessResponse, createErrorResponse } from '../common/types.js';
+/**
+ * Tool for making GET requests
+ */
+export class GetRequestTool extends ApiToolBase {
+    /**
+     * Execute the GET request tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (apiContext) => {
+            const response = await apiContext.get(args.url);
+            let responseText;
+            try {
+                responseText = await response.text();
+            }
+            catch (error) {
+                responseText = "Unable to get response text";
+            }
+            return createSuccessResponse([
+                `GET request to ${args.url}`,
+                `Status: ${response.status()} ${response.statusText()}`,
+                `Response: ${responseText.substring(0, 1000)}${responseText.length > 1000 ? '...' : ''}`
+            ]);
+        });
+    }
+}
+/**
+ * Tool for making POST requests
+ */
+export class PostRequestTool extends ApiToolBase {
+    /**
+     * Execute the POST request tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (apiContext) => {
+            // Check if the value is valid JSON if it starts with { or [
+            if (args.value && typeof args.value === 'string' &&
+                (args.value.startsWith('{') || args.value.startsWith('['))) {
+                try {
+                    JSON.parse(args.value);
+                }
+                catch (error) {
+                    return createErrorResponse(`Failed to parse request body: ${error.message}`);
+                }
+            }
+            const response = await apiContext.post(args.url, {
+                data: typeof args.value === 'string' ? JSON.parse(args.value) : args.value,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(args.token ? { 'Authorization': `Bearer ${args.token}` } : {}),
+                    ...(args.headers || {})
+                }
+            });
+            let responseText;
+            try {
+                responseText = await response.text();
+            }
+            catch (error) {
+                responseText = "Unable to get response text";
+            }
+            return createSuccessResponse([
+                `POST request to ${args.url}`,
+                `Status: ${response.status()} ${response.statusText()}`,
+                `Response: ${responseText.substring(0, 1000)}${responseText.length > 1000 ? '...' : ''}`
+            ]);
+        });
+    }
+}
+/**
+ * Tool for making PUT requests
+ */
+export class PutRequestTool extends ApiToolBase {
+    /**
+     * Execute the PUT request tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (apiContext) => {
+            // Check if the value is valid JSON if it starts with { or [
+            if (args.value && typeof args.value === 'string' &&
+                (args.value.startsWith('{') || args.value.startsWith('['))) {
+                try {
+                    JSON.parse(args.value);
+                }
+                catch (error) {
+                    return createErrorResponse(`Failed to parse request body: ${error.message}`);
+                }
+            }
+            const response = await apiContext.put(args.url, {
+                data: args.value
+            });
+            let responseText;
+            try {
+                responseText = await response.text();
+            }
+            catch (error) {
+                responseText = "Unable to get response text";
+            }
+            return createSuccessResponse([
+                `PUT request to ${args.url}`,
+                `Status: ${response.status()} ${response.statusText()}`,
+                `Response: ${responseText.substring(0, 1000)}${responseText.length > 1000 ? '...' : ''}`
+            ]);
+        });
+    }
+}
+/**
+ * Tool for making PATCH requests
+ */
+export class PatchRequestTool extends ApiToolBase {
+    /**
+     * Execute the PATCH request tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (apiContext) => {
+            // Check if the value is valid JSON if it starts with { or [
+            if (args.value && typeof args.value === 'string' &&
+                (args.value.startsWith('{') || args.value.startsWith('['))) {
+                try {
+                    JSON.parse(args.value);
+                }
+                catch (error) {
+                    return createErrorResponse(`Failed to parse request body: ${error.message}`);
+                }
+            }
+            const response = await apiContext.patch(args.url, {
+                data: args.value
+            });
+            let responseText;
+            try {
+                responseText = await response.text();
+            }
+            catch (error) {
+                responseText = "Unable to get response text";
+            }
+            return createSuccessResponse([
+                `PATCH request to ${args.url}`,
+                `Status: ${response.status()} ${response.statusText()}`,
+                `Response: ${responseText.substring(0, 1000)}${responseText.length > 1000 ? '...' : ''}`
+            ]);
+        });
+    }
+}
+/**
+ * Tool for making DELETE requests
+ */
+export class DeleteRequestTool extends ApiToolBase {
+    /**
+     * Execute the DELETE request tool
+     */
+    async execute(args, context) {
+        return this.safeExecute(context, async (apiContext) => {
+            const response = await apiContext.delete(args.url);
+            let responseText;
+            try {
+                responseText = await response.text();
+            }
+            catch (error) {
+                responseText = "Unable to get response text";
+            }
+            return createSuccessResponse([
+                `DELETE request to ${args.url}`,
+                `Status: ${response.status()} ${response.statusText()}`,
+                `Response: ${responseText.substring(0, 1000)}${responseText.length > 1000 ? '...' : ''}`
+            ]);
+        });
+    }
+}

package/dist/tools/browser/base.d.ts

@@ -0,0 +1,51 @@
+import type { Page } from 'playwright';
+import { ToolHandler, ToolContext, ToolResponse } from '../common/types.js';
+/**
+ * Base class for all browser-based tools
+ * Provides common functionality and error handling
+ */
+export declare abstract class BrowserToolBase implements ToolHandler {
+    protected server: any;
+    constructor(server: any);
+    /**
+     * Main execution method that all tools must implement
+     */
+    abstract execute(args: any, context: ToolContext): Promise<ToolResponse>;
+    /**
+     * Normalize selector shortcuts to full Playwright selectors
+     * - "testid:foo" → "[data-testid='foo']"
+     * - "data-test:bar" → "[data-test='bar']"
+     * - "data-cy:baz" → "[data-cy='baz']"
+     * - Everything else → pass through
+     * @param selector The selector string
+     * @returns Normalized selector
+     */
+    protected normalizeSelector(selector: string): string;
+    /**
+     * Ensures a page is available and returns it
+     * @param context The tool context containing browser and page
+     * @returns The page or null if not available
+     */
+    protected ensurePage(context: ToolContext): Page | null;
+    /**
+     * Validates that a page is available and returns an error response if not
+     * @param context The tool context
+     * @returns Either null if page is available, or an error response
+     */
+    protected validatePageAvailable(context: ToolContext): ToolResponse | null;
+    /**
+     * Safely executes a browser operation with proper error handling
+     * @param context The tool context
+     * @param operation The async operation to perform
+     * @returns The tool response
+     */
+    protected safeExecute(context: ToolContext, operation: (page: Page) => Promise<ToolResponse>): Promise<ToolResponse>;
+    /**
+     * Record that a user interaction occurred (for console log filtering)
+     */
+    protected recordInteraction(): void;
+    /**
+     * Record that a navigation occurred (for console log filtering)
+     */
+    protected recordNavigation(): void;
+}

package/dist/tools/browser/base.js

@@ -0,0 +1,111 @@
+import { createErrorResponse } from '../common/types.js';
+/**
+ * Base class for all browser-based tools
+ * Provides common functionality and error handling
+ */
+export class BrowserToolBase {
+    constructor(server) {
+        this.server = server;
+    }
+    /**
+     * Normalize selector shortcuts to full Playwright selectors
+     * - "testid:foo" → "[data-testid='foo']"
+     * - "data-test:bar" → "[data-test='bar']"
+     * - "data-cy:baz" → "[data-cy='baz']"
+     * - Everything else → pass through
+     * @param selector The selector string
+     * @returns Normalized selector
+     */
+    normalizeSelector(selector) {
+        const prefixMap = {
+            'testid:': 'data-testid',
+            'data-test:': 'data-test',
+            'data-cy:': 'data-cy',
+        };
+        for (const [prefix, attr] of Object.entries(prefixMap)) {
+            if (selector.startsWith(prefix)) {
+                const value = selector.slice(prefix.length);
+                return `[${attr}="${value}"]`;
+            }
+        }
+        return selector; // CSS, text=, etc. pass through
+    }
+    /**
+     * Ensures a page is available and returns it
+     * @param context The tool context containing browser and page
+     * @returns The page or null if not available
+     */
+    ensurePage(context) {
+        if (!context.page) {
+            return null;
+        }
+        return context.page;
+    }
+    /**
+     * Validates that a page is available and returns an error response if not
+     * @param context The tool context
+     * @returns Either null if page is available, or an error response
+     */
+    validatePageAvailable(context) {
+        if (!this.ensurePage(context)) {
+            return createErrorResponse("Browser page not initialized!");
+        }
+        return null;
+    }
+    /**
+     * Safely executes a browser operation with proper error handling
+     * @param context The tool context
+     * @param operation The async operation to perform
+     * @returns The tool response
+     */
+    async safeExecute(context, operation) {
+        const pageError = this.validatePageAvailable(context);
+        if (pageError)
+            return pageError;
+        try {
+            // Verify browser is connected before proceeding
+            if (context.browser && !context.browser.isConnected()) {
+                // If browser exists but is disconnected, reset state
+                const { resetBrowserState } = await import('../../toolHandler.js');
+                resetBrowserState();
+                return createErrorResponse("Browser is disconnected. Please retry the operation.");
+            }
+            // Check if page is closed
+            if (context.page.isClosed()) {
+                return createErrorResponse("Page is closed. Please retry the operation.");
+            }
+            return await operation(context.page);
+        }
+        catch (error) {
+            const errorMessage = error.message;
+            // Check for common browser disconnection errors
+            if (errorMessage.includes("Target page, context or browser has been closed") ||
+                errorMessage.includes("Target closed") ||
+                errorMessage.includes("Browser has been disconnected") ||
+                errorMessage.includes("Protocol error") ||
+                errorMessage.includes("Connection closed")) {
+                // Reset browser state on connection issues
+                const { resetBrowserState } = await import('../../toolHandler.js');
+                resetBrowserState();
+                return createErrorResponse(`Browser connection error: ${errorMessage}. Connection has been reset - please retry the operation.`);
+            }
+            return createErrorResponse(`Operation failed: ${errorMessage}`);
+        }
+    }
+    /**
+     * Record that a user interaction occurred (for console log filtering)
+     */
+    recordInteraction() {
+        import('../../toolHandler.js').then(({ updateLastInteractionTimestamp }) => {
+            updateLastInteractionTimestamp();
+        });
+    }
+    /**
+     * Record that a navigation occurred (for console log filtering)
+     */
+    recordNavigation() {
+        import('../../toolHandler.js').then(({ updateLastNavigationTimestamp }) => {
+            updateLastNavigationTimestamp();
+        });
+    }
+}

package/dist/tools/browser/cleanSession.d.ts

@@ -0,0 +1,10 @@
+import { BrowserToolBase } from './base.js';
+import type { ToolContext, ToolResponse } from '../common/types.js';
+/**
+ * Tool to clean/remove session data
+ */
+export declare class CleanSessionTool extends BrowserToolBase {
+    execute(args: {
+        userDataDir?: string;
+    }, context: ToolContext): Promise<ToolResponse>;
+}

package/dist/tools/browser/cleanSession.js

@@ -0,0 +1,42 @@
+import { BrowserToolBase } from './base.js';
+import { rmSync, existsSync } from 'fs';
+/**
+ * Tool to clean/remove session data
+ */
+export class CleanSessionTool extends BrowserToolBase {
+    async execute(args, context) {
+        const { server } = context;
+        // Get the session directory from args or use the default
+        const sessionDir = args.userDataDir || './.mcp-web-inspector';
+        try {
+            // Check if the directory exists
+            if (!existsSync(sessionDir)) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Session directory does not exist: ${sessionDir}`,
+                        }],
+                    isError: false,
+                };
+            }
+            // Remove the directory recursively
+            rmSync(sessionDir, { recursive: true, force: true });
+            return {
+                content: [{
+                        type: "text",
+                        text: `Session data cleaned successfully from: ${sessionDir}`,
+                    }],
+                isError: false,
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Failed to clean session data: ${error.message}`,
+                    }],
+                isError: true,
+            };
+        }
+    }
+}

package/dist/tools/browser/comparePositions.d.ts

@@ -0,0 +1,11 @@
+import { BrowserToolBase } from './base.js';
+import { ToolContext, ToolResponse } from '../common/types.js';
+/**
+ * Tool for comparing positions and sizes of two elements
+ */
+export declare class ComparePositionsTool extends BrowserToolBase {
+    /**
+     * Execute the compare positions tool
+     */
+    execute(args: any, context: ToolContext): Promise<ToolResponse>;
+}