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.

---

Table of Contents

• Overview
• Key Features
• Quick Start
• Installation
• Usage
• MCP Tools Reference
• MCP Resources
• MCP Prompts
• Verification Modes
• Automatic Verification
• Issue Lifecycle
• Convergence Detection
• Token Optimization
• Configuration
• Architecture
• Security
• Troubleshooting
• Development
• License

---

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

🔍 Automatic Impact Analysis

• Dependency graph construction
• Ripple effect prediction
• Cascade depth calculation
• Risk level assessment

💾 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
VS Code (Copilot)	✅ Supported	Requires v1.102+
Cursor	✅ Supported	40 tool limit applies
Other MCP Clients	✅ Compatible	Any stdio-based client

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

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.

State Management

elenchus_checkpoint

Create a checkpoint for potential rollback.

Inputs:

• sessionId (string, required): The session ID

Returns: Success status and round number.

elenchus_rollback

Rollback to a previous checkpoint.

Inputs:

• sessionId (string, required): The session ID
• toRound (number, required): Round number to rollback to

Returns: Success status and restored round number.

Analysis Tools

elenchus_ripple_effect

Analyze impact of changing a file.

Inputs:

• sessionId (string, required): The session ID
• changedFile (string, required): File that will be changed
• changedFunction (string, optional): Specific function within the file

Returns: Affected files, dependency paths, cascade depth, and recommendations.

Example:

elenchus_ripple_effect({
  sessionId: "...",
  changedFile: "src/auth/login.ts",
  changedFunction: "validateToken"
})
// Returns: { affectedFiles: [...], cascadeDepth: 2, totalAffected: 8 }

elenchus_mediator_summary

Get mediator analysis summary.

Inputs:

• sessionId (string, required): The session ID

Returns: Dependency graph stats, coverage metrics, intervention history.

Role Enforcement

elenchus_get_role_prompt

Get role-specific guidelines.

Inputs:

• role ("verifier" | "critic", required): Role to get prompt for

Returns: System prompt, output template, checklist, mustDo/mustNotDo rules, focus areas.

elenchus_role_summary

Get role compliance summary for a session.

Inputs:

• sessionId (string, required): The session ID

Returns: Compliance history, average scores, violations, current expected role.

elenchus_update_role_config

Update role enforcement settings.

Inputs:

• sessionId (string, required): The session ID
• strictMode (boolean, optional): Reject non-compliant rounds
• minComplianceScore (number, optional): Minimum score (0-100)
• requireAlternation (boolean, optional): Require role alternation

Returns: Updated configuration.

Re-verification

elenchus_start_reverification

Start re-verification of resolved issues from a previous session.

Inputs:

• previousSessionId (string, required): Original session ID
• workingDir (string, required): Working directory
• targetIssueIds (string[], optional): Specific issues to re-verify
• maxRounds (number, optional): Maximum rounds (default: 6)

Returns: New session ID with focused context on target issues.

---

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
auto-verify	Automatic verification using MCP Sampling

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
  }
})

---

Automatic Verification (MCP Sampling)

Elenchus supports fully automatic verification using MCP Sampling capability. The server autonomously orchestrates the Verifier↔Critic debate loop without manual intervention.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                   AUTOMATIC VERIFICATION                     │
├─────────────────────────────────────────────────────────────┤
│  1. Client calls elenchus_auto_verify                       │
│  2. Server creates session and context                      │
│  3. Server requests Verifier completion via MCP Sampling    │
│  4. Server parses response, extracts issues                 │
│  5. Server requests Critic completion via MCP Sampling      │
│  6. Server parses response, updates issue statuses          │
│  7. Repeat until convergence or max rounds                  │
│  8. Return final result with all issues and fix plan        │
└─────────────────────────────────────────────────────────────┘

Client Requirements

Capability	Required	Notes
MCP Sampling	Yes	Server-initiated LLM requests
createMessage	Yes	Part of Sampling capability

Client Support:

• MCP Sampling capability required
• Check your client's documentation for support

Tool: elenchus_auto_verify

Inputs:

• target (string, required): Target path to verify
• requirements (string, required): Verification requirements
• workingDir (string, required): Working directory
• config (object, optional):
  • maxRounds: Maximum rounds (default: 10)
  • maxTokens: Max tokens per request (default: 4000)
  • stopOnCritical: Stop on CRITICAL issue (default: false)
  • minRounds: Min rounds before convergence (default: 2)
  • enableProgress: Stream progress updates (default: true)
  • modelHint: "fast" | "balanced" | "thorough"
  • includePreAnalysis: Include static analysis (default: true)
  • autoConsolidate: Generate fix plan (default: true)

