Skip to main content
Glama
code-auditor-mcp

code-auditor-mcp

by BenAHammond

Code Auditor

Architectural invariants enforced inside your AI agent's edit loop. When the agent writes code that breaks a project rule, Code Auditor catches it and blocks the edit. The agent sees the rule's message and fixes itself.

Install

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

Two commands to install everywhere. code-audit install --agent all copies the skill to every AI coding tool on your machine. Use --agent for specific tools.

What you get per tool: the skill (SKILL.md), MCP server access, and hook wiring where the tool supports it (blocking on Claude Code and Codex, advisory on Cursor).

code-audit install --list   # see the support matrix

Claude Code users can also install via plugin:

claude plugin marketplace add BenAHammond/code-auditor-mcp
claude plugin install code-auditor

The hook auto-installs the auditor on first use via npx.

Related MCP server: Cortex

Requirements

  • Node 18+ to run. Node 23.4+ gets the zero-native-install path: Code Auditor uses the built-in node:sqlite module, so nothing needs to compile or download a prebuilt binary on install.

  • On older Node (18–23.3), Code Auditor falls back to better-sqlite3, an optional dependency whose install script must be approved once on npm 11.2+/12 (they block dependency install scripts by default): npm install-scripts approve better-sqlite3 && npm rebuild better-sqlite3 (with pnpm: pnpm approve-builds, then select better-sqlite3).

Configuration

Project-level settings live in .codeauditor.json (invariant rules, analyzer settings, and thresholds). Eleven environment variables additionally tune process-scoped behavior — worker pool size, daemon and job-queue timeouts, the index location, the SQLite backend, and the UI port.

Variable

Purpose

Accepted values

Default

CODE_AUDITOR_WORKERS

Phase-model worker pool size for per-file fan-out. 1 forces the serial path for byte-identical reports.

Positive integer

max(1, cpus − 1)

CODE_AUDITOR_RULE_TIMING

Per-rule wall-time accounting (one accumulated timer per rule ID, surfaced in the report).

1 enables; unset disables

Off

CODE_AUDITOR_DAEMON_IDLE_MS

Idle timeout before the daemon shuts down.

Positive finite ms; invalid → default

300000 (5 min)

CODE_AUDITOR_DAEMON_LEASE_TTL_MS

Daemon heartbeat lease TTL.

Finite ms; blank/0 → default

60000 (60 s)

CODE_AUDITOR_DATA_DIR

Overrides the code-index database directory.

Directory path (trimmed; blank → default)

user-level OS cache

CODE_AUDITOR_EXIT_ON_FATAL

Exit the MCP server on an uncaught exception / unhandled rejection.

1 or true

Off

CODE_AUDITOR_JOB_TIMEOUT_MS

Per-job timeout for queued audits.

Finite ms, clamped to 60s–4h; below the floor → default

1800000 (30 min)

CODE_AUDITOR_JOB_LEASE_TTL_MS

Heartbeat lease TTL for reclaiming stale running job rows.

Strictly positive finite ms; invalid → default

30000 (30 s)

CODE_AUDITOR_MAX_RUNNING_JOBS

Max concurrently running queued audit jobs.

Integer ≥ 1; invalid → default

1

CODE_AUDITOR_SQLITE_BACKEND

Forces a SQLite backend. An invalid value is reported as invalid and rejected — never silently probed past.

node-sqlite | better-sqlite3

Auto (probe)

MCP_UI_PORT

HTTP UI server port (--ui).

Port number; invalid → default

3001

When CODE_AUDITOR_DATA_DIR is set, the index is scoped per project (<dir>/projects/<sha256(root)[:16]>/index.db) so projects can't leak data into each other. When unset, the index lives in a user-level OS cache (<os_cache>/code-auditor/projects/<hash>/index.db) so it never lands inside the audited repo.

Prompt examples

"Index the codebase and run a full audit, then walk the violations file-by-file with code-audit next-file."

"Create a .codeauditor.json that bans lodash imports and prevents src/languages/ from importing anything in src/analyzers/."

"Run a full audit, fix the highest-priority file, and repeat code-audit next-file until the tree is clean."

