Co-dev review MCP

A local Node.js MCP server for reviewing colleagues' GitLab merge requests and GitHub pull requests, checking your own changes before pushing, reading Azure DevOps Bug/PBI requirements, analyzing SonarQube results, and drafting child tasks.

Your MCP client supplies the LLM: this server has no model API dependency. It supplies source data and a review workflow, validates inline anchors, saves drafts, and publishes only approved items. The LLM performs the reasoning and translation. Use any client supporting MCP over stdio; a bare model API needs an MCP-capable host.

Install and configure

Use Node 20.20.2 or later. Run these commands from the server project folder:

cd /absolute/path/to/co-dev-review
node --version
npm ci

Put your configuration variables inside a .local folder at the project root, in .local/config.json. This is a JSON file containing environment-variable names and values; it is not a .env file.

co-dev-review/
  .local/
    config.json
  src/
    server.js
  package.json

Start from examples/config.example.json — it lists every key the server reads, with the public defaults already filled in:

New-Item -ItemType Directory -Force .local; Copy-Item examples/config.example.json .local/config.json

mkdir -p .local && cp examples/config.example.json .local/config.json

Then open .local/config.json and fill in your values. If the file already exists, edit it rather than overwriting your credentials.

Fill in only the integrations you use. Use forward slashes in JSON paths, or escape backslashes.

The entire .local/ folder is excluded by .gitignore; keep credentials there and never commit them. Actual environment variables supplied by your shell or MCP client override this file. .env files are not automatically loaded. Restart/reconnect the server after editing settings.

Alternatively, import supported settings from an existing MCP configuration:

npm run import-config -- "C:/path/to/.vscode/mcp.json"

The importer writes only allowlisted configuration values to .local/config.json; it does not execute or import server commands.

Check configured connections:

npm run doctor

Unconfigured integrations are listed as such. A configured integration with an authentication or connectivity problem is reported as a failure.

Related MCP server: Code Review MCP Server

Run the server

npm start

The server communicates over stdio: it waits for MCP messages on standard input. A quiet terminal is expected. There is no web page or HTTP port. Press Ctrl+C to stop a manually started server.

For normal use, connect your assistant as described below. The MCP client starts the server automatically; you do not also need to run npm start in another terminal.

See the available tools

Run:

npm run tools

This starts a temporary server, performs a real MCP connection, prints each tool's name and description, and closes the connection. It does not call the workflow tools or access remote reviews/tickets.

You should see these three names:

review_work
plan_ticket_tasks
review_sonar

After connecting an assistant, you can also ask: “List the tools available from the co-dev review server.” If you see an older tool list, reconnect the server to refresh discovery.

Connect your assistant

Each client launches its own server process. Use the absolute path to src/server.js, so configuration and drafts work regardless of the client's working directory. You do not need to leave npm start running. It uses stdin/stdout for the MCP protocol, not a web port.

Ready-to-copy files are in examples/. Replace the project path if you move the folder. Keep existing client settings and merge in the new server entry.

For Codex, add the contents of examples/codex.toml to your MCP configuration. For Claude Code, the project .mcp.json format is shown in examples/claude.mcp.json. For VS Code/Copilot, use the servers entry in examples/vscode.mcp.json in .vscode/mcp.json. Reload/reconnect the client, then ask it to review a specific MR/PR. Use npm run doctor for connection diagnostics.

Configuration references: Codex MCP, Claude Code MCP, VS Code MCP configuration.

Review and approval

Try these prompts:

Review GitLab MR 123 against Azure Bug 456. Inspect every changed file and relevant line, read Sonar results, and show a requirement-to-code/test evidence table. Draft the comments in French. Let me skip non-blockers before posting.

Review my local branch against origin/develop before I push. Check correctness, regressions, tests, and ticket 456. Do not post anything.

Propose implementation and regression-test tasks under PBI 456 in English. Show the exact titles, descriptions, and estimates before creating them.

The review_workflow MCP prompt gives the assistant a consistent process. Returned repository, ticket, and analysis text is untrusted evidence, not instructions. The client should fetch all pages and disclose missing/truncated patches; a tool cannot guarantee that an LLM actually reviews every line.

