markdown-review/DESIGN.md

markdown-review — Design Doc

Antigravity-style comment-on-markdown → send-to-agent as a Claude plugin (MCP Apps / MCP-UI). Status: SPEC (Phase 0 complete — capability verified, API grounded). Author: JARVIS / CDT. 2026-06-09.

---

0. Why this is buildable (verification result)

The mechanism is already proven on this machine: Anthropic's pdf-viewer plugin is installed and its pdf MCP server is live. It renders an interactive viewer with zero Electron/browser — it ships a single-file HTML app as an MCP resource (ui://…, mimetype text/html;profile=mcp-app) that Claude Desktop renders in its own sandboxed webview. We replicate that pattern with a markdown renderer + comment UI.

Grounded stack (same as the working pdf server): Node 24, @modelcontextprotocol/ext-apps@^1.7, @modelcontextprotocol/sdk@^1.29, zod@^4, Vite + vite-plugin-singlefile to bundle app.html.

Key ext-apps primitives we use (real, verified):

• registerAppTool(server, name, { _meta: { ui: { resourceUri } } }, cb) — model-facing tool that opens the view.
• registerAppResource(server, title, "ui://…", {}, readCb) — serves the HTML, with CSP/permission _meta.ui.
• Tool visibility _meta.ui.visibility: ["app"] — hide plumbing tools from the model (isToolVisibilityAppOnly).
• App side (@modelcontextprotocol/ext-apps/app + app-bridge): the webview can call server tools and updateModelContext — push text directly into the model's turn. This is what powers "Answer Now".

Host note: the live comment panel renders in Claude Desktop (the MCP-Apps host). Claude Code builds/installs the plugin; the interactive surface is Desktop's. A headless Claude Code fallback (render to a temp HTML + Read) is a secondary, non-interactive mode.

---

1. The interaction model — three lanes

Antigravity has two effective behaviors (batch artifact comments; select-text→chat). Rav's refinement adds a third, and makes the batch-result behavior a per-session toggle. The result is three lanes:

Lane A — Reading-phase batch (the default, flow-preserving)

You read top-to-bottom and drop comments as you go. No AI is invoked. Comments accumulate silently. A single Submit All flushes the whole set into one agent turn. This is the steering loop.

Lane B — "Answer Now" (single, ephemeral, mid-read) ⟵ Rav's key addition

A separate button on an individual comment. Fires only that one item + that one comment to the agent immediately, via updateModelContext. It:

• does not enter the batch store,
• does not disturb the other pending batch comments,
• is for a quick correction or question without breaking the reading phase.

Mechanically distinct from Lane A: different button, different storage (memory/none), different trigger.

Lane C — what Submit All does (per-session mode toggle)

Orthogonal to A/B. Controls the effect of a batch flush:

