CodeTruth MCP
基于证据的代码审计MCP服务器
“没有证据就没有索赔”-每一项发现都有可验证的证据支持
CodeTruth MCP是一个全面的模型上下文协议（MCP）服务器，可以执行详尽的、基于证据的代码审计。它系统地发现代码库中的所有错误，并为每个发现提供无可辩驳的证据。
核心理念
传统的代码审查侧重于现有内容的正确性。CodeTruth专注于 完备性验证:
- 该功能是否存在端到端？
- 从入口点可以到达吗？
- 它真的会做一些可观察到的事情吗？
- 我们能用测试/日志/跟踪来证明吗？
只有在以下情况下，功能才是“完整的”：
- 可以从UI/入口点访问
- 它具有可观察到的副作用
- 它具有测试（或可重复的验证步骤）
- 它通过CI门
- 它没有关键的绒毛/类型/安全屏障
其他所有内容都是“已实施但未经证实”或“已终止/未终止”。
30个里程碑特征
基础设施（1-4）
- 核心MCP服务器 -STDIO/SSE传输、工具路由、策略执行
- 证据库 -SQLite+SARIF存储，用于所有审计结果和证据
- 多语言AST解析 -树保姆支持160多种语言
- 可达性分析 -调用图生成和死路径检测
静态分析（5-12）
- 死码检测 -无法访问的函数、未使用的导出、孤立组件
- UI接线审核 -死按钮、未绑定处理程序、缺少路由
- API合同确认 -OpenAPI/JSON模式/Zod合规性
- 秘密扫描 -用于凭证检测的gitleaks/trufflehog集成
- 依赖漏洞扫描 -npm审计、pip审计、trivy、OSV
- 多语言Linting -eslint，ruff，更漂亮，剪辑配器
- 类型检查 -tsc、mypy、版权验证
- SAST集成 -semgrep、CodeQL安全扫描
运行时验证（13-16）
- 剧作家E2E测试 -带有跟踪捕获的自动UI流验证
- 视觉回归测试 -截图比较和语义差异
- 代码覆盖率分析 -伊斯坦布尔/纽约，coverage.py集成
- 跟踪ID关联 -从UI到DB的请求跟踪
人工智能与存储（17-18）
- Mem0 AI内存 -跨会话的持久审计上下文
- Supabase本地存储 -自托管审计数据持久化
执行环境（19-21）
- Docker沙盒 -隔离、可重复的分析环境
- 优质门梯 -7层验证系统（0-6号门）
- 多代理编排 -具有交叉检查功能的专业审计代理
报告和跟踪（22-24）
- 固定计划生成器 -验收测试驱动的补救计划
- 特征真值表 -每个特征曲面的状态跟踪
- 功能注册表 -规范源到实现映射
语言专业（25-27）
- HTML/Web审计 -可访问性、SEO、性能分析
- React/TypeScript审计 -挂钩规则、组件生命周期、类型安全
- Python审计 -导入分析、异步模式、类型提示
平台（28-30）
- 离线优先架构 -本地AI模型，无需网络
- 实时仪表盘 -用于审计监控的Web UI
- CI/CD集成 -GitHub操作，GitLab CI支持
安装
先决条件
- Python 3.11+
- Node.js 18+（用于JavaScript/TypeScript分析）
- Docker（用于沙盒执行）
- Git
快速开始
# Clone the repository
git clone https://github.com/yourusername/CodeTruth-MCP.git
cd CodeTruth-MCP
# Create virtual environment
python -m venv venv
source venv/bin/activate # or `venv\Scripts\activate` on Windows
# Install dependencies
pip install -e ".[dev]"
# Initialize the database
codetruth init
# Run the MCP server
codetruth serveDocker安装
docker build -t codetruth-mcp .
docker run -v /path/to/repos:/repos codetruth-mcp audit /repos/my-project用法
作为MCP服务器（克劳德桌面、VS代码等）
添加到MCP客户端配置中：
{
"mcpServers": {
"codetruth": {
"command": "codetruth",
"args": ["serve"],
"env": {
"CODETRUTH_DB_PATH": "~/.codetruth/evidence.db"
}
}
}
}CLI使用情况
# Full audit of a repository
codetruth audit /path/to/repo
# Quick scan (static only)
codetruth audit /path/to/repo --profile fast
# Deep forensics (includes E2E)
codetruth audit /path/to/repo --profile forensics
# Generate Feature Truth Table
codetruth truth-table /path/to/repo
# Run specific analyzers
codetruth analyze /path/to/repo --analyzers lint,types,securityMCP工具
CodeTruth公开了以下MCP工具：
| 工具 | 说明 |
|---|---|
discover_repos | 扫描存储库目录 |
inventory | 生成回购库存（语言、包、入口点） |
run_gates | 执行质量门梯 |
ui_wiring_audit | 检测死UI元素 |
api_contract_audit | 验证API合同 |
reachability_graph | 构建调用图，查找死代码 |
run_e2e | 使用跟踪执行Playwright测试 |
generate_truth_table | 创建特征真值表 |
create_fix_plan | 制定补救计划 |
search_evidence | 查询证据库 |
优质门梯
| 门 | 名称 | 支票 |
|---|---|---|
| 0 | 构建和启动 | 安装、启动、运行状况终结点 |
| 1 | 棉绒/类型 | eslint、ruff、tsc、mypy |
| 2 | 单元测试 | 核心模块覆盖率 |
| 3 | 合同测试 | API架构验证 |
| 4 | 集成/E2E | 编剧点击流 |
| 5 | 安全 | SAST、机密、依赖关系 |
| 6 | 发布 | 可复制的构建、文档 |
特征真值表
对于每个发现的特征曲面：
| 列 | 说明 |
|---|---|
| 特征 | 名称/标识符 |
| 规格来源 | 定义位置 |
| 执行路径 | UI→ API → 服务→ DB |
| Reachable | 代码路径是否可访问？ |
| 可观察 | 网络/状态/DB效应？ |
| 已测试 | 测试名称+断言 |
| 状态 | 工作/部分/卡住/未连接/死亡/损坏 |
| Blockers | 为什么它不完整 |
状态类别
- 工作中 -功能齐全，经过测试，闸门通过
- 部分的 -有些步骤奏效，有些步骤失败
- 脚趾不小心踢到…上 -占位符/TODO/模拟返回
- 无线 -UI存在，但没有未注册的处理程序/路由
- 死 -无法访问的代码
- 破碎的 -投掷/未通过测试
故障模式目录
CodeTruth检测到这些常见的“外观完成但未完成”模式：
- UI元素存在，但没有绑定处理程序（死按钮）
- 处理程序存在但无法访问（未路由/导出）
- 已定义但未注册API路由
- 后端返回成功，但不会持久
- 功能依赖于未记录的env/config
- TODO路径、占位符返回、硬编码模拟
- 异步队列未运行/无工作线程
- 身份验证/权限阻止流静默
- 比赛条件/状态从不更新UI
- 类型漂移/合约不匹配
建筑
┌──────────────────────────────────────────────────────────────┐
│ MCP Host (Claude/VS Code) │
└─────────────────────────────┬────────────────────────────────┘
│ MCP JSON-RPC
▼
┌──────────────────────────────────────────────────────────────┐
│ CodeTruth MCP Server │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Tool Router + Policy Engine ("no claim without proof") │ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────┬──────────────────────────────────────┬────────────┘
│ │
▼ ▼
┌────────────────────┐ ┌─────────────────────────┐
│ Repo Loader │ │ Evidence Vault │
│ - Local clones │◄────────────►│ - SQLite + SARIF │
│ - Inventory │ │ - Traces, snapshots │
│ - AST parsing │ │ - Mem0 context │
└─────────┬──────────┘ └────────────┬────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────────────────────┐
│ Analyzer Orchestrator │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Static │ │ Runtime │ │ Security │ │ Language-Specific│ │
│ │ Analyzers│ │ Analyzers│ │ Scanners │ │ Analyzers │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────────┘ │
└──────────────────────────────┬───────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Report Generator │
│ - Feature Truth Table - Fix Plans with acceptance tests │
│ - SARIF reports - CI/CD gate results │
│ - Evidence citations - Trace correlations │
└──────────────────────────────────────────────────────────────┘配置
创建 codetruth.toml 在您的repo根目录中：
[codetruth]
# Analysis profile: fast, standard, deep, forensics
profile = "standard"
[codetruth.gates]
# Which gates to run
enabled = [0, 1, 2, 3, 4, 5]
[codetruth.analyzers]
# Language-specific settings
python.enabled = true
python.type_checker = "mypy"
typescript.enabled = true
typescript.strict = true
[codetruth.e2e]
# Playwright settings
browser = "chromium"
trace = "on-first-retry"
video = "retain-on-failure"
[codetruth.security]
# Secret scanning
gitleaks.enabled = true
semgrep.enabled = true
semgrep.rulesets = ["p/default", "p/owasp-top-ten"]研究基金会
CodeTruth基于以下研究：
- ReachCheck：基于组合库的调用图可达性分析 （ACM TOSEM 2025）
- 运行24个静态分析工具的见解
- 基于LLM的代理人患有幻觉症 -循证缓解
- SARIF 2.1.0规范
许可证
MIT许可证-请参阅 许可证
贡献
看 贡献.md 作为指导方针。