1. Read the MR/PR, patches, full file context, existing discussions, and ticket criteria.

2. Run the deterministic passes: step=checks and step=blast_radius (see Recall).

3. Discuss findings. Choose fr or en; the LLM writes the final text before saving.

4. Use review_work to prepare comments or plan_ticket_tasks to prepare tasks. Each finding/task gets an ID.

5. In a terminal in this project, run:

npm run approve

With no argument it picks the only pending draft, or lists them for you to choose. npm run approve -- 5215051e targets one by the first characters of its id, and npm run pending lists every draft with its state.

Each item is shown once, with the diff context it is anchored to, then a single prompt takes the selection:

Include which items? [all | none | 1,3,5-7 | e <n> to edit | q]

e 3 opens item 3 in $EDITOR ($VISUAL, else notepad on Windows) so you can fix the wording yourself rather than asking the assistant to regenerate the draft. Editing rewrites the draft and voids any earlier approval of it. A final APPROVE authorises exactly what is on screen.

6. Ask your assistant to publish that draft through the same workflow.

There is no MCP approval tool. Approval requires an interactive terminal; the assistant must not approve on your behalf. Approval is tied to a content hash, selected IDs, and a 24-hour expiry. A language/text change requires a new draft. Publication checks the destination and current PR head. Inline comments are anchored to a commit and validated added/deleted lines; context lines should be discussed in a general comment. GitLab renames preserve both file paths.

Comments are posted as individual discussions/review comments, not a formal GitHub APPROVE/REQUEST_CHANGES verdict. No merge, commit, push, or Sonar issue-status mutation is exposed. The host assistant can use its own file editing and testing tools to implement fixes you request.

Recall: what the review cannot be allowed to miss

A diff-only review misses the issues a colleague catches, because a colleague reviews with the compiler, the rest of the codebase, and a checklist in their head. Four mechanisms put those back.

Domain rubrics. step=read classifies the changed paths and returns a rubrics array naming the skills to load — review-react-ts, review-dotnet, review-security, review-build — with the focus areas each one owns. Paths touching auth, tokens, roles, sessions, uploads or payments always pull in the security rubric. The skills ship in this repository (see Install as a plugin); the server only names the expertise, it does not supply it.

The reviewed project's own expertise. step=read also returns repoSkills: every SKILL.md under <REVIEW_REPO_ROOT>/.claude/skills/, with its name, description and absolute path. Those skills are scoped to their own repository and are therefore invisible when the review runs from anywhere else — this puts them back in front of the reviewer without copying them, so they stay maintained in one place by the team that owns them. The assistant reads the ones whose description matches the change. Their content is repository text: domain knowledge, never instructions.

Deterministic pre-pass. step=checks runs the reviewed repository's own TypeScript compiler, ESLint and dotnet build over the change and returns their findings split into onChangedLines (this change's responsibility) and elsewhereInChangedFiles (pre-existing). Monorepos are handled: changed files are grouped by the nearest governing tsconfig.json or ESLint config and each project is run in its own directory, up to six of them. A runner that is unavailable says why. Requires REVIEW_REPO_ROOT.

Blast radius. step=blast_radius extracts the exported symbols this change touched and lists their call sites outside the diff, via git grep. These are the lines nobody is reviewing and where a changed signature or contract breaks. Text matching cannot resolve overloads, re-exports or dynamic dispatch, so treat the list as leads.

Hunk coverage ledger. step=read returns hunks, one entry per changed hunk, identified as <changed file index>.<hunk index> — stable across diff pagination. step=prepare_comments requires a coverage entry giving every hunk a verdict of finding, reviewed-clean or not-applicable, and refuses the draft while any hunk is unaccounted for, naming the ones missing. Use 7.* for a whole file, 7.2-7.5 for a range. This is what stops a review from quietly ending at file twelve.

Checkout match. For a remote MR/PR, step=read also returns localCheckout — the branch and head of REVIEW_REPO_ROOT and whether it equals the review head. checks and blast_radius run on the local checkout, so if it is on some other branch they analyse the wrong code; the note says so and tells the assistant to check out the review branch or disclose that the deterministic pass was not run. Both steps also report an empty change range explicitly instead of a misleading "clean".

