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 許可證。