codex-review-mcp 1.0.0

package/bin/codex-review-mcp

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import '../dist/mcp-server.js';
+
+

package/dist/mcp-server.js

@@ -0,0 +1,43 @@
+import 'dotenv/config';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+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.',
+    inputSchema: {
+        target: z.enum(['staged', 'head', 'range']).default('head'),
+        baseRef: z.string().optional(),
+        headRef: z.string().optional(),
+        focus: z.string().optional(),
+        paths: z.array(z.string()).optional(),
+        maxTokens: z.number().optional(),
+    },
+}, async (input, extra) => {
+    const reviewInput = {
+        target: input.target,
+        baseRef: input.baseRef,
+        headRef: input.headRef,
+        focus: input.focus,
+        paths: input.paths,
+        maxTokens: input.maxTokens,
+    };
+    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,
+                progress,
+                total,
+                message,
+            },
+        }, { relatedRequestId: extra.requestId });
+    };
+    const markdown = await performCodeReview(reviewInput, onProgress);
+    return { content: [{ type: 'text', text: markdown, mimeType: 'text/markdown' }] };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/review/buildPrompt.js

@@ -0,0 +1,13 @@
+export function buildPrompt({ diffText, context, focus }) {
+    const focusLine = focus ? `Focus areas: ${focus}.` : '';
+    return [
+        'You are an expert AI code reviewer. Be concise, specific, and actionable.',
+        'Prefer minimal diffs and direct fixes. Respect project guidelines when provided.',
+        focusLine,
+        '\n---\nScope and Diff (unified=0):\n',
+        diffText,
+        context ? '\n---\nProject context and guidelines:\n' + context : '',
+        '\n---\nOutput strictly as Markdown with the following sections:\n',
+        '1) Title + scope summary\n2) Quick Summary (3–6 bullets)\n3) Issues table: severity | file:lines | category | explanation | suggested fix\n4) Inline suggested edits for top issues\n5) Positive notes\n6) Next steps',
+    ].join('\n');
+}

package/dist/review/collectDiff.js

@@ -0,0 +1,75 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { minimatch } from 'minimatch';
+const exec = promisify(execFile);
+const DEFAULT_IGNORES = [
+    '**/dist/**',
+    '**/build/**',
+    '**/*.lock',
+];
+function filterPaths(paths) {
+    if (!paths || paths.length === 0)
+        return undefined;
+    return paths.filter((p) => !DEFAULT_IGNORES.some((g) => minimatch(p, g)));
+}
+export async function collectDiff(input) {
+    async function findRepoRoot(startDir) {
+        let dir = startDir;
+        // Walk up to filesystem root (max ~25 hops as a safety guard)
+        for (let i = 0; i < 25; i++) {
+            try {
+                // Accept both .git directory and file (worktree) as signal of repo root
+                await fs.stat(join(dir, '.git'));
+                return dir;
+            }
+            catch {
+                const parent = dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+        return null;
+    }
+    const args = ['diff', '--unified=0'];
+    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,
+            cwd: repoRoot,
+        });
+        // Drop obvious binary diffs
+        const text = stdout
+            .split('\n')
+            .filter((line) => !line.startsWith('Binary files '))
+            .join('\n');
+        // Enforce size cap ~300k chars
+        const cap = 300_000;
+        return text.length > cap ? text.slice(0, cap) + '\n<!-- diff truncated -->\n' : text;
+    }
+    catch (err) {
+        const msg = err?.stderr || err?.message || String(err);
+        throw new Error(`Failed to collect git diff: ${msg}`);
+    }
+}

package/dist/review/formatOutput.js

@@ -0,0 +1,10 @@
+export function formatOutput(agentMarkdown) {
+    // For MVP, trust agent output if non-empty; otherwise return a minimal stub.
+    if (agentMarkdown && agentMarkdown.trim().length > 0)
+        return agentMarkdown;
+    return [
+        '# Code Review',
+        '',
+        'No issues detected or empty output from agent.',
+    ].join('\n');
+}

package/dist/review/gatherContext.js

