coreview 0.1.0

Human-in-the-Loop remote code review MCP server for AI agents

Auto-Review MCP Service

Human-in-the-Loop remote code review MCP server for AI agents

[English | 中文]

A Human-in-the-Loop (HITL) remote code review MCP server that enables Code Agents (Cursor, Antigravity, Claude, Gemini, etc.) to request reviews from human reviewers over the network after completing coding tasks. The agent calls the human_review(task_summary) tool, the request is delivered to a remote reviewer, and the reviewer's feedback is returned to the agent for iterative improvement.

Installation

pip install .
# or for development
pip install -e ".[dev]"

Quick Start

Running the Server

python -m auto_review --port 11440

The Auto-Review MCP server runs as an independent backend, listening for human_review requests from Code Agents via MCP over SSE. When run in a terminal (TTY), it presents a rich multi-line TUI for interactive review.

On startup, the startup prompt is automatically copied to your clipboard — paste it into your AI agent's instructions so the agent knows to call human_review after completing tasks.

Usage Flow

1. Start the server: python -m auto_review --port 11440
2. Enter or confirm the project directory (defaults to the current directory).
3. The server automatically registers the MCP endpoint and creates a .cursor/rules/human_review_protocol.mdc in the project directory.
4. The startup prompt is copied to clipboard automatically. Paste it into your AI agent's instructions.
5. The agent calls human_review(task_summary) after completing a task.
6. A review request appears in the TUI — enter feedback or type LGTM.
7. The agent receives your feedback and iterates.

Tips

• Run python -m auto_review --config to generate config.toml in the current directory. Edit it to fine-tune prompts, review prefix/suffix, LGTM keywords, auto-reply timeout, and more. Changes are hot-reloaded automatically.

Configuration & Hot Reloading

Configuration is stored in TOML format. Run python -m auto_review --config to create a template in the current directory. You can customize:

• [startup] prompt: The prompt text copied to clipboard on server start.
• [review] prompt_text: The CLI terminal prompt asking for input.
• [review] review_prefix / review_suffix: Boilerplate text surrounding your comment.
• [review] lgtm_keywords: Keywords that trigger an immediate approval pass-through.
• [review] auto_reply_timeout_seconds: Seconds before auto-reply (0 to disable).
• [review] auto_reply_message: Message sent automatically when the timeout expires.
• [review] reload_message: Message sent by the /reload command.

The config file is hot-reloaded automatically. Any changes saved to the TOML file will take effect within ~2 seconds without needing to restart the server. A green notification confirms the update as a 5-second toolbar banner with a countdown timer. Use the --config parameter to specify a custom file path.

MCP Endpoint

Protocol	URL
MCP SSE	http://127.0.0.1:11440/mcp/sse

Agent Configuration

Cursor

Auto-Review automatically registers itself in the project's .cursor/mcp.json on startup. No manual configuration needed.

Gemini / iFlow (~/.gemini/settings.json or ~/.iflow/settings.json)

{
  "mcpServers": {
    "auto_review_server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:11440/mcp/sse"]
    }
  }
}

Claude (mcp_config.json)

{
  "mcpServers": {
    "auto_review_server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:11440/mcp/sse"]
    }
  }
}

Launch Claude with:

claude --mcp-config mcp_config.json --strict-mcp-config

Tool Reference

human_review(task_summary: str) -> str

Parameter	Type	Description
task_summary	str	Summary of the completed task for human review
Returns	str	Human reviewer's comments / feedback

Agent usage pattern:

1. Agent completes a task
2. Agent calls human_review(task_summary="Implemented feature X with files A, B, C …")
3. Human reviews the summary and provides feedback
4. Agent receives the feedback and acts on it (fix issues, continue, etc.)

Interactive Review TUI

When the server runs in a TTY terminal, a persistent multi-line editor stays at the bottom of the screen (like Claude Code / OpenCode). Review requests and system messages appear above the editor. It supports:

