@sightmap/mcp

MCP server that wraps @playwright/mcp and adds sightmap-aware tools for browser-driving agents.

Tools

Browser tools (require an upstream)

| Tool | Purpose | |---|---| | sightmap_match | Pure-query: matches a URL against the loaded sightmap and returns view, components, requests, and aggregated memory. No browser call. | | sightmap_snapshot | ARIA snapshot enriched with sightmap awareness (matched view, applicable components with live matchCount). | | sightmap_act | Click / type / hover by sightmap component name; raw selector is an escape hatch. | | sightmap_network_requests | Recent network requests, annotated with sightmap names where the request URL+method matches a sightmap requests: entry. | | sightmap_runtime_snapshot | Capture the live React fiber tree (components, ranked selectors, data-sightmap markers, unmarked candidates) for the agent to fold into .sightmap/. Three sources via kind: "endpoint" (fetch a /__sightmap__/snapshot.json served by @sightmap/react's Vite plugin), "browser" (drive the upstream browser MCP, inject the bippy runtime, and read window.__sightmap__.snapshot()), or "literal" (accept a pre-captured snapshot from any other harness — e.g. Subtext's live-eval-script). |

Curation tools

The MCP exposes a seven-tool family for .sightmap/ authoring. The sightmap-assistant subagent has full authority over every view field (structural and semantic) via these tools.

| Tool | Purpose | |---|---| | sightmap_list_views | List all views (compact summary by default; pass detail: "full" for the entire view). | | sightmap_get_view | Fetch a single view + its source file path. | | sightmap_check | Validate the sightmap (level: "schema" or "quality"; default "quality"). | | sightmap_add_view | Create a new view file (full structural + semantic payload). | | sightmap_update_view | Patch any field on an existing view — name, route, components (incl. per-component selector/memory), description, intent, view-level memory. | | sightmap_delete_view | Remove a view file. | | sightmap_init_project | Scaffold an empty .sightmap/ in a target project. |

Curation write tools operate on the directory passed via --curate-root (defaults to the first --sightmap-dir).

Proposal tools (preview)

A three-stage propose / review / commit flow lets a sub-agent gather edits in memory, surface them to the main thread for confirmation, and then apply them as a batch. Useful for bootstrap and audit-driven fix flows that touch multiple views in one turn.

| Tool | Purpose | |---|---| | sightmap_propose_view | Stage a new-view proposal (no write yet). | | sightmap_propose_component | Stage a new-component proposal against an existing view. | | sightmap_review_proposals | List currently-staged proposals for the main thread to confirm or discard. | | sightmap_commit_proposals | Apply the staged proposals via the underlying add_view / update_view writes. |

Prompts

The MCP server also exposes prompt templates for multi-step authoring workflows.

sightmap_sep_track

Walks an author through writing a Sightmap Enhancement Proposal (SEP), the matching spec/ change, and the matching conformance/ fixture in four phases:

| Phase | Produces | Confirmation gate? | |---|---|---| | draft | seps/NNNN-{slug}.md from the template | Yes | | spec | A diff against spec/ referencing the SEP | Yes | | fixture | conformance/<NNN>-{slug}/ with sightmap/ input + expected.json | Yes | | verify | A summary message with hand-off instructions | No (terminal) |

Arguments:

• phase (required): one of draft, spec, fixture, verify.
• slug (optional): kebab-case short slug, e.g. extend-memory.
• sep_number (optional, set after draft): the four-digit SEP number you claimed.

Confirmation gates are encoded as text directives at the end of each non-final phase's message ("Stop here. Show the draft to the user, ask for explicit 'go' before calling this prompt again with phase: \"spec\"."). The agent honors them; MCP itself has no native pause-and-await primitive for prompts.

Why this exists: SEPs require coordinated edits across three trees (seps/, spec/, conformance/). The track encodes the order, the dependencies, and the user check-in points so neither the author nor the agent can short-circuit them. Pattern adapted from Archcore's architecture_track.

Running curation-only (no browser)

If you're integrating with a tool that already drives the browser (Subtext, agent-browser, or a custom harness), you only need sightmap's curation surface — not its Playwright wrapping. Spawn with --curate-only:

sightmap-mcp --sightmap-dir .sightmap --curate-only

In --curate-only mode, only the curation tools, proposal tools, and sightmap_match are registered — every tool that needs an upstream browser (the four browser tools above plus sightmap_runtime_snapshot kind: "browser") is omitted, and no @playwright/mcp subprocess is launched.

Usage

sightmap-mcp \
  --sightmap-dir ./.sightmap \
  --curate-root ./.sightmap \
  -- npx -y @playwright/mcp@latest

Flags

--sightmap-dir <path>     Directory of sightmap YAML files. Repeatable.
                          Default: .sightmap
--curate-root <path>      Writable .sightmap/ for curation tools.
                          Default: the first --sightmap-dir.
--curate-only             Register only curation tools; do not spawn
                          an upstream browser MCP.
--upstream-command <cmd>  Command to spawn the upstream MCP server. Default: npx
-- <args...>              Args for the upstream command.
                          Default: -y @playwright/mcp@latest