shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

elenchus-mcp

基于验证者与批评者辩论循环的对抗性代码验证系统，通过多轮辩证分析发现代码问题

article

README

🚀 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 解析提供支持： | 类别 | 语言 | |----------|--------------------------------------------------------------| | 网页 | TypeScript、TSX、JavaScript、CSS | | 系统 | Rust、Go、C、C++ | | 企业 | Java、C# | | 脚本 | Python、Ruby、PHP、Bash、PowerShell |

💾 会话管理

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

⚡ 令牌优化（可选）

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

📦 安装指南

支持的客户端

| 客户端 | 状态 | 说明 | |------------------|----------|--------------------------------------------------------------| | Claude Desktop | ✅ 支持 | macOS、Windows | | Claude Code | ✅ 支持 | CLI 工具 | | VS Code (Copilot)| ✅ 支持 | 需要 v1.102+ | | Cursor | ✅ 支持 | 适用 40 个工具限制 | | 其他 MCP 客户端 | ✅ 兼容 | 任何基于标准输入输出的客户端 |

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 的资源访问会话数据： | URI 模式 | 描述 | |----------------------------|--------------------------------------------------------------| | elenchus://sessions/ | 列出所有活动会话 | | elenchus://sessions/{sessionId} | 获取特定会话的详细信息 |

MCP 提示（斜杠命令）

| 提示名称 | 描述 | |--------------|--------------------------------------------------------------| | verify | 运行完整的验证器↔批评者循环 | | consolidate| 创建优先修复计划 | | apply | 应用修复并进行验证 | | complete | 执行完整管道，直到没有问题为止 | | cross-verify| 进行对抗性交叉验证 |

验证模式

| 模式 | 最小回合数 | 批评者是否必需 | 适用场景 | |--------------|------------|----------------|------------------------------------------| | standard | 3 | 是 | 彻底的验证 | | fast-track | 1 | 可选 | 快速验证 | | single-pass| 1 | 否 | 最快，仅使用验证器 |

问题生命周期

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

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_DATA_DIR | 自定义存储目录 | ~/.elenchus | | XDG_DATA_HOME | XDG 基础目录（Linux/macOS） | - | | LOCALAPPDATA | Windows AppData 位置 | - |

存储位置

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

~/.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/     │                             │
│                    └──────────────────┘                             │
└─────────────────────────────────────────────────────────────────────┘

模块职责

| 模块 | 目的 | |------------------|--------------------------------------------------------------| | 会话管理器 | 创建、持久化和管理验证会话 | | 上下文管理器 | 收集和组织目标文件和依赖项 | | 中介系统 | 多语言依赖图（tree-sitter）、问题检测、干预 | | 角色强制 | 确保验证器↔批评者交替，验证合规性 | | 问题生命周期 | 跟踪问题从提出到解决的状态 | | 管道 | 分层验证（筛选 → 聚焦 → 详尽） |

🔧 技术细节

安全模型

  • 无代码执行：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/
  1. 会话可能已被清理 - 启动新会话。
  2. 验证会话 ID 是否正确（检查拼写错误）。

权限被拒绝错误

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

  1. 检查目标目录的文件权限。
  2. 验证对 ~/.elenchus/ 的写入权限：
ls -la ~/.elenchus/
  1. 尝试使用自定义存储位置：
export ELENCHUS_DATA_DIR=/tmp/elenchus

角色合规性拒绝

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

  1. 检查当前角色要求：
elenchus_get_role_prompt({ role: "verifier" })
  1. 降低最低合规性评分：
elenchus_update_role_config({
  sessionId: "...",
  minComplianceScore: 50,
  strictMode: false
})
  1. 确保角色交替（验证器 → 批评者 → 验证器）。

调试

使用 MCP 检查器进行调试：

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

获取帮助

🛠️ 开发

构建命令

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 许可证。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端