md-annotate

A shared markdown review surface between Claude (via MCP) and humans (via browser). Push markdown documents, annotate them inline like a GitHub PR review, and generate structured revision prompts — all in a local-first workflow.

How it works

┌────────────────┐                ┌────────────────┐                ┌────────────────┐
│     Claude     │   MCP tools    │  md-annotate   │  Browser UI    │     Human      │
│   (or any AI)  │ ══════════════>│     daemon     │<══════════════ │   (reviewer)   │
│                │ <══════════════│                │ ══════════════>│                │
└────────────────┘  push / read   └────────────────┘ annotate/view  └────────────────┘

1. Claude pushes a markdown document via the md_push MCP tool
2. Human reviews in the browser — select text, add inline annotations (like PR review comments)
3. Claude reads annotations via md_get_annotations and revises the document
4. Repeat until done

Quick start

# Clone and install
git clone https://github.com/alaeddineG/md-annotate.git
cd md-annotate
npm install

# Build the UI
npm run build

# Start the daemon
npm start
# → http://localhost:4242

Or use the setup script which handles everything including the MCP bridge:

# macOS / Linux
chmod +x setup.sh
./setup.sh

# Windows (PowerShell)
.\setup.ps1

MCP integration

md-annotate exposes four tools to Claude via the Model Context Protocol:

Tool	Description
md_push	Push a markdown document for review
md_get_annotations	Read all human annotations on a document
md_list_documents	List all documents in the review queue
md_clear_annotations	Clear annotations after incorporating feedback

Claude Desktop (stdio transport)

Add to your Claude Desktop MCP config:

{
  "mcpServers": {
    "md-annotate": {
      "command": "npx",
      "args": ["md-annotate", "mcp"]
    }
  }
}

Standalone MCP bridge

For environments where the MCP bridge needs to live outside the project directory (e.g. macOS sandbox restrictions with Claude Desktop):

# Build the self-contained bridge
npm run build:mcp

# Copy it somewhere accessible
mkdir -p ~/.mcp_servers/md-annotate
cp mcp-bridge.js ~/.mcp_servers/md-annotate/

Then configure Claude Desktop:

{
  "mcpServers": {
    "md-annotate": {
      "command": "node",
      "args": [
        "/Users/you/.mcp_servers/md-annotate/mcp-bridge.js",
        "--daemon-url", "http://localhost:4242"
      ]
    }
  }
}

Remote daemon

If the daemon runs on a different machine:

{
  "mcpServers": {
    "md-annotate": {
      "command": "npx",
      "args": ["md-annotate", "mcp", "--daemon-url", "http://192.168.1.100:4242"]
    }
  }
}

CLI

md-annotate start [--port 4242] [--host 0.0.0.0]   Start the daemon
md-annotate stop                                     Stop the daemon
md-annotate status                                   Show daemon status
md-annotate open                                     Open UI in browser
md-annotate push <file.md> [--id ID] [--context ""]  Push a file for review
md-annotate mcp [--daemon-url <url>]                 Run MCP stdio bridge

Architecture

md-annotate/
├── bin/cli.js            # CLI entry point
├── server/
│   ├── daemon.js         # Express server (REST API + SSE + static files)
│   ├── mcp.js            # MCP server (stdio + HTTP transports)
│   └── store.js          # File-based document/annotation storage
├── src/                  # React frontend (Vite + @primer/react)
│   ├── App.jsx           # Main app with SSE real-time updates
│   └── components/
│       ├── RawView.jsx          # Raw markdown with inline review threads
│       ├── MarkdownPreview.jsx  # Rendered markdown preview
│       ├── SelectionPopover.jsx # Text selection → annotation popover
│       ├── DocumentList.jsx     # Sidebar document list
│       ├── ModeToggle.jsx       # Raw/Preview toggle
│       └── PromptGenerator.jsx  # Generate revision prompt from annotations
├── mcp-standalone.js     # Entry point for standalone MCP bridge
├── setup.sh              # Setup script (macOS/Linux)
└── setup.ps1             # Setup script (Windows)

Storage: Documents and annotations are persisted as JSON files under ~/.md-annotate/documents/.

Real-time: The browser connects via Server-Sent Events (SSE) so annotations and document updates appear instantly — whether created from the UI or pushed via MCP.

Development

# Start Vite dev server (hot reload) + proxy to daemon
npm run dev

# In another terminal, start the daemon
node server/daemon.js

Platform support

Works on macOS, Linux, and Windows. The daemon, CLI, and MCP bridge are pure Node.js with no native dependencies. The setup.sh script is bash-only (macOS/Linux) — on Windows, run the steps manually or use WSL.

Requirements

• Node.js >= 18
• A browser
• Claude Desktop or any MCP-compatible client (for the AI side)

License

MIT