alson-annotation

Review Markdown files in your browser with inline annotations. Submit or cancel the review, and get structured feedback back on the command line or through MCP.

Quick start

npm install -g alson-annotation
review-md document.md

The review opens in your browser. Select text, add annotations and comments, then send the feedback. The CLI prints the feedback as JSON.

Related MCP server: GitHub Style Markdown Preview MCP App

Requirements

• Node.js 18 or newer

Install

Usage

review-md <file> [options]

Questions file

The review can include questions for the reviewer. Pass a JSON file with --questions.

[
  {
    "id": "overall-quality",
    "type": "single-select",
    "label": "Overall quality",
    "options": [
      { "id": "good", "label": "Good" },
      { "id": "needs-work", "label": "Needs work" }
    ],
    "required": true
  }
]

• type: single-select or multi-select

• required: optional, defaults to false

• IDs must match ^[a-zA-Z0-9_-]+$

Output

On submit, the CLI prints structured feedback as JSON:

{
  "action": "submitted",
  "file_path": "/path/to/document.md",
  "annotations": [
    {
      "id": "ann-001",
      "source_location": { "start_line": 1, "start_col": 1, "end_line": 1, "end_col": 10 },
      "selected_text": "Hello",
      "comment": "Great intro"
    }
  ],
  "document_comments": ["Nice document"],
  "questions": { "overall-quality": "good" }
}

If the reviewer cancels, the output is { "action": "cancelled", "file_path": "..." }.

MCP server

The package includes an MCP server that exposes a review_markdown tool. Configure it in any MCP client:

{
  "mcpServers": {
    "review-md": {
      "command": "review-md-mcp"
    }
  }
}

The tool takes file_path (required) and optional inline questions. The review blocks until the reviewer submits or cancels, then returns the structured feedback.

Uninstall

npm uninstall -g alson-annotation

Development

npm ci
npm run build
npm test

• npm run build compiles the CLI and MCP server with tsc and the web app with Vite.

• npm test runs the vitest suite (unit, CLI, and MCP integration tests).

• The dist/ folder is committed so the package works when installed directly from GitHub.

License

MIT