# Agent Review MCP

Two local MCP servers for independent code review and multi-round discussions: ask Claude from Codex, or ask Codex from Claude Code. Both can inspect project files. No repository changes are required for a discussion.

## Install

macOS/Linux, Node.js 20.11+, npm and Git are required. Windows is not yet supported. Authenticate the provider you plan to use first: Claude Code for Claude, Codex CLI for Codex. Calls consume your provider usage/credits; this project does not include model access.

```sh
git clone https://github.com/youngpirate32/agent-review-mcp.git
cd agent-review-mcp
node install.mjs
```

The installer installs both commands globally with npm. For one provider use `node install.mjs claude` or `node install.mjs codex`. It does not change MCP client configuration or authentication. You can also run a server directly after `npm ci` inside its package.

Connect Codex as a reviewer/discussion partner in Claude Code:

```sh
claude mcp add --scope user codex-review -- codex-review-mcp
```

Connect Claude in Codex:

```sh
codex mcp add claude-review -- claude-review-mcp
```

For any stdio MCP client, set `command` to `claude-review-mcp` or `codex-review-mcp` and `args` to `[]`. Restart/reconnect the client after installation or upgrades. If your desktop client cannot find commands, use their absolute paths. Codex CLI must support `--ignore-user-config`, `--ignore-rules`, `--ephemeral` (tested with 0.153.4); set `CODEX_REVIEW_BIN` to its executable when it is outside PATH.

## Tools

Replace `PROVIDER` with `claude` or `codex`:

- `PROVIDER_review`: review staged, unstaged and untracked changes against HEAD, or against `base` (a Git commit/ref). Requires the absolute Git repository root in `project` and acceptance criteria in `task`.
- `PROVIDER_review_status` / `PROVIDER_review_cancel`: inspect/cancel using the returned run `id`.
- `PROVIDER_discuss`: first call takes an absolute project directory and `message`; subsequent calls take `sessionId` and `message`. A Git repository is not required.
- `PROVIDER_discuss_status` / `PROVIDER_discuss_cancel`: inspect/cancel using `sessionId`.

Review example:

```json
{"project":"/path/to/project","task":"Check permissions and regressions","depth":"deep","language":"en","effort":"high","timeoutSeconds":900}
```

Discussion example:

```json
{"project":"/path/to/project","message":"Compare stable IDs and slugs for URLs","depth":"deep","language":"en","maxRounds":6}
```

Continue with `{"sessionId":"returned-uuid","message":"What happens after a rename?","depth":"brief"}`.

## Parameters

| Parameter | Default | Meaning |
| --- | --- | --- |
| `model` | Claude: `claude-opus-5`; Codex: `gpt-6-astra` | Explicit model ID. Your account must have access. |
| `effort` | `high` | Provider reasoning effort. Claude: low, medium, high, xhigh, max. Codex: low, medium, high, xhigh, max, ultra. Actual support depends on the selected model. |
| `depth` | `standard` | `brief`, `standard`, `deep`: prompt guidance for scope and detail, not a hard token budget. |
| `language` | `ru` | `ru` or `en`. |
| `timeoutSeconds` | 1800 | 30–1800 per call. |
| `wait` | true | Wait for the result with progress notifications; false returns immediately. |
| `maxRounds` | 6 | Discussion only, 1–20; fixed when creating a session. |

Model, effort, depth, language and timeout selections persist across discussion rounds. Reviews use defaults independently. Unsupported provider combinations return a failure; there is no automatic model substitution. Returned `model` is requested, not proof of provider routing; Claude also records `actualModel` when available.

Do not poll while a waiting call is pending. For background calls use status with `waitSeconds:20`. Inspect `status` and `error`/`result`; a provider failure can be returned in a normal MCP response. A round limit or 160 KB conversation limit requires a summary for the user, not an automatic new discussion. Each message is limited to 20,000 characters. Failed/cancelled rounds count against the limit and are excluded from successful conversation history.

## Permissions and data

Claude gets Read/Grep/Glob only, no shell or MCP delegation. Codex runs shell commands under a read-only sandbox, without user config/rules or web search. Instructions prohibit tests, scripts, edits, external contact and recursive delegation. Read-only access is not confidentiality isolation: project files may be sent to your chosen provider. Use trusted local repositories; project-level Codex configuration may affect its runtime. This server has no network listener or user authentication and is intended for a local stdio client, not exposure as a shared service.

State is stored outside the installation at `~/.local/share/agent-review-mcp/{claude,codex}` (directories 0700, files 0600). Override with `REVIEW_MCP_DATA_DIR`, using separate paths per provider. Full prompts/reports/transcripts are retained until you remove the state directory. Never include secrets in prompts or changes. No credentials, sample user sessions or project content are shipped.

Discussion context is replayed as text into a fresh model call; hidden reasoning/tool transcripts are not persisted. Files are read from the live project. Review diff is captured initially; `worktreeChanged` flags changes during review. A single discussion must be owned by one MCP server process; cross-process concurrent continuation is unsupported. Restarted in-flight sessions are reported as interrupted.

## Development

```sh
npm ci --prefix packages/claude-review-mcp
npm ci --prefix packages/codex-review-mcp
npm test
```

Tests use fake providers and do not consume model access. `npm run test:discussion:live` or `npm run test:live` within a provider package makes real model calls. Packaging uses an explicit file allowlist. GitHub CI tests both packages on Linux/macOS and Node 20/22. Packages are installed from source; no npm registry publication is claimed.

MIT licensed. Contributions welcome; describe the scenario and add meaningful regression tests. Do not include credentials or real discussion/review state in issues or PRs.