Elenchus MCP Server

English | 한국어

Verifier↔Critic 토론 루프를 활용한 적대적 코드 검증 시스템

Elenchus (ἔλεγχος): 체계적 질문을 통해 모순을 드러내어 진실에 도달하는 소크라테스의 논박법.

개요

Elenchus는 적대적 코드 검증을 구현하는 Model Context Protocol (MCP) 서버입니다. 단순한 린팅이나 정적 분석과 달리, Elenchus는 Verifier와 Critic 에이전트 간의 토론을 조율하여 변증법적 추론을 통해 체계적으로 이슈를 발견합니다.

왜 적대적 검증인가?

전통적 접근	Elenchus 접근
단일 패스 분석	다중 라운드 토론
체크리스트 기반	의도 기반 시맨틱 분석
고정된 규칙	적응형 수렴
클린 코드에 침묵	명시적 부정 단언

Verifier↔Critic 루프

┌──────────────────────────────────────────────────────────────┐
│                       검증 루프                                │
├──────────────────────────────────────────────────────────────┤
│  라운드 1: Verifier → 코드 검토, 이슈 제기                      │
│  라운드 2: Critic   → 이슈 검증 (VALID/INVALID/PARTIAL)        │
│  라운드 3: Verifier → 방어, 해결, 또는 새 이슈 발견             │
│  라운드 4: Critic   → 재평가, 커버리지 확인                     │
│  ...수렴까지 계속...                                           │
│  최종: 판정 (PASS / FAIL / CONDITIONAL)                       │
└──────────────────────────────────────────────────────────────┘

주요 기능

🔄 적대적 토론 시스템

Verifier: 증거와 함께 이슈 발견
Critic: 발견 사항 검증, 주장 확인
역할 강제: 준수 점수와 함께 엄격한 교대

📊 의도 기반 수렴

키워드 매칭 대신 시맨틱 이해
5개 카테고리 커버리지 (보안, 정확성, 신뢰성, 유지보수성, 성능)
엣지 케이스 문서화 요구
클린 코드에 대한 부정 단언

🧠 LLM 기반 평가 (선택)

수렴 평가: LLM이 검증 품질 판단 (엄격한 불리언 체크 대신)
심각도 분류: 컨텍스트 인식 영향 분석
엣지 케이스 검증: 실제 분석 여부 확인 (키워드 존재가 아닌)
오탐 감지: 증거 기반 이슈 검증

🔍 자동 영향 분석

다중 언어 의존성 그래프 (tree-sitter 기반 15개 언어)
파급 효과 예측
케스케이드 깊이 계산
위험 수준 평가

🌐 다중 언어 지원

tree-sitter AST 파싱 기반 의존성 분석:

카테고리	언어
웹	TypeScript, TSX, JavaScript, CSS
시스템	Rust, Go, C, C++
엔터프라이즈	Java, C#
스크립트	Python, Ruby, PHP, Bash, PowerShell

💾 세션 관리

체크포인트/롤백 지원
전역 세션 저장소
감사 추적 보존

⚡ 토큰 최적화 (선택)

차분 분석 (변경된 코드만 검증)
응답 캐싱
선택적 청킹
계층화된 검증 파이프라인

빠른 시작

MCP 클라이언트 설정에 추가:

{
  "mcpServers": {
    "elenchus": {
      "command": "npx",
      "args": ["-y", "@jhlee0409/elenchus-mcp"]
    }
  }
}

그 다음 AI 어시스턴트와 자연어로 사용:

"src/auth 보안 이슈 검증해줘"

클라이언트별 설정은 설치 섹션을 참고하세요.

설치

지원 클라이언트

클라이언트	상태	비고
Claude Desktop	✅ 지원	macOS, Windows
Claude Code	✅ 지원	CLI 도구
VS Code (Copilot)	✅ 지원	v1.102+ 필요
Cursor	✅ 지원	40개 도구 제한
기타 MCP 클라이언트	✅ 호환	stdio 기반 클라이언트

Claude Desktop

Claude Desktop 설정 파일에 추가:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "elenchus": {
      "command": "npx",
      "args": ["-y", "@jhlee0409/elenchus-mcp"]
    }
  }
}

Claude Code

Claude Code 설정 (.mcp.json 또는 ~/.claude/settings.json)에 추가:

