内容
# 代码审计MCP
自主代码审计MCP服务器。将其添加到任何仓库中 - 其他一切都会自动运行。
**26种工具。8种内置技能。BM25持久内存。零手动设置。**
---
## 快速入门
```bash
# 1. 添加为子模块
git submodule add https://github.com/your-username/code-audit-mcp
# 2. 设置（检测项目，安装依赖，编写IDE配置）
cd code-audit-mcp && bash scripts/setup.sh
# 3. 重启IDE → 开始审计
```
然后在您的IDE中：
```
get_state() ← 查看当前健康分数和下一步操作
index_codebase() ← 将项目扫描到内存中
list_skills() ← 查看可用的审计模块
```
---
## IDE安装和激活
`setup.sh`会自动检测并编写IDE配置。但您也可以手动添加。
---
### Kiro
在`.kiro/settings.json`文件中添加（在项目根目录中）：
```json
{
"mcpServers": {
"code-audit": {
"command": "node",
"args": ["/absolute/path/to/code-audit-mcp/dist/index.js"],
"env": {
"AUDIT_DATA_DIR": "/absolute/path/to/code-audit-mcp/audit-data",
"SKILLS_DIR": "/absolute/path/to/code-audit-mcp/src/skills",
"PROJECT_ROOT": "/absolute/path/to/your-project"
}
}
}
}
```
重启Kiro。在左侧面板中，您将看到`code-audit`工具。
---
### Claude Desktop
在`~/.claude/claude_desktop_config.json`文件中添加：
```json
{
"mcpServers": {
"code-audit": {
"command": "node",
"args": ["/absolute/path/to/code-audit-mcp/dist/index.js"],
"env": {
"AUDIT_DATA_DIR": "/absolute/path/to/code-audit-mcp/audit-data",
"SKILLS_DIR": "/absolute/path/to/code-audit-mcp/src/skills",
"PROJECT_ROOT": "/absolute/path/to/your-project"
}
}
}
}
```
macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Windows: `%APPDATA%\Claude\claude_desktop_config.json`
重启Claude Desktop。
---
### Cursor
在`.cursor/mcp.json`文件中添加（在项目根目录中）：
```json
{
"mcpServers": {
"code-audit": {
"command": "node",
"args": ["/absolute/path/to/code-audit-mcp/dist/index.js"],
"env": {
"AUDIT_DATA_DIR": "/absolute/path/to/code-audit-mcp/audit-data",
"SKILLS_DIR": "/absolute/path/to/code-audit-mcp/src/skills",
"PROJECT_ROOT": "/absolute/path/to/your-project"
}
}
}
}
```
Cursor → 设置 → MCP → 刷新。
---
### VS Code（GitHub Copilot / Continue）
在`.vscode/mcp.json`文件中添加：
```json
{
"servers": {
"code-audit": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/code-audit-mcp/dist/index.js"],
"env": {
"AUDIT_DATA_DIR": "/absolute/path/to/code-audit-mcp/audit-data",
"SKILLS_DIR": "/absolute/path/to/code-audit-mcp/src/skills",
"PROJECT_ROOT": "/absolute/path/to/your-project"
}
}
}
}
```
---
### 激活检查
重启IDE后，运行：
```
get_state()
```
如果MCP激活，您将看到以下响应：
```json
{
"health": "🟢 100/100 →",
"activeTask": "无",
"next": "运行index_codebase()",
"openTasks": 0,
"memvid": "可用"
}
```
如果出现错误：
- 检查`dist/index.js`是否存在 → `npm run build`
- 确保路径是绝对的（相对路径不起作用）
- 完全关闭并重启IDE（仅reload无效）
---
### 自动查找路径（Mac/Linux）
如果您不知道要写入哪个路径：
```bash
cd code-audit-mcp
pwd # ← 复制此行，写入配置中
```
Windows：
```cmd
cd code-audit-mcp
cd # ← 复制此行
```
---
## 工作原理
LLM调用工具。工具读取/写入状态文件和memvid内存。没有任何基于提示的操作 - 每个操作都是确定性和可审计的。
```
LLM调用工具 → 工具运行 → 返回结果 → LLM继续
↑ ↓
无遗忘 状态写入文件
```
---
## 工具
### 设置和状态
| 工具 | 描述 |
|------|-------------|
| `initialize(project_root?)` | 首次设置。自动检测项目根目录，创建audit-data/，初始化memvid。 |
| `get_state()` | 完整状态：健康分数，活动任务，关键问题，下一步操作。在会话开始时调用。 |
| `update_context(data)` | 写入MASTER_CONTEXT。在任何重要操作后调用。 |
### 任务
| 工具 | 描述 |
|------|-------------|
| `get_next_task()` | 优先级最高的开放任务，带有现成的修复提示。 |
| `create_task(data)` | 自然语言 → TASKS.md条目。自动推断严重性。 |
| `complete_task(id)` | 标记完成，记录关闭日期。 |
| `list_tasks(filter?)` | 按状态/严重性筛选。`sprint_plan: true`添加时间估计。 |
### 技能
| 工具 | 描述 |
|------|-------------|
| `list_skills(category?)` | 所有可用的技能（内置 + 社区）。 |
| `run_skill(name, input)` | 加载技能 + 注入上下文 + 返回准备执行的提示。 |
| `install_skill(github_url)` | 从GitHub安装社区技能。 |
| `create_skill(data)` | 使用专业的SKILL.md格式创建自定义技能。 |
### 报告
| 工具 | 描述 |
|------|-------------|
| `save_report(name, content)` | 写入报告 + 更新INDEX + 添加到memvid + 生成修复提示。 |
| `list_reports(filter?)` | 基于INDEX的快速查找。无需读取文件。 |
| `get_report(id)` | 通过ID或文件名获取完整报告内容。 |
### 内存（Memvid）
| 工具 | 描述 |
|------|-------------|
| `index_codebase(path?)` | 将项目扫描到BM25索引中。默认为增量。 |
| `search_code(query)` | 类似语义的代码搜索。返回文件路径 + 相关行。 |
| `retrieve_chunks(query, file?)` | 高效的token文件读取。相比完整读取，token数量减少约80%。 |
| `search_memory(query, filters?)` | 搜索所有过去的审计发现。 |
| `find_similar_issues(description)` | “我们以前是否见过这个bug？” |
| `get_relevant_context(task, file?)` | 在运行技能之前自动注入过去的发现。 |
| `snapshot_codebase(label)` | 命名的代码库快照，用于差异比较。 |
| `diff_snapshots(label1, label2)` | 两个快照之间发生了什么变化。 |
| `analyze_bug_patterns()` | 循环模式，最受影响的文件，严重性分布。 |
| `rebuild_memory()` | 如果损坏，从reports/重建memory.mv2。 |
### 规范
| 工具 | 描述 |
|------|-------------|
| `create_spec(data)` | Kiro风格的规范：requirements.md + design.md + tasks.md。 |
| `archive_plan()` | 将AKTIF_PLAN.md移动到plans/存档。 |
### 维护
| 工具 | 描述 |
|------|-------------|
| `validate_paths()` | 自我修复路径检测。如果项目移动，自动修复。 |
| `run_maintenance()` | 完整周期：路径 + 健康 + 升级 + memvid检查 + 报告。 |
---
## 技能系统
技能是SKILL.md文件，定义了可重用的审计提示。LLM通过`run_skill()`加载它们。
### 内置技能
| 技能 | 类别 | 描述 |
|-------|----------|-------------|
| `doc-analyzer` | 质量 | 文档完整性和准确性 |
| `deep-dive` | 质量 | 特定文件的深度bug hunt |
| `code-review` | 质量 | 预先审查代码的内联反馈 |
| `bug-reporter` | 质量 | bug检测和重现步骤 |
| `refactor-planner` | 架构 | 安全的增量重构计划（Strangler Fig） |
| `sprint-planner` | 一般 | 将TASKS.md转换为sprint计划 |
| `audit-runner` | 一般 | 完整的审计编排（顺序运行所有技能） |
| `feature-planner` | 架构 | 计划新功能或改进 |
### 社区技能
从GitHub安装：
```
install_skill("https://github.com/user/nextjs-audit-skill")
install_skill("https://github.com/user/django-security-skill")
```
### 创建您自己的技能
```
create_skill({
name: "my-auth-audit",
description: "检查Express路由中的身份验证模式",
category: "安全",
input: ["routes_path"],
prompt: "分析{{routes_path}}的身份验证漏洞..."
})
```
---
## 文件结构
```
audit-data/ ← 在首次运行时创建（.gitignored）
├── MASTER_CONTEXT.md ← 活动状态（健康分数，当前任务，下一步操作）
├── TASKS.md ← 永久待办事项（T-001，T-002，...）
├── AKTIF_PLAN.md ← 当前实施计划
├── reports/
│ ├── INDEX.md ← 快速报告查找
│ └── *.md ← 单个审计报告
├── spec/ ← Kiro风格的规范（需求 + 设计 + 任务）
├── plans/ ← 存档计划
└── memory.mv2 ← memvid BM25内存（所有报告 + 代码索引）
```
---
## Git Hooks
自动检查每次提交中的硬编码密钥、TODO和console.logs：
```bash
bash scripts/install-hooks.sh
```
阻止包含硬编码API密钥或密码的提交。对TODO和console.logs发出警告。
---
## Memvid
Memvid是可选的。如果未安装，除内存相关工具外，所有工具都可用。
```bash
pip install memvid ← 安装
```
内存存储在单个`memory.mv2`文件中。仅BM25模式 - 无嵌入模型，无API密钥。IDE的LLM处理语义重新排序。
如果内存损坏：`bash scripts/rebuild-memory.sh`
---
## 典型会话流程
```
会话开始：
get_state() → 查看健康分数 + 下一步操作
运行审计：
get_relevant_context("jwt.service.ts") → 注入过去的发现
run_skill("deep-dive", { file_path: "src/auth/jwt.service.ts" }) → 获取提示
[LLM执行分析]
save_report("DEEPDIVE_JWT_2026-03", content, { severity: "HIGH" })
create_task({ title: "JWT刷新竞争条件", severity: "HIGH", file: "jwt.service.ts" })
update_context({ last_action: "JWT深入分析", next: "修复T-001" })
修复bug：
get_next_task() → T-001带有修复提示
[LLM修复代码]
complete_task("T-001")
update_context({ last_action: "已修复T-001" })
```
---
## 需求
- Node.js ≥ 18
- Python 3.8+（用于memvid，可选）
- Git（用于增量索引和基于差异的审计）
---
## 许可证
MIT
