# markdown-review

Antigravity-style **comment-on-markdown → send-to-agent** for Claude, as a clean,
installable plugin. Open a `.md` file in a live viewer, highlight a span, leave a
comment, and send it to Claude — without leaving the conversation.

Built on [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) (the same
interactive-webview mechanism Anthropic's `pdf-viewer` plugin uses). The comment
panel renders inside **Claude Desktop**.

## Three ways to comment

| Action | What it does |
|--------|--------------|
| **Answer Now** | Sends *one* comment to Claude immediately — a quick fix or question, without breaking your reading flow. Ephemeral. |
| **Add to batch** | Hold a comment while you keep reading. Nothing is sent yet. |
| **Submit All** | Flush the whole batch to Claude as one message, and save it to a sidecar so the review survives a reload. |

A per-session **Edit / Review** toggle controls what a batch *does*: in **Edit** mode
Claude applies the comments as edits to the file; in **Review** mode they become a
punch-list it works through with your approval.

Comments are stored in a sidecar (`.claude/md-comments/<hash>.json`) so your markdown
stays clean. (Memory-only and inline-marker backends are on the roadmap — see `DESIGN.md`.)

## Install

```
/plugin marketplace add https://git.tlcailab.com/tlc/markdown-review
/plugin install markdown-review@tlc-plugins
```

(or `/plugin marketplace add <local-path>` to install from a clone.)

The plugin ships a prebuilt, self-contained server (`server/dist/`), so there is no
`npm install` step on a fresh machine — it runs on `node` alone.

## Use

```
/review path/to/notes.md            # opens in edit mode
/review path/to/spec.md review      # opens in review (punch-list) mode
```

…or just ask: *"open README.md so I can comment on it."*

## Develop

Source lives in `server/src/` (TypeScript). Rebuild the shipped artifacts:

```
cd server
npm install
npm run build       # -> dist/index.js (server) + dist/mcp-app.html (webview)
npm run typecheck
node test/smoke.mjs  # end-to-end server contract test
```

- `src/server.ts` — MCP tools (`open_markdown`, app-only `submit_batch`) + UI resource
- `src/main.ts` — stdio / HTTP transports
- `src/storage.ts` — sidecar persistence
- `src/app/` — the webview (`index.html` + `mcp-app.ts`, markdown-it renderer + comment UI)
- `build.mjs` — esbuild bundling to self-contained `dist/`

## License

MIT © TLC AI Lab