# Elenchus MCP Server
**English** | [한국어](./README.ko.md)
**Adversarial Code Verification System using Verifier↔Critic Debate Loop**
> **Elenchus** (ἔλεγχος): Socrates' method of refutation through systematic questioning - exposing contradictions to reach truth.
[](https://www.npmjs.com/package/@jhlee0409/elenchus-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
---
## Table of Contents
- [Overview](#overview)
- [Key Features](#key-features)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Usage](#usage)
- [MCP Tools Reference](#mcp-tools-reference)
- [MCP Resources](#mcp-resources)
- [MCP Prompts](#mcp-prompts-slash-commands)
- [Verification Modes](#verification-modes)
- [Automatic Verification](#automatic-verification-mcp-sampling)
- [Issue Lifecycle](#issue-lifecycle)
- [Convergence Detection](#convergence-detection)
- [Token Optimization](#token-optimization)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Security](#security)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [License](#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:
```json
{
"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](#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`:
```json
{
"mcp": {
"servers": {
"elenchus": {
"command": "npx",
"args": ["-y", "@jhlee0409/elenchus-mcp"]
}
}
}
}
```
### Cursor
Go to **Settings > MCP > Add new global MCP Server**:
```json
{
"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-prompts-slash-commands).
---
## 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:**
```typescript
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:**
```typescript
{
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:**
```typescript
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:**
```typescript
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:**
```typescript
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:
```typescript
{
differentialConfig: {
enabled: true,
baseRef: "main" // Compare against main branch
}
}
```
</details>
<details>
<summary><strong>Response Caching</strong></summary>
Cache previous verification results:
```typescript
{
cacheConfig: {
enabled: true,
ttlSeconds: 3600 // Cache for 1 hour
}
}
```
</details>
<details>
<summary><strong>Selective Chunking</strong></summary>
Split large files into focused chunks:
```typescript
{
chunkingConfig: {
enabled: true,
maxChunkSize: 500 // Lines per chunk
}
}
```
</details>
<details>
<summary><strong>Tiered Pipeline</strong></summary>
Start with quick analysis, escalate if needed:
```typescript
{
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
```bash
# 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:
```bash
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](https://github.com/jhlee0409/elenchus-mcp/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:
```bash
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:
```typescript
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/`:
```bash
ls -la ~/.elenchus/
```
3. Try custom storage location:
```bash
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:
```typescript
elenchus_get_role_prompt({ role: "verifier" })
```
2. Lower minimum compliance score:
```typescript
elenchus_update_role_config({
sessionId: "...",
minComplianceScore: 50,
strictMode: false
})
```
3. Ensure role alternation (Verifier → Critic → Verifier)
</details>
### Debugging
Use MCP Inspector for debugging:
```bash
npm run inspector
# or
npx @modelcontextprotocol/inspector node dist/index.js
```
### Getting Help
- **Issues**: [GitHub Issues](https://github.com/jhlee0409/elenchus-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/jhlee0409/elenchus-mcp/discussions)
---
## Development
### Build Commands
```bash
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
