@sightmap/mcp

@sightmap/mcp is an MCP server that wraps @playwright/mcp and adds sightmap-aware tools for browser-driving agents. It is the recommended way to let a host agent (Claude Code, Cursor, Subtext) curate a .sightmap/ directory: the agent gets a typed tool surface for both browser introspection and YAML mutation, with type safety and cascade tracking the bare filesystem can’t provide.

Install and run

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

Wire it into your host agent’s MCP config the same way you’d wire any other server. For Claude Code, that’s ~/.claude/mcp.json or the project-local equivalent.

Flags

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

Browser tools

These require an upstream Playwright MCP. The server proxies the upstream’s primitives and adds sightmap awareness:

Tool	Purpose
sightmap_match	Pure query: matches a URL against the loaded sightmap and returns view, components, requests, and aggregated memory.
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.

The upshot: an agent can drive a browser in terms of component names, not selectors. sightmap_act { component: "LoginButton", action: "click" } resolves the selector at call time, so renames in the YAML take effect immediately without prompt edits.

Curation tools

A five-tool family for .sightmap/ authoring:

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_update_view	Patch a view’s agent-authored fields (description, intent, memory_append, memory_replace).
sightmap_init_project	Scaffold an empty .sightmap/ in a target project.

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

Caution

Component, route, and selector edits are not exposed via MCP. Those are codegen-owned. To track a new component, add a data-sightmap attribute in source and re-run sightmap-react gen. This boundary is deliberate — it prevents agents from authoring selectors that drift from source.

Prompts

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

sightmap_sep_track

Walks an author through writing a Sightmap Enhancement Proposal — the SEP markdown, 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	Hand-off summary	No (terminal)

Confirmation gates are encoded as text directives at the end of each non-final phase (“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.

This exists because 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 author nor agent can short-circuit them.

Composition

The MCP server is the underlying tool surface. The Claude Code plugin layers advisory hooks on top — nudging the agent toward sightmap_update_view instead of raw Write/Edit, and validating any direct edit that slips through. Run both together for the smoothest experience; either one alone works, with predictable trade-offs.