Elenchus MCP

🚀 Elenchus MCP Server

An Adversarial Code Verification System using Verifier↔Critic Debate Loop

English | 한국어

🚀 Quick Start

Add the following to your MCP client configuration:

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

Then, use it naturally with your AI assistant:

"Please verify src/auth for security issues"

See Installation for client-specific setup instructions.

✨ Features

🔄 Adversarial Debate System

• Verifier: Finds issues with evidence.
• Critic: Challenges findings and 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.

📦 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

{
  "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 Examples

Basic 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.

📚 Documentation

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:

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:

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

MCP Prompts (Slash Commands)

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

Verification Modes

Three modes for different use cases:

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

Critic Verdicts

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.

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

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

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

🔧 Technical Details

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:

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
   

Session not found

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

Permission denied errors

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
   

Role compliance rejection

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:

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:

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

📄 License

MIT