• Arrow keys for navigation
• Enter to insert newlines
• Paste large blocks of text freely
• Esc + Enter to submit your review
• Ctrl+T to schedule a test review request (requires --testmode)

Type LGTM (or any configured approval keyword) to approve the agent's work.

Slash Commands

Command	Description
/lgtm	Approve the current review
/reload	Restart the server with updated code
/test	Simulate a fake review request in 2 seconds (requires --testmode)
/dump	Export the current session's review history to HTML
/quit	Gracefully shut down the server
/exit	Alias for /quit

Keyboard Shortcuts

Key	Action
Esc+Enter	Submit review (when a request is pending)
Ctrl+T	Schedule a fake test review request (requires --testmode)

Review History & Export

All review requests and human-written responses are automatically logged in JSONL format under logs/sessions/. Each server session gets its own log file named by timestamp (e.g., 20260307_143022.jsonl).

Use the /dump slash command or make dump to export the current session to a self-contained HTML page in export/html/. The exported page renders both review requests and responses with full markdown support (headings, code blocks, lists, etc.). It supports light/dark themes (follows system preference, with a manual toggle).

CLI Options

usage: auto-review [-h] [--config [CONFIG]] [--port PORT] [--host HOST]
                   [--testmode]

options:
  --config [CONFIG]        Path to TOML config file. Without a value, creates a template in the current directory.
  --port PORT              Port to listen on (default: 11440)
  --host HOST              Host to bind to (default: 127.0.0.1)
  --testmode               Enable Ctrl+T and /test for fake review requests

Development

Prerequisites

• Python 3.11+
• uv (recommended) or pip

Setup

git clone https://github.com/chenjh16/AutoReview.git
cd AutoReview

# Create virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

Make Targets

make test            # Run pytest test suite
make lint            # Run static analysis (ruff + mypy + pylint)
make check           # Run lint + test together
make dump            # Export most recent session to HTML
make release         # Build wheel and sdist
make github-release          # Tag current version and push to trigger release action
make github-release FORCE=1  # Force-overwrite existing tag and re-trigger release
make clean                   # Remove build artifacts

Code Quality

The project enforces strict code quality via:

• Ruff — linting and import sorting (rules: E, F, W, I, UP, B, SIM, RUF)
• Pylint — deep static analysis (strict configuration in pyproject.toml)
• Mypy — static type checking (strict mode)
• Pytest — unit tests and async tests via pytest-asyncio

All checks run automatically on push/PR via GitHub Actions CI.

Running Tests

# Run all tests
pytest tests/

# Run a specific test file
pytest tests/test_tui.py -v

# Run end-to-end test (starts a real server)
pytest tests/e2e_test.py -v

Project Architecture

See docs/architecture.md for a detailed architecture design document, and AGENTS.md for the development guide oriented toward AI agents.

Directory Structure