"Sync the code index and audit only what changed vs main."

"Add an ast-pattern rule that blocks new Function(...)."

"Add a naming rule requiring hooks in src/hooks/ to start with use."

"Add a call-constraint so chargeCustomer() in src/services/payment.ts can only be called from src/api/."

Rule kinds

Seven kinds. The agent writes them to .codeauditor.json. Bad configs fail the audit, not silently.

Kind

What it blocks

import-ban

Banned module imports

call-constraint

Function calls from unauthorized files

module-boundary

Imports across module boundaries

naming

Exported symbols not matching a pattern

ast-pattern

AST nodes matching an ast-grep pattern

style-mechanism

Unapproved style mechanisms per file/glob

no-raw-values

Hardcoded values for specific CSS properties

Works with your agent

One skill, one CLI, one MCP server. Every agent gets the same audit engine — the hook contract is the only difference.

Agent

Skill

Hooks / Blocking

MCP

Verified

Claude Code

Plugin or code-audit install

Yes — blocking

Yes

2026-07-19

Cursor

code-audit install --agent cursor (project-only)

Advisory

Yes

2026-07-19

Codex

code-audit install --agent codex + plugin

Yes — blocking

Yes

2026-07-19

Gemini CLI

code-audit install --agent gemini

No

Yes

2026-07-19

VS Code / Copilot

code-audit install --agent agents

No

Yes

2026-07-19

Other SKILL.md tools

code-audit install --agent agents

No

Yes

2026-07-19

ZCode

code-audit install --agent zcode

No (plugin-scoped)

Yes

2026-09-10

MCP config generation covers a wider set than skill install. The MCP server's generate tool writes a client config file for any of claude, codex, cursor, gemini, copilot, continue, awsq (AWS Q Developer), codeium (Codeium/Windsurf), vscode, cline, and zcode. Four of those — Continue, AWS Q Developer, Codeium/Windsurf, and Cline — are MCP-only: they have no file-based skill or hook path, so they connect through the generate tool rather than code-audit install.

Hook behavior: Blocking means the diff-scoped changed gate is tripped — an invariant rule that declares gating: true (a binary, per-rule flag, independent of severity) blocks the edit from landing (the agent sees the violation and fixes inline). Advisory means violations are reported through the strongest available feedback channel but the edit has already occurred. Cursor's afterFileEdit hook is fire-and-forget with no output consumption. MCP is available everywhere for shell-less use.

Findings: Deterministic vs Advisory

Code Auditor's built-in rules fall into two categories:

Category

Meaning

Examples

Deterministic

Structural fact — an engineer would act on every finding

single-responsibility (300-line functions), solid/method-complexity (cyclomatic complexity > 20), solid/class-size (40+ method classes), dependency-inversion (concrete imports where an interface exists)

Advisory

Heuristic signal — may be wrong depending on domain

sql-injection-risk (AST-level string-pattern matching without type info), missing-org-filter (domain-specific — assumes SaaS tenant isolation), unknown-table (requires user-provided schema), dry/duplicate (token-identical blocks)

Deterministic rules ship at critical or severe. Advisory rules ship at severe or high. Rules proven near-zero precision on a real corpus are disabled by default (off) — users opt in when the rule matches their domain.

Recalibration

Built-in severity defaults are recalibrated from real-corpus triage. The current defaults reflect measurement on three corpora: this tool's own codebase, Gin, and Excalidraw. Six data-access rules that produced near-zero precision across all three corpora are disabled by default.

Every disabled rule documents what corpus it would be useful on. Users can restore any rule via severityOverrides in .codeauditor.json:

{
  "severityOverrides": {
    "sql-injection-risk": "critical",
    "missing-org-filter": "severe",
    "loop-query": "severe"
  }
}

Severity overrides apply globally (before per-directory path profile caps). Setting a rule to "off" removes it from the output entirely.

SQL Injection Detection

