snapshot

Instructions

Implementation Reference

• src/tools/observation.ts:125-173 (handler)

  MCP tool handler for 'snapshot' - the primary tool for reading page content via accessibility tree. Calls deps.client.snapshot() and returns snapshot text, refs count, URL, and optional truncation info.

  server.tool(
    "snapshot",
    "Get accessibility tree snapshot — the PRIMARY way to read page content. Returns element refs, roles, names and values. Token-efficient. Always prefer over screenshot. Refs come from the accessibility tree, so custom SPA elements may be missing; fall back to CSS selectors, camofox_wait_for_selector, or camofox_get_page_html when needed.",
    {
      tabId: z.string().min(1).describe("Tab ID from create_tab"),
      offset: z.number().optional().describe("Offset for paginating large snapshots. Use nextOffset from previous response.")
    },
    async (input: unknown) => {
      try {
        const parsed = z.object({
          tabId: z.string().min(1).describe("Tab ID from create_tab"),
          offset: z.number().optional().describe("Offset for paginating large snapshots. Use nextOffset from previous response.")
        }).parse(input);
        const tracked = getTrackedTab(parsed.tabId);
        const response = await deps.client.snapshot(parsed.tabId, tracked.userId, parsed.offset);
        incrementToolCall(parsed.tabId);
        updateTabUrl(parsed.tabId, response.url);
        updateRefsCount(parsed.tabId, response.refsCount);
  
        const result: {
          url: string;
          snapshot: string;
          refsCount: number;
          truncated?: boolean;
          totalChars?: number;
          hasMore?: boolean;
          nextOffset?: number | null;
          truncationInfo?: string;
        } = {
          url: response.url,
          snapshot: response.snapshot,
          refsCount: response.refsCount
        };
  
        if (response.truncated) {
          result.truncated = response.truncated;
          result.totalChars = response.totalChars;
          result.hasMore = response.hasMore;
          result.nextOffset = response.nextOffset;
          result.truncationInfo = response.hasMore
            ? `TRUNCATED (${response.totalChars ?? "unknown"} total chars) | next offset: ${response.nextOffset ?? "unknown"}`
            : `TRUNCATED (${response.totalChars ?? "unknown"} total chars)`;
        }
  
        return okResult(result);
      } catch (error) {
        return toErrorResult(error);
      }
    }

• src/tools/observation.ts:128-131 (schema)

  Input schema for snapshot tool: tabId (required string) and offset (optional number for pagination).

  {
    tabId: z.string().min(1).describe("Tab ID from create_tab"),
    offset: z.number().optional().describe("Offset for paginating large snapshots. Use nextOffset from previous response.")
  },

• src/client.ts:614-636 (helper)

  Client method snapshot() - makes GET request to /tabs/:tabId/snapshot?userId=&offset= and returns parsed SnapshotResponse.

  async snapshot(tabId: string, userId: string, offset?: number): Promise<SnapshotResponse> {
    const params = new URLSearchParams({ userId });
    if (offset !== undefined) {
      params.set("offset", String(offset));
    }
  
    const response = await this.requestJson(
      `/tabs/${encodeURIComponent(tabId)}/snapshot?${params.toString()}`,
      {
      method: "GET"
      }
    , SnapshotRawResponseSchema);
  
    return {
      url: response.url ?? "",
      snapshot: response.snapshot ?? "",
      refsCount: response.refsCount ?? 0,
      truncated: response.truncated,
      totalChars: response.totalChars,
      hasMore: response.hasMore,
      nextOffset: response.nextOffset
    };
  }

• src/types.ts:81-89 (schema)

  SnapshotResponse TypeScript interface defining the return shape: url, snapshot, refsCount, truncated, totalChars, hasMore, nextOffset.

  export interface SnapshotResponse {
    url: string;
    snapshot: string;
    refsCount: number;
    truncated?: boolean;
    totalChars?: number;
    hasMore?: boolean;
    nextOffset?: number | null;
  }

• src/server.ts:44-44 (registration)

  Registration of registerObservationTools which contains the snapshot tool.

  registerObservationTools(server, deps);