auto_review/                         # Repository root
├── pyproject.toml                   # Build config, dependencies
├── Makefile                         # release, test, lint, check, dump, clean
├── README.md                        # User-facing documentation (EN/CN)
├── AGENTS.md                        # Architecture & development guide
├── docs/
│   └── architecture.md              # Detailed architecture design document
├── .github/workflows/
│   ├── ci.yml                       # GitHub Actions CI (lint + test)
│   └── release.yml                  # GitHub Actions release (build + publish)
│
├── src/auto_review/                 # Python package
│   ├── __init__.py                  # Package init, __version__
│   ├── __main__.py                  # Entry: python -m auto_review
│   ├── cli.py                       # CLI parsing, Cursor auto-registration
│   ├── cli_ui.py                    # Rich startup UI (tool banner, tutorial)
│   ├── cli_templates.py             # Config template & Cursor rule generation
│   ├── server.py                    # FastAPI app factory, CORS, uvicorn
│   ├── bus.py                       # Async EventBus (pub/sub singleton)
│   ├── state.py                     # ReviewStore, PendingReview, state machine
│   ├── actions.py                   # Frozen dataclass action types
│   ├── config.py                    # Hot-reloadable TOML config
│   ├── client.py                    # MCP test client (SSE)
│   ├── utils.py                     # Console, logging, shared state
│   ├── config.toml                  # Default TOML configuration
│   ├── services/
│   │   ├── mcp_service.py           # FastMCP server, human_review tool
│   │   ├── api_service.py           # REST API routes
│   │   ├── notification.py          # Cross-platform desktop notifications
│   │   ├── history.py               # Review history JSONL logger
│   │   ├── export.py                # HTML export for review sessions
│   │   ├── clipboard.py             # Cross-platform clipboard copy
│   │   └── auto_reply.py            # Summary preview helper
│   └── tui/
│       ├── consumer.py              # Main TUI loop (persistent editor)
│       ├── display.py               # Review panels, notifications
│       ├── editor.py                # prompt_toolkit session, keybindings
│       ├── commands.py              # Slash commands, dispatch, completion
│       └── toolbar.py               # Bottom toolbar with keybinding hints
│
└── tests/                           # Unit & E2E tests
    ├── test_actions.py              # Action dataclass tests
    ├── test_bus.py                  # EventBus subscribe/publish tests
    ├── test_cli.py                  # CLI args, auto-registration, templates
    ├── test_config.py               # Config load, reload, defaults
    ├── test_services.py             # MCP, API, notification service tests
    ├── test_state.py                # ReviewStore, PendingReview, timeout
    ├── test_tui.py                  # TUI component tests
    ├── test_utils.py                # log_box helper tests
    └── e2e_test.py                  # Full E2E: server + MCP client + REST

---

Auto-Review MCP 服务（中文版）

[English | 中文]

Human-in-the-Loop (HITL) 远程代码审核 MCP Server 项目，支持让 Code Agent（如 Cursor、Antigravity 等）在完成编码任务后，向网络上的 Reviewer 发起 Review 请求，并按照 Review 建议作出改进。Agent 调用 human_review(task_summary) 工具后，请求会通过 MCP SSE 和 REST API 流转到远程审核者，审核者输入反馈意见后返回给 Agent，形成人机协作的闭环。

快速开始

启动服务器

python -m auto_review --port 11440

Auto-Review MCP Server 作为独立的后端运行，通过 MCP over SSE 监听来自 Code Agent 的 human_review 请求。在终端（TTY）中运行时，它会展示一个富文本多行 TUI 编辑器供审核者交互式地提交审核。

启动时，启动提示词会自动复制到剪贴板——将其粘贴到 AI Agent 的指令中，以便 Agent 在完成任务后调用 human_review。

使用流程

1. 启动服务器：python -m auto_review --port 11440
2. 输入或确认项目目录（默认为当前目录）。
3. 服务器自动在项目目录中注册 MCP 端点并创建 .cursor/rules/human_review_protocol.mdc 规则文件。
4. 启动提示词会自动复制到剪贴板。将其粘贴到 AI Agent 的指令中。
5. Agent 完成任务后调用 human_review(task_summary)。
6. TUI 中出现审核请求——输入反馈意见或输入 LGTM 批准。
7. Agent 收到反馈后据此继续迭代。

使用建议

• 运行 python -m auto_review --config 可在当前目录生成 config.toml 配置模板。编辑它可以微调提示词、审核前缀/后缀、LGTM 关键词、自动回复超时等。配置文件支持自动热更新。

配置与热更新 (Hot Reloading)

配置文件采用 TOML 格式。运行 python -m auto_review --config 可在当前目录创建配置模板。你可以定制：

• [startup] prompt: 启动时复制到剪贴板的提示词。
• [review] prompt_text: 终端上的输入提示语。
• [review] review_prefix / review_suffix: 包裹你的评审建议的样板指引文本。
• [review] lgtm_keywords: 触发立即批准（Approval）的关键词列表。
• [review] auto_reply_timeout_seconds: 自动回复的超时秒数（设为 0 禁用）。
• [review] auto_reply_message: 超时后自动发送的消息。
• [review] reload_message: /reload 命令发送的消息。

