Elenchus MCP Server

English | 한국어

Adversarial Code Verification System using Verifier↔Critic Debate Loop

Elenchus (ἔλεγχος): Socrates' method of refutation through systematic questioning - exposing contradictions to reach truth.

Overview

Elenchus is a Model Context Protocol (MCP) server that implements adversarial code verification. Unlike simple linting or static analysis, Elenchus orchestrates a debate between Verifier and Critic agents to systematically uncover issues through dialectical reasoning.

Why Adversarial Verification?

Traditional Approach	Elenchus Approach
Single-pass analysis	Multi-round debate
Checklist-based	Intent-based semantic analysis
Fixed rules	Adaptive convergence
Silent on clean code	Explicit negative assertions

The Verifier↔Critic Loop

┌──────────────────────────────────────────────────────────────┐
│                    VERIFICATION LOOP                          │
├──────────────────────────────────────────────────────────────┤
│  Round 1: Verifier → Examines code, RAISES issues            │
│  Round 2: Critic   → Challenges issues (VALID/INVALID/PARTIAL)│
│  Round 3: Verifier → Defends, resolves, or finds new issues  │
│  Round 4: Critic   → Re-evaluates, checks coverage           │
│  ...continues until convergence...                            │
│  Final: Verdict (PASS / FAIL / CONDITIONAL)                  │
└──────────────────────────────────────────────────────────────┘

Key Features

🔄 Adversarial Debate System

Verifier: Finds issues with evidence
Critic: Challenges findings, validates claims
Role Enforcement: Strict alternation with compliance scoring

📊 Intent-Based Convergence

Semantic understanding instead of keyword matching
5 category coverage (Security, Correctness, Reliability, Maintainability, Performance)
Edge case documentation requirements
Negative assertions for clean code

🧠 LLM-Based Evaluation (Optional)

Convergence Assessment: LLM judges verification quality (vs rigid boolean checks)
Severity Classification: Context-aware impact analysis
Edge Case Validation: Verifies actual analysis, not just keyword presence
False Positive Detection: Evidence-based issue validation

🔍 Automatic Impact Analysis

Multi-language dependency graph (15 languages via tree-sitter)
Ripple effect prediction
Cascade depth calculation
Risk level assessment

🌐 Multi-Language Support

Dependency analysis powered by tree-sitter AST parsing:

Category	Languages
Web	TypeScript, TSX, JavaScript, CSS
Systems	Rust, Go, C, C++
Enterprise	Java, C#
Scripting	Python, Ruby, PHP, Bash, PowerShell

💾 Session Management

Checkpoint/rollback support
Global session storage
Audit trail preservation

⚡ Token Optimization (Optional)

Differential analysis (verify only changed code)
Response caching
Selective chunking
Tiered verification pipeline

Quick Start

Add to your MCP client configuration:

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

Then use naturally with your AI assistant:

"Please verify src/auth for security issues"

See Installation for client-specific setup instructions.

Installation

Supported Clients

Client	Status	Notes
Claude Desktop	✅ Supported	macOS, Windows
Claude Code	✅ Supported	CLI tool
VS Code (Copilot)	✅ Supported	Requires v1.102+
Cursor	✅ Supported	40 tool limit applies
Other MCP Clients	✅ Compatible	Any stdio-based client

Claude Desktop

Add to your Claude Desktop configuration file:

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

Add to your Claude Code settings (.mcp.json or ~/.claude/settings.json):

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

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

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

Cursor

Go to Settings > MCP > Add new global MCP Server:

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

Usage

Simply describe what you want to verify:

"Verify src/auth for security vulnerabilities"
"Check the payment module for edge cases"
"Review src/api for correctness and reliability issues"

Your AI assistant will automatically use Elenchus tools.

For structured workflows, see MCP Prompts.

MCP Tools Reference

Session Lifecycle

`elenchus_start_session`

Initialize a new verification session.

Inputs:

target (string, required): Target path to verify (file or directory)
requirements (string, required): Verification requirements/focus areas
workingDir (string, required): Working directory for relative paths
maxRounds (number, optional): Maximum rounds before stopping (default: 10)
verificationMode (object, optional): Mode configuration
- mode: "standard" | "fast-track" | "single-pass"
- skipCriticForCleanCode: boolean
differentialConfig (object, optional): Verify only changed files
cacheConfig (object, optional): Cache previous verifications
chunkingConfig (object, optional): Split large files into chunks
pipelineConfig (object, optional): Tiered verification
llmEvalConfig (object, optional): LLM-based evaluation settings
- enabled: boolean - Enable LLM evaluation
- convergenceEval: boolean - Use LLM for convergence quality
- severityEval: boolean - Use LLM for severity classification
- edgeCaseEval: boolean - Use LLM for edge case validation
- falsePositiveEval: boolean - Use LLM for false positive detection

