Code Review MCP Server

A Gemini-CLI (for now), powered code review assistant that runs as a Model Context Protocol (MCP) server.

Why this project exists

Manual code reviews are time-consuming and often miss the opportunity to combine static analysis with contextual, human-friendly feedback. This project was created to experiment with MCP tooling that gives AI assistants access to a purpose-built reviewer:

• Automates the busywork of gathering diffs and lint results from local, uncommitted changes.
• Streams that context into the Gemini CLI so the model can focus on actionable insights.
• Returns a structured JSON review that fits naturally into MCP-compatible clients.

What it does

• Connects to MCP clients over stdio using the official @modelcontextprotocol/sdk.
• Runs a "hybrid" review workflow that gathers git diff output and linter findings.
• Falls back between ESLint, JSHint, and TypeScript to maximise coverage across projects.
• Safely invokes the Gemini CLI, handling long prompts and timeouts.
• Ships as TypeScript with Zod-backed types for predictable MCP responses.

Requirements

• Node.js 18 or later (ES modules and AbortSignals are used throughout).
• npm (installed with Node.js).
• Git (used to collect local diffs).
• Google Gemini CLI (gemini) installed and authenticated. See the Gemini quickstart for setup instructions.

Installation

git clone https://github.com/<your-org>/ndlovu-code-reviewer.git
cd ndlovu-code-reviewer
npm install
npm run build

If you plan to iterate on the TypeScript source, you can skip npm run build and rely on the dev script described below.

Usage

Start the MCP server

npm start

The server communicates over stdio, so it is ready to be registered with any MCP-compatible client (e.g. IDE integrations or assistant sandboxes). Once connected, call the review-local-changes tool to trigger the hybrid analysis and receive the JSON review.

How to call the MCP tool

The server exposes a single tool called review-local-changes that performs comprehensive analysis of your local, uncommitted code changes.

Prerequisites:

• You must have uncommitted changes in your git repository
• Changed files should be JavaScript, TypeScript, or Vue files (.js, .ts, .tsx, .vue)
• The Gemini CLI must be installed and authenticated

Using the tool:

Once your MCP client is connected to the server, you can call the review-local-changes tool. The tool:

1. Automatically detects changes - Finds all modified/added JS/TS/Vue files using git diff
2. Runs static analysis - Executes the best available linter (ESLint, JSHint, or TypeScript compiler)
3. Performs AI review - Sends the combined context to Gemini CLI for intelligent analysis
4. Returns structured results - Provides a JSON response with findings and recommendations

How to use it with Claude Code:

For best results, be explicit about using the code review functionality. While natural language requests sometimes work, the most reliable approach is to use specific keywords:

Most reliable requests (recommended):

• "Use the code review tool to analyze my changes"
• "Run code review on my local changes"
• "Perform a comprehensive code review of my uncommitted changes"
• "Analyze my code changes with static analysis"

Natural language requests (may work but less reliable):

• "Please review my local changes"
• "Can you analyze the code changes I've made?"

Explicit tool invocation (most reliable):

• "Use the review-local-changes tool"
• "Call the review-local-changes tool to check my modifications"

The tool has been enhanced with better descriptions to help Claude recognize when to use it, but being specific about "code review," "analyze changes," or mentioning the tool name directly will give you the most consistent results.

Example output format:

{
  "summary": "Overview of changes made",
  "assessment": "Overall code quality evaluation",
  "findings": [
    {
      "filePath": "src/example.js",
      "lineNumber": 42,
      "severity": "warning",
      "category": "style",
      "comment": "Detailed explanation of the issue",
      "suggestion": "Specific recommendation for improvement"
    }
  ]
}

Note: If no relevant files have been changed, the tool will return a "No relevant files changed" message, which is normal behavior.

Local development

• npm run dev – Launches the server with ts-node for rapid iteration.
• npm run build – Produces the compiled JavaScript output in dist/.

The project structure is intentionally small:

• src/ – TypeScript source for the MCP server.
• dist/ – Compiled JavaScript created by npm run build.
• assets/ – Static assets, including the logo used above.

Connect from MCP clients

Before wiring the server into any client, make sure you have run npm run build so dist/index.js exists. The commands below assume you execute the client from the repository root so the server can read your git workspace.

Claude Code (VS Code extension)

1. In VS Code, open the command palette (Cmd/Ctrl+Shift+P) and run Claude: Edit Config File.

2. Locate the mcpServers section (create it if needed) and add an entry similar to:

   {
     "mcpServers": {
       "ndlovu-code-reviewer": {
         "command": "node",
         "args": ["/absolute/path/to/ndlovu-code-reviewer/dist/index.js"],
         "cwd": "/absolute/path/to/ndlovu-code-reviewer"
       }
     }
   }
   

3. Save the file and run Claude: Restart Claude Code (or reload VS Code) so the server appears under Tools.

4. Enable the tool for a conversation; Claude Code will stream review-local-changes results directly in the sidebar.

Gemini CLI

1. From the project root run:

   gemini mcp add ndlovu-code-reviewer node $(pwd)/dist/index.js
   

2. Verify the registration with gemini mcp list.

3. Launch gemini from the same repository directory and use the review-local-changes tool (e.g., run :tools in the CLI and select it). The CLI spawns the server and forwards stdout back as the review JSON.

Roo Code

1. Open Roo Code and click the server icon in the top of the Roo panel.

2. Choose Add MCP Server → STDIO and fill in:

   • Name: ndlovu-code-reviewer
   • Command: node
   • Arguments: /absolute/path/to/ndlovu-code-reviewer/dist/index.js
   • Working Directory: /absolute/path/to/ndlovu-code-reviewer

3. Save the configuration and enable the server for your workspace. Roo stores it in either the global mcp_settings.json or the project .roo/mcp.json file.

4. To share with teammates, commit a .roo/mcp.json that contains your preferred launch command, for example:

   {
     "mcpServers": {
       "ndlovu-code-reviewer": {
         "command": "npm",
         "args": ["run", "start"],
         "cwd": "."
       }
     }
   }
   

   Roo resolves the working directory relative to the project root, so the npm run start script builds on the repository’s own package scripts.

Codex CLI

1. Register the server once:

   codex mcp add ndlovu-code-reviewer node $(pwd)/dist/index.js
   

2. Use codex mcp list to confirm the entry, then start Codex from the repository root. The CLI exposes review-local-changes as a tool you can call inside interactive runs.

Contributing

Contributions are very welcome. If you have ideas for new tools, better linters, or improved prompts:

1. Open an issue or discussion so we can align on scope.
2. Fork the repository and create a feature branch.
3. Add or update documentation/tests where it helps future contributors.
4. Submit a pull request describing the change and how you validated it.

If you're unsure where to start, feel free to reach out—there is plenty of room to expand the reviewer’s capabilities, add client examples, and tighten the prompts.

License

This project is licensed under the ISC License. See LICENSE (if present) for details.