viewpo-mcp

Instructions

Implementation Reference

• src/index.ts:40-96 (handler)

  Tool registration and handler implementation for viewpo_screenshot. Defines the tool schema using zod, handles the request by calling client.screenshot(), processes the response into text and image content, and returns formatted results or error messages.
  // --- Tool: viewpo_screenshot --- server.tool( "viewpo_screenshot", "Capture screenshots of a URL at one or more viewport widths. Returns base64 JPEG images. Use this to SEE what a webpage looks like at different screen sizes.", { url: z.string().url().describe("The URL to screenshot"), viewports: z .array( z.object({ width: z .number() .int() .min(100) .max(3840) .describe("Viewport width in CSS pixels"), name: z .string() .optional() .describe('Label for this viewport (e.g. "phone", "desktop")'), }) ) .optional() .describe( "Viewports to capture. Defaults to desktop (1920px) if omitted. Common widths: 375 (phone), 820 (tablet), 1920 (desktop)." ), }, async ({ url, viewports }) => { try { const result = await client.screenshot({ url, viewports }); const content = result.viewports.flatMap((vp) => [ { type: "text" as const, text: `**${vp.viewport}** (${vp.width}\u00d7${vp.height})`, }, { type: "image" as const, data: vp.image_base64, mimeType: "image/jpeg" as const, }, ]); return { content }; } catch (error) { return { content: [ { type: "text" as const, text: `Screenshot failed: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } } );
• src/types.ts:3-24 (schema)

  Type definitions for the screenshot tool. Includes ViewportSpec (width and optional name), ScreenshotRequest (url and optional viewports array), ViewportResult (viewport dimensions and base64 image), and ScreenshotResponse (array of viewport results).
  // --- Screenshot --- export interface ViewportSpec { width: number; name?: string; } export interface ScreenshotRequest { url: string; viewports?: ViewportSpec[]; } export interface ViewportResult { viewport: string; width: number; height: number; image_base64: string; } export interface ScreenshotResponse { viewports: ViewportResult[]; }
• src/client.ts:30-32 (helper)

  HTTP client method that sends POST request to /screenshot endpoint. Takes ScreenshotRequest parameters and returns ScreenshotResponse, handling communication with the Viewpo macOS app's bridge API.
  async screenshot(request: ScreenshotRequest): Promise<ScreenshotResponse> { return this.post<ScreenshotResponse>("/screenshot", request); }
• src/index.ts:42-66 (schema)

  Zod schema validation for the viewpo_screenshot tool parameters. Defines url as a required URL string, and viewports as an optional array of objects with width (100-3840) and optional name fields.
  server.tool( "viewpo_screenshot", "Capture screenshots of a URL at one or more viewport widths. Returns base64 JPEG images. Use this to SEE what a webpage looks like at different screen sizes.", { url: z.string().url().describe("The URL to screenshot"), viewports: z .array( z.object({ width: z .number() .int() .min(100) .max(3840) .describe("Viewport width in CSS pixels"), name: z .string() .optional() .describe('Label for this viewport (e.g. "phone", "desktop")'), }) ) .optional() .describe( "Viewports to capture. Defaults to desktop (1920px) if omitted. Common widths: 375 (phone), 820 (tablet), 1920 (desktop)." ), },
• src/client.ts:50-57 (helper)

  Generic POST method implementation that handles HTTP requests with JSON body, including authentication headers and response processing via handleResponse method.
  private async post<T>(path: string, body: unknown): Promise<T> { const response = await fetch(`${this.baseURL}${path}`, { method: "POST", headers: this.headers(true), body: JSON.stringify(body), }); return this.handleResponse<T>(response); }