Returns: Session ID and initial context including files collected, dependency graph stats, and role configuration.

Example:

elenchus_start_session({
  target: "src/auth",
  requirements: "Security audit for authentication",
  workingDir: "/path/to/project",
  verificationMode: { mode: "fast-track" }
})

`elenchus_get_context`

Get current session context including files, issues, and proactive guidance.

Inputs:

sessionId (string, required): The session ID

Returns: Files, issues summary, focus areas, unreviewed files, recommendations.

`elenchus_submit_round`

Submit a Verifier or Critic round.

Inputs:

sessionId (string, required): The session ID
role ("verifier" | "critic", required): Role for this round
output (string, required): Full agent analysis output
issuesRaised (Issue[], optional): New issues (Verifier role)
issuesResolved (string[], optional): Resolved issue IDs (Critic role)

Issue Schema:

{
  id: string,
  category: "SECURITY" | "CORRECTNESS" | "RELIABILITY" | "MAINTAINABILITY" | "PERFORMANCE",
  severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW",
  summary: string,
  location: string,        // "file:line" format
  description: string,
  evidence: string         // Code snippet or proof
}

Returns: Round number, convergence status, mediator interventions, role compliance score.

`elenchus_end_session`

End session with final verdict.

Inputs:

sessionId (string, required): The session ID
verdict ("PASS" | "FAIL" | "CONDITIONAL", required): Final verdict

Returns: Session summary including total rounds, issues by category and severity.

`elenchus_get_issues`

Query issues with optional filtering.

Inputs:

sessionId (string, required): The session ID
status ("all" | "unresolved" | "critical", optional): Filter by status

Returns: Array of issues matching the filter.

Additional Tools (31 more)

Beyond the core tools above, Elenchus provides 31 additional tools for advanced workflows:

Category	Tools
LLM Evaluation	`elenchus_evaluate_convergence`, `elenchus_evaluate_severity`, `elenchus_evaluate_edge_cases`, `elenchus_submit_llm_evaluation`
State Management	`elenchus_checkpoint`, `elenchus_rollback`, `elenchus_apply_fix`
Analysis	`elenchus_ripple_effect`, `elenchus_mediator_summary`
Role Enforcement	`elenchus_get_role_prompt`, `elenchus_role_summary`, `elenchus_update_role_config`
Re-verification	`elenchus_start_reverification`
Differential	`elenchus_save_baseline`, `elenchus_get_diff_summary`, `elenchus_get_project_history`
Cache	`elenchus_get_cache_stats`, `elenchus_clear_cache`
Pipeline	`elenchus_get_pipeline_status`, `elenchus_escalate_tier`, `elenchus_complete_tier`
Safeguards	`elenchus_get_safeguards_status`, `elenchus_update_confidence`, `elenchus_record_sampling_result`, `elenchus_check_convergence_allowed`
Optimization	`elenchus_set_compression_mode`, `elenchus_get_optimization_stats`, `elenchus_configure_optimization`, `elenchus_estimate_savings`
Dynamic Roles	`elenchus_generate_roles`, `elenchus_set_dynamic_roles`

All tools are auto-discovered by MCP clients. Use MCP Inspector (npm run inspector) for detailed schemas.

MCP Resources

Access session data via URI-based resources:

URI Pattern	Description
`elenchus://sessions/`	List all active sessions
`elenchus://sessions/{sessionId}`	Get specific session details

Usage:

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

MCP Prompts (Slash Commands)

Prompt Name	Description
`verify`	Run complete Verifier↔Critic loop
`consolidate`	Create prioritized fix plan
`apply`	Apply fixes with verification
`complete`	Full pipeline until zero issues
`cross-verify`	Adversarial cross-verification

Invocation format varies by client. Check your MCP client's documentation.

Verification Modes

Three modes for different use cases:

Mode	Min Rounds	Critic Required	Best For
`standard`	3	Yes	Thorough verification
`fast-track`	1	Optional	Quick validation
`single-pass`	1	No	Fastest, Verifier-only

Example:

elenchus_start_session({
  target: "src/",
  requirements: "Security audit",
  workingDir: "/project",
  verificationMode: {
    mode: "fast-track",
    skipCriticForCleanCode: true
  }
})

Issue Lifecycle