该配置文件支持自动热更新。 任何对 TOML 文件的保存修改都会在约 2 秒内生效，无需重启服务器！更新后会在工具栏显示 5 秒倒计时的绿色通知横幅。亦可通过 --config 参数指定自定义的配置文件路径。

MCP 端点

协议	URL
MCP SSE	http://127.0.0.1:11440/mcp/sse

Agent 配置

Cursor

Auto-Review 启动时会自动注册到项目的 .cursor/mcp.json，无需手动配置。

Gemini / iFlow（~/.gemini/settings.json 或 ~/.iflow/settings.json）

{
  "mcpServers": {
    "auto_review_server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:11440/mcp/sse"]
    }
  }
}

Claude（mcp_config.json）

{
  "mcpServers": {
    "auto_review_server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:11440/mcp/sse"]
    }
  }
}

启动 Claude：

claude --mcp-config mcp_config.json --strict-mcp-config

工具参考

human_review(task_summary: str) -> str

参数	类型	说明
task_summary	str	已完成任务的摘要，供人类审核
返回值	str	人类审核者的意见 / 反馈

Agent 使用流程：

1. Agent 完成一个任务
2. Agent 调用 human_review(task_summary="实现了功能 X，涉及文件 A、B、C …")
3. 人类审核者查看摘要并输入反馈意见
4. Agent 收到反馈后据此继续操作（修复问题、继续开发等）

交互式审核 TUI

当服务器在 TTY 终端中运行时，屏幕底部会常驻一个多行编辑器（类似 Claude Code / OpenCode）。审核请求和系统消息显示在编辑器上方。编辑器支持：

• 方向键导航
• Enter 插入换行
• 自由粘贴大段文本
• Esc + Enter 提交审核
• Ctrl+T 调度测试审核请求（需要 --testmode）

输入 LGTM（或任何配置的批准关键词）即可批准 Agent 的工作。

斜杠命令

命令	说明
/lgtm	批准当前审核
/reload	重启服务器并加载更新后的代码
/test	2 秒后模拟一个假审核请求（需要 --testmode）
/dump	将当前会话的审核历史导出为 HTML
/quit	优雅地关闭服务器
/exit	/quit 的别名

快捷键

按键	操作
Esc+Enter	提交审核（有待处理请求时）
Ctrl+T	调度一个假测试审核请求（需要 --testmode）

审核历史与导出

所有审核请求和人工编写的审核回复会自动以 JSONL 格式记录在 logs/sessions/ 目录下。每个服务器会话拥有独立的日志文件，以时间戳命名（如 20260307_143022.jsonl）。

使用 /dump 斜杠命令或 make dump 可将当前会话导出为独立的 HTML 页面，保存在 export/html/ 目录下。导出页面支持完整的 Markdown 渲染（标题、代码块、列表等），并提供亮色 / 暗色主题（跟随系统偏好，支持手动切换）。

命令行参数

用法: auto-review [-h] [--config [CONFIG]] [--port PORT] [--host HOST]
                  [--testmode]

选项:
  --config [CONFIG]        TOML 配置文件路径。不带参数时，在当前目录创建配置模板。
  --port PORT              监听端口（默认: 11440）
  --host HOST              绑定地址（默认: 127.0.0.1）
  --testmode               启用 Ctrl+T 和 /test 假审核请求功能

开发

前置条件

• Python 3.11+
• uv（推荐）或 pip

环境搭建

git clone https://github.com/chenjh16/AutoReview.git
cd AutoReview

# 创建虚拟环境并安装依赖
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 以可编辑模式安装（含开发依赖）
pip install -e ".[dev]"

Make 命令

