cc-reviewer 1.0.0

package/dist/errors.js

@@ -0,0 +1,188 @@
+/**
+ * Error Handling for AI Reviewer MCP Server
+ */
+// CLI installation commands
+// Codex: https://developers.openai.com/codex/cli/
+// Gemini: https://github.com/google-gemini/gemini-cli
+const INSTALL_COMMANDS = {
+    codex: 'npm install -g @openai/codex-cli',
+    gemini: 'npm install -g @google/gemini-cli'
+};
+// Environment variables for API keys
+const ENV_VARS = {
+    codex: 'OPENAI_API_KEY',
+    gemini: 'GEMINI_API_KEY'
+};
+// Authentication commands
+const AUTH_COMMANDS = {
+    codex: 'codex login',
+    gemini: 'gemini (follow prompts)'
+};
+/**
+ * Create a CLI not found error
+ */
+export function createCliNotFoundError(cli) {
+    return {
+        type: 'cli_not_found',
+        cli,
+        installCmd: INSTALL_COMMANDS[cli]
+    };
+}
+/**
+ * Create a timeout error
+ */
+export function createTimeoutError(cli, durationMs) {
+    return {
+        type: 'timeout',
+        cli,
+        durationMs
+    };
+}
+/**
+ * Create a rate limit error
+ */
+export function createRateLimitError(cli, retryAfterMs) {
+    return {
+        type: 'rate_limit',
+        cli,
+        retryAfterMs
+    };
+}
+/**
+ * Create an auth error
+ */
+export function createAuthError(cli, message) {
+    return {
+        type: 'auth_error',
+        cli,
+        message
+    };
+}
+/**
+ * Create an invalid response error
+ */
+export function createInvalidResponseError(cli, rawOutput) {
+    return {
+        type: 'invalid_response',
+        cli,
+        rawOutput
+    };
+}
+/**
+ * Create a CLI crash error
+ */
+export function createCliError(cli, exitCode, stderr) {
+    return {
+        type: 'cli_error',
+        cli,
+        exitCode,
+        stderr
+    };
+}
+/**
+ * Format an error for user display
+ */
+export function formatErrorForUser(error) {
+    const otherCli = error.cli === 'codex' ? 'gemini' : 'codex';
+    switch (error.type) {
+        case 'cli_not_found':
+            return `❌ ${error.cli} CLI not found.
+
+Install with: ${error.installCmd}
+
+Alternative: Use /${otherCli}-review instead`;
+        case 'timeout':
+            return `⏱️ ${error.cli} timed out after ${Math.round(error.durationMs / 1000)}s.
+
+This might happen with complex reviews. Try:
+• Reviewing a smaller scope
+• Using --focus to narrow the review`;
+        case 'rate_limit':
+            const retryMsg = error.retryAfterMs
+                ? `Try again in ${Math.ceil(error.retryAfterMs / 1000)}s`
+                : 'Wait a moment and try again';
+            return `🚫 ${error.cli} rate limit hit.
+
+${retryMsg}
+
+Alternative: Use /${otherCli}-review instead`;
+        case 'auth_error':
+            return `🔐 ${error.cli} authentication failed.
+
+${error.message}
+
+Check your API key: ${ENV_VARS[error.cli]}
+Run: ${AUTH_COMMANDS[error.cli]}`;
+        case 'invalid_response':
+            return `⚠️ ${error.cli} returned an unusable response.
+
+The output couldn't be parsed as valid feedback.
+Raw output (truncated): ${error.rawOutput.slice(0, 200)}...`;
+        case 'cli_error':
+            return `❌ ${error.cli} crashed (exit code ${error.exitCode}).
+
+${error.stderr}`;
+    }
+}
+/**
+ * Detect error type from CLI output and error messages
+ */
+export function detectErrorType(cli, error, stdout, stderr, exitCode) {
+    // CLI not found
+    if (error.code === 'ENOENT') {
+        return createCliNotFoundError(cli);
+    }
+    // Rate limit
+    if (stderr.toLowerCase().includes('rate limit') ||
+        stdout.toLowerCase().includes('rate limit')) {
+        const retryAfterMatch = stderr.match(/retry after (\d+)/i);
+        const retryAfterMs = retryAfterMatch ? parseInt(retryAfterMatch[1]) * 1000 : undefined;
+        return createRateLimitError(cli, retryAfterMs);
+    }
+    // Auth error
+    if (stderr.toLowerCase().includes('unauthorized') ||
+        stderr.toLowerCase().includes('authentication') ||
+        stderr.toLowerCase().includes('401') ||
+        stderr.toLowerCase().includes('403')) {
+        return createAuthError(cli, stderr);
+    }
+    // Generic CLI error
+    if (exitCode !== null && exitCode !== 0) {
+        return createCliError(cli, exitCode, stderr);
+    }
+    // Invalid response (fallback)
+    return createInvalidResponseError(cli, stdout);
+}
+/**
+ * Parse retry-after from error response
+ */
+export function parseRetryAfter(errorMessage) {
+    const match = errorMessage.match(/retry[- ]?after[:\s]+(\d+)/i);
+    if (match) {
+        return parseInt(match[1]) * 1000; // Convert to ms
+    }
+    return undefined;
+}
+/**
+ * Generate suggestion based on error type
+ */
+export function getSuggestion(error) {
+    switch (error.type) {
+        case 'cli_not_found':
+            return `Install ${error.cli} CLI or use the other model`;
+        case 'timeout':
+            return 'Try reviewing a smaller scope or using --focus';
+        case 'rate_limit':
+            return error.retryAfterMs
+                ? `Wait ${Math.ceil(error.retryAfterMs / 1000)}s and retry`
+                : 'Wait a moment and retry';
+        case 'auth_error':
+            return `Check your ${ENV_VARS[error.cli]} environment variable`;
+        case 'invalid_response':
+            return 'Retry with a more specific focus area';
+        case 'cli_error':
+            return 'Check the CLI documentation for troubleshooting';
+        default:
+            return undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * AI Reviewer MCP Server
+ *
+ * Provides tools for getting second-opinion feedback from external AI CLIs
+ * (Codex and Gemini) on Claude Code's work.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * AI Reviewer MCP Server
+ *
+ * Provides tools for getting second-opinion feedback from external AI CLIs
+ * (Codex and Gemini) on Claude Code's work.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { handleCodexFeedback, handleGeminiFeedback, handleMultiFeedback, FeedbackInputSchema, TOOL_DEFINITIONS } from './tools/feedback.js';
+import { logCliStatus } from './cli/check.js';
+// Create the MCP server
+const server = new Server({
+    name: 'ai-reviewer',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Handle tool listing
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            TOOL_DEFINITIONS.codex_feedback,
+            TOOL_DEFINITIONS.gemini_feedback,
+            TOOL_DEFINITIONS.multi_feedback,
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        // Validate input
+        const input = FeedbackInputSchema.parse(args);
+        switch (name) {
+            case 'codex_feedback':
+                return await handleCodexFeedback(input);
+            case 'gemini_feedback':
+                return await handleGeminiFeedback(input);
+            case 'multi_feedback':
+                return await handleMultiFeedback(input);
+            default:
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Unknown tool: ${name}`
+                        }],
+                    isError: true
+                };
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Error: ${errorMessage}`
+                }],
+            isError: true
+        };
+    }
+});
+// Start the server
+async function main() {
+    // Log CLI availability status on startup
+    await logCliStatus();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('AI Reviewer MCP Server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/prompt.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 7-Section Prompt Builder for External CLI Delegation
+ */
+import { FeedbackRequest, CliType } from './types.js';
+/**
+ * Build the 7-section delegation prompt for external CLIs
+ */
+export declare function build7SectionPrompt(request: FeedbackRequest): string;
+/**
+ * Build the developer instructions (persona) for a specific CLI
+ */
+export declare function buildDeveloperInstructions(cli: CliType): string;
+/**
+ * Build a retry prompt that includes previous attempt information
+ */
+export declare function buildRetryPrompt(request: FeedbackRequest, attemptNumber: number, previousError: string, previousOutput: string): string;
+/**
+ * Detect output type from CC's output content
+ */
+export declare function detectOutputType(ccOutput: string): 'findings' | 'plan' | 'proposal' | 'analysis';
+/**
+ * Validate that external CLI output follows expected structure
+ */
+export declare function isValidFeedbackOutput(output: string): boolean;

package/dist/prompt.js

@@ -0,0 +1,134 @@
+/**
+ * 7-Section Prompt Builder for External CLI Delegation
+ */
+import { REVIEWER_PERSONAS, FOCUS_AREA_DESCRIPTIONS } from './types.js';
+/**
+ * Build the 7-section delegation prompt for external CLIs
+ */
+export function build7SectionPrompt(request) {
+    const { workingDir, ccOutput, outputType, analyzedFiles = [], focusAreas = [], customPrompt } = request;
+    const focusDescription = focusAreas.length > 0
+        ? focusAreas.map(f => `${f} (${FOCUS_AREA_DESCRIPTIONS[f]})`).join(', ')
+        : 'General review';
+    const filesAnalyzed = analyzedFiles.length > 0
+        ? analyzedFiles.join(', ')
+        : 'Not specified';
+    const customInstructions = customPrompt
+        ? `\n  Special Instructions: ${customPrompt}`
+        : '';
+    return `TASK: Review CC's ${outputType} and provide structured feedback.
+
+EXPECTED OUTCOME: Identify agreements, disagreements, additions, and alternatives.
+
+CONTEXT:
+  Working Directory: ${workingDir}
+  Output Type: ${outputType}
+  Files Analyzed: ${filesAnalyzed}
+  CC's Output:
+${indent(ccOutput, 4)}
+
+CONSTRAINTS:
+  Focus Areas: ${focusDescription}
+  Advisory mode only (no file changes)
+  You have filesystem access${customInstructions}
+
+MUST DO:
+  • Review CC's findings critically
+  • Verify claims by reading files yourself
+  • Reference specific file:line when relevant
+  • Follow OUTPUT FORMAT exactly
+
+MUST NOT DO:
+  • Make any file changes
+  • Hallucinate file paths
+  • Return unstructured text
+
+OUTPUT FORMAT:
+## Agreements
+- [Finding]: [Why correct]
+
+## Disagreements
+- [Finding]: [Why wrong] - [Correct assessment]
+
+## Additions
+- [New finding]: [File:line] - [Impact]
+
+## Alternatives
+- [Topic]: [Alternative] - [Tradeoffs]
+
+## Risk Assessment
+[Low/Medium/High] - [Reason]`;
+}
+/**
+ * Build the developer instructions (persona) for a specific CLI
+ */
+export function buildDeveloperInstructions(cli) {
+    const persona = REVIEWER_PERSONAS[cli];
+    return `You are a ${persona.name} code review expert.
+
+Focus on: ${persona.focus}
+
+Style: ${persona.style}
+
+You are reviewing another AI assistant's (Claude Code) work on a codebase.
+Your job is to provide a second opinion - validate their findings, challenge
+incorrect assessments, and add anything they missed.
+
+Be specific. Reference file paths and line numbers when relevant.
+Use the structured OUTPUT FORMAT provided in the prompt.`;
+}
+/**
+ * Build a retry prompt that includes previous attempt information
+ */
+export function buildRetryPrompt(request, attemptNumber, previousError, previousOutput) {
+    const basePrompt = build7SectionPrompt(request);
+    return `TASK: Review CC's ${request.outputType} (RETRY - attempt ${attemptNumber}/3)
+
+PREVIOUS ATTEMPT FAILED:
+  Error: ${previousError}
+  Raw output (truncated): ${previousOutput.slice(0, 300)}...
+
+ADDITIONAL INSTRUCTION: Follow the OUTPUT FORMAT exactly. Each section header
+must start with "## " and contain structured content.
+
+${basePrompt.split('\n').slice(1).join('\n')}`;
+}
+/**
+ * Helper to indent text
+ */
+function indent(text, spaces) {
+    const padding = ' '.repeat(spaces);
+    return text.split('\n').map(line => padding + line).join('\n');
+}
+/**
+ * Detect output type from CC's output content
+ */
+export function detectOutputType(ccOutput) {
+    if (/\b(vulnerab|injection|XSS|CSRF|SSRF|auth.*issue|security)/i.test(ccOutput)) {
+        return 'findings';
+    }
+    if (/\b(fix|bug|issue|error|proposed fix|solution|patch)/i.test(ccOutput)) {
+        return 'proposal';
+    }
+    if (/\b(architect|design|plan|implement|phase|step \d|structure)/i.test(ccOutput)) {
+        return 'plan';
+    }
+    return 'analysis';
+}
+/**
+ * Validate that external CLI output follows expected structure
+ */
+export function isValidFeedbackOutput(output) {
+    const requiredSections = [
+        /^## Agreements$/m,
+        /^## Disagreements$/m,
+        /^## Additions$/m,
+        /^## Alternatives$/m,
+        /^## Risk Assessment$/m
+    ];
+    // Must have all required sections: Agreements, Disagreements, Additions, Alternatives, Risk Assessment
+    const hasRequiredSections = requiredSections.every(regex => regex.test(output));
+    // Must not be empty or too short
+    const hasContent = output.length > 100;
+    return hasRequiredSections && hasContent;
+}

package/dist/tools/feedback.d.ts

@@ -0,0 +1,185 @@
+/**
+ * MCP Tool Implementations for AI Reviewer
+ */
+import { z } from 'zod';
+export declare const FeedbackInputSchema: z.ZodObject<{
+    workingDir: z.ZodString;
+    ccOutput: z.ZodString;
+    outputType: z.ZodEnum<["plan", "findings", "analysis", "proposal"]>;
+    analyzedFiles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    focusAreas: z.ZodOptional<z.ZodArray<z.ZodEnum<["security", "performance", "architecture", "correctness", "maintainability", "scalability", "testing", "documentation"]>, "many">>;
+    customPrompt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    workingDir: string;
+    ccOutput: string;
+    outputType: "plan" | "findings" | "analysis" | "proposal";
+    analyzedFiles?: string[] | undefined;
+    focusAreas?: ("security" | "performance" | "architecture" | "correctness" | "maintainability" | "scalability" | "testing" | "documentation")[] | undefined;
+    customPrompt?: string | undefined;
+}, {
+    workingDir: string;
+    ccOutput: string;
+    outputType: "plan" | "findings" | "analysis" | "proposal";
+    analyzedFiles?: string[] | undefined;
+    focusAreas?: ("security" | "performance" | "architecture" | "correctness" | "maintainability" | "scalability" | "testing" | "documentation")[] | undefined;
+    customPrompt?: string | undefined;
+}>;
+export type FeedbackInput = z.infer<typeof FeedbackInputSchema>;
+/**
+ * Codex feedback tool handler
+ */
+export declare function handleCodexFeedback(input: FeedbackInput): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+/**
+ * Gemini feedback tool handler
+ */
+export declare function handleGeminiFeedback(input: FeedbackInput): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+/**
+ * Multi-model feedback tool handler (parallel execution)
+ */
+export declare function handleMultiFeedback(input: FeedbackInput): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+/**
+ * Tool definitions for MCP registration
+ */
+export declare const TOOL_DEFINITIONS: {
+    codex_feedback: {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                workingDir: {
+                    type: string;
+                    description: string;
+                };
+                ccOutput: {
+                    type: string;
+                    description: string;
+                };
+                outputType: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                analyzedFiles: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                focusAreas: {
+                    type: string;
+                    items: {
+                        type: string;
+                        enum: string[];
+                    };
+                    description: string;
+                };
+                customPrompt: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    gemini_feedback: {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                workingDir: {
+                    type: string;
+                    description: string;
+                };
+                ccOutput: {
+                    type: string;
+                    description: string;
+                };
+                outputType: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                analyzedFiles: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                focusAreas: {
+                    type: string;
+                    items: {
+                        type: string;
+                        enum: string[];
+                    };
+                    description: string;
+                };
+                customPrompt: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    multi_feedback: {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                workingDir: {
+                    type: string;
+                    description: string;
+                };
+                ccOutput: {
+                    type: string;
+                    description: string;
+                };
+                outputType: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                analyzedFiles: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                focusAreas: {
+                    type: string;
+                    items: {
+                        type: string;
+                        enum: string[];
+                    };
+                    description: string;
+                };
+                customPrompt: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+};