Codex Checker MCP Server

AI 에이전트가 코드 작업을 완료한 후 Codex CLI에 자동으로 코드 리뷰를 요청하는 MCP 서버입니다.

✨ 주요 기능

| 도구 | 설명 | 토큰 효율 | |------|------|----------| | review_changes | Git 변경사항 리뷰 (Codex가 직접 diff 실행) | ⭐⭐⭐ 최고 | | review_code | 파일 경로 기반 코드 리뷰 (Codex가 파일 읽음) | ⭐⭐ 좋음 | | submit_diff_for_review | 제공된 diff 리뷰 (diff 전달 필요) | ⭐ 보통 | | verify_review | 리뷰 제안사항 데이터 반환 | - | | mark_verified | 검증 결과 기록 | - | | optimize_diff | Diff 수동 최적화 | - | | get_review_history | 리뷰 기록 조회 | - | | setup_encoding | UTF-8 인코딩 스크립트 반환 | - |

🚀 설치 방법

방법 1: npx로 직접 실행 (권장)

npx codexchecker-mcp-server

방법 2: 글로벌 설치

npm install -g codexchecker-mcp-server
codexchecker

방법 3: 로컬 빌드

git clone https://github.com/user/codexchecker
cd codexchecker
npm install
npm run build

⚙️ VS Code MCP 설정

.vscode/mcp.json 또는 사용자 설정에 추가:

{
  "servers": {
    "codexchecker": {
      "type": "stdio",
      "command": "npx",
      "args": ["codexchecker-mcp-server"]
    }
  }
}

또는 로컬 빌드 사용 시:

{
  "servers": {
    "codexchecker": {
      "type": "stdio",
      "command": "node",
      "args": ["d:/repos/codexchecker/build/index.js"]
    }
  }
}

📋 사전 요구사항

• Node.js >= 18.0.0
• Codex CLI 설치 및 PATH에 등록

  # Codex CLI 설치 (예시)
  npm install -g @openai/codex

🔧 도구 상세 설명

review_changes ⭐ (권장)

Git 변경사항을 Codex가 직접 읽어서 리뷰합니다. Codex CLI의 /review 명령과 유사합니다.

가장 토큰 효율적! - diff를 프롬프트에 포함하지 않고 Codex가 직접 git diff 실행

파라미터:

• workingDir (필수): Git 저장소 경로
• staged: staged 변경만 리뷰 (기본: false)
• lastCommit: 마지막 커밋 리뷰 (기본: false)
• focusAreas: 집중 영역 (예: ["security", "performance"])

사용 예시:

// 현재 uncommitted 변경사항 리뷰
{ "workingDir": "d:/repos/myproject" }

// staged 변경만 리뷰
{ "workingDir": "d:/repos/myproject", "staged": true }

// 마지막 커밋 리뷰
{ "workingDir": "d:/repos/myproject", "lastCommit": true }

// 보안 집중 리뷰
{ "workingDir": "d:/repos/myproject", "focusAreas": ["security"] }

review_code

파일 경로를 지정하면 Codex가 직접 파일을 읽어 리뷰합니다.

파라미터:

• filePath (필수): 리뷰할 파일 경로
• startLine: 리뷰 시작 라인 번호
• endLine: 리뷰 종료 라인 번호
• workingDir: 작업 디렉토리
• context: 추가 컨텍스트
• reviewType: general | security | performance | style | bugs
• sandbox: read-only | workspace-write | danger-full-access

사용 예시:

// 파일 전체 리뷰
{ "filePath": "src/index.ts" }

// 특정 라인 범위만 리뷰
{ "filePath": "src/index.ts", "startLine": 100, "endLine": 150 }

// 보안 리뷰
{ "filePath": "src/auth.ts", "reviewType": "security" }

submit_diff_for_review

diff 내용을 직접 전달하여 리뷰합니다. 가능하면 review_changes를 사용하세요 (더 효율적).

파라미터:

