cloudflare-browser-rendering-mcp

Instructions

Implementation Reference

• src/server.ts:451-498 (handler)

  MCP tool handler for 'take_screenshot': validates args, delegates to BrowserClient.takeScreenshot(), returns screenshot URL as text content.

  private async handleTakeScreenshot(args: any) {
    // Validate arguments
    if (typeof args !== 'object' || args === null || typeof args.url !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid arguments for take_screenshot');
    }
  
    const { 
      url, 
      width = 1280, 
      height = 800, 
      fullPage = false
    } = args;
  
    try {
      console.error(`[API] Taking screenshot of ${url} with parameters:`, { width, height, fullPage });
      console.error(`[API] Using endpoint: ${process.env.BROWSER_RENDERING_API}`);
      
      // Take the screenshot - returns only the URL
      const screenshotUrl = await this.browserClient.takeScreenshot(url, {
        width,
        height,
        fullPage,
      });
      
      console.error('[API] Screenshot taken successfully, URL:', screenshotUrl);
      
      // Return just the URL as text (without embedding the image)
      return {
        content: [
          {
            type: 'text',
            text: `Screenshot of ${url} is available at: ${screenshotUrl}\n\n(URL provided as text to prevent potential rendering issues)`
          }
        ]
      };
    } catch (error) {
      console.error('[Error] Error taking screenshot:', error);
      return {
        content: [
          {
            type: 'text',
            text: `Error taking screenshot: ${error instanceof Error ? error.message : String(error)}`,
          }
        ],
        isError: true,
      };
    }
  }

• src/server.ts:150-170 (schema)

  Input schema for take_screenshot tool defining parameters: url (required), width, height, fullPage.

  inputSchema: {
    type: 'object',
    properties: {
      url: {
        type: 'string',
        description: 'URL to take a screenshot of',
      },
      width: {
        type: 'number',
        description: 'Width of the viewport in pixels (default: 1280)',
      },
      height: {
        type: 'number',
        description: 'Height of the viewport in pixels (default: 800)',
      },
      fullPage: {
        type: 'boolean',
        description: 'Whether to take a screenshot of the full page or just the viewport (default: false)',
      },
    },
    required: ['url'],

• src/server.ts:147-172 (registration)

  Registration of the take_screenshot tool in the ListTools response, including name, description, and inputSchema.

  {
    name: 'take_screenshot',
    description: 'Takes a screenshot of a web page and returns it as an image',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'URL to take a screenshot of',
        },
        width: {
          type: 'number',
          description: 'Width of the viewport in pixels (default: 1280)',
        },
        height: {
          type: 'number',
          description: 'Height of the viewport in pixels (default: 800)',
        },
        fullPage: {
          type: 'boolean',
          description: 'Whether to take a screenshot of the full page or just the viewport (default: false)',
        },
      },
      required: ['url'],
    },
  },

• src/browser-client.ts:61-129 (helper)

  Helper method in BrowserClient that performs the actual screenshot by POSTing to Cloudflare Browser Rendering API /screenshot endpoint and returns the image URL.

  async takeScreenshot(url: string, options: {
    width?: number;
    height?: number;
    fullPage?: boolean;
    waitUntil?: string;
    timeout?: number;
  } = {}): Promise<string> {
    try {
      console.error(`[API] Taking screenshot of: ${url}`);
      
      // Validate URL before sending
      try {
        new URL(url); // Will throw if URL is invalid
      } catch (e) {
        throw new Error(`Invalid URL provided: ${url}`);
      }
      
      // Add timeout for the request
      const requestTimeout = options.timeout || 30000;
      
      // Make the API call to the Cloudflare Worker with timeout
      const response = await axios.post(`${this.apiEndpoint}/screenshot`, {
        url,
        width: options.width || 1280,
        height: options.height || 800,
        fullPage: options.fullPage || false,
        waitUntil: options.waitUntil || 'networkidle0',
        timeout: requestTimeout,
      }, {
        timeout: requestTimeout + 5000, // Add 5 seconds to the request timeout
      });
      
      // Check if the response has the expected structure with a URL
      if (response.data && response.data.url) {
        // Validate the returned URL
        try {
          new URL(response.data.url);
          return response.data.url;
        } catch (e) {
          throw new Error(`Invalid screenshot URL returned: ${response.data.url}`);
        }
      }
      
      // If we can't find the URL, log the response and throw an error
      console.error('[Error] Unexpected response structure:', JSON.stringify(response.data, null, 2));
      throw new Error('Screenshot URL not found in Cloudflare Worker response');
    } catch (error: any) {
      console.error('[Error] Error taking screenshot:', error);
      
      // If API is unavailable, throw an error
      if (error.code === 'ECONNREFUSED' || error.code === 'ENOTFOUND' || !process.env.BROWSER_RENDERING_API) {
        console.error('[Error] Cloudflare worker API is unavailable or not configured');
        throw new Error('Cloudflare worker API is unavailable or not configured. Please check your BROWSER_RENDERING_API environment variable.');
      }
      
      // Handle timeout errors specifically
      if (error.code === 'ETIMEDOUT' || error.code === 'ESOCKETTIMEDOUT' || error.message?.includes('timeout')) {
        throw new Error(`Screenshot request timed out for URL: ${url}. Try increasing the timeout value.`);
      }
      
      // Log more detailed error information if available
      if (error.response) {
        console.error('[Error] Response status:', error.response.status);
        console.error('[Error] Response data:', JSON.stringify(error.response.data, null, 2));
      }
      
      throw new Error(`Failed to take screenshot: ${error instanceof Error ? error.message : String(error)}`);
    }
  }