@sightmap/mcp 0.2.0

package/README.md

@@ -0,0 +1,79 @@
+# @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. |
+| `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. |
+
+### Curation tools
+
+The MCP also exposes 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 write tools operate on the directory passed via `--curate-root`
+(defaults to the first `--sightmap-dir`).
+
+**Component / route / selector edits are not exposed via MCP** — those are
+codegen-owned. To track a new component, add a `data-sightmap` attribute to
+source and re-run `sightmap-react gen`.
+
+## 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`.
+
+## Usage
+
+```sh
+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.
+--upstream-command <cmd>  Command to spawn the upstream MCP server. Default: npx
+-- <args...>              Args for the upstream command.
+                          Default: -y @playwright/mcp@latest
+```

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+interface CliArgs {
+    sightmapDirs: string[];
+    curateRoot: string;
+    upstreamCommand: string;
+    upstreamArgs: string[];
+}
+/** Argv parser. Exposed for unit testing. */
+declare function parseArgv(argv: string[]): CliArgs;
+
+export { parseArgv };