Content
# code-audit-mcp
Autonomous code audit MCP server. Add it to any repo — everything else runs automatically.
**26 tools. 8 built-in skills. BM25 persistent memory. Zero manual setup.**
---
## Quickstart
```bash
# 1. Add as submodule
git submodule add https://github.com/your-username/code-audit-mcp
# 2. Setup (detects project, installs deps, writes IDE config)
cd code-audit-mcp && bash scripts/setup.sh
# 3. Restart IDE → start auditing
```
Then in your IDE:
```
get_state() ← see current health score and next action
index_codebase() ← scan your project into memory
list_skills() ← see available audit modules
```
---
## IDE Kurulumu ve Aktivasyon
`setup.sh` IDE config'ini otomatik algılar ve yazar. Ama elle de ekleyebilirsin.
---
### Kiro
`.kiro/settings.json` dosyasına ekle (proje root'unda):
```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'yu restart et. Sol panelde `code-audit` tool'ları görünür.
---
### Claude Desktop
`~/.claude/claude_desktop_config.json` dosyasına ekle:
```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'u restart et.
---
### Cursor
`.cursor/mcp.json` dosyasına ekle (proje root'unda):
```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 → Settings → MCP → Refresh.
---
### VS Code (GitHub Copilot / Continue)
`.vscode/mcp.json` dosyasına ekle:
```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"
}
}
}
}
```
---
### Aktivasyon Kontrolü
IDE restart sonrası şunu yaz:
```
get_state()
```
Şu şekilde cevap gelirse MCP aktif:
```json
{
"health": "🟢 100/100 →",
"activeTask": "YOK",
"next": "index_codebase() çalıştır",
"openTasks": 0,
"memvid": "available"
}
```
Hata gelirse:
- `dist/index.js` var mı kontrol et → `npm run build`
- Path'lerin absolute olduğundan emin ol (relative path çalışmaz)
- IDE'yi tamamen kapat/aç (reload yetmez)
---
### Otomatik Path Bul (Mac/Linux)
Hangi path yazacağını bilmiyorsan:
```bash
cd code-audit-mcp
pwd # ← bu satırı kopyala, config'e yaz
```
Windows için:
```cmd
cd code-audit-mcp
cd # ← bu satırı kopyala
```
---
## How It Works
The LLM calls tools. Tools read/write state files and memvid memory. Nothing is prompt-based — every action is deterministic and auditable.
```
LLM calls tool → tool runs → result returned → LLM continues
↑ ↓
no forgetting state written to files
```
---
## Tools
### Setup & State
| Tool | Description |
|------|-------------|
| `initialize(project_root?)` | First-time setup. Auto-detects project root, creates audit-data/, inits memvid. |
| `get_state()` | Full state: health score, active task, critical issues, next action. Call at session start. |
| `update_context(data)` | Write to MASTER_CONTEXT. Call after any significant action. |
### Tasks
| Tool | Description |
|------|-------------|
| `get_next_task()` | Highest priority open task with ready-to-use fix prompt. |
| `create_task(data)` | Natural language → TASKS.md entry. Severity auto-inferred. |
| `complete_task(id)` | Mark done, record close date. |
| `list_tasks(filter?)` | Filter by status/severity. `sprint_plan: true` adds time estimates. |
### Skills
| Tool | Description |
|------|-------------|
| `list_skills(category?)` | All available skills (built-in + community). |
| `run_skill(name, input)` | Load skill + inject context + return ready-to-execute prompt. |
| `install_skill(github_url)` | Install community skill from GitHub. |
| `create_skill(data)` | Create custom skill with professional SKILL.md format. |
### Reports
| Tool | Description |
|------|-------------|
| `save_report(name, content)` | Write report + update INDEX + add to memvid + generate fix prompt. |
| `list_reports(filter?)` | Fast INDEX-based lookup. No file reads. |
| `get_report(id)` | Full report content by ID or filename. |
### Memory (Memvid)
| Tool | Description |
|------|-------------|
| `index_codebase(path?)` | Scan project into BM25 index. Incremental by default. |
| `search_code(query)` | Semantic-style code search. Returns file paths + relevant lines. |
| `retrieve_chunks(query, file?)` | Token-efficient file reading. ~80% fewer tokens vs full read. |
| `search_memory(query, filters?)` | Search all past audit findings. |
| `find_similar_issues(description)` | "Have we seen this bug before?" |
| `get_relevant_context(task, file?)` | Auto-inject past findings before running a skill. |
| `snapshot_codebase(label)` | Named codebase snapshot for diff comparison. |
| `diff_snapshots(label1, label2)` | What changed between two snapshots. |
| `analyze_bug_patterns()` | Recurring patterns, most affected files, severity distribution. |
| `rebuild_memory()` | Rebuild memory.mv2 from reports/ if corrupted. |
### Spec
| Tool | Description |
|------|-------------|
| `create_spec(data)` | Kiro-style spec: requirements.md + design.md + tasks.md. |
| `archive_plan()` | Move AKTIF_PLAN.md to plans/ archive. |
### Maintenance
| Tool | Description |
|------|-------------|
| `validate_paths()` | Self-healing path detection. Auto-fixes if project moved. |
| `run_maintenance()` | Full cycle: paths + health + escalation + memvid check + report. |
---
## Skills System
Skills are SKILL.md files that define reusable audit prompts. The LLM loads them via `run_skill()`.
### Built-in Skills
| Skill | Category | Description |
|-------|----------|-------------|
| `doc-analyzer` | quality | Documentation completeness and accuracy |
| `deep-dive` | quality | Deep bug hunt in a specific file |
| `code-review` | quality | Pre-PR review with inline feedback |
| `bug-reporter` | quality | Bug detection with reproduction steps |
| `refactor-planner` | architecture | Safe incremental refactor planning (Strangler Fig) |
| `sprint-planner` | general | Turn TASKS.md into a sprint plan |
| `audit-runner` | general | Full orchestrated audit (runs all skills in sequence) |
| `feature-planner` | architecture | Plan new features or improvements |
### Community Skills
Install from GitHub:
```
install_skill("https://github.com/user/nextjs-audit-skill")
install_skill("https://github.com/user/django-security-skill")
```
### Create Your Own
```
create_skill({
name: "my-auth-audit",
description: "Check auth patterns in Express routes",
category: "security",
input: ["routes_path"],
prompt: "Analyze {{routes_path}} for auth vulnerabilities..."
})
```
---
## File Structure
```
audit-data/ ← created on first run (.gitignored)
├── MASTER_CONTEXT.md ← active state (health score, current task, next action)
├── TASKS.md ← permanent backlog (T-001, T-002, ...)
├── AKTIF_PLAN.md ← current implementation plan
├── reports/
│ ├── INDEX.md ← fast report lookup
│ └── *.md ← individual audit reports
├── spec/ ← Kiro-style specs (requirements + design + tasks)
├── plans/ ← archived plans
└── memory.mv2 ← memvid BM25 memory (all reports + code index)
```
---
## Git Hooks
Auto-check every commit for hardcoded secrets, TODOs, and console.logs:
```bash
bash scripts/install-hooks.sh
```
Blocks commits with hardcoded API keys or passwords. Warns on TODOs and console.logs.
---
## Memvid
Memvid is optional. If not installed, all tools work except memory-related ones.
```bash
pip install memvid ← install
```
Memory is stored in a single `memory.mv2` file. BM25-only mode — no embedding model, no API keys. The IDE's LLM handles semantic re-ranking.
If memory gets corrupted: `bash scripts/rebuild-memory.sh`
---
## Typical Session Flow
```
Session start:
get_state() → see health score + next action
Run an audit:
get_relevant_context("jwt.service.ts") → inject past findings
run_skill("deep-dive", { file_path: "src/auth/jwt.service.ts" }) → get prompt
[LLM executes the analysis]
save_report("DEEPDIVE_JWT_2026-03", content, { severity: "HIGH" })
create_task({ title: "JWT refresh race condition", severity: "HIGH", file: "jwt.service.ts" })
update_context({ last_action: "JWT deep dive", next: "Fix T-001" })
Fix a bug:
get_next_task() → T-001 with fix prompt
[LLM fixes the code]
complete_task("T-001")
update_context({ last_action: "Fixed T-001" })
```
---
## Requirements
- Node.js ≥ 18
- Python 3.8+ (for memvid, optional)
- Git (for incremental indexing and diff-based auditing)
---
## License
MIT
