GPT Cross Validator

Claude와 독립적으로 작동하는 GPT-5.2 기반 교차검증 MCP 서버

개요

gpt-cross-validator는 Claude 에이전트의 의사결정을 검증하는 MCP(Model Context Protocol) 서버입니다. GPT-5.2 모델을 사용하여 계획 검토와 코드 리뷰를 독립적으로 수행하므로, Claude의 판단에 대한 객관적인 교차검증이 가능합니다.

핵심 특징

• 독립적 검증: Claude와 별개의 GPT-5.2 모델로 의사결정 검증
• 계획 검토: 작업 계획의 명확성, 완전성, 위험도 평가
• 코드 리뷰: 보안, 성능, 코드 품질 종합 검토
• 구조화된 출력: JSON 형식의 명확한 평가 결과
• OAuth 인증: 안전한 OpenAI API 토큰 관리

기능

1. gpt_critique - 계획 검토

작업 계획, 설계, 아키텍처를 평가합니다.

평가 기준:

• 명확성: 구현에 필요한 정보가 명확한가?
• 검증 가능성: 성공 기준이 객관적인가?
• 맥락 완전성: 필요한 정보가 충분한가?
• 전체 이해도: 개발자가 전체 목표를 이해할 수 있는가?

응답 예시:

{
  "verdict": "OKAY",
  "confidence": 0.92,
  "summary": "계획은 명확한 목표와 구현 경로를 제시합니다.",
  "strengths": [
    "각 단계별 명확한 성공 기준 제시",
    "참고 문서 및 기존 코드 패턴 명시",
    "의존성과 제약사항 전부 포함"
  ],
  "concerns": [
    "데이터베이스 마이그레이션 전략이 불분명함",
    "무중단 배포 계획이 누락됨"
  ],
  "suggestions": [
    "마이그레이션 단계를 docs/migration-plan.md로 구체화",
    "무중단 배포 전략을 추가하거나 다단계 롤아웃 계획 수립"
  ],
  "risk_assessment": {
    "level": "MEDIUM",
    "factors": [
      "기존 데이터와의 호환성 불명확",
      "사용자 영향 최소화 전략 부재"
    ]
  }
}

2. gpt_review - 코드 리뷰

코드 품질, 보안, 성능을 종합적으로 검토합니다.

검토 항목:

• 보안 (필수): 하드코딩된 자격증명, SQL 인젝션, XSS, 입력 검증, 경로 조회, 인증 우회
• 코드 품질: 함수 크기, 파일 크기, 중첩 깊이, 에러 처리, 디버그 코드, 테스트 커버리지
• 성능: 알고리즘 효율성, 불필요한 리렌더링, 캐싱 누락, N+1 쿼리, 메모리 누수
• 모범 사례: TODO 주석, 문서화, 변수명, 매직 넘버, 포맷팅, 타입 안전성

응답 예시:

{
  "verdict": "REQUEST_CHANGES",
  "overall_score": 6,
  "summary": "코드 구조는 좋으나 보안 취약점과 에러 처리 누락이 있습니다.",
  "issues": [
    {
      "severity": "critical",
      "line": 42,
      "message": "API 키가 하드코딩되어 있습니다.",
      "suggestion": "환경 변수로 이동: process.env.API_KEY"
    },
    {
      "severity": "major",
      "line": 15,
      "message": "사용자 입력이 검증되지 않고 SQL 쿼리에 직접 사용됨",
      "suggestion": "parameterized query 사용: db.query('SELECT * FROM users WHERE id = ?', [userId])"
    },
    {
      "severity": "major",
      "message": "async 함수에서 promise 처리 누락",
      "suggestion": ".catch()나 try-catch 블록 추가"
    },
    {
      "severity": "minor",
      "message": "console.log() 디버그 출력이 남아있음",
      "suggestion": "배포 전에 제거"
    }
  ],
  "highlights": [
    "타입스크립트 타입이 잘 정의됨",
    "에러 처리 구조가 명확함",
    "단위 테스트 커버리지가 높음"
  ],
  "security_concerns": [
    "API 인증 헤더가 로그에 기록될 수 있음",
    "SQL 쿼리 문자열 연결 사용"
  ],
  "performance_notes": [
    "데이터베이스 쿼리가 인덱스를 활용하도록 최적화 필요"
  ]
}