make test            # 运行 pytest 测试套件
make lint            # 运行静态分析（ruff + mypy + pylint）
make check           # 同时运行 lint + test
make dump            # 导出最近会话为 HTML
make release         # 构建 wheel 和 sdist
make github-release          # 标记当前版本并推送以触发 release action
make github-release FORCE=1  # 强制覆盖已有标签并重新触发发布
make clean                   # 清理构建产物

代码质量

项目通过以下工具强制执行严格的代码质量标准：

• Ruff — 代码检查与导入排序（规则：E, F, W, I, UP, B, SIM, RUF）
• Mypy — 静态类型检查（严格模式）
• Pytest — 单元测试与异步测试（通过 pytest-asyncio）

所有检查在 push/PR 时通过 GitHub Actions CI 自动运行。

运行测试

# 运行所有测试
pytest tests/

# 运行指定测试文件
pytest tests/test_tui.py -v

# 运行端到端测试（会启动真实服务器）
pytest tests/e2e_test.py -v

项目架构

详见 docs/architecture.md 获取详细的架构设计文档，以及 AGENTS.md 获取面向 AI Agent 的开发指南。

目录结构

auto_review/                         # 仓库根目录
├── pyproject.toml                   # 构建配置、依赖
├── Makefile                         # release, test, lint, check, dump, clean
├── README.md                        # 用户文档（中英文）
├── AGENTS.md                        # 架构与开发指南
├── docs/
│   └── architecture.md              # 详细架构设计文档
├── .github/workflows/
│   ├── ci.yml                       # GitHub Actions CI（lint + test）
│   └── release.yml                  # GitHub Actions 发布（build + publish）
│
├── src/auto_review/                 # Python 包
│   ├── __init__.py                  # 包初始化、__version__
│   ├── __main__.py                  # 入口：python -m auto_review
│   ├── cli.py                       # CLI 参数解析、Cursor 自动注册
│   ├── cli_ui.py                    # Rich 启动 UI（工具横幅、启动教程）
│   ├── cli_templates.py             # 配置模板与 Cursor 规则文件生成
│   ├── server.py                    # FastAPI 应用工厂、CORS、uvicorn
│   ├── bus.py                       # 异步 EventBus（发布/订阅单例）
│   ├── state.py                     # ReviewStore、PendingReview、状态机
│   ├── actions.py                   # 冻结 dataclass 动作类型
│   ├── config.py                    # 热更新 TOML 配置
│   ├── client.py                    # MCP 测试客户端（SSE）
│   ├── utils.py                     # 控制台、日志、共享状态
│   ├── config.toml                  # 默认 TOML 配置
│   ├── services/
│   │   ├── mcp_service.py           # FastMCP 服务器、human_review 工具
│   │   ├── api_service.py           # REST API 路由
│   │   ├── notification.py          # 跨平台桌面通知
│   │   ├── history.py               # 审核历史 JSONL 记录器
│   │   ├── export.py                # 审核会话 HTML 导出
│   │   ├── clipboard.py             # 跨平台剪贴板复制
│   │   └── auto_reply.py            # 摘要预览辅助
│   └── tui/
│       ├── consumer.py              # 主 TUI 循环（常驻编辑器）
│       ├── display.py               # 审核面板、通知
│       ├── editor.py                # prompt_toolkit 会话、快捷键
│       ├── commands.py              # 斜杠命令、分发、补全
│       └── toolbar.py               # 底部工具栏与快捷键提示
│
└── tests/                           # 单元测试与端到端测试
    ├── test_actions.py              # Action dataclass 测试
    ├── test_bus.py                  # EventBus 订阅/发布测试
    ├── test_cli.py                  # CLI 参数、自动注册、模板测试
    ├── test_config.py               # 配置加载、重载、默认值测试
    ├── test_services.py             # MCP、API、通知服务测试
    ├── test_state.py                # ReviewStore、PendingReview、超时测试
    ├── test_tui.py                  # TUI 组件测试
    ├── test_utils.py                # log_box 辅助函数测试
    └── e2e_test.py                  # 端到端：服务器 + MCP 客户端 + REST