RealityCheck

RealityCheck 是一個 MCP (Model Context Protocol) Server，專門設計用來驗證由 AI 生成的程式碼庫。它作為一個確定性的「地面實況 (Ground Truth)」檢查器，能夠檢測出機率性 LLM 可能忽略的幻覺（如虛假依賴、不存在的 API）、邏輯斷層以及實作完整性。

功能特性

RealityCheck 採用插件化架構，目前提供 12 個檢測插件，全面捕獲 AI 生成程式碼的幻覺與不完整實作。

🔍 幻覺檢測 (Hallucination Detection)

• 虛假套件 (Fake Packages)：檢測是否引入了未在 package.json 中列出的套件。
• 虛假 API (Fake APIs)：驗證引入的變數或函式是否真實存在於目標函式庫中（透過 TypeScript AST 分析）。
• 佔位代碼 (Placeholders)：識別被遺留的 TODO、FIXME 或僅作為樁 (stub) 的實作。

🏗️ 流程與完整性 (Flow & Completeness)

• 流程分析 (Flow Analysis)：建立呼叫圖 (Call Graph)，自動識別沒被使用的孤兒程式碼 (Orphan Code) 與未定義的參考 (Logic Gaps)。
• 完整性檢查 (Completeness Check)：自動讀取專案文件 (如 PRD.md, README.md) 的標題，並比對程式碼中是否包含對應的關鍵字與實作，確保功能不遺漏。

🛡️ 程式碼品質檢測 (Quality Checks)

• 空實作檢測 (Empty Implementation)：檢測函式本體為空或只回傳假值（null, undefined, {}, []）。
• 錯誤處理檢測 (Error Handling)：檢測 async 函式缺少 try-catch 錯誤處理。
• 邊界檢查 (Boundary Check)：檢測陣列/物件存取缺少 null/length 檢查。
• 未使用匯入 (Unused Imports)：檢測引入但從未使用的依賴（named、default、namespace imports）。
• 過時 API (Deprecated API)：檢測使用已過時的 API（包含 Node.js、React、TypeScript 等 20+ 種已知過時 API）。
• 型別不匹配 (Type Mismatch)：檢測函式宣告與實際使用的型別不一致（參數、回傳值、賦值）。
• 循環依賴 (Circular Dependency)：檢測模組間的循環引用。

🔐 安全檢測 (Security Checks)

• 安全風險檢測 (Security Check)：檢測常見安全風險，包含硬編碼機密（API keys、密碼、AWS credentials）、不安全加密（MD5、SHA1）、SQL 注入風險、eval 使用、路徑遍歷攻擊等。
• Gitignore 檢查 (Gitignore Check)：驗證 Git 專案的 .gitignore 配置，檢測缺少的建議模式（如 node_modules/、.env），並警告可能被追蹤的敏感檔案。

✨ 最新改進 (v1.0.0+)

程式碼品質提升: 從 8.5/10 提升至 9.0+/10

• ✅ CRITICAL 安全漏洞全部修復：
  • Path Traversal 攻擊防護（專案根目錄邊界驗證）
  • ReDoS 拒絕服務防護（限制 regex 回溯）
  • Regex Injection 防護（輸入清理與逸出）
• ✅ 效能優化：
  • UnusedImportPlugin 改用 Symbol tracking（30-50% 更快）
  • DeprecatedAPIPlugin 改用 AST 分析（消除 false positives）
• ✅ 錯誤處理改善：詳細的錯誤記錄取代靜默失敗
• ✅ 完整測試覆蓋：17 tests passing，包含安全插件的完整單元測試

---

安裝與使用

1. 作為 CLI 工具使用 (推薦)

您可以直接在終端機中使用 RealityCheck 來掃描專案：

# 1. Clone 專案
git clone https://github.com/kevintseng/realitycheck-mcp.git
cd realitycheck-mcp

# 2. 安裝與建置
npm install
npm run build

# 3. 連結到全域 (可選)
npm link

# 4. 執行驗證 (若已連結)
realitycheck validate . --depth deep

# 或者直接執行編譯後的檔案
node dist/cli.js validate /path/to/project --depth deep

CLI 命令：

• realitycheck validate <path> [options]: 執行完整驗證。
  • --depth <quick|standard|deep>: 驗證深度 (預設: standard)。
  • --format <json|toon|markdown>: 輸出格式 (預設: markdown)。
  • --json: --format json 的捷徑。
  • --toon: --format toon 的捷徑。
• realitycheck check <path>: 僅執行幻覺檢測。