설치

사전 요구사항

• Node.js ≥ 18.0.0
• OpenAI API 계정 (GPT-5.2 모델 접근 권한 필요)
• ~/.omc 디렉토리 (OMC 설정 디렉토리)

1단계: 저장소 클론 및 설치

git clone <repository-url>
cd gpt-cross-validator
npm install

2단계: TypeScript 컴파일

npm run build

컴파일된 코드는 dist/ 디렉토리에 생성됩니다.

3단계: OpenAI OAuth 토큰 설정

자세한 내용은 OAuth 토큰 설정을 참고하세요.

OAuth 토큰 설정

토큰 파일 위치

~/.omc/secrets/openai-oauth.json

토큰 파일 형식

{
  "access_token": "sk-...",
  "refresh_token": "sk-...",
  "token_type": "Bearer",
  "expires_at": 1234567890,
  "scope": "openai-api"
}

필수 필드:

• access_token: OpenAI API 접근 토큰
• token_type: 항상 "Bearer"
• expires_at: UNIX 타임스탐프 (초 단위) - 토큰 만료 시간

선택 필드:

• refresh_token: 토큰 자동 갱신용 (있으면 만료 시 자동 갱신)
• scope: API 범위 정보

토큰 파일 생성 방법

방법 1: 수동 생성 (개발용)

# 디렉토리 생성
mkdir -p ~/.omc/secrets

# 파일 생성 및 권한 설정
cat > ~/.omc/secrets/openai-oauth.json << EOF
{
  "access_token": "your-access-token-here",
  "token_type": "Bearer",
  "expires_at": $(date -v+2H +%s)
}
EOF

# 보안 권한 설정 (소유자만 읽기 가능)
chmod 600 ~/.omc/secrets/openai-oauth.json

방법 2: OpenAI OAuth 흐름 (프로덕션용)

1. OpenAI 플랫폼에서 계정 설정
2. API 키 생성 또는 OAuth 토큰 발급
3. 토큰 파일 형식으로 저장

보안 고려사항

• 파일 권한은 반드시 600 (소유자만 읽기)으로 설정
• 토큰은 버전 관리 시스템에 커밋하지 않음
• 토큰이 노출되면 즉시 OpenAI 플랫폼에서 폐지
• 프로덕션 환경에서는 환경 변수 또는 시크릿 매니저 사용

Claude Code MCP 서버 등록

Claude Code 설정

Claude Code(oh-my-claudecode)에서 이 MCP 서버를 사용하려면 Claude 설정 파일에 등록해야 합니다.

1단계: 빌드 확인

npm run build
# dist/index.js가 생성되었는지 확인
ls -la dist/index.js

2단계: Claude 설정 파일 수정

Claude Code 설정 파일 위치:

~/.claude/claude.json

또는 CLAUDE.md가 있는 경우:

~/.claude/CLAUDE.md

3단계: MCP 서버 추가

