# 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

```bash
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`.

```json
[
  {
    "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:

```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:

```json
{
  "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

```bash
npm uninstall -g alson-annotation
```

## Development

```bash
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