{
  "mcpServers": {
    "elenchus": {
      "command": "npx",
      "args": ["-y", "@jhlee0409/elenchus-mcp"]
    }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json에 추가:

{
  "mcp": {
    "servers": {
      "elenchus": {
        "command": "npx",
        "args": ["-y", "@jhlee0409/elenchus-mcp"]
      }
    }
  }
}

Cursor

Settings > MCP > Add new global MCP Server:

{
  "mcpServers": {
    "elenchus": {
      "command": "npx",
      "args": ["-y", "@jhlee0409/elenchus-mcp"]
    }
  }
}

사용법

검증하고 싶은 내용을 설명하면 됩니다:

"src/auth 보안 취약점 검증해줘"
"결제 모듈 엣지 케이스 확인해줘"
"src/api 정확성과 신뢰성 이슈 검토해줘"

AI 어시스턴트가 자동으로 Elenchus 도구를 사용합니다.

구조화된 워크플로우는 MCP 프롬프트 참고.

MCP 도구 레퍼런스

세션 라이프사이클

`elenchus_start_session`

새 검증 세션 초기화.

입력:

target (string, 필수): 검증 대상 경로 (파일 또는 디렉토리)
requirements (string, 필수): 검증 요구사항/집중 영역
workingDir (string, 필수): 상대 경로의 기준 작업 디렉토리
maxRounds (number, 선택): 최대 라운드 (기본: 10)
verificationMode (object, 선택): 모드 설정
- mode: "standard" | "fast-track" | "single-pass"
- skipCriticForCleanCode: boolean
differentialConfig (object, 선택): 변경된 파일만 검증
cacheConfig (object, 선택): 이전 검증 캐싱
chunkingConfig (object, 선택): 큰 파일 청킹
pipelineConfig (object, 선택): 계층화된 검증
llmEvalConfig (object, 선택): LLM 기반 평가 설정
- enabled: boolean - LLM 평가 활성화
- convergenceEval: boolean - 수렴 품질에 LLM 사용
- severityEval: boolean - 심각도 분류에 LLM 사용
- edgeCaseEval: boolean - 엣지 케이스 검증에 LLM 사용
- falsePositiveEval: boolean - 오탐 감지에 LLM 사용

반환: 세션 ID와 수집된 파일, 의존성 그래프 통계, 역할 설정을 포함한 초기 컨텍스트.

예시:

elenchus_start_session({
  target: "src/auth",
  requirements: "인증 보안 감사",
  workingDir: "/path/to/project",
  verificationMode: { mode: "fast-track" }
})

`elenchus_get_context`

파일, 이슈, 선제적 가이던스를 포함한 현재 세션 컨텍스트 조회.

입력:

sessionId (string, 필수): 세션 ID

반환: 파일, 이슈 요약, 집중 영역, 미검토 파일, 권장사항.

`elenchus_submit_round`

Verifier 또는 Critic 라운드 제출.

입력:

sessionId (string, 필수): 세션 ID
role ("verifier" | "critic", 필수): 이 라운드의 역할
output (string, 필수): 전체 에이전트 분석 출력
issuesRaised (Issue[], 선택): 새 이슈 (Verifier 역할)
issuesResolved (string[], 선택): 해결된 이슈 ID (Critic 역할)

이슈 스키마:

{
  id: string,
  category: "SECURITY" | "CORRECTNESS" | "RELIABILITY" | "MAINTAINABILITY" | "PERFORMANCE",
  severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW",
  summary: string,
  location: string,        // "file:line" 형식
  description: string,
  evidence: string         // 코드 스니펫 또는 증거
}

반환: 라운드 번호, 수렴 상태, 중재자 개입, 역할 준수 점수.

`elenchus_end_session`

최종 판정과 함께 세션 종료.

입력:

sessionId (string, 필수): 세션 ID
verdict ("PASS" | "FAIL" | "CONDITIONAL", 필수): 최종 판정

반환: 총 라운드, 카테고리별/심각도별 이슈를 포함한 세션 요약.

`elenchus_get_issues`

선택적 필터링으로 이슈 조회.

입력:

sessionId (string, 필수): 세션 ID
status ("all" | "unresolved" | "critical", 선택): 상태 필터

반환: 필터에 맞는 이슈 배열.

추가 도구 (31개)

위의 핵심 도구 외에 고급 워크플로우를 위한 31개 추가 도구 제공:

카테고리	도구
LLM 평가	`elenchus_evaluate_convergence`, `elenchus_evaluate_severity`, `elenchus_evaluate_edge_cases`, `elenchus_submit_llm_evaluation`
상태 관리	`elenchus_checkpoint`, `elenchus_rollback`, `elenchus_apply_fix`
분석	`elenchus_ripple_effect`, `elenchus_mediator_summary`
역할 강제	`elenchus_get_role_prompt`, `elenchus_role_summary`, `elenchus_update_role_config`
재검증	`elenchus_start_reverification`
차분 분석	`elenchus_save_baseline`, `elenchus_get_diff_summary`, `elenchus_get_project_history`
캐시	`elenchus_get_cache_stats`, `elenchus_clear_cache`
파이프라인	`elenchus_get_pipeline_status`, `elenchus_escalate_tier`, `elenchus_complete_tier`
세이프가드	`elenchus_get_safeguards_status`, `elenchus_update_confidence`, `elenchus_record_sampling_result`, `elenchus_check_convergence_allowed`
최적화	`elenchus_set_compression_mode`, `elenchus_get_optimization_stats`, `elenchus_configure_optimization`, `elenchus_estimate_savings`
동적 역할	`elenchus_generate_roles`, `elenchus_set_dynamic_roles`

모든 도구는 MCP 클라이언트에서 자동 검색됩니다. 상세 스키마는 MCP Inspector (npm run inspector)로 확인하세요.

MCP 리소스

URI 기반 리소스로 세션 데이터 접근:

URI 패턴	설명
`elenchus://sessions/`	모든 활성 세션 목록
`elenchus://sessions/{sessionId}`	특정 세션 상세 정보

사용법:

Read elenchus://sessions/
Read elenchus://sessions/2026-01-17_src-auth_abc123

MCP 프롬프트 (슬래시 커맨드)

프롬프트 이름	설명
`verify`	완전한 Verifier↔Critic 루프 실행
`consolidate`	우선순위화된 수정 계획 생성
`apply`	검증과 함께 수정 적용
`complete`	이슈 0까지 전체 파이프라인
`cross-verify`	적대적 교차 검증

호출 형식은 클라이언트에 따라 다릅니다. MCP 클라이언트 문서를 참고하세요.

검증 모드

다양한 용도에 맞는 세 가지 모드:

모드	최소 라운드	Critic 필수	용도
`standard`	3	예	철저한 검증
`fast-track`	1	선택	빠른 검증
`single-pass`	1	아니오	가장 빠름, Verifier만

예시:

elenchus_start_session({
  target: "src/",
  requirements: "보안 감사",
  workingDir: "/project",
  verificationMode: {
    mode: "fast-track",
    skipCriticForCleanCode: true
  }
})

이슈 라이프사이클

이슈는 여러 상태를 거칩니다:

RAISED → CHALLENGED → RESOLVED
           ↓
        DISMISSED (오탐)
           ↓
        MERGED (병합)
           ↓
        SPLIT (분할)

이슈 상태

상태	설명
`RAISED`	Verifier가 최초 발견
`CHALLENGED`	Verifier와 Critic 간 논쟁 중
`RESOLVED`	수정되고 검증됨
`DISMISSED`	오탐으로 무효화
`MERGED`	다른 이슈와 병합
`SPLIT`	여러 이슈로 분할

Critic 판정

판정	의미
`VALID`	이슈가 정당함
`INVALID`	오탐
`PARTIAL`	부분적으로 유효, 개선 필요

수렴 감지

세션은 모든 조건이 충족되면 수렴합니다:

CRITICAL 또는 HIGH 심각도 미해결 이슈 없음
2라운드 이상 안정 (새 이슈 없음)
최소 라운드 완료 (모드에 따라 다름)
5개 카테고리 모두 검토 완료
최근 이슈 상태 전이 없음
엣지 케이스 문서화 완료
클린 영역 명시적 선언 (부정 단언)
고위험 영향 파일 검토 완료

카테고리 커버리지

5개 카테고리 모두 검토 필수:

SECURITY - 인증, 권한, 인젝션
CORRECTNESS - 로직 오류, 타입 불일치
RELIABILITY - 에러 처리, 리소스 관리
MAINTAINABILITY - 코드 구조, 문서화
PERFORMANCE - 효율성, 리소스 사용

토큰 최적화

차분 분석

변경된 파일만 검증:

{
  differentialConfig: {
    enabled: true,
    baseRef: "main"  // main 브랜치와 비교
  }
}

응답 캐싱

이전 검증 결과 캐싱:

{
  cacheConfig: {
    enabled: true,
    ttlSeconds: 3600  // 1시간 캐시
  }
}

선택적 청킹

큰 파일을 집중된 청크로 분할:

{
  chunkingConfig: {
    enabled: true,
    maxChunkSize: 500  // 청크당 라인 수
  }
}

계층화된 파이프라인

빠른 분석으로 시작, 필요시 에스컬레이션:

{
  pipelineConfig: {
    enabled: true,
    startTier: "screen"  // screen → focused → exhaustive
  }
}

설정

환경 변수

변수	설명	기본값
`ELENCHUS_DATA_DIR`	커스텀 저장소 디렉토리	`~/.elenchus`
`XDG_DATA_HOME`	XDG 기본 디렉토리 (Linux/macOS)	-
`LOCALAPPDATA`	Windows AppData 위치	-

저장소 위치

세션과 데이터는 클라이언트 독립적 위치에 저장:

~/.elenchus/
├── sessions/          # 검증 세션
├── baselines/         # 차분 분석 베이스라인
├── cache/             # 응답 캐시
└── safeguards/        # 품질 세이프가드 데이터

우선순위:

$ELENCHUS_DATA_DIR - 명시적 오버라이드
$XDG_DATA_HOME/elenchus - XDG 스펙
%LOCALAPPDATA%\elenchus - Windows
~/.elenchus - 기본 폴백

커스텀 저장소

# 커스텀 위치 설정
export ELENCHUS_DATA_DIR=/path/to/custom/storage

# 또는 XDG 스펙 사용
export XDG_DATA_HOME=~/.local/share

세션 정리

세션은 감사 기록으로 보존됩니다. 수동 정리:

rm -rf ~/.elenchus/sessions/*
# 또는 특정 세션만
rm -rf ~/.elenchus/sessions/2026-01-17_*

아키텍처

시스템 다이어그램

┌─────────────────────────────────────────────────────────────────────┐
│                       ELENCHUS MCP SERVER                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                     MCP 프로토콜 레이어                        │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐ │  │
│  │  │  Tools   │  │Resources │  │ Prompts  │  │ Notifications│ │  │
│  │  │  (36)    │  │  (URI)   │  │   (5)    │  │  (선택)      │ │  │
│  │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────────────┘ │  │
│  └───────┼─────────────┼─────────────┼──────────────────────────┘  │
│          │             │             │                              │
│  ┌───────┴─────────────┴─────────────┴──────────────────────────┐  │
│  │                       코어 모듈                                │  │
│  │  Session Manager │ Context Manager │ Mediator System          │  │
│  │  Role Enforcement │ Issue Lifecycle │ Pipeline (계층화)       │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              │                                       │
│                              ▼                                       │
│                    ┌──────────────────┐                             │
│                    │     STORAGE      │                             │
│                    │ ~/.elenchus/     │                             │
│                    └──────────────────┘                             │
└─────────────────────────────────────────────────────────────────────┘

모듈 책임

모듈	목적
Session Manager	검증 세션 생성, 영속화, 관리
Context Manager	대상 파일과 의존성 수집 및 조직
Mediator System	다중 언어 의존성 그래프 (tree-sitter), 이슈 감지, 개입 트리거
Role Enforcement	Verifier↔Critic 교대 보장, 준수 검증
Issue Lifecycle	RAISED에서 RESOLVED까지 이슈 상태 추적
Pipeline	계층화된 검증 (screen → focused → exhaustive)

보안

보안 모델

Elenchus는 다음 보안 사항을 고려하여 운영됩니다:

코드 실행 없음: Elenchus는 검증하는 코드를 실행하지 않습니다. 정적 분석만 수행합니다.
로컬 저장소: 모든 세션 데이터는 ~/.elenchus/에 로컬로 저장됩니다. 외부 서버로 데이터가 전송되지 않습니다.
경로 검증: 모든 파일 경로는 경로 탐색 공격을 방지하기 위해 검증됩니다.
출력에 비밀 없음: 도구 출력은 민감한 데이터 노출을 방지하기 위해 정제됩니다.

권한

Elenchus는 다음을 필요로 합니다:

검증을 위한 대상 파일 읽기 권한
세션 저장을 위한 ~/.elenchus/ 쓰기 권한

보안 이슈 보고

보안 취약점은 GitHub Security Advisories를 통해 보고해 주세요.

문제 해결

일반적인 문제

서버를 찾을 수 없음 / 도구 사용 불가

증상: MCP 클라이언트가 Elenchus 명령이나 도구를 인식하지 못함.

해결책:

클라이언트의 MCP 설정에서 설치 확인
서버 추가 후 MCP 클라이언트 재시작
설정 문법 확인 (JSON이 유효해야 함)
Node.js ≥18 설치 확인:
```
node --version
```

세션을 찾을 수 없음

증상: "Session not found: xxx" 오류

해결책:

활성 세션 목록 확인:
```
Read elenchus://sessions/
```
세션이 정리되었을 수 있음 - 새 세션 시작
세션 ID 오타 확인

권한 거부 오류

증상: 파일 읽기 또는 세션 쓰기 불가.

해결책:

대상 디렉토리 파일 권한 확인
~/.elenchus/ 쓰기 권한 확인:
```
ls -la ~/.elenchus/
```
커스텀 저장소 위치 시도:
```
export ELENCHUS_DATA_DIR=/tmp/elenchus
```

역할 준수 거부

증상: 준수 점수로 인해 라운드 거부.

해결책:

현재 역할 요구사항 확인:

elenchus_get_role_prompt({ role: "verifier" })

최소 준수 점수 낮추기:

elenchus_update_role_config({
  sessionId: "...",
  minComplianceScore: 50,
  strictMode: false
})

역할 교대 확인 (Verifier → Critic → Verifier)

디버깅

MCP Inspector로 디버깅:

npm run inspector
# 또는
npx @modelcontextprotocol/inspector node dist/index.js

도움 받기

이슈: GitHub Issues
토론: GitHub Discussions

개발

빌드 명령

npm run build      # TypeScript를 dist/로 컴파일
npm run dev        # 자동 리빌드 Watch 모드
npm run start      # 컴파일된 서버 실행
npm run inspector  # MCP Inspector 실행 (디버깅)

프로젝트 구조

elenchus-mcp/
├── src/
│   ├── index.ts           # 진입점, MCP 서버 설정
│   ├── tools/             # 도구 정의 및 핸들러
│   ├── resources/         # 리소스 정의
│   ├── prompts/           # 프롬프트 템플릿
│   ├── types/             # TypeScript 인터페이스
│   ├── state/             # 세션 및 컨텍스트 관리
│   ├── mediator/          # 다중 언어 의존성 분석 (tree-sitter)
│   ├── roles/             # 역할 강제
│   ├── config/            # 설정 상수
│   ├── cache/             # 응답 캐싱
│   ├── chunking/          # 코드 청킹
│   ├── diff/              # 차분 분석
│   ├── pipeline/          # 계층화된 검증
│   └── safeguards/        # 품질 세이프가드
├── dist/                  # 컴파일된 출력
├── package.json
├── tsconfig.json
└── README.md

기여

기여를 환영합니다!

저장소 포크
기능 브랜치 생성
풀 리퀘스트 제출

라이선스

MIT

FilesExpand file tree

README.ko.md

Latest commit

History

README.ko.md

File metadata and controls

Elenchus MCP Server

목차

개요

왜 적대적 검증인가?

Verifier↔Critic 루프

주요 기능

🔄 적대적 토론 시스템

📊 의도 기반 수렴

🧠 LLM 기반 평가 (선택)

🔍 자동 영향 분석

🌐 다중 언어 지원

💾 세션 관리

⚡ 토큰 최적화 (선택)

빠른 시작

설치

지원 클라이언트

Claude Desktop

Claude Code

VS Code (GitHub Copilot)

Cursor

사용법

MCP 도구 레퍼런스

세션 라이프사이클

elenchus_start_session

elenchus_get_context

elenchus_submit_round

elenchus_end_session

elenchus_get_issues

추가 도구 (31개)

MCP 리소스

MCP 프롬프트 (슬래시 커맨드)

검증 모드

이슈 상태

Critic 판정

카테고리 커버리지

토큰 최적화

설정

환경 변수

저장소 위치

커스텀 저장소

세션 정리

아키텍처

모듈 책임

보안

보안 모델

권한

보안 이슈 보고

문제 해결

일반적인 문제

디버깅

도움 받기

개발

빌드 명령

프로젝트 구조

기여

라이선스

`elenchus_start_session`

`elenchus_get_context`

`elenchus_submit_round`

`elenchus_end_session`

`elenchus_get_issues`