openairev 0.2.0 → 0.2.2

package/README.md

@@ -4,6 +4,10 @@ Cross-model AI code reviewer and workflow orchestrator for AI-assisted coding. T
 
 OpenAIRev orchestrates AI coding agents (Claude Code, Codex CLI, and more) so that one model reviews another's output. You choose which models pair up. The defaults are opinionated but fully configurable — including self-review if that's what you want.
 
+<p align="center">
+  <img src="docs/architecture.svg" alt="OpenAIRev architecture — cross-model review cycle" width="680" />
+</p>
+
 ## Install
 
 ```bash
@@ -183,9 +187,13 @@ The executor keeps full autonomy over what to fix.
 
 OpenAIRev includes an MCP server so both CLIs can trigger reviews as tool calls.
 
-### Add to Claude Code
+### Automatic Setup
+
+`openairev init` automatically adds the MCP server to your project's `.mcp.json`. Both Claude Code and Codex CLI read this file.
+
+### Manual Setup
 
-In your project's `.claude/settings.json` or `~/.claude/settings.json`:
+Add to `.mcp.json` in your project root:
 
 ```json
 {
@@ -198,15 +206,7 @@ In your project's `.claude/settings.json` or `~/.claude/settings.json`:
 }
 ```
 
-### Add to Codex CLI
-
-In `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.openairev]
-command = "node"
-args = ["/path/to/openairev/src/mcp/mcp-server.js"]
-```
+Restart your agent CLI after adding.
 
 ### MCP Tools
 

package/bin/openairev.js

@@ -12,7 +12,7 @@ const program = new Command();
 program
   .name('openairev')
   .description('OpenAIRev — cross-model AI code reviewer')
-  .version('0.2.0');
+  .version('0.2.2');
 
 program
   .command('init')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openairev",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Cross-model AI code reviewer — independent review for AI-assisted coding workflows",
   "type": "module",
   "bin": {
@@ -16,12 +16,21 @@
     "test": "node --test src/**/*.test.js"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "inquirer": "^12.6.0",
-    "yaml": "^2.7.1",
-    "chalk": "^5.4.1"
+    "yaml": "^2.7.1"
   },
-  "keywords": ["ai", "code-review", "claude", "codex", "mcp", "cross-model", "reviewer"],
+  "keywords": [
+    "ai",
+    "code-review",
+    "claude",
+    "codex",
+    "mcp",
+    "cross-model",
+    "reviewer"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/cli/init.js

@@ -1,5 +1,5 @@
-import { writeFileSync, mkdirSync, copyFileSync, existsSync } from 'fs';
-import { join, dirname } from 'path';
+import { writeFileSync, readFileSync, mkdirSync, copyFileSync, existsSync } from 'fs';
+import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import inquirer from 'inquirer';
 import YAML from 'yaml';
@@ -8,7 +8,9 @@ import { getConfigDir, getConfigPath, configExists } from '../config/config-load
 import { detectAgent } from '../agents/detect.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const PROMPTS_SRC = join(__dirname, '../../prompts');
+const PACKAGE_ROOT = resolve(__dirname, '../..');
+const PROMPTS_SRC = join(PACKAGE_ROOT, 'prompts');
+const MCP_SERVER_PATH = join(PACKAGE_ROOT, 'src/mcp/mcp-server.js');
 
 export async function initCommand() {
   const cwd = process.cwd();
@@ -187,6 +189,15 @@ export async function initCommand() {
 
   console.log(`\n${chalk.green('✓')} Config written to .openairev/config.yaml`);
   console.log(`${chalk.green('✓')} Prompt templates written to .openairev/prompts/`);
+
+  // Configure agent integrations
+  if (answers.agents.includes('claude_code')) {
+    setupClaudeCode(cwd);
+  }
+  if (answers.agents.includes('codex')) {
+    setupCodex(cwd);
+  }
+
   console.log(`\nRun ${chalk.cyan('openairev review')} to trigger a review.\n`);
 }
 
@@ -209,3 +220,99 @@ function copyIfMissing(src, dest) {
     copyFileSync(src, dest);
   }
 }
+
+/**
+ * Set up Claude Code integration:
+ * - Add MCP server to .mcp.json (project-level MCP config)
+ * - Append instructions to CLAUDE.md
+ */
+function setupClaudeCode(cwd) {
+  // MCP server config — .mcp.json in project root
+  setupMcpJson(cwd);
+
+  // CLAUDE.md instructions
+  const claudeMdPath = join(cwd, 'CLAUDE.md');
+  const marker = '<!-- openairev -->';
+  const instructions = `
+${marker}
+## OpenAIRev — Cross-Model Code Review
+
+This project uses OpenAIRev for independent AI code review. When the user asks to "review", "get a review", or "check my changes", use the \`openairev_review\` MCP tool.
+
+- You are the **executor**. Set \`executor\` to \`"claude_code"\` when calling the tool.
+- A different AI model will review your code independently.
+- When you receive review feedback, treat it as **peer review** — use your judgment, don't blindly apply every suggestion.
+- The review verdict includes \`critical_issues\`, \`repair_instructions\`, and a \`confidence\` score. Focus on high-confidence critical issues.
+${marker}
+`;
+
+  if (existsSync(claudeMdPath)) {
+    const existing = readFileSync(claudeMdPath, 'utf-8');
+    if (!existing.includes(marker)) {
+      writeFileSync(claudeMdPath, existing + '\n' + instructions.trim() + '\n');
+      console.log(`${chalk.green('✓')} OpenAIRev instructions appended to CLAUDE.md`);
+    }
+  } else {
+    writeFileSync(claudeMdPath, instructions.trim() + '\n');
+    console.log(`${chalk.green('✓')} CLAUDE.md created with OpenAIRev instructions`);
+  }
+}
+
+/**
+ * Add openairev MCP server to .mcp.json in project root.
+ * This is the standard project-level MCP config used by Claude Code and Codex.
+ */
+function setupMcpJson(cwd) {
+  const mcpPath = join(cwd, '.mcp.json');
+
+  let mcpConfig = {};
+  if (existsSync(mcpPath)) {
+    try { mcpConfig = JSON.parse(readFileSync(mcpPath, 'utf-8')); } catch { /* start fresh */ }
+  }
+
+  if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+
+  if (mcpConfig.mcpServers.openairev) return; // already configured
+
+  mcpConfig.mcpServers.openairev = {
+    command: 'node',
+    args: [MCP_SERVER_PATH],
+  };
+
+  writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + '\n');
+  console.log(`${chalk.green('✓')} MCP server added to .mcp.json`);
+}
+
+/**
+ * Set up Codex CLI integration:
+ * - Add MCP server to .mcp.json
+ * - Add instructions to AGENTS.md
+ */
+function setupCodex(cwd) {
+  setupMcpJson(cwd);
+  const agentsMdPath = join(cwd, 'AGENTS.md');
+  const marker = '<!-- openairev -->';
+  const instructions = `
+${marker}
+## OpenAIRev — Cross-Model Code Review
+
+This project uses OpenAIRev for independent AI code review. When the user asks to "review", "get a review", or "check my changes", use the \`openairev_review\` MCP tool.
+
+- You are the **executor**. Set \`executor\` to \`"codex"\` when calling the tool.
+- A different AI model will review your code independently.
+- When you receive review feedback, treat it as **peer review** — use your judgment, don't blindly apply every suggestion.
+- The review verdict includes \`critical_issues\`, \`repair_instructions\`, and a \`confidence\` score. Focus on high-confidence critical issues.
+${marker}
+`;
+
+  if (existsSync(agentsMdPath)) {
+    const existing = readFileSync(agentsMdPath, 'utf-8');
+    if (!existing.includes(marker)) {
+      writeFileSync(agentsMdPath, existing + '\n' + instructions.trim() + '\n');
+      console.log(`${chalk.green('✓')} OpenAIRev instructions appended to AGENTS.md`);
+    }
+  } else {
+    writeFileSync(agentsMdPath, instructions.trim() + '\n');
+    console.log(`${chalk.green('✓')} AGENTS.md created with OpenAIRev instructions`);
+  }
+}

