@frmwrkd/snag-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 Snag contributors
+
+   Full text: https://www.apache.org/licenses/LICENSE-2.0.txt

package/README.md

@@ -0,0 +1,187 @@
+# @frmwrkd/snag-mcp
+
+stdio MCP server exposing the Snag queue to Claude Code. **Five tools, four resources.**
+
+**Licence:** Apache-2.0 · Spec: `docs/02-BACKEND-SPEC.md` §9. Locked decisions: `docs/00-MASTER-BUILD-PLAN.md` §7 — do not relitigate them.
+
+---
+
+## The number that shapes this package
+
+Claude Code **warns at 10,000 tokens of MCP tool output and hard-caps at
+25,000** (`MAX_MCP_OUTPUT_TOKENS`, doc 03 §4.3). Chrome DevTools MCP ships
+~17,000 tokens of tool *definitions* before a single call, and pays that on
+every turn.
+
+So: `.snag/` files carry the bulk, and MCP carries actions and filtered
+queries. Measured on this server:
+
+| | tokens |
+|---|---|
+| Tool definitions, every turn | **~2,900** |
+| `snag_list` on a 20-task queue | ~600 |
+| `snag_get` on one task | ~500 |
+| A screenshot, if you ask for one | ~1,568 visual |
+
+The regression guards live in `test/tools.test.ts`; they fail if a sixth tool
+appears or the definitions cross 4,000 tokens.
+
+---
+
+## Install
+
+`@frmwrkd/snag-mcp` is not published yet, so the server runs from a local build:
+
+```powershell
+npx pnpm@10.33.0 build
+node scripts/install-claude-code.mjs "C:\code\my-app"
+```
+
+The installer writes `.mcp.json` with an absolute `node` command, plus the
+skill, hooks and settings — see `integrations/claude-code/README.md`:
+
+```json
+// .mcp.json, project-scoped — machine-specific: do not commit it yet
+{ "mcpServers": { "snag": { "type": "stdio", "command": "node", "args": ["L:/snag/apps/mcp/dist/index.js"] } } }
+```
+
+That absolute path exists only on the machine that ran the installer, which
+warns about it every run. Until `@frmwrkd/snag-mcp` is published and the entry can be
+`npx -y @frmwrkd/snag-mcp`, keep `.mcp.json` out of commits.
+
+The server is spawned with the project directory as its cwd and finds `.snag/`
+by walking up from there — skipping `~/.snag/`, which is snagd's token
+directory, not a project. It only talks to a snagd whose `/health` `root` is
+this project — or, when no such daemon answers, one serving another `git
+worktree` of the same repository (same `git rev-parse --git-common-dir`). A
+snagd for some other project is never used, and a write then fails naming it:
+
+> snagd on :7654 serves L:\code\other-app, not L:\code\my-app — open Claude Code
+> in L:\code\other-app, or start snagd with --root L:\code\my-app
+
+Before every status change and verify request the cached daemon's `/health` is
+asked again, so a port another project's snagd took over after a restart is
+dropped and discovery runs again.
+
+`snag_resolve` first asks `POST /verify/:taskId` with `dry_run: true`, before it
+moves the task at all. `no_capture_url` (an authored task has no page to
+re-open) leaves the task `in_progress` and says a human must resolve it;
+`verify_disabled` resolves it directly with `verified: false` where §5.3
+allows. Otherwise it moves the task to `verifying` and gets `202` back from the
+real `POST` at once; Verify runs in Chrome afterwards, so the tool tells the
+agent to `snag_get` the task in ~30 s, where `verify` carries the last
+`outcome` and `reason` from `GET /verify/:taskId`. When no extension is
+connected (`503 verify_unavailable`) the daemon's message is passed through
+word for word and the task stays `verifying` — the only refusal that says to
+call `snag_resolve` again.
+
+---
+
+## Tools
+
+| Tool | Signature | Returns |
+|---|---|---|
+| `snag_list` | `(status?, wave?, limit=20)` | Compact list: id, title, severity, kind, wave, status, first suspect file + line range. Non-terminal tasks by default. |
+| `snag_get` | `(id)` | The full task via `structuredContent`, plus `resource_link`s to screenshots on disk, a `next_actions` list, and — once Verify is involved — `verify: { running, outcome, reason, last_at }`. |
+| `snag_claim` | `(id)` | `open → claimed`. Returns the full task. |
+| `snag_resolve` | `(id, commit?, note?)` | Verify preflight, then `→ verifying` and queues a verify run. **Never `resolved`** while Verify is enabled. |
+| `snag_screenshot` | `(id, index=0)` | The image inline. Only when explicitly called. |
+
+`id` is `SNAG-<n>` or `tsk_<ulid>`; both work everywhere.
+
+### Three invariants
+
+1. **Screenshots are never inlined by `snag_get`** (locked decision D13). They
+   go out as `resource_link`s with `file://` paths — Claude Code can `Read` a
+   local PNG directly, which sidesteps the output cap entirely.
+2. **`snag_resolve` never sets `resolved`.** doc 02 §5.3: "`resolved` is only
+   ever set by Verify, never by the agent directly." The single documented
+   exception is `plan.verify_on_resolve: false` in snagd's `.snag/config.json`
+   — reported by the verify preflight as `verify_disabled` — in which case the
+   task goes straight to `resolved` with `verified: false`, and the daemon
+   still gates that edge on the config value. Verify itself re-opens the page,
+   re-resolves the anchor and checks the captured console errors; it does not
+   compare pixels yet, and a capture with no console error goes to
+   `needs_review`.
+3. **`next_actions` is Jam's `getDetails` pattern.** One cheap call tells the
+   agent which expensive calls are worth making: it suggests
+   `snag_screenshot` when `kind` is `ux`/`a11y`/`layout`, and explicitly tells
+   the agent not to bother otherwise.
+
+## Resources
+
+`snag://queue` · `snag://plan` · `snag://task/{id}` · `snag://map`
+
+Surfaced in Claude Code as `@snag:snag://…` autocompletes.
+
+`snag://task/{id}` returns the **bytes of `.snag/tasks/SNAG-<n> - <title>.md`
+unchanged**, so reading a task through MCP and reading it with `Read` produce
+character-identical text. The frontmatter carries edit anchors; they must not
+be re-rendered.
+
+Every resource is capped: if a payload would exceed the client's warning
+threshold it projects itself down to a summary and names the file on disk.
+Losing detail loudly beats a client truncating mid-JSON.
+
+---
+
+## How it gets its data
+
+```
+snag_list / snag_get / resources  →  snagd HTTP  →  falls back to .snag/ files
+snag_claim / snag_resolve         →  /health re-checked → snagd HTTP  →  hard error if absent
+snag_screenshot                   →  .snag/shots/*.png on disk
+```
+
+Reads prefer the daemon because the SQLite index carries live status;
+`.snag/plan.json` is a snapshot whose statuses go stale the moment a task is
+claimed. When the daemon is unreachable the fallback still answers, and every
+response is labelled `source: "daemon" | "files"` so a stale status is a known
+stale status.
+
+Writes require the daemon. Editing `.snag/tasks/*.md` from here would race the
+daemon's file watcher and desynchronise the index, so `snag_claim` and
+`snag_resolve` fail with an error that names the fix:
+
+> snagd is not running (probed http://127.0.0.1:7654-7664 and /repo/.snag/.port).
+> Start it with `npx snagd` in /repo. Until then the queue is still readable
+> without me — Read/Grep .snag/tasks/\*.md and .snag/plan.json.
+
+**Port discovery** reads `.snag/.port` first, then probes 7654–7664 for a
+`GET /health` that identifies itself as `snagd` (doc 02 §7.3 — nothing
+hard-codes 7654). **Auth** is the token from `~/.snag/token`, sent as
+`Authorization: Bearer`.
+
+---
+
+## Implementation notes
+
+**Why the low-level `Server` and not `McpServer`.** `McpServer.registerTool`
+generates each tool's wire schema itself, at draft-7. The MCP `2026-07-28`
+spec says tool schemas are JSON Schema **2020-12**, and `@frmwrkd/snag-core`'s
+`toInlineJsonSchema` emits exactly that. Going through the low-level `Server`
+keeps `@frmwrkd/snag-core` the single source of truth *and* makes the emitted bytes
+inspectable, which is what lets the tests assert their token cost.
+
+**One interop wrinkle, found by running it.** The SDK's own client validates
+`structuredContent` against the declared `outputSchema` with an Ajv instance
+built from `ajv`'s **draft-07** entry point. Draft-07 has no `prefixItems`, so
+the spec-correct 2020-12 tuple for `Task.suspect_files[].lines`
+(`prefixItems` + `items: false`) was rejected with
+
+> MCP error -32602: … data/tasks/0/suspect_lines/0 boolean schema is false
+
+`openTupleTail` in `src/tools.ts` drops the `items: false` when `maxItems`
+already pins the arity — a no-op under 2020-12, and the difference between
+working and not under draft-07. `test/schema-interop.test.ts` runs the SDK's
+real validator over the real schemas so it cannot regress.
+
+---
+
+## Development
+
+```bash
+pnpm --filter @frmwrkd/snag-mcp build
+pnpm --filter @frmwrkd/snag-mcp test        # vitest, 160 tests
+pnpm --filter @frmwrkd/snag-mcp typecheck
+```