Returns: Session ID, final status, all issues, and optional consolidated fix plan.

Example:

elenchus_auto_verify({
  target: "src/auth",
  requirements: "Security audit for authentication module",
  workingDir: "/path/to/project",
  config: {
    maxRounds: 10,
    modelHint: "thorough",
    autoConsolidate: true
  }
})

Tool: elenchus_get_auto_loop_status

Inputs:

• sessionId (string, required): Session ID to query

Returns: Current round, status, issues found so far, convergence info.

Comparison: Manual vs Automatic

Aspect	Manual (elenchus_submit_round)	Automatic (elenchus_auto_verify)
Control	Full control over each round	Server-controlled
Intervention	Can modify between rounds	No intervention
Client Work	Parse prompts, call LLM, format response	Single tool call
Best For	Custom workflows, debugging	Standard verification

---

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:

1. SECURITY - Authentication, authorization, injection
2. CORRECTNESS - Logic errors, type mismatches
3. RELIABILITY - Error handling, resource management
4. MAINTAINABILITY - Code structure, documentation
5. PERFORMANCE - Efficiency, resource usage

<details> <summary><strong>Edge Case Categories</strong></summary>

Based on OWASP Testing Guide, Netflix Chaos Engineering, Google DiRT:

#	Category	Example Checks
1	Code-level	Null inputs, boundary values
2	User Behavior	Double-clicks, concurrent sessions
3	External Dependencies	Service failures, timeouts
4	Business Logic	Permission changes, state conflicts
5	Data State	Legacy data, corruption
6	Environment	Config drift, resource limits
7	Scale	Traffic spikes, massive data
8	Security	Validation bypass, session attacks
9	Side Effects	Mid-operation changes, partial failures

</details>

---

Token Optimization

<details> <summary><strong>Differential Analysis</strong></summary>

Verify only changed files:

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

</details>

<details> <summary><strong>Response Caching</strong></summary>

Cache previous verification results:

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

</details>

<details> <summary><strong>Selective Chunking</strong></summary>

Split large files into focused chunks:

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

</details>

<details> <summary><strong>Tiered Pipeline</strong></summary>

Start with quick analysis, escalate if needed:

{
  pipelineConfig: {
    enabled: true,
    startTier: "quick"  // quick → standard → deep
  }
}

</details>

---

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:

1. $ELENCHUS_DATA_DIR - Explicit override
2. $XDG_DATA_HOME/elenchus - XDG spec
3. %LOCALAPPDATA%\elenchus - Windows
4. ~/.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

<details> <summary><strong>System Diagram</strong></summary>

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

</details>

Module Responsibilities

Module	Purpose
Session Manager	Create, persist, and manage verification sessions
Context Manager	Collect and organize target files and dependencies
Mediator System	Build dependency graphs, detect issues, trigger interventions
Role Enforcement	Ensure Verifier↔Critic alternation, validate compliance
Issue Lifecycle	Track issue states from RAISED to RESOLVED
Pipeline	Tiered verification (quick → standard → deep)

---

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

<details> <summary><strong>Server not found / Tools not available</strong></summary>

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

Solutions:

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

   node --version
   

</details>

<details> <summary><strong>Session not found</strong></summary>

Symptom: Error "Session not found: xxx"

Solutions:

1. List active sessions:

   Read elenchus://sessions/
   

2. Sessions may have been cleaned up - start a new session
3. Verify session ID is correct (check for typos)

</details>

<details> <summary><strong>MCP Sampling not supported</strong></summary>

Symptom: elenchus_auto_verify fails with sampling error.

Solutions:

1. Check if your MCP client supports MCP Sampling capability
2. Use manual verification instead:

   elenchus_start_session(...)
   elenchus_submit_round(...)
   

</details>

<details> <summary><strong>Permission denied errors</strong></summary>

Symptom: Cannot read files or write sessions.

Solutions:

1. Check file permissions on target directory
2. Verify write access to ~/.elenchus/:

   ls -la ~/.elenchus/
   

3. Try custom storage location:

   export ELENCHUS_DATA_DIR=/tmp/elenchus
   

</details>

<details> <summary><strong>Role compliance rejection</strong></summary>

Symptom: Round rejected due to compliance score.

Solutions:

1. Check current role requirements:

   elenchus_get_role_prompt({ role: "verifier" })
   

2. Lower minimum compliance score:

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

3. Ensure role alternation (Verifier → Critic → Verifier)

</details>

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/          # Dependency analysis
│   ├── 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:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

---

License

MIT