codex-review-mcp 1.0.0 → 1.1.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 codex-review-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,156 @@
+# Codex Review MCP Server
+
+Get AI-powered code reviews without leaving your conversation. Keep coding with your AI assistant, and when you need a second opinion, just ask for a review - all in the same context window.
+
+## Why This Exists
+
+You're coding with an AI assistant. It makes changes. You want a quick review. Normally you'd copy/paste code into another chat, wait, copy feedback back. **That breaks your flow.**
+
+With this MCP server, your AI assistant can call out for a code review **right in the middle of your conversation**. No context switching. No copy/paste. The review comes back in the same chat.
+
+## Features
+
+- 🎯 **Zero Configuration** - Just add your OpenAI API key
+- 🔍 Automatically reviews your uncommitted changes
+- 🤖 Powered by GPT-5 Codex for intelligent code analysis
+- 📊 Returns actionable feedback in Markdown format
+- ⚡ Works with any git repository
+- 🔄 Stays in your conversation context
+
+## Installation
+
+### For Cursor Users
+
+Add the following configuration to your Cursor MCP settings (`~/.cursor/mcp.json` or `%USERPROFILE%\.cursor\mcp.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "codex-reviewer": {
+      "command": "npx",
+      "args": ["-y", "codex-review-mcp@latest"],
+      "env": {
+        "OPENAI_API_KEY": "your-openai-api-key-here",
+        "CODEX_MODEL": "gpt-5-codex",
+        "WORKSPACE_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+**Important**: Replace `your-openai-api-key-here` with your actual OpenAI API key.
+
+### For Claude Desktop Users
+
+Add to your Claude Desktop MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "codex-reviewer": {
+      "command": "npx",
+      "args": ["-y", "codex-review-mcp@latest"],
+      "env": {
+        "OPENAI_API_KEY": "your-openai-api-key-here",
+        "CODEX_MODEL": "gpt-5-codex"
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+Once configured, just ask your AI assistant:
+
+> "Do a code review with codex-reviewer"
+
+That's it! The MCP server automatically figures out what to review:
+- **If you have uncommitted changes**: Reviews your working tree vs HEAD (what you just coded)
+- **If your working tree is clean**: Reviews your current branch vs the default branch (main/master)
+- **If you're on the default branch with no changes**: Reports "No changes to review"
+
+**Example conversation:**
+```
+You: "Add a login form with email validation"
+AI: [makes changes]
+AI: "Let me get a code review on this..."
+AI: [calls codex-reviewer MCP - automatically reviews uncommitted changes]
+AI: "The review found a potential issue with the email regex..."
+```
+
+No need to specify what to review - it just works!
+
+### Advanced Options (Optional)
+
+Most users won't need these, but they're available if you want more control:
+
+- `target` (default: `"head"`): What to review
+  - `"head"`: All uncommitted changes (default - what you just coded)
+  - `"staged"`: Only staged changes (`git add`ed files)
+  - `"range"`: Specific commit range (requires baseRef and headRef)
+- `focus`: Ask the reviewer to focus on something specific (e.g., "security issues")
+- `paths`: Review only specific files
+- `baseRef` / `headRef`: For reviewing commit ranges
+- `maxTokens`: Limit the length of the review
+- `workspaceDir`: Override auto-detection of repository location
+
+## How It Works
+
+1. **Detects Repository**: Automatically finds your git repository root
+2. **Collects Diff**: Runs git diff to get the changes
+3. **Gathers Context**: Collects relevant context about your codebase
+4. **AI Review**: Sends to GPT-5 Codex for intelligent analysis
+5. **Returns Feedback**: Provides actionable Markdown feedback
+
+## Requirements
+
+- Node.js 18+ (for running the MCP server)
+- Git repository
+- OpenAI API key with access to GPT-5 Codex
+- Cursor or Claude Desktop (or any MCP-compatible client)
+
+## Environment Variables
+
+- `OPENAI_API_KEY` (required): Your OpenAI API key
+- `CODEX_MODEL` (optional, default: "gpt-5-codex"): The model to use for reviews
+- `WORKSPACE_ROOT` (optional): Path to your workspace (auto-detected in most cases)
+
+## Development
+
+### Local Development Setup
+
+```bash
+# Clone the repository
+git clone <your-repo-url>
+cd codex-review-mcp
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# For local testing, update your MCP config to point to the local build:
+{
+  "codex-reviewer": {
+    "command": "node",
+    "args": ["/absolute/path/to/codex-review-mcp/dist/mcp-server.js"],
+    "env": {
+      "OPENAI_API_KEY": "your-key",
+      "CODEX_MODEL": "gpt-5-codex",
+      "WORKSPACE_ROOT": "${workspaceFolder}"
+    }
+  }
+}
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or PR.
+

package/dist/mcp-server.js

@@ -6,14 +6,15 @@ import { performCodeReview } from './tools/performCodeReview.js';
 const server = new McpServer({ name: 'codex-review-mcp', version: '0.1.0' });
 server.registerTool('perform_code_review', {
     title: 'Perform Code Review',
-    description: 'Review git diffs in the current repo and return actionable Markdown feedback.',
+    description: 'Review git diffs in the current repo and return actionable Markdown feedback. In auto mode (default), reviews uncommitted changes if present, otherwise reviews current branch vs default branch. No need to commit changes first - the tool reviews your working tree.',
     inputSchema: {
-        target: z.enum(['staged', 'head', 'range']).default('head'),
+        target: z.enum(['auto', 'staged', 'head', 'range']).default('auto'),
         baseRef: z.string().optional(),
         headRef: z.string().optional(),
         focus: z.string().optional(),
         paths: z.array(z.string()).optional(),
         maxTokens: z.number().optional(),
+        workspaceDir: z.string().optional().describe('Absolute path to the workspace/repository directory. If not provided, attempts to detect from environment or current working directory.'),
     },
 }, async (input, extra) => {
     const reviewInput = {
@@ -23,18 +24,19 @@ server.registerTool('perform_code_review', {
         focus: input.focus,
         paths: input.paths,
         maxTokens: input.maxTokens,
+        workspaceDir: input.workspaceDir,
     };
     const onProgress = async (message, progress, total) => {
         // Attach to tool-call request via related request ID so clients can map progress
         await server.server.notification({
             method: 'notifications/progress',
             params: {
-                progressToken: extra?._meta?.progressToken ?? extra.requestId,
+                progressToken: extra?._meta?.progressToken ?? extra?.requestId,
                 progress,
                 total,
                 message,
             },
-        }, { relatedRequestId: extra.requestId });
+        }, extra?.requestId ? { relatedRequestId: extra.requestId } : undefined);
     };
     const markdown = await performCodeReview(reviewInput, onProgress);
     return { content: [{ type: 'text', text: markdown, mimeType: 'text/markdown' }] };

package/dist/review/collectDiff.js

@@ -14,7 +14,7 @@ function filterPaths(paths) {
         return undefined;
     return paths.filter((p) => !DEFAULT_IGNORES.some((g) => minimatch(p, g)));
 }
-export async function collectDiff(input) {
+export async function collectDiff(input, workspaceDir) {
     async function findRepoRoot(startDir) {
         let dir = startDir;
         // Walk up to filesystem root (max ~25 hops as a safety guard)
@@ -33,27 +33,97 @@ export async function collectDiff(input) {
         }
         return null;
     }
+    async function detectDefaultBranch(repoRoot) {
+        // Try to get default branch from remote
+        try {
+            const { stdout } = await exec('git', ['remote', 'show', 'origin'], { cwd: repoRoot, encoding: 'utf8' });
+            const match = stdout.match(/HEAD branch:\s*(\S+)/);
+            if (match?.[1])
+                return match[1];
+        }
+        catch {
+            // Remote not available or other error, continue to fallback
+        }
+        // Fallback: check if main or master exists locally
+        for (const branch of ['main', 'master']) {
+            try {
+                await exec('git', ['rev-parse', '--verify', branch], { cwd: repoRoot });
+                return branch;
+            }
+            catch {
+                // Branch doesn't exist, try next
+            }
+        }
+        // Last resort: use HEAD~1 as baseline
+        return 'HEAD~1';
+    }
+    async function hasUncommittedChanges(repoRoot) {
+        try {
+            const { stdout } = await exec('git', ['status', '--porcelain'], { cwd: repoRoot, encoding: 'utf8' });
+            return stdout.trim().length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    async function getCurrentBranch(repoRoot) {
+        try {
+            const { stdout } = await exec('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repoRoot, encoding: 'utf8' });
+            return stdout.trim();
+        }
+        catch {
+            return null;
+        }
+    }
+    // Priority order: explicit workspaceDir param > env vars > process.cwd()
+    const preferredStart = workspaceDir || process.env.CODEX_REPO_ROOT || process.env.WORKSPACE_ROOT || process.env.INIT_CWD || process.cwd();
+    const preferredRoot = await findRepoRoot(preferredStart);
+    // If workspaceDir was explicitly provided but no repo found, fail immediately
+    if (workspaceDir && !preferredRoot) {
+        throw new Error(`Could not locate a Git repository starting from workspaceDir "${workspaceDir}".`);
+    }
+    const repoRoot = preferredRoot || (await findRepoRoot(process.cwd())) || process.cwd();
     const args = ['diff', '--unified=0'];
-    switch (input.target) {
-        case 'staged':
-            args.splice(1, 0, '--staged');
-            break;
-        case 'head':
+    if (input.target === 'auto') {
+        // Auto mode: detect what to review
+        const hasChanges = await hasUncommittedChanges(repoRoot);
+        if (hasChanges) {
+            // Review uncommitted changes vs HEAD
             args.push('HEAD');
-            break;
-        case 'range':
-            if (!input.baseRef || !input.headRef) {
-                throw new Error('range target requires baseRef and headRef');
+        }
+        else {
+            // No uncommitted changes, review branch vs default
+            const currentBranch = await getCurrentBranch(repoRoot);
+            const defaultBranch = await detectDefaultBranch(repoRoot);
+            if (currentBranch === defaultBranch) {
+                // On default branch with no changes - nothing to review
+                return '';
             }
-            args.push(`${input.baseRef}...${input.headRef}`);
-            break;
+            // Review current branch vs default branch
+            args.push(`${defaultBranch}...HEAD`);
+        }
+    }
+    else {
+        // Explicit target modes
+        switch (input.target) {
+            case 'staged':
+                args.splice(1, 0, '--staged');
+                break;
+            case 'head':
+                args.push('HEAD');
+                break;
+            case 'range':
+                if (!input.baseRef || !input.headRef) {
+                    throw new Error('range target requires baseRef and headRef');
+                }
+                args.push(`${input.baseRef}...${input.headRef}`);
+                break;
+        }
     }
     const filtered = filterPaths(input.paths);
     if (filtered && filtered.length)
         args.push(...filtered);
     try {
-        const preferredStart = process.env.CODEX_REPO_ROOT || process.env.WORKSPACE_ROOT || process.env.INIT_CWD || process.cwd();
-        const repoRoot = (await findRepoRoot(preferredStart)) || (await findRepoRoot(process.cwd())) || process.cwd();
         const { stdout } = await exec('git', args, {
             encoding: 'utf8',
             maxBuffer: 10 * 1024 * 1024,

package/dist/tools/performCodeReview.js

@@ -6,9 +6,9 @@ import { formatOutput } from '../review/formatOutput.js';
 import { debugLog } from '../util/debug.js';
 export async function performCodeReview(input, onProgress) {
     await onProgress?.('Collecting diff…', 10, 100);
-    const diffText = await collectDiff(input);
+    const diffText = await collectDiff(input, input.workspaceDir);
     if (!diffText.trim()) {
-        throw new Error('No diff found. Ensure you have changes or a valid git range.');
+        throw new Error('No changes to review. You are on the default branch with a clean working tree.');
     }
     await onProgress?.('Gathering context…', 30, 100);
     const context = await gatherContext();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-review-mcp",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "main": "index.js",
   "scripts": {
     "build": "tsc",
@@ -27,10 +27,19 @@
     "node": ">=18",
     "npm": ">=9"
   },
-  "keywords": [],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "code-review",
+    "ai",
+    "gpt",
+    "codex",
+    "cursor",
+    "claude"
+  ],
   "author": "",
-  "license": "ISC",
-  "description": "",
+  "license": "MIT",
+  "description": "MCP server for AI-powered code reviews using GPT-5 Codex",
   "type": "module",
   "bin": {
     "codex-review-mcp": "./bin/codex-review-mcp"