Metadata-Version: 2.4
Name: coreview
Version: 0.1.0
Summary: Human-in-the-Loop remote code review MCP server for AI agents
Author-email: chenjh <chenjh16@foxmail.com>
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.100
Requires-Dist: httpx>=0.24
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: rich>=13.0
Requires-Dist: uvicorn>=0.20
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pylint>=3.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

<div align="center">

# Auto-Review MCP Service

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

[![CI](https://github.com/chenjh16/AutoReview/actions/workflows/ci.yml/badge.svg)](https://github.com/chenjh16/AutoReview/actions/workflows/ci.yml) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![Ruff](https://img.shields.io/badge/linter-ruff-261230.svg)](https://docs.astral.sh/ruff/) [![Pylint](https://img.shields.io/badge/pylint-10.0-brightgreen.svg)](https://pylint.readthedocs.io/) [![Mypy](https://img.shields.io/badge/types-mypy-blue.svg)](https://mypy-lang.org/)

**[\[English](#auto-review-mcp-service)** | **[中文\]](#auto-review-mcp-服务中文版)**

</div>

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

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

## Quick Start

### Running the Server

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

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

### Claude (`mcp_config.json`)

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

Launch Claude with:

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

```text
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](https://docs.astral.sh/uv/) (recommended) or pip

### Setup

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

```bash
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](https://docs.astral.sh/ruff/)** — linting and import sorting (rules: E, F, W, I, UP, B, SIM, RUF)
- **[Pylint](https://pylint.readthedocs.io/)** — deep static analysis (strict configuration in `pyproject.toml`)
- **[Mypy](https://mypy-lang.org/)** — static type checking (strict mode)
- **[Pytest](https://docs.pytest.org/)** — unit tests and async tests via `pytest-asyncio`

All checks run automatically on push/PR via [GitHub Actions CI](https://github.com/chenjh16/AutoReview/actions/workflows/ci.yml).

### Running Tests

```bash
# 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`](docs/architecture.md) for a detailed architecture design document, and [`AGENTS.md`](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
```

---

<div align="center">

# Auto-Review MCP 服务（中文版）

**[\[English](#auto-review-mcp-service)** | **[中文\]](#auto-review-mcp-服务中文版)**

</div>

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

## 快速开始

### 启动服务器

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

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

### Claude（`mcp_config.json`）

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

启动 Claude：

```bash
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 渲染（标题、代码块、列表等），并提供亮色 / 暗色主题（跟随系统偏好，支持手动切换）。

## 命令行参数

```text
用法: 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](https://docs.astral.sh/uv/)（推荐）或 pip

### 环境搭建

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

```bash
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](https://docs.astral.sh/ruff/)** — 代码检查与导入排序（规则：E, F, W, I, UP, B, SIM, RUF）
- **[Mypy](https://mypy-lang.org/)** — 静态类型检查（严格模式）
- **[Pytest](https://docs.pytest.org/)** — 单元测试与异步测试（通过 `pytest-asyncio`）

所有检查在 push/PR 时通过 [GitHub Actions CI](https://github.com/chenjh16/AutoReview/actions/workflows/ci.yml) 自动运行。

### 运行测试

```bash
# 运行所有测试
pytest tests/

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

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

### 项目架构

详见 [`docs/architecture.md`](docs/architecture.md) 获取详细的架构设计文档，以及 [`AGENTS.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
```