{
  "mcpServers": {
    "gpt-cross-validator": {
      "command": "node",
      "args": ["/Users/kimtaeyoun/Bamboos/04_2026_withcharlie/gpt-cross-validator/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

주의: 경로를 본인의 환경에 맞게 수정하세요.

4단계: 서버 재시작

Claude Code를 재시작하면 MCP 서버가 등록됩니다.

등록 확인

Claude에서 다음을 시도해보세요:

gpt_critique를 사용하여 이 계획을 검토해줄래?

또는

gpt_review를 사용해서 이 코드를 검토해줘.

사용 예시

계획 검토 (gpt_critique)

Claude 에이전트 프롬프트:

다음 마이그레이션 계획을 GPT-5.2로 검토해줘:

## 사용자 인증 시스템 마이그레이션 계획

1. 현재 세션 기반 인증에서 JWT로 전환
2. 단계:
   - 신규 JWT 토큰 생성 로직 구현 (src/auth/jwt.ts)
   - 기존 로그인 엔드포인트에 JWT 발급 추가
   - 모든 인증 미들웨어를 JWT 검증으로 업데이트
   - 라우트별 테스트 추가 (tests/auth.spec.ts)
3. 성공 기준: 모든 테스트 통과, 무중단 배포 가능

context: 현재 60개의 API 엔드포인트가 있으며, 연결된 모바일 클라이언트 2개가 있습니다.

응답:

{
  "verdict": "OKAY",
  "confidence": 0.88,
  "summary": "계획은 명확한 구현 경로를 제시하나, 마이그레이션 일정과 롤백 전략이 필요합니다.",
  "strengths": [
    "단계별 구현 순서가 명확",
    "테스트 전략이 포함됨",
    "무중단 배포 가능성 고려"
  ],
  "concerns": [
    "이전 클라이언트와의 호환성 전략 누락",
    "토큰 갱신 로직이 언급되지 않음",
    "만료된 토큰 처리 방법 불명확"
  ],
  "suggestions": [
    "세션 기반과 JWT 인증을 동시 지원하는 기간 명시",
    "토큰 갱신 엔드포인트 추가 계획 포함",
    "클라이언트 버전별 호환성 매트릭스 작성"
  ],
  "risk_assessment": {
    "level": "MEDIUM",
    "factors": [
      "모바일 클라이언트 2개의 호환성 확보 필요",
      "기존 세션 데이터 마이그레이션 전략 부재"
    ]
  }
}

코드 리뷰 (gpt_review)

Claude 에이전트 프롬프트:

gpt_review로 이 코드를 검토해줄 수 있어?

파일: src/auth/jwt.ts
언어: TypeScript

코드:

import jwt from 'jsonwebtoken';

export function createToken(userId: string): string {
  const secret = 'my-secret-key'; // 주의: 이건 예시
  return jwt.sign({ userId }, secret, { expiresIn: '24h' });
}

export function verifyToken(token: string): string {
  const secret = 'my-secret-key';
  const decoded = jwt.verify(token, secret) as any;
  return decoded.userId;
}

export async function handleLogin(req, res) {
  const { email, password } = req.body;
  const user = await User.findByEmail(email);

  if (user.password === password) {
    const token = createToken(user.id);
    res.json({ token });
  } else {
    res.status(401).send('Unauthorized');
  }
}

context: JWT 토큰 검증 로직입니다. 모든 보호된 라우트에서 사용됩니다.

**응답:**

```json
{
  "verdict": "REQUEST_CHANGES",
  "overall_score": 3,
  "summary": "심각한 보안 취약점이 있습니다. 즉시 수정 필요합니다.",
  "issues": [
    {
      "severity": "critical",
      "line": 4,
      "message": "JWT 비밀키가 하드코딩되어 있습니다.",
      "suggestion": "환경 변수 사용: const secret = process.env.JWT_SECRET || 'development-secret';"
    },
    {
      "severity": "critical",
      "line": 13,
      "message": "입력 검증 없음. 빈 토큰, null, undefined가 처리되지 않음.",
      "suggestion": "if (!token || typeof token !== 'string') throw new Error('Invalid token');"
    },
    {
      "severity": "critical",
      "line": 23,
      "message": "평문 비밀번호 비교. 암호화된 해시와 비교해야 함.",
      "suggestion": "bcrypt.compare(password, user.passwordHash) 사용"
    },
    {
      "severity": "major",
      "line": 17,
      "message": "any 타입 사용. 타입 안전성 감소.",
      "suggestion": "interface TokenPayload { userId: string; } 정의 후 사용"
    },
    {
      "severity": "major",
      "line": 21,
      "message": "try-catch 블록 없음. JWT 검증 실패 시 예외 처리 안 됨.",
      "suggestion": "jwt.verify를 try-catch로 감싸기"
    },
    {
      "severity": "major",
      "line": 28,
      "message": "요청 본문이 검증되지 않음. 빈 값이 전달될 수 있음.",
      "suggestion": "zod, joi, 또는 내장 검증 라이브러리로 검증"
    }
  ],
  "highlights": [
    "토큰 만료 시간이 적절하게 설정됨",
    "표준 JWT 라이브러리 사용"
  ],
  "security_concerns": [
    "하드코딩된 비밀키 - 코드가 노출되면 모든 토큰이 위조 가능",
    "평문 비밀번호 저장 - 데이터베이스 침해 시 즉시 손상",
    "토큰 검증 실패에 대한 에러 처리 부재",
    "HTTPS 사용 여부가 코드에 강제되지 않음"
  ],
  "performance_notes": [
    "JWT 검증은 동기 연산으로 비용이 적으므로 현재 구현 충분"
  ]
}

출력 형식

gpt_critique 응답 구조

{
  verdict: "OKAY" | "REJECT"              // 계획 승인 여부
  confidence: number (0.0 ~ 1.0)          // 평가 확신도
  summary: string                          // 1-2줄 요약
  strengths: string[]                      // 잘된 점들
  concerns: string[]                       // 문제점들 (구체적)
  suggestions: string[]                    // 개선 제안 (실행 가능)
  risk_assessment: {
    level: "LOW" | "MEDIUM" | "HIGH"       // 위험도
    factors: string[]                      // 위험 요인들
  }
}

gpt_review 응답 구조

{
  verdict: "APPROVE" | "REQUEST_CHANGES"   // 코드 승인 여부
  overall_score: number (1 ~ 10)           // 종합 점수
  summary: string                          // 평가 요약
  issues: Array<{
    severity: "critical" | "major" | "minor" | "suggestion"
    line?: number                          // 문제 발생 줄 번호 (선택)
    message: string                        // 문제 설명
    suggestion?: string                    // 해결 방법 (선택)
  }>
  highlights: string[]                     // 잘된 부분들
  security_concerns?: string[]             // 보안 관련 사항
  performance_notes?: string[]             // 성능 관련 사항
}

문제 해결

토큰 에러

에러 메시지:

Error: OpenAI OAuth 토큰이 설정되지 않았습니다.
위치: ~/.omc/secrets/openai-oauth.json
형식: { "access_token": "...", "expires_at": 1234567890 }

해결 방법:

1. 토큰 파일이 존재하는지 확인:

ls -la ~/.omc/secrets/openai-oauth.json

2. 파일이 없으면 생성:

mkdir -p ~/.omc/secrets
cat > ~/.omc/secrets/openai-oauth.json << EOF
{
  "access_token": "sk-your-token",
  "token_type": "Bearer",
  "expires_at": $(python3 -c "import time; print(int(time.time()) + 7200)")
}
EOF
chmod 600 ~/.omc/secrets/openai-oauth.json

3. 파일 형식 확인:

cat ~/.omc/secrets/openai-oauth.json | python3 -m json.tool

토큰 만료 에러

에러 메시지:

Error: 토큰이 만료되었고 refresh_token이 없습니다. 재인증이 필요합니다.

해결 방법:

토큰 파일의 expires_at을 현재 시간보다 뒤로 설정:

# 현재 시간부터 2시간 유효한 새 토큰 발급
python3 << EOF
import json
import time

token_file = '/Users/kimtaeyoun/.omc/secrets/openai-oauth.json'
with open(token_file, 'r') as f:
    token = json.load(f)

# 만료 시간 업데이트 (2시간 후)
token['expires_at'] = int(time.time()) + 7200

with open(token_file, 'w') as f:
    json.dump(token, f, indent=2)

print("Token updated!")
EOF

MCP 서버 연결 실패

증상: Claude에서 gpt_critique나 gpt_review 도구를 사용할 수 없음

해결 단계:

1. 서버 빌드 확인:

cd /Users/kimtaeyoun/Bamboos/04_2026_withcharlie/gpt-cross-validator
npm run build
ls -la dist/index.js

2. 서버 수동 실행 테스트:

node dist/index.js
# "GPT Cross Validator MCP Server running on stdio"가 표시되어야 함

3. Claude 설정 파일 확인:

cat ~/.claude/claude.json | grep -A 10 "gpt-cross-validator"

4. Claude 재시작

권한 에러

에러 메시지:

Error: EACCES: permission denied

해결 방법:

# 토큰 파일 권한 확인 및 수정
chmod 600 ~/.omc/secrets/openai-oauth.json

# 디렉토리 권한 확인
chmod 700 ~/.omc/secrets
chmod 700 ~/.omc

GPT API 연결 실패

에러 메시지:

Error: 401 Unauthorized

해결 방법:

1. 토큰이 유효한지 확인:

cat ~/.omc/secrets/openai-oauth.json | jq '.expires_at'
python3 -c "import time; print('Current timestamp:', int(time.time()))"

2. expires_at이 현재 시간보다 뒤에 있는지 확인

3. OpenAI 플랫폼에서 토큰이 폐지되지 않았는지 확인

모델 접근 불가

에러 메시지:

Error: 404 Model gpt-5.2 not found

해결 방법:

1. OpenAI 계정이 GPT-5.2에 접근 권한이 있는지 확인
2. 사용 가능한 모델 확인: https://platform.openai.com/docs/models
3. 필요하면 src/tools/gpt-critique.ts와 src/tools/gpt-review.ts에서 모델명 변경:

// gpt-4.5-preview 또는 다른 사용 가능 모델로 변경
model: 'gpt-4.5-preview',

개발

개발 서버 실행

npm run dev

TypeScript 코드를 직접 실행합니다. (ts-node 사용)

TypeScript 컴파일

npm run build

src/의 TypeScript 코드를 dist/로 컴파일합니다.

프로젝트 구조

gpt-cross-validator/
├── src/
│   ├── index.ts                  # MCP 서버 진입점
│   ├── auth/
│   │   └── oauth-manager.ts      # OpenAI OAuth 토큰 관리
│   ├── tools/
│   │   ├── index.ts              # 도구 내보내기
│   │   ├── gpt-critique.ts       # 계획 검토 도구
│   │   └── gpt-review.ts         # 코드 리뷰 도구
│   └── prompts/
│       ├── critic-system.ts      # 계획 검토 프롬프트
│       └── code-reviewer-system.ts # 코드 리뷰 프롬프트
├── dist/                         # 컴파일된 JavaScript
├── package.json
├── tsconfig.json
└── README.md

아키텍처

데이터 흐름

Claude Agent
    │
    ├─→ [gpt_critique 요청]
    │   └─→ OAuthManager (토큰 로드/갱신)
    │       └─→ OpenAI API (GPT-5.2)
    │           └─→ 계획 평가
    │               └─→ 구조화된 JSON 응답
    │
    └─→ [gpt_review 요청]
        └─→ OAuthManager (토큰 로드/갱신)
            └─→ OpenAI API (GPT-5.2)
                └─→ 코드 평가
                    └─→ 구조화된 JSON 응답

인증 흐름

1. OAuthManager 초기화
   └─→ 토큰 경로 설정: ~/.omc/secrets/openai-oauth.json

2. getAccessToken() 호출
   ├─→ 토큰 파일 로드
   ├─→ 만료 여부 확인 (5분 여유)
   ├─→ 만료되었으면 refresh_token으로 갱신
   └─→ access_token 반환

3. OpenAI API 호출
   └─→ Authorization: Bearer {access_token}

라이센스

MIT License

기여

버그 리포트, 기능 요청, Pull Request를 환영합니다.

지원

문제가 발생하면:

1. 문제 해결 섹션을 먼저 확인
2. 에러 메시지와 함께 이슈 리포트
3. 토큰 파일 내용은 공유하지 않기 (보안)

변경 로그

v1.0.0

• 초기 릴리스
• gpt_critique 도구 (계획 검토)
• gpt_review 도구 (코드 리뷰)
• OAuth 토큰 관리
• MCP 서버 통합