spa-reader-mcp

Instructions

Implementation Reference

• src/tools/spa-screenshot.ts:62-102 (handler)

  The main handler function that executes the spa_screenshot tool logic. It processes input parameters, calls takeScreenshot helper, converts the buffer to base64, and returns the image content or error.

  async ({ url, waitForSelector, waitTimeout, width, height, fullPage, cookies, headers }) => {
    try {
      const viewport =
        width !== undefined || height !== undefined
          ? { width: width ?? 1280, height: height ?? 720 }
          : undefined;
  
      const buffer = await takeScreenshot({
        url,
        waitForSelector,
        waitTimeout,
        viewport,
        fullPage,
        cookies,
        headers,
      });
  
      const base64 = buffer.toString("base64");
  
      return {
        content: [
          {
            type: "image" as const,
            data: base64,
            mimeType: "image/png",
          },
        ],
      };
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text" as const,
            text: `Error capturing screenshot of ${url}: ${message}`,
          },
        ],
        isError: true,
      };
    }
  },

• src/tools/spa-screenshot.ts:20-104 (registration)

  Registers the spa_screenshot tool with the MCP server, defining the tool name, description, Zod schema for input validation (url, waitForSelector, waitTimeout, width, height, fullPage, cookies, headers), and the async handler.

  export function registerSpaScreenshotTool(server: McpServer): void {
    server.tool(
      "spa_screenshot",
      "Take a screenshot of a JavaScript SPA page after rendering. " +
        "Uses a headless browser to execute JavaScript and capture the visual output as PNG.",
      {
        url: z.string().url().describe("The URL to screenshot"),
        waitForSelector: z
          .string()
          .optional()
          .describe("CSS selector to wait for before capturing"),
        waitTimeout: z
          .number()
          .min(1000)
          .max(120000)
          .optional()
          .describe("Navigation timeout in ms (default: 30000)"),
        width: z
          .number()
          .min(320)
          .max(3840)
          .optional()
          .describe("Viewport width in pixels (default: 1280)"),
        height: z
          .number()
          .min(240)
          .max(2160)
          .optional()
          .describe("Viewport height in pixels (default: 720)"),
        fullPage: z
          .boolean()
          .optional()
          .describe("Capture full scrollable page (default: false)"),
        cookies: z
          .array(cookieSchema)
          .optional()
          .describe("Cookies to inject before screenshot"),
        headers: z
          .record(z.string(), z.string())
          .optional()
          .describe("Custom HTTP headers"),
      },
      async ({ url, waitForSelector, waitTimeout, width, height, fullPage, cookies, headers }) => {
        try {
          const viewport =
            width !== undefined || height !== undefined
              ? { width: width ?? 1280, height: height ?? 720 }
              : undefined;
  
          const buffer = await takeScreenshot({
            url,
            waitForSelector,
            waitTimeout,
            viewport,
            fullPage,
            cookies,
            headers,
          });
  
          const base64 = buffer.toString("base64");
  
          return {
            content: [
              {
                type: "image" as const,
                data: base64,
                mimeType: "image/png",
              },
            ],
          };
        } catch (error) {
          const message = error instanceof Error ? error.message : String(error);
          return {
            content: [
              {
                type: "text" as const,
                text: `Error capturing screenshot of ${url}: ${message}`,
              },
            ],
            isError: true,
          };
        }
      },
    );
  }

• src/tools/spa-screenshot.ts:9-61 (schema)

  Input schema definitions using Zod: cookieSchema (lines 9-18) for cookie validation and the main tool parameters schema (lines 25-61) with url, waitForSelector, waitTimeout, width, height, fullPage, cookies, and headers fields.

  const cookieSchema = z.object({
    name: z.string().min(1).describe("Cookie name"),
    value: z.string().describe("Cookie value"),
    domain: z.string().optional().describe("Cookie domain (auto-inferred from URL if omitted)"),
    path: z.string().optional().describe("Cookie path (default: '/')"),
    secure: z.boolean().optional().describe("Secure flag"),
    httpOnly: z.boolean().optional().describe("HttpOnly flag"),
    expires: z.number().optional().describe("Expiration timestamp"),
    sameSite: z.enum(["Strict", "Lax", "None"]).optional().describe("SameSite attribute"),
  });
  
  export function registerSpaScreenshotTool(server: McpServer): void {
    server.tool(
      "spa_screenshot",
      "Take a screenshot of a JavaScript SPA page after rendering. " +
        "Uses a headless browser to execute JavaScript and capture the visual output as PNG.",
      {
        url: z.string().url().describe("The URL to screenshot"),
        waitForSelector: z
          .string()
          .optional()
          .describe("CSS selector to wait for before capturing"),
        waitTimeout: z
          .number()
          .min(1000)
          .max(120000)
          .optional()
          .describe("Navigation timeout in ms (default: 30000)"),
        width: z
          .number()
          .min(320)
          .max(3840)
          .optional()
          .describe("Viewport width in pixels (default: 1280)"),
        height: z
          .number()
          .min(240)
          .max(2160)
          .optional()
          .describe("Viewport height in pixels (default: 720)"),
        fullPage: z
          .boolean()
          .optional()
          .describe("Capture full scrollable page (default: false)"),
        cookies: z
          .array(cookieSchema)
          .optional()
          .describe("Cookies to inject before screenshot"),
        headers: z
          .record(z.string(), z.string())
          .optional()
          .describe("Custom HTTP headers"),
      },

• src/lib/renderer.ts:226-258 (helper)

  The takeScreenshot helper function that uses Playwright to launch a headless browser, navigate to the URL, wait for rendering, and capture a PNG screenshot. Handles viewport configuration, cookies, headers, and full-page capture.

  export async function takeScreenshot(options: ScreenshotOptions): Promise<Buffer> {
    const { parsedUrl, timeout, resolvedCookies, cleanedHeaders } = validateOptions(options);
    const width = options.viewport?.width ?? DEFAULT_VIEWPORT_WIDTH;
    const height = options.viewport?.height ?? DEFAULT_VIEWPORT_HEIGHT;
  
    const browser = await getBrowser();
    const viewportSize = { width, height };
    const context: BrowserContext = await browser.newContext({
      userAgent: "spa-reader-mcp/1.0.0",
      viewport: viewportSize,
      screen: viewportSize,
      extraHTTPHeaders: Object.keys(cleanedHeaders).length > 0 ? cleanedHeaders : undefined,
    });
  
    try {
      if (resolvedCookies.length > 0) {
        await context.addCookies(resolvedCookies);
      }
  
      const page = await context.newPage();
      await page.setViewportSize(viewportSize);
      await navigateAndWait(page, options, parsedUrl, timeout);
  
      const screenshot = await page.screenshot({
        fullPage: options.fullPage ?? false,
        type: "png",
      });
  
      return Buffer.from(screenshot);
    } finally {
      await context.close();
    }
  }

• src/types.ts:31-34 (schema)

  TypeScript interface ScreenshotOptions extending RenderOptions with optional viewport (width/height) and fullPage boolean properties.

  export interface ScreenshotOptions extends RenderOptions {
    readonly viewport?: ViewportConfig;
    readonly fullPage?: boolean;
  }