@@ -0,0 +1,42 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+const CANDIDATE_FILES = [
+    '.cursor/rules/project.mdc',
+    '.cursor/rules/**/*.md',
+    'CODE_REVIEW.md',
+    'CONTRIBUTING.md',
+    'SECURITY.md',
+    '.eslintrc',
+    '.eslintrc.cjs',
+    '.eslintrc.js',
+    '.eslintrc.json',
+    'package.json',
+    'tsconfig.json',
+];
+async function readIfExists(path) {
+    try {
+        const data = await fs.readFile(path, 'utf8');
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+export async function gatherContext() {
+    const chunks = [];
+    for (const rel of CANDIDATE_FILES) {
+        // naive glob: only handle literal paths here to keep MVP simple
+        if (rel.includes('*'))
+            continue;
+        const data = await readIfExists(join(process.cwd(), rel));
+        if (!data)
+            continue;
+        // bound each file contribution to ~8k chars
+        const capped = data.slice(0, 8000);
+        chunks.push(`\n<!-- ${rel} -->\n${capped}`);
+        // global size guard ~50k chars
+        if (chunks.join('').length > 50_000)
+            break;
+    }
+    return chunks.join('\n');
+}

package/dist/review/invokeAgent.js

@@ -0,0 +1,14 @@
+import { Agent, run } from '@openai/agents';
+import { debugLog } from '../util/debug.js';
+export async function invokeAgent({ prompt, maxTokens }) {
+    const model = process.env.CODEX_MODEL || 'gpt-5-codex';
+    const agent = new Agent({
+        name: 'Code Reviewer',
+        instructions: 'You are a precise code-review agent. Follow the output contract exactly. Use minimal verbosity.',
+        model,
+    });
+    const result = await run(agent, prompt);
+    const out = result.finalOutput ?? '';
+    await debugLog(`Agent model=${model} outputLen=${out.length}`);
+    return out;
+}

package/dist/tools/performCodeReview.js

@@ -0,0 +1,24 @@
+import { collectDiff } from '../review/collectDiff.js';
+import { gatherContext } from '../review/gatherContext.js';
+import { buildPrompt } from '../review/buildPrompt.js';
+import { invokeAgent } from '../review/invokeAgent.js';
+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);
+    if (!diffText.trim()) {
+        throw new Error('No diff found. Ensure you have changes or a valid git range.');
+    }
+    await onProgress?.('Gathering context…', 30, 100);
+    const context = await gatherContext();
+    await onProgress?.('Building prompt…', 45, 100);
+    const prompt = buildPrompt({ diffText, context, focus: input.focus });
+    await onProgress?.('Calling GPT-5 Codex…', 65, 100);
+    const agentMd = await invokeAgent({ prompt, maxTokens: input.maxTokens });
+    await debugLog(`Review produced ${agentMd.length} chars`);
+    await onProgress?.('Formatting output…', 90, 100);
+    const out = formatOutput(agentMd);
+    await onProgress?.('Done', 100, 100);
+    return out;
+}

package/dist/util/debug.js

@@ -0,0 +1,15 @@
+import { appendFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const LOG_PATH = join(homedir(), '.codex-review-mcp-debug.log');
+export async function debugLog(message) {
+    if (process.env.CODEX_REVIEW_MCP_DEBUG !== '1')
+        return;
+    const line = `[${new Date().toISOString()}] ${message}\n`;
+    try {
+        await appendFile(LOG_PATH, line, 'utf8');
+    }
+    catch {
+        // ignore logging failures in MVP
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "codex-review-mcp",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "prepare": "npm run build",
+    "mcp": "node dist/mcp-server.js",
+    "agents:sample": "node agents-sample.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pmerwin/codex-review-mcp.git"
+  },
+  "homepage": "https://github.com/pmerwin/codex-review-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/pmerwin/codex-review-mcp/issues"
+  },
+  "files": [
+    "dist/**",
+    "bin/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18",
+    "npm": ">=9"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "type": "module",
+  "bin": {
+    "codex-review-mcp": "./bin/codex-review-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.1",
+    "@openai/agents": "^0.1.9",
+    "dotenv": "^17.2.3",
+    "minimatch": "^10.0.3",
+    "openai": "^6.2.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.0",
+    "typescript": "^5.9.3"
+  }
+}