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.

Requirements

• Node.js 18 or newer

Install

Method	Command
Global (recommended)	npm install -g alson-annotation
Run once without install	npx alson-annotation document.md
From GitHub	npm install -g github:agnojf/alson-annotation
From source	git clone https://github.com/agnojf/alson-annotation.git then npm ci && npm run build

Usage

review-md <file> [options]

Argument / option	Description
<file>	Path to the Markdown file to review (required)
--questions, -q <path>	Path to a questions JSON file
--port, -p <number>	Preferred port for the local server
--help, -h	Print help
--version, -v	Print version

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