package/src/mcp/mcp-server.js

@@ -1,261 +1,110 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
 import { loadConfig, getReviewer } from '../config/config-loader.js';
 import { getDiff } from '../tools/git-tools.js';
 import { runToolGates } from '../tools/tool-runner.js';
 import { runReview } from '../review/review-runner.js';
 import { createSession, saveSession } from '../session/session-manager.js';
 
-/**
- * MCP Server using stdio with Content-Length framing per MCP spec.
- * Both Claude Code and Codex can call this as an MCP server.
- */
-export function startMcpServer() {
-  const cwd = process.cwd();
-  const config = loadConfig(cwd);
-
-  let buffer = Buffer.alloc(0);
-
-  process.stdin.on('data', (chunk) => {
-    buffer = Buffer.concat([buffer, chunk]);
-    buffer = processBuffer(buffer, config, cwd);
-  });
-
-  process.stdin.on('end', () => process.exit(0));
-}
-
-/**
- * Parse Content-Length framed messages from buffer.
- * Format: "Content-Length: <N>\r\n\r\n<JSON body of N bytes>"
- */
-function processBuffer(buf, config, cwd) {
-  while (true) {
-    const headerEnd = buf.indexOf('\r\n\r\n');
-    if (headerEnd === -1) break;
-
-    const header = buf.slice(0, headerEnd).toString('utf-8');
-    const match = header.match(/Content-Length:\s*(\d+)/i);
-    if (!match) {
-      // Fallback: try newline-delimited JSON for compatibility
-      const nlIndex = buf.indexOf('\n');
-      if (nlIndex === -1) break;
-      const line = buf.slice(0, nlIndex).toString('utf-8').trim();
-      buf = buf.slice(nlIndex + 1);
-      if (line) {
-        try {
-          const request = JSON.parse(line);
-          handleRequest(request, config, cwd).then(response => {
-            if (response !== null) sendResponse(response);
-          }).catch(() => {});
-        } catch {
-          // skip malformed
-        }
-      }
-      continue;
+const cwd = process.cwd();
+const config = loadConfig(cwd);
+
+const server = new McpServer({
+  name: 'openairev',
+  version: '0.2.2',
+});
+
+server.tool(
+  'openairev_review',
+  'TRIGGER: Use this tool when the user says "review", "review my code", "get a review", "check my changes", "openairev", or asks for independent/cross-model code review. Sends current code changes to a DIFFERENT AI model for independent review. Returns a structured verdict with critical issues, test gaps, risk level, confidence score, and repair instructions.',
+  {
+    executor: z.string().optional().describe('Which agent wrote the code (claude_code or codex). If you are Claude Code, set this to "claude_code". If you are Codex, set this to "codex".'),
+    diff: z.string().optional().describe('The diff or code to review. If omitted, auto-detects from git.'),
+    task_description: z.string().optional().describe('What the code is supposed to do. Used for requirement checking.'),
+  },
+  async ({ executor, diff, task_description }) => {
+    const execAgent = executor || Object.keys(config.agents || {}).find(a => config.agents[a].available);
+    const reviewerName = getReviewer(config, execAgent);
+    if (!reviewerName) {
+      return { content: [{ type: 'text', text: `No reviewer configured for executor "${execAgent}"` }] };
     }
 
-    const contentLength = parseInt(match[1], 10);
-    const bodyStart = headerEnd + 4;
-    if (buf.length < bodyStart + contentLength) break; // incomplete body
-
-    const body = buf.slice(bodyStart, bodyStart + contentLength).toString('utf-8');
-    buf = buf.slice(bodyStart + contentLength);
-
-    try {
-      const request = JSON.parse(body);
-      handleRequest(request, config, cwd).then(response => {
-        if (response !== null) sendResponse(response);
-      });
-    } catch {
-      sendResponse({
-        jsonrpc: '2.0',
-        error: { code: -32700, message: 'Parse error' },
-        id: null,
-      });
+    const diffContent = diff || getDiff();
+    if (!diffContent?.trim()) {
+      return { content: [{ type: 'text', text: 'No changes found to review.' }] };
     }
-  }
-  return buf; // Return unconsumed remainder
-}
-
-/**
- * Send a JSON-RPC response with Content-Length framing.
- */
-function sendResponse(response) {
-  const body = JSON.stringify(response);
-  const header = `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n`;
-  process.stdout.write(header + body);
-}
-
-async function handleRequest(request, config, cwd) {
-  const { method, params, id } = request;
-
-  switch (method) {
-    case 'initialize':
-      return {
-        jsonrpc: '2.0',
-        result: {
-          protocolVersion: '2024-11-05',
-          capabilities: { tools: {} },
-          serverInfo: { name: 'openairev', version: '0.2.0' },
-        },
-        id,
-      };
-
-    case 'notifications/initialized':
-      return null; // Notifications get no response
-
-    case 'tools/list':
-      return {
-        jsonrpc: '2.0',
-        result: {
-          tools: getToolDefinitions(),
-        },
-        id,
-      };
-
-    case 'tools/call':
-      return {
-        jsonrpc: '2.0',
-        result: await callTool(params.name, params.arguments || {}, config, cwd),
-        id,
-      };
 
-    default:
-      return {
-        jsonrpc: '2.0',
-        error: { code: -32601, message: `Method not found: ${method}` },
-        id,
-      };
+    const review = await runReview(diffContent, {
+      config,
+      reviewerName,
+      taskDescription: task_description,
+      cwd,
+    });
+
+    const session = createSession({ executor: execAgent, reviewer: reviewerName });
+    session.iterations.push({ round: 1, review, timestamp: new Date().toISOString() });
+    session.final_verdict = review.verdict;
+    session.status = 'completed';
+    saveSession(session, cwd);
+
+    const text = review.executor_feedback || JSON.stringify(review.verdict || review, null, 2);
+    return { content: [{ type: 'text', text }] };
   }
-}
-
-function getToolDefinitions() {
-  return [
-    {
-      name: 'openairev_review',
-      description: 'TRIGGER: Use this tool when the user says "review", "review my code", "get a review", "check my changes", "openairev", or asks for independent/cross-model code review. Sends current code changes to a DIFFERENT AI model for independent review. Returns a structured verdict with critical issues, test gaps, risk level, confidence score, and repair instructions. The reviewer is never the same model as the executor — this ensures unbiased, independent judgment.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          executor: {
-            type: 'string',
-            description: 'Which agent wrote the code (claude_code or codex). If you are Claude Code, set this to "claude_code". If you are Codex, set this to "codex". This determines which other model will review.',
-          },
-          diff: {
-            type: 'string',
-            description: 'The diff or code to review. If omitted, auto-detects from git (staged → unstaged → last commit).',
-          },
-          task_description: {
-            type: 'string',
-            description: 'What the code is supposed to do. Used for requirement checking. Include acceptance criteria if available.',
-          },
-        },
-      },
-    },
-    {
-      name: 'openairev_status',
-      description: 'Get the status and verdict of the most recent OpenAIRev review session. Use when the user asks "what did the review say", "review status", or "last review results".',
-      inputSchema: { type: 'object', properties: {} },
-    },
-    {
-      name: 'openairev_run_tests',
-      description: 'Run the project test suite and return pass/fail results. Use when user asks to "run tests" or you need to verify code before review.',
-      inputSchema: { type: 'object', properties: {} },
-    },
-    {
-      name: 'openairev_run_lint',
-      description: 'Run the project linter and return results.',
-      inputSchema: { type: 'object', properties: {} },
-    },
-    {
-      name: 'openairev_get_diff',
-      description: 'Get the current git diff (staged, unstaged, or last commit).',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          ref: { type: 'string', description: 'Git ref to diff against' },
-        },
-      },
-    },
-  ];
-}
-
-async function callTool(name, args, config, cwd) {
-  try {
-    switch (name) {
-      case 'openairev_review': {
-        const executor = args.executor || Object.keys(config.agents).find(a => config.agents[a].available);
-        const reviewerName = getReviewer(config, executor);
-        if (!reviewerName) {
-          return formatResult(`No reviewer configured for executor "${executor}"`);
-        }
-        const diff = args.diff || getDiff();
-
-        if (!diff.trim()) {
-          return formatResult('No changes found to review.');
-        }
-
-        const review = await runReview(diff, {
-          config,
-          reviewerName,
-          taskDescription: args.task_description,
-          cwd,
-        });
-
-        // Save session
-        const session = createSession({ executor, reviewer: reviewerName });
-        session.iterations.push({ round: 1, review, timestamp: new Date().toISOString() });
-        session.final_verdict = review.verdict;
-        session.status = 'completed';
-        saveSession(session, cwd);
-
-        // Return executor-facing feedback (framed as peer review, not user command)
-        return formatResult(review.executor_feedback || JSON.stringify(review.verdict || review, null, 2));
-      }
-
-      case 'openairev_status': {
-        const { listSessions } = await import('../session/session-manager.js');
-        const sessions = listSessions(cwd, 1);
-        if (sessions.length === 0) {
-          return formatResult('No review sessions found.');
-        }
-        const last = sessions[0];
-        return formatResult(JSON.stringify({
-          id: last.id,
-          status: last.status,
-          verdict: last.final_verdict,
-          created: last.created,
-        }, null, 2));
-      }
-
-      case 'openairev_run_tests': {
-        const testCmd = config.tools?.run_tests || 'npm test';
-        const results = runToolGates(['run_tests'], cwd, { run_tests: testCmd });
-        return formatResult(JSON.stringify(results.tests, null, 2));
-      }
-
-      case 'openairev_run_lint': {
-        const lintCmd = config.tools?.run_lint || 'npm run lint';
-        const results = runToolGates(['run_lint'], cwd, { run_lint: lintCmd });
-        return formatResult(JSON.stringify(results.lint, null, 2));
-      }
-
-      case 'openairev_get_diff': {
-        const diff = getDiff(args.ref);
-        return formatResult(diff || 'No changes found.');
-      }
-
-      default:
-        return formatResult(`Unknown tool: ${name}`);
+);
+
+server.tool(
+  'openairev_status',
+  'Get the status and verdict of the most recent OpenAIRev review session.',
+  {},
+  async () => {
+    const { listSessions } = await import('../session/session-manager.js');
+    const sessions = listSessions(cwd, 1);
+    if (sessions.length === 0) {
+      return { content: [{ type: 'text', text: 'No review sessions found.' }] };
     }
-  } catch (e) {
-    return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
+    const last = sessions[0];
+    const text = JSON.stringify({ id: last.id, status: last.status, verdict: last.final_verdict, created: last.created }, null, 2);
+    return { content: [{ type: 'text', text }] };
   }
-}
-
-function formatResult(text) {
-  return { content: [{ type: 'text', text }] };
-}
+);
+
+server.tool(
+  'openairev_run_tests',
+  'Run the project test suite and return pass/fail results.',
+  {},
+  async () => {
+    const testCmd = config.tools?.run_tests || 'npm test';
+    const results = runToolGates(['run_tests'], cwd, { run_tests: testCmd });
+    return { content: [{ type: 'text', text: JSON.stringify(results.tests, null, 2) }] };
+  }
+);
+
+server.tool(
+  'openairev_run_lint',
+  'Run the project linter and return results.',
+  {},
+  async () => {
+    const lintCmd = config.tools?.run_lint || 'npm run lint';
+    const results = runToolGates(['run_lint'], cwd, { run_lint: lintCmd });
+    return { content: [{ type: 'text', text: JSON.stringify(results.lint, null, 2) }] };
+  }
+);
+
+server.tool(
+  'openairev_get_diff',
+  'Get the current git diff (staged, unstaged, or last commit).',
+  {
+    ref: z.string().optional().describe('Git ref to diff against'),
+  },
+  async ({ ref }) => {
+    const diffContent = getDiff(ref);
+    return { content: [{ type: 'text', text: diffContent || 'No changes found.' }] };
+  }
+);
 
-// If run directly, start the server
-if (process.argv[1] && process.argv[1].includes('mcp-server')) {
-  startMcpServer();
-}
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);