coreview 0.1.0.dev3

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

CoReview 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

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

Quick Start

Running the Server

coreview
# or
python -m coreview

The CoReview 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: coreview (auto-selects a free port, use --port to specify).
2. Enter or confirm the project directory (defaults to cwd). Enter - to skip registration.
3. The server auto-registers the MCP endpoint and installs rules. Existing human_review_* entries are scanned: offline servers are removed, online servers are kept, then the new entry is added. Rules are replaced only if content differs.
4. The startup prompt is copied to clipboard — 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 coreview --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 coreview --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 (Streamable HTTP)	http://127.0.0.1:<port>/mcp
MCP (SSE, legacy)	http://127.0.0.1:<port>/mcp/sse

The actual port is shown in the server banner on startup. Both transports serve the same MCP tool.

Agent Configuration

Use --agent to select the client agent (default: cursor). CoReview auto-registers the MCP endpoint and installs rules on startup.

MCP Auto-Registration

Agent	--agent value	Config file	Scope
Cursor	cursor	.cursor/mcp.json	per-project
Claude Code	claudecode	.mcp.json	per-project
OpenCode	opencode	opencode.json	per-project
Gemini CLI	gemini	.gemini/settings.json	per-project
Antigravity	antigravity	~/.gemini/antigravity/mcp_config.json	global

Upsert logic: When registering, CoReview scans existing human_review_* entries in the config file. Each entry's server URL is probed — offline entries are removed, online entries are preserved. The new entry is then always added.

Rule Auto-Installation