Issues transition through states:

RAISED → CHALLENGED → RESOLVED
           ↓
        DISMISSED (false positive)
           ↓
        MERGED (combined)
           ↓
        SPLIT (divided)

Issue States

Status	Description
`RAISED`	Initially discovered by Verifier
`CHALLENGED`	Under debate between Verifier and Critic
`RESOLVED`	Fixed and verified
`DISMISSED`	Invalidated as false positive
`MERGED`	Combined with another issue
`SPLIT`	Divided into multiple issues

Critic Verdicts

Verdict	Meaning
`VALID`	Issue is legitimate
`INVALID`	False positive
`PARTIAL`	Partially valid, needs refinement

Convergence Detection

A session converges when ALL criteria are met:

No CRITICAL or HIGH severity unresolved issues
Stable for 2+ rounds (no new issues)
Minimum rounds completed (varies by mode)
All 5 categories examined
No recent issue state transitions
Edge cases documented
Clean areas explicitly stated (negative assertions)
High-risk impacted files reviewed

Category Coverage

All 5 categories must be examined:

SECURITY - Authentication, authorization, injection
CORRECTNESS - Logic errors, type mismatches
RELIABILITY - Error handling, resource management
MAINTAINABILITY - Code structure, documentation
PERFORMANCE - Efficiency, resource usage

Token Optimization

Differential Analysis

Verify only changed files:

{
  differentialConfig: {
    enabled: true,
    baseRef: "main"  // Compare against main branch
  }
}

Response Caching

Cache previous verification results:

{
  cacheConfig: {
    enabled: true,
    ttlSeconds: 3600  // Cache for 1 hour
  }
}

Selective Chunking

Split large files into focused chunks:

{
  chunkingConfig: {
    enabled: true,
    maxChunkSize: 500  // Lines per chunk
  }
}

Tiered Pipeline

Start with quick analysis, escalate if needed:

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

Configuration

Environment Variables

Variable	Description	Default
`ELENCHUS_DATA_DIR`	Custom storage directory	`~/.elenchus`
`XDG_DATA_HOME`	XDG base directory (Linux/macOS)	-
`LOCALAPPDATA`	Windows AppData location	-

Storage Location

Sessions and data are stored in a client-agnostic location:

~/.elenchus/
├── sessions/          # Verification sessions
├── baselines/         # Differential analysis baselines
├── cache/             # Response cache
└── safeguards/        # Quality safeguards data

Priority Order:

$ELENCHUS_DATA_DIR - Explicit override
$XDG_DATA_HOME/elenchus - XDG spec
%LOCALAPPDATA%\elenchus - Windows
~/.elenchus - Default fallback

Custom Storage

# Set custom location
export ELENCHUS_DATA_DIR=/path/to/custom/storage

# Or use XDG spec
export XDG_DATA_HOME=~/.local/share

Session Cleanup

Sessions are preserved as audit records. Manual cleanup:

