Batch Review

A collaborative code and markdown review tool that bridges human reviewers and AI agents. Both can browse files, inspect git diffs, leave structured comments, and save a final review report — all from the same UI, in real time.

Features

Requirements

• Python ≥ 3.11 with uv
• Node.js ≥ 18 (for the one-time frontend build)

Installation

git clone https://github.com/your-org/batch-review-mcp
cd batch-review-mcp
uv sync

The first run will automatically build the React frontend if frontend/dist/ does not exist (requires Node.js + npm on PATH).

Usage

Standalone mode (browser opens by default)

# Review the current directory
uv run batch-review

# Review a specific git repository
uv run batch-review --root /path/to/your/repo

# Custom host / port
uv run batch-review --root /path/to/repo --host 0.0.0.0 --port 9100

# Specify output filenames
uv run batch-review --root /path/to/repo --output review --output-dir /tmp/reviews
# → saves /tmp/reviews/review.json and /tmp/reviews/review.md

The server auto-selects a free port in the 9000–9999 range if the default port is already in use.

MCP stdio mode (Claude Desktop / Cursor / any MCP client; browser opens by default)

uv run batch-review --mcp --root /path/to/repo

The HTTP server starts in a background thread (so the browser UI remains accessible), your default browser opens to the app URL (same as standalone mode; use --no-browser to skip), and the MCP stdio transport runs in the main thread.

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "batch-review": {
      "command": "uv",
      "args": ["run", "batch-review", "--mcp", "--root", "/path/to/repo"]
    }
  }
}

Official MCP registry

This project includes a root-level server.json for the Model Context Protocol registry (preview). The entry uses registryType": "mcpb": the download URL must be a public GitHub release asset, and fileSha256 must match those bytes exactly (the Release workflow builds the .mcpb on Linux, which can differ from a pack produced on Windows).

Recommended order for a new version (e.g. v0.2.0):

1. Bump version in pyproject.toml, mcpb/manifest.json, and server.json (top-level version plus packages[0].identifier URL: .../releases/download/v0.2.0/batch-review-mcp-0.2.0.mcpb).
2. In GitHub Actions, run MCP registry preflight (Linux MCPB hash) (workflow_dispatch). Open the job summary and copy the printed SHA-256 into server.json → packages[0].fileSha256. Commit and push to main.
3. Push the tag (e.g. git tag v0.2.0 && git push origin v0.2.0). The Release workflow runs scripts/verify_release_mcp_registry.py before uploading; if identifier, versions, or fileSha256 do not match the Linux-built .mcpb, the job fails so you never publish a broken asset to the registry.
4. After the release exists, run mcp-publisher publish (with mcp-publisher and mcp-publisher login github). Optional: add PYPI_API_TOKEN so the same workflow can uv publish the wheel/sdist.

CLI flags

UI Walkthrough

Left panel — two tabs

Files tab — recursive directory tree. Click a file to open it in the center panel.

Git tab — lists files changed relative to HEAD with status badges:

• 🟡 M modified
• 🟢 A added
• 🔴 D deleted
• ⚪ U untracked

Click a changed file to open it in inline diff mode.

Center panel

• Markdown files — fully rendered. Select any text with the mouse and click + Add Comment to create a comment anchored to those line numbers.
• Code files — Monaco Editor with syntax highlighting. Select lines and click + Add Comment in the toolbar.
• Diff view — Monaco DiffEditor showing original (HEAD) vs working tree inline (red = removed, green = added). Switch back to normal view via the Git tab or by clicking the file in the Files tab.

Right panel

Each comment shows:

• @filename:L10-15 reference — click to jump to that location in the center panel
• A text area for your review notes (auto-saves on blur)
• A delete button

The 💾 Save Review button saves all comments to:

• <output-dir>/<output>.json — machine-readable JSON array
• <output-dir>/<output>.md — human-readable Markdown report grouped by file

When the server starts, if that JSON file already exists it is loaded into the session so you can continue a saved review (invalid files are skipped with a log warning).

MCP Tools

AI agents connect via http://localhost:<port>/mcp (HTTP transport) or stdio (--mcp flag).

Repo-local MCP host configuration

This repository includes checked-in defaults so common agents can use Batch Review and Playwright together:

All definitions run uv run batch-review --mcp --root . --skip-build so the review root is the workspace directory hosts use as the server cwd. Cursor’s agent CLI does not always expand ${workspaceFolder} inside args, so these configs use "." for --root (VS Code may still use ${workspaceFolder} in .vscode/mcp.json, which that host expands).

Verifying stdio MCP

# Smoke test with the official Python MCP client
uv run python scripts/test_mcp_client.py

# Cursor Agent CLI (after install: https://cursor.com/docs/cli )
cd /path/to/batch_review_mcp
agent mcp enable batch-review
agent mcp list-tools batch-review
agent --approve-mcps -p "Your prompt that may call MCP tools"

Comment add, update, delete, and load_review_by_stem also push a dismissible toast at the bottom of the right panel (similar styling to the post-save path hints).

Output formats

JSON (review_comments.json)

[
  {
    "id": "4c66b5fc-...",
    "file_path": "src/auth.py",
    "line_start": 42,
    "line_end": 55,
    "reference": "@src/auth.py:L42-55",
    "text": "Token is never validated — add expiry check.",
    "created_at": "2026-04-15T10:00:00+00:00"
  }
]

Markdown (review_comments.md)

# Code Review

_Generated: 2026-04-15 10:00 UTC — 3 comment(s)_

---

## src/auth.py

### `@src/auth.py:L42-55`
> Token is never validated — add expiry check.

---

Development

# Backend only (no frontend build needed)
uv run batch-review --root . --skip-build --no-browser

# Frontend dev server (proxies API to port 9000)
cd frontend && npm run dev

# Full production build
cd frontend && npm run build

License

MIT