• diff (필수): Git diff 내용
• commitMessage: 변경 설명
• focusAreas: 집중 검토 영역
• workingDir: 작업 디렉토리
• maxLines: 최대 diff 라인 수 (기본: 500)
• excludePatterns: 제외할 파일 패턴
• skipOptimization: 최적화 건너뛰기

자동 제외 파일:

• node_modules/, package-lock.json, yarn.lock
• *.min.js, *.min.css, dist/, build/, *.map

verify_review

리뷰 제안사항 데이터를 반환합니다. Codex를 호출하지 않고, 이 도구를 호출한 AI 에이전트가 직접 각 제안의 타당성을 검증해야 합니다.

파라미터:

• reviewId (필수): 검증할 리뷰 ID
• suggestionIndex: 특정 제안사항 인덱스 (0부터 시작, 생략시 전체 반환)

반환 데이터:

• 각 제안사항의 타입, 심각도, 설명, 파일, 라인 정보
• 구조화된 JSON 데이터 포함

mark_verified

AI 에이전트가 검증한 제안사항의 결과를 기록합니다.

파라미터:

• reviewId (필수): 리뷰 ID
• suggestionIndex (필수): 제안사항 인덱스 (0부터 시작)
• isValid (필수): 제안이 타당한지 여부
• action (필수): 조치 방법
  • fix_required: 즉시 수정 필요
  • recommended: 수정 권장
  • optional: 선택적 수정
  • dismissed: 기각
• reason: 검증 결과에 대한 이유 설명

optimize_diff

Diff를 사전에 최적화하여 토큰 사용량을 줄입니다.

파라미터:

• diff (필수): 최적화할 diff 내용
• maxLines: 최대 라인 수
• excludePatterns: 추가 제외 패턴
• prioritize: 우선할 키워드 목록

🛡️ 경로 신뢰 문제 해결

Codex CLI가 작업 디렉토리를 신뢰하지 않는 경우:

1. workingDir 파라미터에 Git 저장소 경로 지정
2. 자동으로 -C <dir> 옵션 적용
3. --skip-git-repo-check 옵션 자동 추가
4. 기본 샌드박스 모드: workspace-write

📊 토큰 절약 전략

| 순위 | 방법 | 설명 | |------|------|------| | 1️⃣ | review_changes | Codex가 직접 git diff 실행 | | 2️⃣ | review_code (filePath만) | Codex가 직접 파일 읽음 | | 3️⃣ | review_code (라인 범위) | 필요한 부분만 리뷰 | | 4️⃣ | submit_diff_for_review | 자동 최적화 적용 |

추가 최적화:

• 자동 파일 필터링: lock 파일, 빌드 산출물, 바이너리 제외
• 우선순위 기반 정렬: 보안/버그 관련 변경사항 우선
• 라인 수 제한: 기본 500줄, 초과 시 자동 truncate

📝 예시 워크플로우

1. 코드 작업 완료

2. review_changes로 Git 변경사항 리뷰 (권장)
   → Codex가 직접 git diff 실행 (토큰 최소화)
   
   또는 review_code로 특정 파일 리뷰
   → filePath + startLine/endLine으로 범위 지정

3. 리뷰 결과 확인 (제안사항 ID 발급)

4. verify_review로 제안사항 데이터 조회
   → AI 에이전트가 직접 코드를 확인하여 검증

5. mark_verified로 검증 결과 기록
   → fix_required / recommended / optional / dismissed

6. 검증된 제안사항 적용

🌐 인코딩 문제 해결 (Windows)

한글이 깨지는 경우 setup_encoding 도구 사용:

# PowerShell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; [Console]::InputEncoding = [System.Text.Encoding]::UTF8; $OutputEncoding = [System.Text.Encoding]::UTF8; chcp 65001 | Out-Null

# CMD
chcp 65001

# Bash
export LANG=en_US.UTF-8; export LC_ALL=en_US.UTF-8

🔗 관련 링크

• MCP TypeScript SDK
• MCP 문서
• Codex CLI

📄 라이선스

MIT