The sql-injection-risk rule is disabled by default (off) after recalibration. On the self-audit corpus, it produced 0% precision — the rule misinterpreted TypeScript pattern-matching code (string constants like 'SELECT', 'FROM', 'WHERE' used for the tool's own SQL detection) as database queries. On the Gin and Excalidraw corpora, precision was also near zero.

When to re-enable it: your project's SQL is constructed via string concatenation or template literals in functions whose sole purpose is query assembly. The rule detects those patterns. For codebases using ORMs or parameterized queries exclusively, the rule produces noise.

To re-enable and block on SQL injection:

{
  "severityOverrides": {
    "sql-injection-risk": "critical"
  }
}

With sql-injection-risk: critical (and the rule marked gating), your agent's hook will block edits that introduce AST-level SQL injection patterns.

Dismissals

Every finding is a measurement, not a verdict — but measurements are occasionally wrong. When the agent hits a false positive (the rule is right in general, wrong for this specific code), it can dismiss that one instance rather than work around it:

code-audit dismiss <fingerprint> --reason "generated code, not hand-written"

The <fingerprint> comes from the JSON report (every violation carries a fingerprint field). A written --reason is required, and the dismissal clears exactly one finding — rule + file + symbol — so the same rule still fires everywhere else. Dismissals live in a committed .codeauditor.dismissals.json, reviewable in a diff.

Anonymous dismissal feedback (opt-in)

The reason an agent gives for dismissing a finding is the most useful signal for improving the rules. Code Auditor can send dismissed findings to an anonymous feedback service that collects them.

It is off by default and turned on only by an explicit opt-in, via any of three methods (in precedence order):

  1. per-invocation — code-audit dismiss --telemetry … sends just that one dismissal; --no-telemetry suppresses one.

  2. environment — CODE_AUDITOR_TELEMETRY=1 (or 0) as a machine-level default for headless/CI runs.

  3. persisted — code-audit telemetry status|enable|disable (or the telemetry MCP tool), which records the choice in your user config dir.

telemetry enable needs no arguments: it opts in against the built-in service endpoint (overridable for self-hosting). Opting in generates an anonymous install ID: a random value generated locally, never derived from your machine, user, or project, used only to group submissions by source.

What is sent — the tool version, the rule ID, the urgency level, the dismissal reason exactly as typed, a structural AST signature (grammar kinds only, never their contents), a coarse language hint, a timestamp, and the anonymous install ID. What is never sent — source code, identifiers, literals, file paths, or anything derived from your code or environment. Sending is best-effort: offline or an unreachable endpoint is silent and never blocks an edit or fails a gate.

Style Intelligence

Code Auditor indexes every style declaration in your project — CSS, SCSS, Tailwind, inline styles, and CSS-in-JS. The styles rules read global distributions and flag fragmentation that no single-file linter can see.

7 detectors, 10 rule IDs:

Detector

What it finds

Value drift

Near-duplicate color values (delta-E < 2.0) and exact-value outliers where one value dominates

Off-scale

Margin/padding/gap/font-size values not on the inferred project scale

Undefined class

className values with no matching CSS selector or Tailwind utility

Token bypass

Hardcoded values that match a design token but don't reference it

Mechanism fragmentation

Same (property, value) delivered via ≥ 3 mechanisms (CSS, inline, Tailwind)

Declaration-set similarity

Two CSS rule blocks with > 90% identical declarations

Z-index sprawl

Project-wide z-index inventory — too many distinct values or orphan singletons

The styles rules read from a project-wide SQLite index, so scoped runs (changed files only) still compare against the full project baseline. A fresh #273828 drift color in a scoped run is caught against the full corpus of #1e2328 values.

Style invariant rules:

{
  "rules": [
    {
      "kind": "style-mechanism",
      "message": "Only Tailwind in src/components/",
      "allow": ["tailwind"],
      "path": "src/components/**"
    },
    {
      "kind": "no-raw-values",
      "message": "No raw colors in src/pages/ — use design tokens",
      "properties": ["color", "background-color"],
      "path": "src/pages/**"
    }
  ]
}

Style search operators — search by property, value, mechanism, or token:

code-audit search "css:margin-top value:16px"          # specific value
code-audit search "mechanism:inline css:color"          # inline color declarations
code-audit search "token:--color-primary"                # bypassing a design token

The React rules also gain raw-element detection: if your project has a Button wrapper, raw <button> usages outside Button's definition become severe findings.

License

MIT

Available Tools

16 tools
auditAInspect

Fetch paginated results for a completed audit by resultId (or auditId alias). This tool never starts a new audit.

Inputs: limit, offset, auditId, resultId.

audit_healthCInspect

Quick health check of a codebase with key metrics

Inputs: path, threshold, indexFunctions, analyzerConfigs, +1 more.

audit_resultsAInspect

Fetch paginated violations for a completed audit result by resultId.

Inputs: resultId (required), limit, offset.

audit_statusAInspect

Get current status for a previously started background audit job. Returns resultId when completed.

Inputs: jobId (required).

find_definitionAInspect

Find the exact definition of a specific function or React component

Inputs: name (required), filePath.

generate_ai_configAInspect

Generate configuration files for AI coding assistants

Inputs: tools (required), outputDir.

get_analyzer_configBInspect

Get current configuration for an analyzer

Inputs: projectPath, analyzerName.

get_code_map_sectionBInspect

Retrieve a specific section of a previously generated code map

Inputs: mapId (required), sectionType (required).

get_workflow_guideAInspect

Get recommended workflows and best practices for using code auditor tools effectively

Inputs: scenario.

list_code_map_sectionsBInspect

List all available sections for a code map

Inputs: mapId (required).

project_tasksAInspect

Manage a persistent per-project task queue. Tasks and analyzer configs survive sync_index reset; reset clears function index, cached audits, code maps, and schema overlays (no ghost code references). Use delete to remove a task.

Inputs: action (required), mode, dueAt, label, +21 more.

reset_analyzer_configCInspect

Reset analyzer configuration to defaults

Inputs: projectPath, analyzerName.

search_codeAInspect

Search indexed functions and React components with natural language queries. Supports operators: entity:component, component:functional|class|memo|forwardRef, hook:useState|useEffect|etc, prop:propName, dep:packageName, dependency:lodash, uses:express, calls:functionName, calledby:functionName, dependents-of:functionName, used-by:functionName, depends-on:module, imports-from:file, unused-imports, dead-imports, type:fileType, file:path, lang:language, complexity:1-10, jsdoc:true|false

Inputs: query (required), limit, offset, filters.

set_analyzer_configAInspect

Set or update analyzer configuration that persists across audit runs

Inputs: config (required), analyzerName (required), projectPath.

start_auditAInspect

Start a background audit job. Returns immediately with a jobId. Poll audit_status until completed, then fetch pages with audit or audit_results.

Inputs: path, analyzers, maxRetries, minSeverity, +13 more.

sync_indexAInspect

Synchronize, cleanup, or reset analysis-derived data (indexed functions, FlexSearch, cached audits, code maps, schema overlays). Project tasks, analyzer configs, and whitelist entries are preserved on reset.

Inputs: mode, path.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose; even closely related tools like audit and audit_results are separated by 'results' vs 'violations', and descriptions clarify usage without ambiguity.

    Naming Consistency5/5

    All tool names use consistent snake_case and mostly follow a verb_noun pattern (e.g., search_code, start_audit), with no mixing of naming conventions.

    Tool Count4/5

    With 16 tools, it slightly exceeds the typical 3-15 range, but the comprehensive code auditing domain justifies the count, covering audit lifecycle, config, search, code maps, tasks, and maintenance.

    Completeness4/5

    Core workflows are well-covered (audit start/status/results, config CRUD, search, code maps), though missing a stop audit or list all audits option, which are minor gaps.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI clients to perform local code search, indexing, and analysis across Java, JavaScript/TypeScript, .NET/C#, and Python projects through the MCP protocol.
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI coding assistants to semantically search and retrieve relevant code patterns, documentation, and implementations from a codebase via MCP tools.
      8
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to query language intelligence over MCP, including definitions, references, symbols, and code relationship graphs across many languages, all in one native process with no external language servers.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables local code intelligence for AI agents and editors by indexing source code, dependencies, Git history, tests, and documentation, and provides change-impact analysis and relevant test selection through MCP.
      1
      AGPL 3.0