playwright-stealth-mcp-server 0.0.1 → 0.0.3

package/README.md

@@ -62,11 +62,13 @@ Add to your Claude Desktop config file:
 
 ### Environment Variables
 
-| Variable       | Description                                      | Default |
-| -------------- | ------------------------------------------------ | ------- |
-| `STEALTH_MODE` | Enable stealth mode with anti-detection measures | `false` |
-| `HEADLESS`     | Run browser in headless mode                     | `true`  |
-| `TIMEOUT`      | Default execution timeout in milliseconds        | `30000` |
+| Variable                  | Description                                                                | Default                       |
+| ------------------------- | -------------------------------------------------------------------------- | ----------------------------- |
+| `STEALTH_MODE`            | Enable stealth mode with anti-detection measures                           | `false`                       |
+| `HEADLESS`                | Run browser in headless mode                                               | `true`                        |
+| `TIMEOUT`                 | Default timeout for Playwright actions (click, fill, etc.) in milliseconds | `30000`                       |
+| `NAVIGATION_TIMEOUT`      | Default timeout for page navigation (goto, reload, etc.) in milliseconds   | `60000`                       |
+| `SCREENSHOT_STORAGE_PATH` | Directory for storing screenshots                                          | `/tmp/playwright-screenshots` |
 
 ## Available Tools
 
@@ -89,11 +91,19 @@ return title;
 
 ### `browser_screenshot`
 
-Take a screenshot of the current page.
+Take a screenshot of the current page. Screenshots are saved to filesystem storage and can be accessed later via MCP resources.
 
 **Parameters:**
 
 - `fullPage` (optional): Capture full scrollable page. Default: `false`
+- `resultHandling` (optional): How to handle the result:
+  - `saveAndReturn` (default): Saves to storage AND returns inline base64 image
+  - `saveOnly`: Saves to storage and returns only the resource URI (more efficient for large screenshots)
+
+**Returns:**
+
+- With `saveAndReturn`: Inline base64 PNG image plus a `resource_link` with the file URI
+- With `saveOnly`: Only a `resource_link` with the `file://` URI to the saved screenshot
 
 ### `browser_get_state`
 
@@ -103,6 +113,15 @@ Get the current browser state including URL, title, and configuration.
 
 Close the browser session. A new browser will be launched on the next `browser_execute` call.
 
+## MCP Resources
+
+The server exposes saved screenshots as MCP resources. Clients can use:
+
+- `resources/list`: List all saved screenshots with their URIs and metadata
+- `resources/read`: Read a screenshot by its `file://` URI
+
+This allows clients to access previously captured screenshots without needing to take new ones.
+
 ## Usage Examples
 
 ### Navigate and Extract Data

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-stealth-mcp-server",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Local implementation of Playwright Stealth MCP server",
   "mcpName": "com.pulsemcp.servers/playwright-stealth",
   "main": "build/index.js",

package/shared/index.d.ts

@@ -1,4 +1,6 @@
 export { createMCPServer, type IPlaywrightClient, type ClientFactory } from './server.js';
 export { createRegisterTools } from './tools.js';
+export { registerResources } from './resources.js';
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';
+export * from './storage/index.js';
 //# sourceMappingURL=index.d.ts.map

package/shared/index.js

@@ -1,3 +1,5 @@
 export { createMCPServer } from './server.js';
 export { createRegisterTools } from './tools.js';
+export { registerResources } from './resources.js';
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';
+export * from './storage/index.js';

package/shared/playwright-client/playwright-client.integration-mock.js

@@ -67,5 +67,6 @@ export function createMockPlaywrightClient() {
         stealthMode: false,
         headless: true,
         timeout: 30000,
+        navigationTimeout: 60000,
     });
 }

package/shared/resources.d.ts

@@ -0,0 +1,6 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+/**
+ * Register screenshot resources handlers to an MCP server
+ */
+export declare function registerResources(server: Server): void;
+//# sourceMappingURL=resources.d.ts.map

package/shared/resources.js

@@ -0,0 +1,40 @@
+import { ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { ScreenshotStorageFactory } from './storage/index.js';
+/**
+ * Register screenshot resources handlers to an MCP server
+ */
+export function registerResources(server) {
+    // Register resource list handler
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const storage = await ScreenshotStorageFactory.create();
+        const resources = await storage.list();
+        return {
+            resources: resources.map((resource) => ({
+                uri: resource.uri,
+                name: resource.name,
+                description: resource.description,
+                mimeType: resource.mimeType,
+            })),
+        };
+    });
+    // Register resource read handler
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        const storage = await ScreenshotStorageFactory.create();
+        try {
+            const content = await storage.read(uri);
+            return {
+                contents: [
+                    {
+                        uri: content.uri,
+                        mimeType: content.mimeType,
+                        blob: content.blob,
+                    },
+                ],
+            };
+        }
+        catch {
+            throw new Error(`Resource not found: ${uri}`);
+        }
+    });
+}

