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

• 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?

The Verifier↔Critic Loop

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:

💾 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:

Then use naturally with your AI assistant:

See Installation for client-specific setup instructions.

Installation

Supported Clients

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

Claude Code

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

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

Cursor

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

Usage

Simply describe what you want to verify:

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_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:

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:

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:

Usage:

MCP Prompts (Slash Commands)

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

Verification Modes

Three modes for different use cases:

Example:

Issues transition through states:

Issue States

Critic Verdicts

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

Token Optimization

Verify only changed files:

Cache previous verification results:

Split large files into focused chunks:

Start with quick analysis, escalate if needed:

Configuration

Environment Variables

Storage Location

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

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

Session Cleanup

Sessions are preserved as audit records. Manual cleanup:

Architecture

Module Responsibilities

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

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

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)

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

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)

Debugging

Use MCP Inspector for debugging:

Getting Help

• Issues: GitHub Issues

• Discussions: GitHub Discussions

Development

Build Commands

Project Structure

Contributing

Contributions welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Submit a pull request

License

MIT