2. 搭配 Claude Code (MCP)

方法一：使用 npm link（推薦）

# 1. Clone 並建置專案
git clone https://github.com/kevintseng/realitycheck-mcp.git
cd realitycheck-mcp
npm install
npm run build

# 2. 連結到全域
npm link

# 3. 驗證安裝
which realitycheck-mcp
# 應該顯示: /Users/<your-username>/.nvm/versions/node/<version>/bin/realitycheck-mcp

方法二：直接使用絕對路徑

若您使用 Claude Desktop，請將以下設定加入 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "realitycheck": {
      "command": "node",
      "args": ["/absolute/path/to/realitycheck-mcp/dist/index.js"]
    }
  }
}

注意: 若使用 npm link，MCP Server 會自動使用全域連結的版本，無需額外配置。

驗證深度 (Depth)

• quick: 僅檢查語法與明顯幻覺。
• standard (預設): 包含幻覺檢測與基本完整性檢查。
• deep: 執行完整的 Call Graph 分析與詳細比對 (最耗時但最精確)。

輸出格式 (Output Formats)

• Markdown (預設): 易於閱讀，適合人類檢查或作為 PR 評論。
• JSON (--json): 結構化數據，適合 CI/CD 流程 (如 GitHub Actions) 自動解析。
• TOON (--toon): TOON 格式，高密度的結構化文本，專為減少 LLM Token 使用量而設計。若您需要將報告貼回 LLM 進行修復，使用此格式可節省大量 Token。

---

可用工具 (MCP Tools)

realitycheck_check

掃描目錄或檔案以檢測 AI 幻覺。

• 參數: path (string), types (string[])

realitycheck_validate

對整個專案執行完整的驗證套件，包含幻覺、流程與完整性檢查。

• 參數: path (string), depth ("quick" | "standard" | "deep")

---

---

🪄 技能

• Skills (Prompts): Use MCP Prompts like realitycheck_code_review for guided workflows.
• Smart Alias Resolution: Correctly resolves @/, ~/ paths using tsconfig.json.
• Interactive Fix Mode: Use --fix to address issues directly from the CLI.

🔗 Integrations

GitHub Action

You can integrate RealityCheck into your PR flow using the following workflow: View Example Workflow

VS Code Task

Add this to your .vscode/tasks.json for quick validation:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "RealityCheck: Validate",
      "type": "shell",
      "command": "npx realitycheck validate . --depth standard",
      "problemMatcher": [],
      "group": { "kind": "test", "isDefault": true }
    }
  ]
}

RealityCheck 提供了一些預定義的 Prompts 輔助 LLM 進行標準化流程：

• validate_daily: 日常快速檢查。執行 quick 深度驗證，確保沒有明顯的幻覺或語法錯誤。
• validate_release: 發布前審計。執行 deep 深度加上 strictMode 驗證，找出所有潛在的死代碼與邏輯斷層。
• code_review: 代碼審查標準流程。要求先執行 standard 驗證，確保無客觀錯誤後再進行語意審查。

開發指南

# 監聽模式 (Watch mode)
npm run watch

# 執行測試
npm test

架構說明

🧩 插件化架構

RealityCheck 採用完全插件化的架構設計，每個檢測類型都是獨立的插件：

核心元件：

• PluginInterface: 定義所有插件必須遵循的契約
• PluginRegistry: 管理插件生命週期，支援延遲載入（Lazy Loading）
• Validator: 協調插件執行，根據深度過濾插件

插件優先序與深度：

Priority 100: Hallucination (quick/standard/deep)
Priority  90: Flow (standard/deep)
Priority  80: Completeness (standard/deep)
Priority  60: ErrorHandling (standard/deep)
Priority  55: DeprecatedAPI (standard/deep)
Priority  50: EmptyImplementation (standard/deep)
Priority  45: UnusedImport (standard/deep)
Priority  40: BoundaryCheck (deep only)
Priority  35: TypeMismatch (deep only)
Priority  30: CircularDependency (deep only)

技術實作：

• 使用 ts-morph 進行 AST (抽象語法樹) 分析
• 100% 確定性的驗證結果，避免「用 AI 檢查 AI」的循環
• Factory Pattern 實現延遲實例化
• Adapter Pattern 保持向後相容

驗證層次：

1. 靜態依賴層 (Hallucination Detection)
2. 調用圖層 (Flow Analysis)
3. 語意規格層 (Completeness Check)
4. 程式碼品質層 (Quality Checks) - NEW

授權

ISC