Canvas Reading

canvas_read exposes a Canvas through WebMCP and Site Tools. canvasId is optional: full-access local MCP can target the short persistent ID returned by canvas_manage with the list action; that action returns currentCanvas for the page the user currently has open. Archived Canvases are omitted from list by default; pass includeArchived: true when archived pages are explicitly needed. Omitted input reads that active Canvas; use the full canvases list only for explicit cross-Canvas work. The local bridge is discovered and connected automatically when the Canvas page and Agent are running. Agent → Local MCP controls inspect, read, search, and write grants; a legacy Canvas-scoped pairing remains restricted to its original Canvas. It belongs to the spatial Canvas group in the WebMCP contract. It reads the Cell surface without changing the user's camera, selection, or document. Freeform and local document previews use their current projection; Slides use the current page.

Viewport

{ "viewport": [100, 200, 800, 240], "representation": "text" }

The optional tuple is [x, y, width, height] in original Cell coordinates. Coordinates are signed safe integers; sizes are positive safe integers, and endpoints must remain safe integers. Bounds are half-open. {} fits all occupied content; an empty Canvas returns viewport: null and empty content.

Read nearby content by moving the rectangle, retaining overlap for orientation. Resize it around a target to zoom. Reading does not require titles, groups, or objects.

Projection

The content grid is at most 80 columns by 24 rows. Coordinate decoration is outside that budget. Uniform sampling uses sampleSize = max(1, ceil(width / 80), ceil(height / 24)); partial edge buckets cover only the requested rectangle.

Non-whitespace characters, explicit backgrounds, and inverse/underlined/struck spaces count as occupied; wide graphemes occupy their Cell width. Any nonzero density remains visible. Projection symbols and coordinate rulers are navigation aids, not source characters. Text output preserves characters and interior spacing. Style information is an explicit read option, not part of the default text payload.

Coordinates and appearance

At text precision, the open top ruler has ticks every 5 Cells and centred coordinate labels every 10; rows are labelled every 5 Cells. Negative coordinates use signed labels. Ticks align with absolute coordinates, not the viewport origin. Large labels and sampled maps use wider intervals to avoid overlap. In sampled maps a tick marks the bucket containing that coordinate; viewport and sampleSize still define each bucket's exact bounds. Wide graphemes occupy two columns. Pass style: "appearance" to append a compact spatial appearance map:

The grid has no right or bottom border. Trailing ASCII spaces are omitted; viewport declares the full width and height. Leading and interior spaces and empty row positions remain unchanged. Style notes retain attributed trailing spaces. The active theme foreground is the default: light #1f2328 and dark #f0f6fc are omitted from appearance regions; non-default colors and attributes remain.

appearance:
  y=20..21 x=10..12{fg:#ff0000;bold}
  y=21 x=14{underline;link:"https://example.com"}

Ranges are inclusive original Canvas coordinates, not output offsets. Appearance regions include foreground, background, bold, italic, underline, strike, inverse, and links. Adjacent equal styles merge into horizontal runs and matching runs on consecutive rows merge vertically. Styled spaces are included; boundary-clipped graphemes are excluded with their text. At most 256 style regions are shown, with an explicit truncation notice.

Projection and density modes omit appearance and ask the caller to read a smaller viewport; their symbols are navigation aids, not styled source content. The default text path omits appearance. representation: "cells" returns exact character/style records for precise edits. Reading source files or exporting ANSI is not part of this tool.

overviewOnly makes this distinction machine-readable: it is false for exact text reads and true for projection or density. When it is true, do not describe the sampled symbols as the Canvas's actual characters. Use search or read a smaller viewport until overviewOnly: false.

Content blocks

representation is optional and defaults to text; style is optional and defaults to none:

style: "appearance" adds merged spatial style regions to text and structuredContent; it does not infer semantic roles such as heading or body.

Image reads accept detail: "low" | "high" | "original" | "auto" and default to auto. Machine-readable metadata is exposed in structuredContent; visual material is exposed through contentBlocks. Existing callers can continue using the default top-level content text. Image data is a model-compatible PNG image block carrying the original Cell viewport and pixel scale; the internal SVG intermediate never leaves the Canvas tool boundary. Oversized images are omitted with a note; narrow the viewport or use representation: "text" instead.

Appearance reads also include a compact write rendering note: mode, theme, Markdown wrap width, and feature state. These describe how a material render would behave, not the historical source or rendering profile of existing Cells.

The response contains an optional canvasId, actual viewport, sampleSize, mode, overviewOnly, representation, content, and contentBlocks. Rulers use original coordinates; output column c and row r cover the region starting at (x + c * sampleSize, y + r * sampleSize). Invalid input, missing active Canvas, and unavailable content return explicit errors.

Authorities

• Tool definition
• Projection and sampling
• Projection verification
• Shared CLI and WebMCP style-note contract
• Headless host verification