MCP Web Research Server

Instructions

Implementation Reference

• index.ts:1056-1113 (handler)

  Main handler for executing the 'take_screenshot' tool. Captures screenshot of current page, optimizes and saves it, stores in research session as a resource, notifies clients, and returns resource URI.

  case "take_screenshot": {
      try {
          // Step 1: Capture screenshot with retry mechanism
          const screenshot = await withRetry(async () => {
              // Take and optimize screenshot with default size limits
              return await takeScreenshotWithSizeLimit(page);
          });
  
          // Step 2: Initialize session if needed
          if (!currentSession) {
              currentSession = {
                  query: "Screenshot Session",            // Session identifier
                  results: [],                            // Empty results array
                  lastUpdated: new Date().toISOString(),  // Current timestamp
              };
          }
  
          // Step 3: Get current page information
          const pageUrl = await page.url();      // Current page URL
          const pageTitle = await page.title();  // Current page title
  
          // Step 4: Save screenshot to disk
          const screenshotPath = await saveScreenshot(screenshot, pageTitle || 'untitled');
  
          // Step 5: Create and store screenshot result
          const resultIndex = currentSession ? currentSession.results.length : 0;
          addResult({
              url: pageUrl,
              title: pageTitle || "Untitled Page",  // Fallback title if none available
              content: "Screenshot taken",          // Simple content description
              timestamp: new Date().toISOString(),  // Capture time
              screenshotPath                        // Path to screenshot file
          });
  
          // Step 6: Notify clients about new screenshot resource
          server.notification({
              method: "notifications/resources/list_changed"
          });
  
          // Step 7: Return success message with resource URI
          const resourceUri = `research://screenshots/${resultIndex}`;
          return {
              content: [{
                  type: "text" as const,
                  text: `Screenshot taken successfully. You can view it via *MCP Resources* (Paperclip icon) @ URI: ${resourceUri}`
              }]
          };
      } catch (error) {
          // Handle and format screenshot errors
          return {
              content: [{
                  type: "text" as const,
                  text: `Failed to take screenshot: ${(error as Error).message}`
              }],
              isError: true
          };
      }
  }

• index.ts:479-562 (helper)

  Core helper function that captures the screenshot using Playwright page.screenshot(), automatically resizing the viewport to ensure the image is under 5MB, and returns base64-encoded PNG data.

  async function takeScreenshotWithSizeLimit(page: Page): Promise<string> {
      const MAX_SIZE = 5 * 1024 * 1024;
      const MAX_DIMENSION = 1920;
      const MIN_DIMENSION = 800;
  
      // Set viewport size
      await page.setViewportSize({
          width: 1600,
          height: 900
      });
  
      // Take initial screenshot
      let screenshot = await page.screenshot({
          type: 'png',
          fullPage: false
      });
  
      // Handle buffer conversion
      let buffer = screenshot;
      let attempts = 0;
      const MAX_ATTEMPTS = 3;
  
      // While screenshot is too large, reduce size
      while (buffer.length > MAX_SIZE && attempts < MAX_ATTEMPTS) {
          // Get current viewport size
          const viewport = page.viewportSize();
          if (!viewport) continue;
  
          // Calculate new dimensions
          const scaleFactor = Math.pow(0.75, attempts + 1);
          let newWidth = Math.round(viewport.width * scaleFactor);
          let newHeight = Math.round(viewport.height * scaleFactor);
  
          // Ensure dimensions are within bounds
          newWidth = Math.max(MIN_DIMENSION, Math.min(MAX_DIMENSION, newWidth));
          newHeight = Math.max(MIN_DIMENSION, Math.min(MAX_DIMENSION, newHeight));
  
          // Update viewport with new dimensions
          await page.setViewportSize({
              width: newWidth,
              height: newHeight
          });
  
          // Take new screenshot
          screenshot = await page.screenshot({
              type: 'png',
              fullPage: false
          });
  
          // Update buffer with new screenshot
          buffer = screenshot;
  
          // Increment retry attempts
          attempts++;
      }
  
      // Final attempt with minimum settings
      if (buffer.length > MAX_SIZE) {
          await page.setViewportSize({
              width: MIN_DIMENSION,
              height: MIN_DIMENSION
          });
  
          // Take final screenshot
          screenshot = await page.screenshot({
              type: 'png',
              fullPage: false
          });
  
          // Update buffer with final screenshot
          buffer = screenshot;
  
          // Throw error if final screenshot is still too large
          if (buffer.length > MAX_SIZE) {
              throw new McpError(
                  ErrorCode.InvalidRequest,
                  `Failed to reduce screenshot to under 5MB even with minimum settings`
              );
          }
      }
  
      // Convert Buffer to base64 string before returning
      return buffer.toString('base64');
  }

• index.ts:156-164 (registration)

  Tool registration in the TOOLS array, including name, description, and empty input schema (no parameters required). This is returned by the list_tools handler.

      {
          name: "take_screenshot",
          description: "Take a screenshot of the current page",
          inputSchema: {
              type: "object",
              properties: {},  // No parameters needed
          },
      },
  ];

• index.ts:89-113 (helper)

  Helper function to save the base64 screenshot to disk in a temporary directory, with size validation and safe filename generation.

  async function saveScreenshot(screenshot: string, title: string): Promise<string> {
      // Convert screenshot from base64 to buffer
      const buffer = Buffer.from(screenshot, 'base64');
  
      // Check size before saving
      const MAX_SIZE = 5 * 1024 * 1024;  // 5MB
      if (buffer.length > MAX_SIZE) {
          throw new McpError(
              ErrorCode.InvalidRequest,
              `Screenshot too large: ${Math.round(buffer.length / (1024 * 1024))}MB exceeds ${MAX_SIZE / (1024 * 1024)}MB limit`
          );
      }
  
      // Generate a safe filename
      const timestamp = new Date().getTime();
      const safeTitle = title.replace(/[^a-z0-9]/gi, '_').toLowerCase();
      const filename = `${safeTitle}-${timestamp}.png`;
      const filepath = path.join(SCREENSHOTS_DIR, filename);
  
      // Save the validated screenshot
      await fs.promises.writeFile(filepath, buffer);
  
      // Return the filepath to the saved screenshot
      return filepath;
  }