package/shared/server.js

@@ -1,5 +1,6 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { createRegisterTools } from './tools.js';
+import { registerResources } from './resources.js';
 /**
  * Playwright client implementation with optional stealth mode
  */
@@ -44,6 +45,9 @@ export class PlaywrightClient {
                 : undefined,
         });
         this.page = await this.context.newPage();
+        // Apply timeout configuration to Playwright
+        this.page.setDefaultTimeout(this.config.timeout);
+        this.page.setDefaultNavigationTimeout(this.config.navigationTimeout);
         // Capture console messages
         this.page.on('console', (msg) => {
             this.consoleMessages.push(`[${msg.type()}] ${msg.text()}`);
@@ -125,10 +129,11 @@ export function createMCPServer() {
     const stealthMode = process.env.STEALTH_MODE === 'true';
     const server = new Server({
         name: 'playwright-stealth-mcp-server',
-        version: '0.0.1',
+        version: '0.0.3',
     }, {
         capabilities: {
             tools: {},
+            resources: {},
         },
     });
     // Track active client for cleanup
@@ -139,15 +144,19 @@ export function createMCPServer() {
             (() => {
                 const headless = process.env.HEADLESS !== 'false';
                 const timeout = parseInt(process.env.TIMEOUT || '30000', 10);
+                const navigationTimeout = parseInt(process.env.NAVIGATION_TIMEOUT || '60000', 10);
                 activeClient = new PlaywrightClient({
                     stealthMode,
                     headless,
                     timeout,
+                    navigationTimeout,
                 });
                 return activeClient;
             });
         const registerTools = createRegisterTools(factory);
         registerTools(server);
+        // Register resources handlers for screenshot storage
+        registerResources(server);
     };
     const cleanup = async () => {
         if (activeClient) {

package/shared/storage/factory.d.ts

@@ -0,0 +1,7 @@
+import { ScreenshotStorage } from './types.js';
+export declare class ScreenshotStorageFactory {
+    private static instance;
+    static create(): Promise<ScreenshotStorage>;
+    static reset(): void;
+}
+//# sourceMappingURL=factory.d.ts.map

package/shared/storage/factory.js

@@ -0,0 +1,17 @@
+import { FileSystemScreenshotStorage } from './filesystem.js';
+export class ScreenshotStorageFactory {
+    static instance = null;
+    static async create() {
+        if (this.instance) {
+            return this.instance;
+        }
+        const rootDir = process.env.SCREENSHOT_STORAGE_PATH;
+        const fsStorage = new FileSystemScreenshotStorage(rootDir);
+        await fsStorage.init();
+        this.instance = fsStorage;
+        return this.instance;
+    }
+    static reset() {
+        this.instance = null;
+    }
+}

package/shared/storage/filesystem.d.ts

@@ -0,0 +1,16 @@
+import { ScreenshotStorage, ScreenshotResourceData, ScreenshotResourceContent, ScreenshotMetadata } from './types.js';
+export declare class FileSystemScreenshotStorage implements ScreenshotStorage {
+    private rootDir;
+    private initialized;
+    constructor(rootDir?: string);
+    init(): Promise<void>;
+    list(): Promise<ScreenshotResourceData[]>;
+    read(uri: string): Promise<ScreenshotResourceContent>;
+    write(base64Data: string, metadata: Omit<ScreenshotMetadata, 'timestamp'>): Promise<string>;
+    exists(uri: string): Promise<boolean>;
+    delete(uri: string): Promise<void>;
+    private fileExists;
+    private uriToFilePath;
+    private generateFileName;
+}
+//# sourceMappingURL=filesystem.d.ts.map

package/shared/storage/filesystem.js

@@ -0,0 +1,126 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+export class FileSystemScreenshotStorage {
+    rootDir;
+    initialized = false;
+    constructor(rootDir) {
+        this.rootDir = rootDir || path.join(os.tmpdir(), 'playwright-screenshots');
+    }
+    async init() {
+        if (this.initialized) {
+            return;
+        }
+        await fs.mkdir(this.rootDir, { recursive: true });
+        this.initialized = true;
+    }
+    async list() {
+        await this.init();
+        const resources = [];
+        try {
+            const files = await fs.readdir(this.rootDir);
+            for (const file of files) {
+                if (file.endsWith('.png')) {
+                    const metadataFile = file.replace('.png', '.json');
+                    const filePath = path.join(this.rootDir, file);
+                    const metadataPath = path.join(this.rootDir, metadataFile);
+                    try {
+                        const metadataContent = await fs.readFile(metadataPath, 'utf-8');
+                        const metadata = JSON.parse(metadataContent);
+                        const uri = `file://${filePath}`;
+                        resources.push({
+                            uri,
+                            name: file,
+                            description: metadata.pageUrl
+                                ? `Screenshot of ${metadata.pageUrl}`
+                                : `Screenshot taken at ${metadata.timestamp}`,
+                            mimeType: 'image/png',
+                            metadata,
+                        });
+                    }
+                    catch {
+                        // Ignore files without metadata
+                    }
+                }
+            }
+        }
+        catch {
+            // Directory might not exist yet
+        }
+        // Sort by timestamp descending (most recent first)
+        resources.sort((a, b) => {
+            const timeA = new Date(a.metadata.timestamp).getTime();
+            const timeB = new Date(b.metadata.timestamp).getTime();
+            return timeB - timeA;
+        });
+        return resources;
+    }
+    async read(uri) {
+        const filePath = this.uriToFilePath(uri);
+        if (!(await this.fileExists(filePath))) {
+            throw new Error(`Resource not found: ${uri}`);
+        }
+        const buffer = await fs.readFile(filePath);
+        const blob = buffer.toString('base64');
+        return {
+            uri,
+            mimeType: 'image/png',
+            blob,
+        };
+    }
+    async write(base64Data, metadata) {
+        await this.init();
+        const timestamp = new Date().toISOString();
+        const fileName = this.generateFileName(timestamp);
+        const filePath = path.join(this.rootDir, fileName);
+        const metadataPath = path.join(this.rootDir, fileName.replace('.png', '.json'));
+        const fullMetadata = {
+            ...metadata,
+            timestamp,
+        };
+        // Write the screenshot image
+        const buffer = Buffer.from(base64Data, 'base64');
+        await fs.writeFile(filePath, buffer);
+        // Write the metadata
+        await fs.writeFile(metadataPath, JSON.stringify(fullMetadata, null, 2), 'utf-8');
+        return `file://${filePath}`;
+    }
+    async exists(uri) {
+        const filePath = this.uriToFilePath(uri);
+        return this.fileExists(filePath);
+    }
+    async delete(uri) {
+        const filePath = this.uriToFilePath(uri);
+        if (!(await this.fileExists(filePath))) {
+            throw new Error(`Resource not found: ${uri}`);
+        }
+        await fs.unlink(filePath);
+        // Also delete metadata file if it exists
+        const metadataPath = filePath.replace('.png', '.json');
+        try {
+            await fs.unlink(metadataPath);
+        }
+        catch {
+            // Ignore if metadata file doesn't exist
+        }
+    }
+    async fileExists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    uriToFilePath(uri) {
+        if (uri.startsWith('file://')) {
+            return uri.substring(7);
+        }
+        throw new Error(`Invalid file URI: ${uri}`);
+    }
+    generateFileName(timestamp) {
+        const timestampPart = timestamp.replace(/[^0-9T-]/g, '').replace('T', '_');
+        return `screenshot_${timestampPart}.png`;
+    }
+}

package/shared/storage/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './factory.js';
+export * from './filesystem.js';
+//# sourceMappingURL=index.d.ts.map

package/shared/storage/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './factory.js';
+export * from './filesystem.js';

package/shared/storage/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Types for screenshot resource storage
+ */
+export interface ScreenshotMetadata {
+    timestamp: string;
+    pageUrl?: string;
+    pageTitle?: string;
+    fullPage: boolean;
+}
+export interface ScreenshotResourceData {
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType: string;
+    metadata: ScreenshotMetadata;
+}
+export interface ScreenshotResourceContent {
+    uri: string;
+    mimeType: string;
+    blob: string;
+}
+export interface ScreenshotStorage {
+    list(): Promise<ScreenshotResourceData[]>;
+    read(uri: string): Promise<ScreenshotResourceContent>;
+    write(base64Data: string, metadata: Omit<ScreenshotMetadata, 'timestamp'>): Promise<string>;
+    exists(uri: string): Promise<boolean>;
+    delete(uri: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/shared/storage/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for screenshot resource storage
+ */
+export {};

package/shared/tools.js

@@ -1,5 +1,6 @@
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
+import { ScreenshotStorageFactory } from './storage/index.js';
 // =============================================================================
 // TOOL SCHEMAS
 // =============================================================================
@@ -9,6 +10,10 @@ const ExecuteSchema = z.object({
 });
 const ScreenshotSchema = z.object({
     fullPage: z.boolean().optional().describe('Capture the full scrollable page. Default: false'),
+    resultHandling: z
+        .enum(['saveAndReturn', 'saveOnly'])
+        .optional()
+        .describe("How to handle the screenshot result. 'saveAndReturn' (default) saves to storage and returns inline base64, 'saveOnly' saves to storage and returns only the resource URI"),
 });
 // =============================================================================
 // TOOL DESCRIPTIONS
@@ -56,15 +61,23 @@ await page.click('button[type="submit"]');
 **Note:** When STEALTH_MODE=true, the browser includes anti-detection measures to help bypass bot protection.`;
 const SCREENSHOT_DESCRIPTION = `Take a screenshot of the current page.
 
-Captures the visible viewport or full page as a PNG image encoded in base64.
+Captures the visible viewport or full page as a PNG image. Screenshots are saved to filesystem storage and can be accessed later via MCP resources.
+
+**Parameters:**
+- \`fullPage\`: Whether to capture the full scrollable page (default: false)
+- \`resultHandling\`: How to handle the result:
+  - \`saveAndReturn\` (default): Saves to storage AND returns inline base64 image
+  - \`saveOnly\`: Saves to storage and returns only the resource URI (more efficient for large screenshots)
 
 **Returns:**
-- Base64-encoded PNG image data
+- With \`saveAndReturn\`: Inline base64 PNG image data plus a resource_link to the saved file
+- With \`saveOnly\`: A resource_link with the \`file://\` URI to the saved screenshot
 
 **Use cases:**
 - Verify page state after navigation
 - Debug automation issues
-- Capture visual content for analysis`;
+- Capture visual content for analysis
+- Store screenshots for later reference via MCP resources`;
 const GET_STATE_DESCRIPTION = `Get the current browser state.
 
 Returns information about the current browser session including the URL, page title, and whether a browser is open.
@@ -161,14 +174,47 @@ export function createRegisterTools(clientFactory) {
                         type: 'boolean',
                         description: 'Capture the full scrollable page. Default: false',
                     },
+                    resultHandling: {
+                        type: 'string',
+                        enum: ['saveAndReturn', 'saveOnly'],
+                        description: "How to handle the screenshot result. 'saveAndReturn' (default) saves to storage and returns inline base64, 'saveOnly' saves to storage and returns only the resource URI",
+                    },
                 },
             },
             handler: async (args) => {
                 try {
                     const validated = ScreenshotSchema.parse(args);
-                    const base64 = await getClient().screenshot({
+                    const client = getClient();
+                    const base64 = await client.screenshot({
                         fullPage: validated.fullPage,
                     });
+                    // Get page metadata for the screenshot
+                    const state = await client.getState();
+                    // Save to storage
+                    const storage = await ScreenshotStorageFactory.create();
+                    const uri = await storage.write(base64, {
+                        pageUrl: state.currentUrl,
+                        pageTitle: state.title,
+                        fullPage: validated.fullPage ?? false,
+                    });
+                    const resultHandling = validated.resultHandling ?? 'saveAndReturn';
+                    // Generate a name from the URI for the resource link
+                    const fileName = uri.split('/').pop() || 'screenshot.png';
+                    if (resultHandling === 'saveOnly') {
+                        // Return only the resource link
+                        return {
+                            content: [
+                                {
+                                    type: 'resource_link',
+                                    uri,
+                                    name: fileName,
+                                    description: `Screenshot saved to ${uri}`,
+                                    mimeType: 'image/png',
+                                },
+                            ],
+                        };
+                    }
+                    // Default: saveAndReturn - return both inline image and resource link
                     return {
                         content: [
                             {
@@ -176,6 +222,13 @@ export function createRegisterTools(clientFactory) {
                                 data: base64,
                                 mimeType: 'image/png',
                             },
+                            {
+                                type: 'resource_link',
+                                uri,
+                                name: fileName,
+                                description: `Screenshot also saved to ${uri}`,
+                                mimeType: 'image/png',
+                            },
                         ],
                     };
                 }

package/shared/types.d.ts

@@ -5,6 +5,7 @@ export interface PlaywrightConfig {
     stealthMode: boolean;
     headless: boolean;
     timeout: number;
+    navigationTimeout: number;
 }
 export interface ExecuteResult {
     success: boolean;