MITBenAHammond/code-auditor-mcp

Code Auditor

Code Auditor 通读你的整个代码库,告诉你哪里出了问题——包括那些只存在于文件之间的问题。安装一个技能,你的智能体就会在每次编辑时保持它干净。

两条命令,随处安装:

npm install -g code-auditor-mcp
code-audit install --agent all

支持 Claude Code、Cursor、Codex、Gemini CLI 以及任何 SKILL.md 智能体。在 Claude Code 和 Codex 上有阻断式钩子;在其他地方通过 MCP 报告。 code-audit install --list 显示支持矩阵。

工作原理

接手了一个代码库?几个月没碰过又回来了?快速搭了东西,现在想知道里面到底有什么?先审计一次看清全貌,再让你的智能体在每次编辑时保持它干净。无论哪种方式,分析都是确定性的。

清理你的代码

code-audit audit

对任何 TypeScript、JavaScript、Go 或 CSS/SCSS 项目运行它,获得一份完整、结构化的诊断报告——每条规则一条读数。修复真正的问题,将其余的设为基线,从一张白纸重新开始。

  1. 确定性,而非模型驱动

    tree-sitter 和 ast-grep 负责分析——每次运行的读数都完全一致,无论使用任何模型,或完全不使用模型。

  2. 一份可执行的报告

    HTML · JSON · CSV · SARIF 2.1.0

    覆盖面板开头列出测量范围,然后是每条读数的文件、行号、严重级别、规则 ID 和消息。将已知问题设为基线作为技术债,只有新问题才会凸显出来。

保持代码干净

code-audit changed

安装后,你的智能体只审计它刚刚改动的文件。达到阻断严重级别的读数——默认是 critical 和 warning——在进入仓库之前就被捕获并修复,无需重新读取整个代码库,因此模型成本保持低廉。

  1. 安装技能

    code-audit install --agent claude

    将一个 SKILL.md 以及一个 PostToolUse 钩子放入你的智能体——支持 Claude Code 和 Codex。

  2. 它审计改动

    code-audit changed --json

    只审计发生变化的文件,而不是整个项目。钩子在每次 Write 和 Edit 之后触发。

  3. 阻断级别的读数会阻止编辑

    hardcoded-secret · critical · src/login.ts:52

    智能体读取规则 ID、严重级别、文件、行号和消息——修复它——只有没有阻断读数的代码才会进入你的仓库。阻断的严重级别可通过 .codeauditor.json 中的 gateSeverities 配置。

TypeScript、JavaScript、Go 和 CSS/SCSS——使用 tree-sitter 和 ast-grep 语法进行解析。

它能发现什么

十个分析器,加三个跨语言分析器,覆盖 TypeScript、JavaScript、Go 和 CSS/SCSS。下面每一个例子都来自真实代码库的真实读数——其中大多数在任何单个文件里都看不见。

N+1 查询

for (const org of orgs) { await db.select().from(organizations) }

一个循环在每次迭代时都发出一条查询,在一次层级遍历中被发现。每个节点都是对数据库的一次额外往返。

死模块

compliance-enhanced.ts — 563 lines, 0 external importers

563 行代码,零个外部引用者,已被更新的兄弟模块取代却仍在代码树里。没有任何东西链接到它,所以没人发现它。

已删除的表仍在被查询

SELECT * FROM generation_queue // dropped in migration 0198

一次迁移删除了这张表,但仍有八处调用点引用它。schema 已经前进,代码没有。

硬编码凭据

page.type('#password', 'vyy8AUVvish34Fq')

一段脚本里躺着明文的密码,随时可能被发布。靠读文件就能发现——不需要运行。

完整目录——十个分析器,加三个跨语言

SOLID 原则

五大原则,机械式强制执行。

DRY

复制粘贴,在变成技术债之前被捕获。

数据访问与安全

SQL 注入、租户泄漏、N+1。

文档质量

没有文档的导出就是未来的 bug。

React 最佳实践

那些能逃过审查的错误。

Schema 感知

引用了不存在的列的查询。

不变量规则

你团队的规则,作为硬性不变量强制执行。

Schema 定义
跨语言

当 schema 和代码不一致时。

API 契约
跨语言

端点、字段、鉴权是否符合契约。

依赖图
跨语言

循环、耦合、枢纽、孤儿。

样式

令牌漂移、z-index 泛滥。

约定

挖掘你代码的约定,标记偏离。

跨域

只有跨越边界才能看到的东西。

逐改动、每次编辑

你的智能体在它刚刚改动的文件上运行 code-audit changed ,而不是整个项目。每个分析器返回结构化的读数——文件、行号、严重级别、规则 ID,以及智能体可以读取并修复的消息。

JSON 输出
SARIF 2.1.0 输出
CSV 输出
HTML 输出

它不做什么

三条诚实的边界,说在明处。

它不写修复

它只报告。改代码的是人——或智能体。Code Auditor 告诉你哪里出了问题、在哪里;它绝不会替你改代码。

它不是 linter 的替代品

和 ESLint、Prettier 等一起使用。linter 读单个文件;Code Auditor 读整个代码库。它们回答的是不同的问题。

规模规则是阈值,不是裁决

函数长度、参数数量、类大小——这些都是你可以调整的测量值,不是评判。它们是读数:是行动顺序,绝不是对你代码的裁决。