slugaudit-mcp

A PostgreSQL-backed code audit system for AI-assisted code reviews. Extracts code signatures and import dependencies from source files using tree-sitter, builds a dependency graph, tracks changes between imports, and generates structured briefings for AI auditors.

Available as both a CLI tool (slugaudit-mcp) and an MCP server (slugaudit-mcp).

Quick Start

# 1. Install dependencies (system packages, Python deps, tree-sitter parsers)
bash setup.sh

# 2. Set up PostgreSQL connection
export PGHOST=localhost
export PGPORT=5432
export PGDATABASE=my_audit_db
export PGUSER=my_user
export PGPASSWORD=my_password

# 3. Import a project (schema auto-creates on first use!)
slugaudit-mcp import /path/to/your/project --project-name "My Project"

# 4. Check project status
slugaudit-mcp status --project "My Project"

# 5. Generate an AI audit briefing
slugaudit-mcp briefing --project "My Project" --output briefing.md

MCP Server Mode (Recommended for AI Assistants)

# Run the MCP server
python3 mcp_server.py

Then in your AI client (Claude Desktop, VS Code, Cursor, Codebuff, etc.), configure the MCP server:

{
  "mcpServers": {
    "slugaudit-mcp": {
      "command": "python3",
      "args": ["/path/to/slugaudit-mcp/mcp_server.py"],
      "env": {
        "PGHOST": "localhost",
        "PGPORT": "5432",
        "PGDATABASE": "my_audit_db",
        "PGUSER": "my_user",
        "PGPASSWORD": "my_password"
      }
    }
  }
}

Once configured, the AI can use these tools directly:

• audit_import — Import a codebase

• audit_brief — Generate an audit briefing

• audit_status — Show project status

• audit_changed — List changed files

• audit_list — List all projects

• audit_init_db — Manually initialize schema (usually auto-done)

Related MCP server: Code Expert MCP Server

Architecture

The system follows a layered architecture with clear separation of concerns:

[CLI / MCP] → [Services] → [Repositories] → [Infrastructure]
                ↓
        [Languages] → [Source Files]

Commands

Supported Languages

Key Concepts

• Signature cache: Public API surface of each file stored as JSONB. Lets the AI understand a file's interface without reading its full source.

• Dependency edges: File-to-file dependencies resolved from import statements. Enables blast radius computation.

• Change detection: SHA-256 hash compared against last_audited_hash. Only changed files become audit targets.

• Blast radius: Files that depend on changed files, computed from dependency edges.

• Ghost context: Signatures of unchanged files provided for AI reference — reduces token usage by avoiding full source reads.

Configuration

Environment Variables

Connection String

Override env vars with --connection:

slugaudit-mcp import . --connection "postgresql://user:pass@host:5432/dbname?sslmode=require"

Database Schema

All projects share one database. Each project's data is isolated via project_id foreign keys with ON DELETE CASCADE:

Workflow

First-time audit

# 1. Import the baseline
slugaudit-mcp import /path/to/project --project-name "My Project"

# 2. Make edits to the codebase...

# 3. Re-import to sync
slugaudit-mcp import /path/to/project

# 4. Generate briefing for changed files
slugaudit-mcp briefing --project "My Project" --output briefing.md

# 5. Feed briefing.md to an AI for audit

Continuous audit with MCP

1. Call audit_import to scan the project

2. Call audit_status to verify the import

3. After code changes, call audit_import again to sync

4. Call audit_brief to get the generated briefing

5. The AI returns findings directly in conversation

Adding a New Language

1. Create languages/yourlang.py extending BaseExtractor

2. Implement: name(), source_extensions(), find_source_files(), extract_signatures(), extract_imports(), resolve_import(), hash_file()

3. Register in LANG_MAP in languages/__init__.py

4. Install tree-sitter grammar: pip install tree-sitter-yourlang

Testing

110 tests using unittest with mocking — no database required:

python3 -m pytest tests/ -v       # preferred
python3 -m unittest tests          # alternative

Code Quality

# Linting
ruff check .

# Type checking
mypy .

# Pre-commit hooks
pre-commit install
pre-commit run --all-files

Configured tools: ruff (E/W/F/UP/S/B/C4 rules, line-length=100), mypy (strict mode), pre-commit (trailing-whitespace, end-of-file-fixer, check-yaml, ruff, mypy).

Requirements

• Python 3.10+

• PostgreSQL 15+ (uses UUID, JSONB, gen_random_uuid())

• tree-sitter parsers for each supported language

License

MIT