viewpo_get_layout_map

Instructions

Implementation Reference

• src/index.ts:98-143 (registration)

  MCP tool registration for viewpo_get_layout_map. This includes the tool schema definition (url, viewport, selector parameters with validation) and the async handler that calls client.layoutMap() and returns the JSON result.

  // --- Tool: viewpo_get_layout_map ---
  
  server.tool(
    "viewpo_get_layout_map",
    "Extract the DOM layout tree of a URL at a given viewport width. Returns element hierarchy with tags, classes, bounding rects, and computed CSS styles. Use this to understand page structure and find layout issues.",
    {
      url: z.string().url().describe("The URL to inspect"),
      viewport: z
        .number()
        .int()
        .min(100)
        .max(3840)
        .optional()
        .describe("Viewport width in CSS pixels (default: 1920)"),
      selector: z
        .string()
        .optional()
        .describe(
          'CSS selector to scope the layout map to a subtree (e.g. ".main-content", "#hero")'
        ),
    },
    async ({ url, viewport, selector }) => {
      try {
        const result = await client.layoutMap({ url, viewport, selector });
  
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Layout map failed: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/index.ts:119-142 (handler)

  Tool handler function that executes the layout map logic. Calls client.layoutMap() with the provided parameters and returns the result as formatted JSON text with error handling.

  async ({ url, viewport, selector }) => {
    try {
      const result = await client.layoutMap({ url, viewport, selector });
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Layout map failed: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/client.ts:34-36 (handler)

  HTTP client method that makes a POST request to the Viewpo bridge API's /layout endpoint. Handles authentication and JSON serialization.

  async layoutMap(request: LayoutMapRequest): Promise<LayoutMapResponse> {
    return this.post<LayoutMapResponse>("/layout", request);
  }

• src/types.ts:28-54 (schema)

  Type definitions for the layout map API. Includes LayoutMapRequest (url, viewport, selector) and LayoutMapResponse with nested types for LayoutElement and ElementRect defining the DOM hierarchy structure.

  export interface LayoutMapRequest {
    url: string;
    viewport?: number;
    selector?: string;
  }
  
  export interface ElementRect {
    x: number;
    y: number;
    width: number;
    height: number;
  }
  
  export interface LayoutElement {
    tag: string;
    id?: string;
    classes?: string[];
    rect: ElementRect;
    styles: Record<string, string>;
    children: LayoutElement[];
  }
  
  export interface LayoutMapResponse {
    url: string;
    viewport: number;
    root: LayoutElement;
  }