codex-review-mcp 1.3.1 → 2.0.0

package/README.md

@@ -11,6 +11,7 @@ With this MCP server, your AI assistant can call out for a code review **right i
 ## Features
 
 - 🎯 **Zero Configuration** - Just add your OpenAI API key
+- 📋 **Respects Your Cursor Rules** - Automatically reads `.cursor/rules/` and enforces YOUR coding standards
 - 🔍 Automatically reviews your uncommitted changes
 - 🤖 Powered by GPT-5 Codex for intelligent code analysis
 - 📊 Returns actionable feedback in Markdown format
@@ -100,9 +101,9 @@ Most users won't need these, but they're available if you want more control:
 
 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
+3. **Gathers Context**: Reads your `.cursor/rules/`, `CODE_REVIEW.md`, `.eslintrc`, and other project files
+4. **AI Review**: Sends to GPT-5 Codex with YOUR project's coding standards
+5. **Returns Feedback**: Provides actionable Markdown feedback that respects YOUR rules
 
 ## Requirements
 

package/dist/mcp-server.js

@@ -2,33 +2,86 @@ import 'dotenv/config';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import { performCodeReview } from './tools/performCodeReview.js';
-const server = new McpServer({ name: 'codex-review-mcp', version: '0.1.0' });
+// Read version from package.json
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+const VERSION = packageJson.version;
+const server = new McpServer({ name: 'codex-review-mcp', version: VERSION });
+server.registerTool('get_version', {
+    title: 'Get Version',
+    description: 'Get the version of the codex-review-mcp server.',
+    inputSchema: {}, // Empty schema - no parameters required
+}, async () => {
+    return {
+        content: [{
+                type: 'text',
+                text: `codex-review-mcp version ${VERSION}`,
+                mimeType: 'text/plain'
+            }]
+    };
+});
 server.registerTool('perform_code_review', {
     title: 'Perform Code Review',
-    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.',
+    description: `Review code/diffs using GPT-5 Codex with expert prompts and project-specific context.
+
+🎯 USAGE:
+
+  1. Get the code/diff to review:
+     const diff = await runCommand("git diff");
+     
+  2. Optionally gather project context:
+     const rules = await readFile(".cursor/rules/project.mdc");
+     
+  3. Call with content:
+     await perform_code_review({
+       content: diff,                    // REQUIRED
+       contentType: "diff",              // "diff" or "code"
+       customContext: rules,             // Optional: saves tokens!
+       focus: "security and performance" // Optional: specific focus
+     });
+
+💡 KEY BENEFITS:
+  - Expert Reviews: GPT-5 Codex with project-specific context
+  - Codebase-Aware: Checks YOUR patterns, enforces YOUR rules
+  - Efficient: Provide customContext to skip auto-gathering
+
+📋 PARAMETERS:
+  - content: Code or diff to review (REQUIRED)
+  - contentType: "diff" | "code"
+  - customContext: Project rules/guidelines (saves tokens if provided)
+  - skipContextGathering: Skip auto-gathering if you don't need context
+  - focus: Specific areas to review (e.g., "security", "performance")
+  - workspaceDir: Base directory for context gathering (defaults to cwd)`,
     inputSchema: {
-        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.'),
+        // REQUIRED
+        content: z.string().describe('Code or diff content to review (REQUIRED). Agent should run git commands or read files to get this.'),
+        // CONTENT TYPE
+        contentType: z.enum(['diff', 'code']).optional().describe('Type of content: "diff" for git diffs, "code" for static code review'),
+        // CONTEXT OPTIONS
+        customContext: z.string().optional().describe('⭐ RECOMMENDED: Project context (.cursor/rules, CODE_REVIEW.md, etc). Saves tokens and time!'),
+        skipContextGathering: z.boolean().optional().describe('Set to true to skip automatic context gathering (useful if no context needed)'),
+        workspaceDir: z.string().optional().describe('Base directory for context gathering (defaults to current directory)'),
+        // REVIEW OPTIONS
+        focus: z.string().optional().describe('Specific areas to focus on (e.g., "security and performance")'),
+        maxTokens: z.number().optional().describe('Maximum tokens for review response'),
     },
 }, async (input, extra) => {
     try {
         const reviewInput = {
-            target: input.target,
-            baseRef: input.baseRef,
-            headRef: input.headRef,
+            content: input.content,
+            contentType: input.contentType,
+            workspaceDir: input.workspaceDir,
+            customContext: input.customContext,
+            skipContextGathering: input.skipContextGathering,
             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: {

package/dist/review/buildPrompt.js

@@ -1,13 +1,51 @@
-export function buildPrompt({ diffText, context, focus }) {
+export function buildPrompt({ diffText, context, focus, version, isStaticReview }) {
     const focusLine = focus ? `Focus areas: ${focus}.` : '';
+    const versionLine = version ? `codex-review-mcp v${version}` : '';
+    const reviewType = isStaticReview ? 'Static File Review' : 'Diff Review';
     return [
+        versionLine,
+        '',
         'You are an expert AI code reviewer. Be concise, specific, and actionable.',
-        'Prefer minimal diffs and direct fixes. Respect project guidelines when provided.',
+        'Prefer minimal diffs and direct fixes.',
+        '',
+        'ENVIRONMENT ASSUMPTION: The runtime and tooling are POSIX (macOS/Linux). Do NOT suggest Windows/PowerShell/cmd-specific commands or paths.',
+        '',
+        '🚨 CRITICAL REPO-SPECIFIC GUIDANCE HIERARCHY:',
+        '1. HIGHEST PRIORITY: Project documentation (.cursor/rules/*, CODE_REVIEW.md, CONTRIBUTING.md, etc.)',
+        '2. Configuration files (tsconfig.json, .eslintrc, prettier config, etc.)',
+        '3. Existing patterns in similar files within the same directory',
+        '4. General best practices (ONLY when not conflicting with above)',
+        '',
+        'MANDATORY REVIEW REQUIREMENTS:',
+        '- 🔍 EXAMINE existing code patterns in the same directory/module before suggesting changes',
+        '- 📚 CHECK for existing utility functions, abstractions, and helpers before creating new ones',
+        '- 🎯 FOLLOW the exact naming conventions, file structure, and import patterns used in this repo',
+        '- 🧪 MATCH existing test patterns and testing approaches when reviewing test files',
+        '- ⚙️ VALIDATE against linting and formatting rules defined in the project config',
+        '- 🚫 NEVER suggest patterns that are inconsistent with the existing codebase',
+        '- 🚫 NEVER introduce external libraries/patterns not already in use',
+        '- ✅ PREFER reusing existing abstractions over creating new ones',
+        '',
+        'SPECIFIC TECHNICAL GUIDELINES:',
+        '- Follow ALL guidelines, conventions, and architectural patterns defined in the project documentation below',
+        '- Maintain consistency with the existing codebase styling, naming conventions, and structural themes',
+        '- Base your recommendations on the internal documentation, .cursor/rules files, and configuration files provided',
+        '- Do NOT suggest changes that deviate from the project\'s established patterns or introduce external patterns',
+        '- When project guidelines conflict with general best practices, prioritize the project guidelines',
+        '- For accessibility audits: apply axe-core best practices and WCAG 2.1 Level AA guidelines',
+        '- CRITICAL Z-INDEX WARNING: Be extremely cautious with z-index changes on modals, overlays, or components. Analyze the entire z-index hierarchy before suggesting changes. Flag any z-index modifications as HIGH RISK and verify they won\'t break stacking context upstream or downstream. Always check for existing z-index patterns in the codebase first.',
         focusLine,
-        '\n---\nScope and Diff (unified=0):\n',
+        '',
+        'BEFORE making ANY suggestion, ask yourself:',
+        '1. Does this pattern already exist in the codebase? (Check similar files)',
+        '2. Is there an existing utility/helper that could be reused?',
+        '3. Does this follow the exact conventions shown in the project documentation?',
+        '4. Would this change maintain consistency with the surrounding code?',
+        '',
+        `\n---\n${reviewType}${isStaticReview ? ' - Code Files' : ' (unified=0)'}:\n`,
         diffText,
-        context ? '\n---\nProject context and guidelines:\n' + context : '',
+        context ? '\n---\nProject context and guidelines (FOLLOW THESE STRICTLY):\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',
+        '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 (mention when code follows project guidelines well)\n6) Next steps',
     ].join('\n');
 }

package/dist/review/buildPrompt.test.js

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'vitest';
+import { buildPrompt } from './buildPrompt.js';
+describe('buildPrompt', () => {
+    const mockDiff = `diff --git a/test.ts b/test.ts
++++ b/test.ts
++export function hello() {
++  return "world";
++}`;
+    it('should include version in prompt when provided', () => {
+        const prompt = buildPrompt({
+            diffText: mockDiff,
+            version: '1.4.0',
+        });
+        expect(prompt).toContain('codex-review-mcp v1.4.0');
+        expect(prompt.startsWith('codex-review-mcp v1.4.0')).toBe(true);
+    });
+    it('should not include version line when version is not provided', () => {
+        const prompt = buildPrompt({
+            diffText: mockDiff,
+        });
+        expect(prompt).not.toContain('codex-review-mcp v');
+    });
+    it('should indicate "Diff Review" when isStaticReview is false', () => {
+        const prompt = buildPrompt({
+            diffText: mockDiff,
+            isStaticReview: false,
+        });
+        expect(prompt).toContain('Diff Review (unified=0)');
+    });
+    it('should indicate "Static File Review" when isStaticReview is true', () => {
+        const prompt = buildPrompt({
+            diffText: 'File: test.ts\ncode here',
+            isStaticReview: true,
+        });
+        expect(prompt).toContain('Static File Review - Code Files');
+    });
+    it('should default to "Diff Review" when isStaticReview is not provided', () => {
+        const prompt = buildPrompt({
+            diffText: mockDiff,
+        });
+        expect(prompt).toContain('Diff Review (unified=0)');
+    });
+    it('should include focus areas when provided', () => {
+        const prompt = buildPrompt({
+            diffText: mockDiff,
+            focus: 'security and performance',
+        });
+        expect(prompt).toContain('Focus areas: security and performance');
+    });
+    it('should include context when provided', () => {
+        const context = 'This is a TypeScript project using React';
+        const prompt = buildPrompt({
+            diffText: mockDiff,
+            context,
+        });
+        expect(prompt).toContain('Project context and guidelines (FOLLOW THESE STRICTLY)');
+        expect(prompt).toContain(context);
+    });
+    it('should include all required sections', () => {
+        const prompt = buildPrompt({
+            diffText: mockDiff,
+        });
+        // Verify key sections are present
+        expect(prompt).toContain('You are an expert AI code reviewer');
+        expect(prompt).toContain('CRITICAL REPO-SPECIFIC GUIDANCE HIERARCHY');
+        expect(prompt).toContain('MANDATORY REVIEW REQUIREMENTS');
+        expect(prompt).toContain('SPECIFIC TECHNICAL GUIDELINES');
+        expect(prompt).toContain('Output strictly as Markdown with the following sections');
+    });
+    it('should include the diff text', () => {
+        const prompt = buildPrompt({
+            diffText: mockDiff,
+        });
+        expect(prompt).toContain(mockDiff);
+    });
+    it('should handle all parameters together', () => {
+        const prompt = buildPrompt({
+            diffText: mockDiff,
+            version: '1.4.0',
+            isStaticReview: true,
+            focus: 'code quality',
+            context: 'TypeScript best practices',
+        });
+        expect(prompt).toContain('codex-review-mcp v1.4.0');
+        expect(prompt).toContain('Static File Review - Code Files');
+        expect(prompt).toContain('Focus areas: code quality');
+        expect(prompt).toContain('TypeScript best practices');
+        expect(prompt).toContain(mockDiff);
+    });
+    it('should include POSIX environment assumption', () => {
+        const prompt = buildPrompt({
+            diffText: mockDiff,
+        });
+        expect(prompt).toContain('ENVIRONMENT ASSUMPTION: The runtime and tooling are POSIX (macOS/Linux)');
+        expect(prompt).toContain('Do NOT suggest Windows/PowerShell/cmd-specific commands');
+    });
+    it('should include z-index warning', () => {
+        const prompt = buildPrompt({
+            diffText: mockDiff,
+        });
+        expect(prompt).toContain('CRITICAL Z-INDEX WARNING');
+        expect(prompt).toContain('z-index changes on modals, overlays, or components');
+    });
+    it('should include guidance hierarchy with proper priorities', () => {
+        const prompt = buildPrompt({
+            diffText: mockDiff,
+        });
+        expect(prompt).toContain('1. HIGHEST PRIORITY: Project documentation');
+        expect(prompt).toContain('2. Configuration files');
+        expect(prompt).toContain('3. Existing patterns in similar files');
+        expect(prompt).toContain('4. General best practices');
+    });
+});