Agent	Rule target	Method
Cursor	.cursor/rules/*.mdc	Individual rule files
Claude Code	.claude/rules/*.md	Individual rule files (frontmatter adapted)
Antigravity	.agent/rules/*.md	Individual rule files (frontmatter stripped)
OpenCode	AGENTS.md	Append with HTML comment markers
Gemini CLI	GEMINI.md	Append with HTML comment markers

Rules are content-compared: existing files are only replaced if content differs. Instruction file sections are wrapped in <!-- coreview:rule:name --> markers for idempotent updates.

Enter - as the project directory to skip all MCP and rule registration.

Manual MCP Configuration

For agents that require manual configuration (e.g. iFlow):

{
  "mcpServers": {
    "coreview_server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:<port>/mcp/sse"]
    }
  }
}

Replace <port> with the actual port shown in the server banner.

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
• Esc + Esc to clear the editor
• Ctrl+Z to undo
• 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)
Esc+Esc	Clear editor content
Ctrl+Z	Undo last edit
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 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: coreview [-h] [--config [CONFIG]] [--port PORT] [--host HOST]
                [--agent AGENT] [--rules [RULE ...]] [--list-rules]
                [--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: auto-select free port)
  --host HOST              Host to bind to (default: 127.0.0.1)
  --agent AGENT            Client agent type: cursor, antigravity, claudecode,
                           opencode, gemini (default: cursor)
  --rules [RULE ...]       Rules to install (default: human-review-protocol).
                           Use --rules with no args to install all.
  --list-rules             List available rules and exit.
  --testmode               Enable Ctrl+T and /test for fake review requests

Development

Prerequisites

• Python 3.11+
• uv — this project uses uv for all venv and package operations

Setup

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

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

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

Make Targets

make                         # Show help (default target)
make build                   # Build wheel with current Python
make build-all               # Build wheels for all Python versions (3.11–3.14)
make test                    # Run pytest test suite
make test-e2e VER=3.13       # Full pipeline: lint → test → build → install → e2e
make test-e2e-all            # E2E for all Python versions
make lint                    # Run static analysis (ruff + mypy + pylint)
make check                   # Run lint + test together
make release                 # Build + zip wheel
make release-all             # Build + zip for all versions
make upload-testpypi         # Upload to TestPyPI
make upload-pypi             # Upload to PyPI
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/test_e2e.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

coreview/                            # Repository root
├── pyproject.toml                   # Build config, dependencies
├── Makefile                         # help, build, release, test, lint, check, 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/coreview/                    # Python package
│   ├── __init__.py                  # Package init, __version__
│   ├── __main__.py                  # Entry: python -m coreview
│   ├── cli.py                       # CLI parsing, server startup orchestration
│   ├── cli_ui.py                    # Rich startup UI (tool banner, tutorial)
│   ├── cli_templates.py             # Config template & rule generation delegate
│   ├── data/
│   │   ├── config.toml              # Default TOML configuration
│   │   └── rules/                   # Bundled rule files (*.md)
│   │       └── human-review-protocol.md
│   └── core/                        # Core logic (binary-packaged via Nuitka)
│       ├── __init__.py              # Core package init
│       ├── agents.py                # Agent registry, MCP registration, rules
│       ├── 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
│       ├── 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, agent registration, rules
    ├── 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
    └── test_e2e.py                  # Full E2E: server + MCP client + REST

---

CoReview 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，形成人机协作的闭环。

快速开始

启动服务器

coreview
# 或
python -m coreview

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

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

使用流程

1. 启动服务器：coreview（自动选择空闲端口，可用 --port 指定）。
2. 输入或确认项目目录（默认为当前目录）。输入 - 可跳过注册。
3. 服务器自动注册 MCP 端点并安装规则文件。已有的 human_review_* 条目会被逐一检查：离线的服务器会被移除，在线的服务器会被保留，然后新增当前实例。规则文件仅在内容不同时替换。
4. 启动提示词自动复制到剪贴板——粘贴到 AI Agent 的指令中。
5. Agent 完成任务后调用 human_review(task_summary)。
6. TUI 中出现审核请求——输入反馈意见或输入 LGTM 批准。
7. Agent 收到反馈后据此继续迭代。

使用建议

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

配置与热更新 (Hot Reloading)

配置文件采用 TOML 格式。运行 python -m coreview --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（Streamable HTTP）	http://127.0.0.1:<port>/mcp
MCP（SSE，旧版）	http://127.0.0.1:<port>/mcp/sse

实际端口号显示在启动时的服务器横幅中。两种传输协议提供相同的 MCP 工具。

Agent 配置

使用 --agent 选择客户端 Agent（默认：cursor）。CoReview 启动时会自动注册 MCP 端点并安装规则。

MCP 自动注册

Agent	--agent 值	配置文件	作用域
Cursor	cursor	.cursor/mcp.json	项目级
Claude Code	claudecode	.mcp.json	项目级
OpenCode	opencode	opencode.json	项目级
Gemini CLI	gemini	.gemini/settings.json	项目级
Antigravity	antigravity	~/.gemini/antigravity/mcp_config.json	全局

Upsert 逻辑：注册时，CoReview 会扫描配置文件中已有的 human_review_* 条目，逐一探测其服务器 URL — 离线的条目会被移除，在线的条目会被保留。然后始终新增当前实例的条目。

规则自动安装

Agent	规则目标	方式
Cursor	.cursor/rules/*.mdc	独立规则文件
Claude Code	.claude/rules/*.md	独立规则文件（frontmatter 适配）
Antigravity	.agent/rules/*.md	独立规则文件（frontmatter 剥离）
OpenCode	AGENTS.md	以 HTML 注释标记追加
Gemini CLI	GEMINI.md	以 HTML 注释标记追加

规则按内容比对：已有文件仅在内容不同时替换。指令文件中的规则段落以 <!-- coreview:rule:name --> 标记包裹，支持幂等更新。

输入 - 作为项目目录可跳过所有 MCP 和规则注册。

手动 MCP 配置

对于需要手动配置的 Agent（如 iFlow）：

{
  "mcpServers": {
    "coreview_server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:<port>/mcp/sse"]
    }
  }
}

将 <port> 替换为启动时服务器横幅中显示的实际端口号。

工具参考

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 提交审核
• Esc + Esc 清空编辑器
• Ctrl+Z 撤销
• Ctrl+T 调度测试审核请求（需要 --testmode）

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

斜杠命令

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

快捷键

按键	操作
Esc+Enter	提交审核（有待处理请求时）
Esc+Esc	清空编辑器内容
Ctrl+Z	撤销上一次编辑
Ctrl+T	调度一个假测试审核请求（需要 --testmode）

审核历史与导出

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

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

命令行参数

用法: coreview [-h] [--config [CONFIG]] [--port PORT] [--host HOST]
               [--agent AGENT] [--rules [RULE ...]] [--list-rules]
               [--testmode]

选项:
  --config [CONFIG]        TOML 配置文件路径。不带参数时，在当前目录创建配置模板。
  --port PORT              监听端口（默认: 自动选择空闲端口）
  --host HOST              绑定地址（默认: 127.0.0.1）
  --agent AGENT            客户端 Agent 类型: cursor, antigravity, claudecode,
                           opencode, gemini（默认: cursor）
  --rules [RULE ...]       安装的规则（默认: human-review-protocol）。
                           不带参数时安装全部规则。
  --list-rules             列出可用规则并退出。
  --testmode               启用 Ctrl+T 和 /test 假审核请求功能

开发

前置条件

• Python 3.11+
• uv — 本项目使用 uv 进行所有虚拟环境和包管理操作

环境搭建

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

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

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

Make 命令

make                         # 显示帮助（默认目标）
make build                   # 使用当前 Python 构建 wheel
make build-all               # 为所有 Python 版本构建 wheel（3.11–3.14）
make test                    # 运行 pytest 测试套件
make test-e2e VER=3.13       # 完整流水线：lint → test → build → install → e2e
make test-e2e-all            # 为所有 Python 版本运行 E2E
make lint                    # 运行静态分析（ruff + mypy + pylint）
make check                   # 同时运行 lint + test
make release                 # 构建 + 打包 wheel
make release-all             # 为所有版本构建 + 打包
make upload-testpypi         # 上传到 TestPyPI
make upload-pypi             # 上传到 PyPI
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/test_e2e.py -v

项目架构

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

目录结构

coreview/                            # 仓库根目录
├── pyproject.toml                   # 构建配置、依赖
├── Makefile                         # help, build, release, test, lint, check, clean
├── README.md                        # 用户文档（中英文）
├── AGENTS.md                        # 架构与开发指南
├── docs/
│   └── architecture.md              # 详细架构设计文档
├── .github/workflows/
│   ├── ci.yml                       # GitHub Actions CI（lint + test）
│   └── release.yml                  # GitHub Actions 发布（build + publish）
│
├── src/coreview/                    # Python 包
│   ├── __init__.py                  # 包初始化、__version__
│   ├── __main__.py                  # 入口：python -m coreview
│   ├── cli.py                       # CLI 参数解析、服务启动编排
│   ├── cli_ui.py                    # Rich 启动 UI（工具横幅、启动教程）
│   ├── cli_templates.py             # 配置模板与规则文件生成委托
│   ├── data/
│   │   ├── config.toml              # 默认 TOML 配置
│   │   └── rules/                   # 内置规则文件（*.md）
│   │       └── human-review-protocol.md
│   └── core/                        # 核心逻辑（通过 Nuitka 二进制打包）
│       ├── __init__.py              # Core 包初始化
│       ├── agents.py                # Agent 注册表、MCP 注册、规则管理
│       ├── server.py                # FastAPI 应用工厂、CORS、uvicorn
│       ├── bus.py                   # 异步 EventBus（发布/订阅单例）
│       ├── state.py                 # ReviewStore、PendingReview、状态机
│       ├── actions.py               # 冻结 dataclass 动作类型
│       ├── config.py                # 热更新 TOML 配置
│       ├── client.py                # MCP 测试客户端（SSE）
│       ├── utils.py                 # 控制台、日志、共享状态
│       ├── 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 参数、Agent 注册、规则测试
    ├── test_config.py               # 配置加载、重载、默认值测试
    ├── test_services.py             # MCP、API、通知服务测试
    ├── test_state.py                # ReviewStore、PendingReview、超时测试
    ├── test_tui.py                  # TUI 组件测试
    ├── test_utils.py                # log_box 辅助函数测试
    └── test_e2e.py                  # 端到端：服务器 + MCP 客户端 + REST