codex-review-mcp 1.0.0 → 1.1.0

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

@@ -8,12 +8,13 @@ server.registerTool('perform_code_review', {
     title: 'Perform Code Review',
     description: 'Review git diffs in the current repo and return actionable Markdown feedback.',
     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,7 +6,7 @@ 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.');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-review-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "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"