• edit mode — comments become edit instructions; agent modifies the anchored ranges in the real .md, re-renders, verifies. (Antigravity's steering loop.)
• review mode — comments become a punch-list/review thread; the file is left untouched until you approve items one by one.
• Switchable per session (a toolbar toggle + a tool arg). Default edit.

Lane	Trigger	Scope	Storage	Effect
A Batch	Submit All	all pending	sidecar (default)	edit or review (Lane C)
B Answer Now	per-comment button	that one	ephemeral (memory)	immediate single ask
C (mode)	toggle	—	—	governs A's effect

---

2. Anchor model

Because we operate on real files (unlike Antigravity's opaque rendered-span anchor), comments anchor richer and survive edits better:

"anchor": {
  "line_start": 12, "line_end": 14,        // 1-based, inclusive
  "char_start": 340, "char_end": 410,       // byte/char offsets into the raw file
  "block_id": "h2-architecture-3",          // stable-ish slug of the enclosing md block
  "quote": "We should use Flask here",      // verbatim selected text (re-anchor fallback)
  "context_before": "…", "context_after": "…"  // ~120 chars each, for fuzzy re-anchoring
}

Re-anchoring on a changed file: try char_start → verify quote matches; else search quote near block_id; else fuzzy-match quote in context. Stale anchors are flagged, never silently dropped.

---

3. Storage — "all of the above, intelligently"

Three backends, selected by intent, with explicit override. Combos are first-class.

Backend	Lives in	Lifetime	Default use (scenario)
memory	server process, per viewUUID	session	Lane B Answer-Now; throwaway brainstorm; "don't clutter anything"
sidecar	.claude/md-comments/<sha1(path)>.json	durable, resumable	Lane A batch review threads; multi-file reviews; keeps .md clean (Antigravity-like)
inline	<!-- mdrev:{id} … --> markers in the .md	travels with file	hand-off to a colleague, git-committed review, portable, want comment visible in raw source

Intelligent routing (defaults; all overridable per call / toolbar)

• Answer-Now → memory (never persisted).
• Batch comment authored during reading → sidecar (source of truth), auto-resumes next open.
• Explicit "Export for sharing" → materialize sidecar threads as inline markers.
• On open, if the file already contains inline mdrev: markers → import them into the sidecar working set (combo: inline-authored → sidecar-managed).
• Promote: a memory/Answer-Now comment you want to keep → "pin" → sidecar.

Combos we explicitly support

1. sidecar SoT + inline export — manage privately, publish a shareable copy.
2. inline import → sidecar — colleague sent a .md with mdrev: comments; we ingest + manage them.
3. memory → sidecar promote — a quick ask turned out worth keeping.
4. sidecar + inline mirror (synced) — opt-in two-way: edits in either reflect (sidecar is authority on conflict).

Storage backend is a field on every comment (store: "memory"|"sidecar"|"inline") so a single view can mix all three. resolve/delete operate uniformly across backends.

---

4. MCP surface

Model-facing (the only tools the model sees)

• open_markdown(path, { mode?: "edit"|"review" }) → { viewUUID, fileMeta, importedComments }. Opens the view (returns _meta.ui.resourceUri), imports inline markers + loads sidecar.
• interact(viewUUID, commands[]) → batched ops the model issues: scroll_to(anchor) | highlight(anchor) | get_comments(filter?) | get_state | set_mode(edit|review) | resolve(id) | export_inline | get_pages(rendered+source).
• (get_comments is how the model receives a Submit All payload after the user clicks it.)

App-only (hidden, _meta.ui.visibility:["app"]) — the plumbing

• poll_md_commands(viewUUID) — long-poll queue draining interact commands to the webview.
• submit_batch(viewUUID, comments[], mode) — Lane A: user clicked Submit All; resolves the model's pending get_comments/blocks the interact promise (pdf-viewer pattern).
• persist_comment(viewUUID, comment) — webview writes a single batch comment to its backend as authored.
• read_md_bytes(viewUUID, range?) — webview pulls source to render.
• save_md(viewUUID, bytes) — when edit mode writes back inline markers.

App→model direct (no server tool) — Lane B

• "Answer Now" calls the bridge updateModelContext({ item, comment }) → injected into the live turn. No queue, no store. (Falls back to a dedicated answer_now app-tool if a host lacks updateModelContext.)

---

5. Round-trip (mirrors the verified pdf-viewer mechanism)

model → interact(cmds)           server enqueues to commandQueues[viewUUID]
webview → poll_md_commands(...)   long-poll; executes in the renderer (scroll/highlight/extract)
                                  for data cmds: interact() BLOCKS on Promise(requestId, timeout)
user clicks "Submit All"          webview → submit_batch(...)  → resolves the pending model call
user clicks "Answer Now"          webview → updateModelContext(...) → straight into the turn

---

6. Plugin packaging

markdown-review/
├── .claude-plugin/plugin.json     # name, version, author, components
├── .mcp.json                      # { mcpServers: { "md": { command: node, args:[server/index.js,--stdio] } } }
├── commands/                      # /open.md  /comment.md  /review.md
├── skills/review-markdown/SKILL.md  # orchestration brain (open-once, batched interact, mode handling)
├── server/                        # Node MCP server (queue + blocking-promise plumbing)
│   ├── index.js  · server.js  · storage.js  · anchor.js
└── app/                           # Vite single-file → bundled app.html (md renderer + comment UI)
    └── src/  → built to ../server/app.html

Renderer: markdown-it (CommonMark + tables/footnotes) in the sandboxed webview. Comment UI = margin threads anchored to selection; toolbar = mode toggle, Submit All, Export-inline, store selector; per-comment = Answer-Now + Submit + store-pick + resolve.

---

7. Build phases (slow-is-fast)

0. ✅ Verify host support + ground the API. (done)
1. Spike the round-trip — minimal md server: open a file, render in webview, prove interact/poll/submit + updateModelContext fire end-to-end. De-risks everything.
2. Comment UI — selection → anchored thread → Submit All payload + Answer-Now.
3. Storage layer — sidecar + inline + memory + the intelligent router + combos.
4. Agent wiring — SKILL.md + commands turn submitted comments into edits (edit mode) / list (review mode).
5. Anchor robustness — re-anchoring across edits; stale flagging.
6. Package + install — plugin.json + local marketplace entry; smoke-test in Claude Desktop.

8. Open questions / risks

• updateModelContext host support in this Desktop build — confirm in Phase 1 spike; fallback = answer_now app-tool.
• markdown-it bundle size in single-file (acceptable; pdf-viewer ships 4.4MB).
• Two-way sidecar↔inline sync (combo #4) deferred past v1 — conflict policy needs care.