Elenchus MCP

🚀 Elenchus MCP 服务器

Elenchus MCP 服务器是一个实现对抗性代码验证的模型上下文协议（MCP）服务器。它通过验证器与批评者的辩论循环，系统地揭示代码中的问题，为代码质量保驾护航。

🚀 快速开始

将以下内容添加到你的 MCP 客户端配置中：

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

然后就可以自然地与你的 AI 助手配合使用，例如：

"请验证 src/auth 是否存在安全问题"

有关特定客户端的设置说明，请参阅 安装指南。

✨ 主要特性

🔄 对抗性辩论系统

• 验证器：找出有证据支持的问题。
• 批评者：挑战发现的问题，验证主张。
• 角色强制：严格交替角色，并进行合规性评分。

📊 基于意图的收敛

• 语义理解而非关键字匹配。
• 覆盖 5 个类别（安全性、正确性、可靠性、可维护性、性能）。
• 边缘情况文档要求。
• 对干净代码进行否定断言。

🧠 基于大语言模型的评估（可选）

• 收敛评估：大语言模型判断验证质量（而非严格的布尔检查）。
• 严重性分类：上下文感知的影响分析。
• 边缘情况验证：验证实际分析，而非仅检查关键字存在性。
• 误报检测：基于证据的问题验证。

🔍 自动影响分析

• 多语言依赖图（通过 tree-sitter 支持 15 种语言）。
• 涟漪效应预测。
• 级联深度计算。
• 风险级别评估。

🌐 多语言支持

依赖分析由 tree-sitter AST 解析提供支持：

💾 会话管理

• 支持检查点/回滚。
• 全局会话存储。
• 保留审计跟踪。

⚡ 令牌优化（可选）

• 差异分析（仅验证更改的代码）。
• 响应缓存。
• 选择性分块。
• 分层验证管道。

📦 安装指南

支持的客户端

Claude Desktop

将以下内容添加到你的 Claude Desktop 配置文件中：

• 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

将以下内容添加到你的 Claude Code 设置（.mcp.json 或 ~/.claude/settings.json）中：

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

VS Code (GitHub Copilot)

将以下内容添加到 .vscode/mcp.json 中：

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

Cursor

转到 设置 > MCP > 添加新的全局 MCP 服务器，并输入：

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

💻 使用示例

只需描述你想要验证的内容：

"验证 src/auth 是否存在安全漏洞"
"检查支付模块是否存在边缘情况"
"审查 src/api 是否存在正确性和可靠性问题"

你的 AI 助手将自动使用 Elenchus 工具。

有关结构化工作流，请参阅 MCP 提示。

📚 详细文档

MCP 工具参考

会话生命周期

• elenchus_start_session：初始化一个新的验证会话。

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

• elenchus_get_context：获取当前会话上下文，包括文件、问题和主动指导。
• elenchus_submit_round：提交验证器或批评者回合。
• elenchus_end_session：以最终裁决结束会话。
• elenchus_get_issues：查询问题，并可选择进行过滤。

其他工具（31 个）

Elenchus 还提供 31 个额外的工具，用于高级工作流。

MCP 资源

通过基于 URI 的资源访问会话数据：

MCP 提示（斜杠命令）

验证模式

问题生命周期

问题会经历以下状态转换：

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

收敛检测

会话在满足所有条件时收敛：

• 没有严重或高严重性的未解决问题。
• 连续 2 轮以上稳定（无新问题）。
• 完成最小回合数（因模式而异）。
• 检查了所有 5 个类别。
• 最近没有问题状态转换。
• 记录了边缘情况。
• 明确指出了干净区域（否定断言）。
• 审查了高风险影响的文件。

令牌优化

差异分析

仅验证更改的文件：

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

响应缓存

缓存先前的验证结果：

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

选择性分块

将大文件拆分为聚焦的块：

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

分层管道

从快速分析开始，必要时升级：

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

配置

环境变量

存储位置

会话和数据存储在与客户端无关的位置：

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

自定义存储

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

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

会话清理

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

架构

系统图

┌─────────────────────────────────────────────────────────────────────┐
│                       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/     │                             │
│                    └──────────────────┘                             │
└─────────────────────────────────────────────────────────────────────┘

模块职责

🔧 技术细节

安全模型

• 无代码执行：Elenchus 不会执行它验证的代码，仅执行静态分析。
• 本地存储：所有会话数据存储在本地 ~/.elenchus/ 中，不会将数据发送到外部服务器。
• 路径验证：验证所有文件路径，防止路径遍历攻击。
• 输出无秘密信息：清理工具输出，避免暴露敏感数据。

权限

Elenchus 需要：

• 读取权限：对目标文件进行验证。
• 写入权限：对 ~/.elenchus/ 进行会话存储。

报告安全问题

请通过 GitHub 安全建议 报告安全漏洞。

🛠️ 故障排除

常见问题

服务器未找到/工具不可用

症状：你的 MCP 客户端无法识别 Elenchus 命令或工具。 解决方案：

1. 验证客户端的 MCP 设置中的安装情况。
2. 添加服务器后重启 MCP 客户端。
3. 检查配置语法（JSON 必须有效）。
4. 确保安装了 Node.js ≥18：

node --version

会话未找到

症状：出现错误 "Session not found: xxx"。 解决方案：

1. 列出活动会话：

Read elenchus://sessions/

2. 会话可能已被清理 - 启动新会话。
3. 验证会话 ID 是否正确（检查拼写错误）。

权限被拒绝错误

症状：无法读取文件或写入会话。 解决方案：

1. 检查目标目录的文件权限。
2. 验证对 ~/.elenchus/ 的写入权限：

ls -la ~/.elenchus/

3. 尝试使用自定义存储位置：

export ELENCHUS_DATA_DIR=/tmp/elenchus

角色合规性拒绝

症状：回合因合规性评分被拒绝。 解决方案：

1. 检查当前角色要求：

elenchus_get_role_prompt({ role: "verifier" })

2. 降低最低合规性评分：

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

3. 确保角色交替（验证器 → 批评者 → 验证器）。

调试

使用 MCP 检查器进行调试：

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

获取帮助

• 问题：GitHub 问题
• 讨论：GitHub 讨论

🛠️ 开发

构建命令

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

项目结构

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

贡献

欢迎贡献代码！请按以下步骤操作：

1. 分叉仓库。
2. 创建功能分支。
3. 提交拉取请求。

📄 许可证

本项目采用 MIT 许可证。