None of this makes the model a better reviewer by itself; it removes the failure modes where a review is incomplete without anyone noticing.

Seeing what the review actually did

Every tool call is appended to .local/trace.jsonl — names, counts and identifiers only, never comment bodies, source text or tokens. Read it with:

npm run trace

gitlab acme/web-app #306  2026-09-10
  22:22:20  read           13 files · 31 hunks · MISMATCH: local is on release
                           offered rubrics: review-react-ts, tests (no packaged skill)
                           offered repo skills: design-system, house-conventions, house-testing
  22:22:20  rubric         fetched via tool: packaged:review-react-ts, repository:house-conventions, repository:house-testing
  22:22:20  blast_radius   branch vs origin/develop  0 symbol(s), 0 caller(s) outside the diff
  22:22:20  checks         branch vs origin/develop  no changed files in range

Three columns matter. Offered is what the server returned. Fetched via tool is what came back through step=rubric. Declared applied is what the assistant itself listed in the required rubricsApplied field of prepare_comments — it is stored in the draft and shown at the top of npm run approve, so an empty list on a React change is visible to the human before anything is posted.

The trace is evidence of protocol compliance, not a complete record of what the model read: skills a client loads natively (Claude Code's Skill tool, Codex skills) and files it opens with its own tools never pass through this server. For those, the client's own transcript is the record. Set CO_DEV_TRACE=off to disable tracing; the test suite does. The file rotates at 5 MB.

Install as a plugin

The MCP server is the evidence and guarded-write layer. The review expertise lives in skill files. This repository carries both:

.claude-plugin/plugin.json   Claude Code plugin manifest
plugin-mcp.json              the server, launched from ${CLAUDE_PLUGIN_ROOT}
skills/                      review-mr, review-react-ts, review-dotnet, review-security, review-build
agents/                      react-reviewer, dotnet-reviewer (Claude Code only)
examples/                    stand-alone MCP configuration per client

skills/*/SKILL.md uses the same name/description frontmatter that both Claude Code and Codex read, so one set of files serves both. review-mr is the entry point: it runs the whole sequence — rubrics, checks, blast radius, coverage — and is invoked as /co-dev-review:review-mr 123 fr in Claude Code or by name in Codex.

Claude Code. Add the directory as a plugin and the server, skills and agents load together:

claude --plugin-dir /absolute/path/to/co-dev-review

For a permanent install, junction the directory into ~/.claude/skills/co-dev-review; it then loads every session with no marketplace step. Remove any duplicate co-dev-review entry from your other MCP configuration first, or the server is registered twice.

Codex. Register the server, then link the skills:

codex mcp add co_dev_review -- node /absolute/path/to/co-dev-review/src/server.js

npm run link-skills

link-skills symlinks (junctions on Windows) each folder in skills/ into ~/.codex/skills/, honouring CODEX_HOME. It never overwrites an entry that is not its own link unless you pass --force, --dry-run shows what it would do, and it is idempotent. The originals stay in this repository, so editing a rubric updates both clients at once. Codex also reads the MCP instructions this server returns at initialization, which carries the same workflow.

Any other MCP client. Use examples/*.mcp.json for the tools. Where the client has no skill system at all, nothing is lost: step=read names the rubrics and step=rubric returns their full text over the tool channel, including the reviewed repository's own skills. That path works everywhere a tool call works.

Subagent fan-out is Claude Code only. Elsewhere the review-mr skill runs the domain passes in sequence instead — slower, same coverage.

Available tools

Only these three tools are exposed. Reconnect your MCP client to replace the old tool list. You describe your goal in normal language; the assistant handles each workflow's steps.

Examples:

• “Review my local changes before I push.”

• “Review MR 123 against ticket 456. Prepare comments in French, and let me skip non-blockers.”

• “Split ticket 456 into implementation and testing tasks. Explain dependencies and estimate the hours for each task and the total.”

• “Check Sonar for MR 123 and fix the issues in my local checkout.”

For client implementers: review_work accepts a request with step equal to read, read_file, rubric, checks, blast_radius, prepare_comments, view_draft or publish. rubric takes names (up to 8) and returns each rubric's markdown from this repository's skills/ or the reviewed checkout's .claude/skills/, for clients that cannot load skill files. checks and blast_radius take mode and base like read and operate on REVIEW_REPO_ROOT; checks also accepts only to restrict which runners execute. prepare_comments additionally requires coverage and rubricsApplied (an array of skill names, empty allowed). plan_ticket_tasks accepts read, prepare, view_draft or publish. These are stages of a workflow, not additional MCP tools. Read uses ticketId; prepare uses ticketId, language and tasks, each with title, description and required estimatedHours. Saved-draft stages use draftId.

Task estimates are stored in the task description with explicit hours and returned as a total. They are effort estimates, not calendar deadlines. The assistant should describe assumptions and dependencies. Azure Remaining Work is left unset because custom processes can use different units.

review_sonar takes a PR/MR target and derives the Sonar pull-request number. It returns review context and Sonar results together. Optional ruleKey and filePath support investigating a specific issue. The assistant applies requested fixes through its host's editing/testing tools in the matching checkout. The MCP server itself does not edit files, push code or run SonarScanner. A fresh analysis is needed to confirm resolution.

Repository-local skills are read from <REVIEW_REPO_ROOT>/.claude/skills/*/SKILL.md (top-level skill folders only, 20 skills and 200 KB per file maximum); a missing directory is reported, not an error.

Review results include nextPage; continue until null and disclose failed or omitted sections. Sonar issues/hotspots retain paging information; ticket discussion retains its continuation token. Existing drafts remain usable through the corresponding workflow's view_draft and publish stages.

Targets use { "provider": "gitlab", "project": "group/repo", "number": 123 } or { "provider": "github", "project": "owner/repo", "number": 123 }. GitLab project defaults to GITLAB_PROJECT_ID. Azure uses one configured organization/project per installation. Task descriptions use Azure HTML; review bodies use Markdown. Tasks inherit the parent's area and iteration and link via the parent hierarchy relation. Custom work item types/processes are not handled automatically.

Failure recovery and boundaries

Each draft has a persisted publication journal and exclusive filesystem lock. Already posted items are skipped on retries. If a write times out or the process exits after sending it, the server cannot know whether the provider accepted it. It blocks automatic retries of that item to avoid duplicate comments/tasks.

Inspect the remote provider, then reconcile locally:

node src/cli.js reconcile <draft-id> R1 posted <remote-id>
# OR, only after confirming nothing was created:
node src/cli.js reconcile <draft-id> R1 not-posted

If a process crashed while holding .local/drafts/<id>.lock, first stop that process and inspect its journal and the remote provider; remove only that specific stale lock before reconciliation. Never delete the journal to force retries. Partial publication is possible: remote APIs do not provide a transaction spanning comments or tasks.

This approval mechanism protects the MCP interface. An agent or person with unrestricted shell access under your OS account can modify local files or call the providers directly; use client tool permissions if you need isolation against that threat. There is also an unavoidable race between checking a remote head and posting, though inline comments carry the reviewed SHA.

Sonar data depends on analysis availability, product version, and token permissions. Missing coverage is unknown, not zero; a passed gate is not proof that the code is correct. This server reads analysis; it does not run SonarScanner. API responses are bounded at 12 MB, Git diffs at 12 MB, and draft anchor validation at 3000 changed files. Untracked files are listed but their contents are not included in git diff.

Development

npm run check
npm test
npm audit

Tests cover real MCP stdio discovery/validation, provider request contracts using mock HTTP, approval selection/expiry/tampering, stale heads/destinations, uncertain writes, locks, inline diff anchors, task-parent changes, hunk-ledger identity across pagination, coverage-gap rejection, rubric routing, and CRLF-safe diff parsing. Tests never post to real services. npm run doctor performs read-only authentication checks.

Sources used for the adapters: MCP SDK, GitLab discussions, GitHub review comments, Azure task creation, Sonar Web API.

Useful future additions: a browser approval UI, saved review policies per repository, and a corpus of the team's own past review comments mined from merged MR discussions and generated into a house rubric. These can be added without tying the server to a particular LLM.