rm -rf ~/.elenchus/sessions/*
# Or for specific sessions
rm -rf ~/.elenchus/sessions/2026-01-17_*

Architecture

System Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                       ELENCHUS MCP SERVER                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                     MCP PROTOCOL LAYER                        │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐ │  │
│  │  │  Tools   │  │Resources │  │ Prompts  │  │ Notifications│ │  │
│  │  │  (36)    │  │  (URI)   │  │   (5)    │  │  (optional)  │ │  │
│  │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────────────┘ │  │
│  └───────┼─────────────┼─────────────┼──────────────────────────┘  │
│          │             │             │                              │
│  ┌───────┴─────────────┴─────────────┴──────────────────────────┐  │
│  │                       CORE MODULES                            │  │
│  │  Session Manager │ Context Manager │ Mediator System          │  │
│  │  Role Enforcement │ Issue Lifecycle │ Pipeline (Tiered)       │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              │                                       │
│                              ▼                                       │
│                    ┌──────────────────┐                             │
│                    │     STORAGE      │                             │
│                    │ ~/.elenchus/     │                             │
│                    └──────────────────┘                             │
└─────────────────────────────────────────────────────────────────────┘

Module Responsibilities

Module	Purpose
Session Manager	Create, persist, and manage verification sessions
Context Manager	Collect and organize target files and dependencies
Mediator System	Multi-language dependency graphs (tree-sitter), issue detection, interventions
Role Enforcement	Ensure Verifier↔Critic alternation, validate compliance
Issue Lifecycle	Track issue states from RAISED to RESOLVED
Pipeline	Tiered verification (screen → focused → exhaustive)

Security

Security Model

Elenchus operates with the following security considerations:

No Code Execution: Elenchus does NOT execute the code it verifies. It performs static analysis only.
Local Storage: All session data is stored locally in ~/.elenchus/. No data is sent to external servers.
Path Validation: All file paths are validated to prevent path traversal attacks.
No Secrets in Output: Tool outputs are sanitized to avoid exposing sensitive data.

Permissions

Elenchus requires:

Read access to target files for verification
Write access to ~/.elenchus/ for session storage

Reporting Security Issues

Please report security vulnerabilities via GitHub Security Advisories.

Troubleshooting

Common Issues

Server not found / Tools not available

Symptom: Your MCP client doesn't recognize Elenchus commands or tools.

Solutions:

Verify installation in your client's MCP settings
Restart your MCP client after adding the server
Check config syntax (JSON must be valid)
Ensure Node.js ≥18 is installed:
```
node --version
```

Session not found

Symptom: Error "Session not found: xxx"

Solutions:

List active sessions:
```
Read elenchus://sessions/
```
Sessions may have been cleaned up - start a new session
Verify session ID is correct (check for typos)

Permission denied errors

Symptom: Cannot read files or write sessions.

Solutions:

Check file permissions on target directory
Verify write access to ~/.elenchus/:
```
ls -la ~/.elenchus/
```
Try custom storage location:
```
export ELENCHUS_DATA_DIR=/tmp/elenchus
```

Role compliance rejection

Symptom: Round rejected due to compliance score.

Solutions:

Check current role requirements:

elenchus_get_role_prompt({ role: "verifier" })

Lower minimum compliance score:

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

Ensure role alternation (Verifier → Critic → Verifier)

Debugging

Use MCP Inspector for debugging:

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

Getting Help

Issues: GitHub Issues
Discussions: GitHub Discussions

Development

Build Commands

npm run build      # Compile TypeScript to dist/
npm run dev        # Watch mode with auto-rebuild
npm run start      # Run the compiled server
npm run inspector  # Launch MCP Inspector for debugging

Project Structure

elenchus-mcp/
├── src/
│   ├── index.ts           # Entry point, MCP server setup
│   ├── tools/             # Tool definitions and handlers
│   ├── resources/         # Resource definitions
│   ├── prompts/           # Prompt templates
│   ├── types/             # TypeScript interfaces
│   ├── state/             # Session and context management
│   ├── mediator/          # Multi-language dependency analysis (tree-sitter)
│   ├── roles/             # Role enforcement
│   ├── config/            # Configuration constants
│   ├── cache/             # Response caching
│   ├── chunking/          # Code chunking
│   ├── diff/              # Differential analysis
│   ├── pipeline/          # Tiered verification
│   └── safeguards/        # Quality safeguards
├── dist/                  # Compiled output
├── package.json
├── tsconfig.json
└── README.md

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Submit a pull request

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 71 Commits
docs		docs
src		src
tests		tests
.gitignore		.gitignore
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.ko.md		README.ko.md
README.md		README.md
ZOD_UNIFICATION_PLAN.md		ZOD_UNIFICATION_PLAN.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.integration.config.ts		vitest.integration.config.ts

Folders and files

Latest commit

History

Repository files navigation

Elenchus MCP Server

Table of Contents

Overview

Why Adversarial Verification?

The Verifier↔Critic Loop

Key Features

🔄 Adversarial Debate System

📊 Intent-Based Convergence

🧠 LLM-Based Evaluation (Optional)

🔍 Automatic Impact Analysis

🌐 Multi-Language Support

💾 Session Management

⚡ Token Optimization (Optional)

Quick Start

Installation

Supported Clients

Claude Desktop

Claude Code

VS Code (GitHub Copilot)

Cursor

Usage

MCP Tools Reference

Session Lifecycle

elenchus_start_session

elenchus_get_context

elenchus_submit_round

elenchus_end_session

elenchus_get_issues

Additional Tools (31 more)

MCP Resources

MCP Prompts (Slash Commands)

Verification Modes

Issue States

Critic Verdicts

Category Coverage

Token Optimization

Configuration

Environment Variables

Storage Location

Custom Storage

Session Cleanup

Architecture

Module Responsibilities

Security

Security Model

Permissions

Reporting Security Issues

Troubleshooting

Common Issues

Debugging

Getting Help

Development

Build Commands

Project Structure

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`elenchus_start_session`

`elenchus_get_context`

`elenchus_submit_round`

`elenchus_end_session`

`elenchus_get_issues`

Packages