MCP Repo Auditor README

mcp-repo-auditor

Check your code changes against the rules your repository already gives AI agents: AGENTS.md, CLAUDE.md, .cursorrules, Copilot instructions, Kiro steering, skills and more.

It is a local Model Context Protocol server. You ask your AI assistant to "audit my changes" and get back a compliance table in the chat, or an HTML report you open in a browser.

• Local. No API key, no account, no network calls. It reads your git diff and your rule files, nothing else.
• Any repository, any language. Nothing to configure per repo; the rules come from the files already in it.
• Only relevant rules. A Python rule is not checked against a TypeScript file, and a testing rule is not checked against a migration.

Demo

https://github.com/user-attachments/assets/3414f3aa-ac69-45a1-a277-c8e9797ff5da

The HTML report for a sample audit:

Requirements

• Node.js 18.17 or newer
• Git on your PATH
• An MCP client: Claude Code, Claude Desktop, Cursor, VS Code, Kiro, Windsurf or any other

Install

There is nothing to download by hand. Your MCP client starts the server with npx, which fetches the package the first time.

Claude Code

claude mcp add repo-auditor --scope user -- npx -y mcp-repo-auditor

On Windows (not WSL), npx has to be started through cmd:

claude mcp add repo-auditor --scope user -- cmd /c npx -y mcp-repo-auditor

--scope user makes it available in every project. Start a new Claude Code session, then run /mcp to confirm repo-auditor is connected.

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "repo-auditor": {
      "command": "npx",
      "args": ["-y", "mcp-repo-auditor"]
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "repo-auditor": {
      "command": "npx",
      "args": ["-y", "mcp-repo-auditor"]
    }
  }
}

Kiro

Add to .kiro/settings/mcp.json (workspace) or ~/.kiro/settings/mcp.json (all workspaces):

{
  "mcpServers": {
    "repo-auditor": {
      "command": "npx",
      "args": ["-y", "mcp-repo-auditor"],
      "autoApprove": ["audit_repo_compliance", "render_compliance_report"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json, using the same block as Cursor.

Claude Desktop

Config file: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).

Claude Desktop does not run inside your repository, so tell the server where it is:

{
  "mcpServers": {
    "repo-auditor": {
      "command": "npx",
      "args": ["-y", "mcp-repo-auditor"],
      "env": { "MCP_REPO_AUDITOR_ROOT": "/path/to/your/repo" }
    }
  }
}

You can also leave env out and name the repository in your request: "audit the working changes in /path/to/your/repo".

Windows note for JSON configs

If the server fails to start on Windows with npx as the command, launch it through cmd:

{ "command": "cmd", "args": ["/c", "npx", "-y", "mcp-repo-auditor"] }

Use

Open your repository in the client and ask in plain words:

First run: four questions

The first time you audit a repository, you are asked:

1. Results format: Markdown table in the chat, or an HTML report file.
2. Report folder (HTML only): an absolute path, or a word like downloads, desktop or documents. Blank uses the system temp folder.
3. Extra rule files: files or folders to audit against besides the ones found automatically. Blank means none.
4. Base branch for branch audits. Blank means the repository's default branch (main, master, ...), which is found automatically.

Clients that support MCP forms (Claude Code does) show these as a form. In other clients the assistant asks them in the chat.

Your answers are saved per repository in ~/.mcp-repo-auditor/preferences.json, never inside the repository. To change them, say "reconfigure the repo auditor". To override the format once, say it in the request: "audit my working changes as an HTML report".

Large changes

MCP clients limit how much a tool may return in one result (Claude Code allows 25,000 tokens by default), so a big change cannot be handed to the assistant in one piece. Nothing is cut or sampled. The change is audited in parts, and you decide how before anything runs.

1. You see the plan first. The audit stops and shows how the change is divided:

   CodeCopy

   This change is too large for one result: 3 file(s), 4,201 added line(s),
   about 107,000 tokens to read (estimate). It will be audited in 6 parts,
   every line in exactly one of them:
     Part 1 (+743 lines): src/big-one.ts (lines 1-743)
     Part 2 (+720 lines): src/big-one.ts (lines 744-1463)
     ...
     Part 6 (+587 lines): src/big-two.ts (lines 615-1200), src/small.ts
   Not audited: 1 file(s) (lockfiles, binaries, generated or deleted files).
   

2. You choose. Audit every part one after another, every part in parallel (see below), only some parts ("just parts 1 and 2"), only some files or folders ("only src/api"), or cancel. In Claude Code this is a form; in other clients the assistant asks in the chat.

3. You watch it run. Each part is reported as it is judged. In Markdown you get that part's table and its counts. For HTML, the report file is rewritten after every part and you get a one-line progress note.

4. You always know what was covered. The final result says which parts were audited. An HTML report with parts still open is marked INCOMPLETE, lists the files not audited yet, and tags files that were only partly covered. It never shows COMPLIANT for a partial audit.

A file too big for one part continues in the next one with its line numbers intact. All parts come from one snapshot of the diff taken when the plan is made, so edits you make while the audit runs do not shift the parts.

A bigger change takes proportionally more time and tokens; the estimate in the plan is there so you can narrow the audit instead.

One after another, or in parallel

In parallel mode every subagent sends its verdicts to the server. The server adds them up and builds the combined result: the HTML report, or the finished Markdown table, which the assistant prints as it is. If a subagent fails, the result names the part that is still open and the assistant retries it once. If the client cannot run subagents, the assistant says so and audits the parts one after another instead.

What you get

Markdown (in the chat):

• Compliance Matrix: one row per file and rule that passed, failed or could not be judged.
• Violations: each failure with the line, the reason and a fix.
• Rules Considered: what each rule key (R1, R2, ...) means and which file it came from.
• Result: counts and a verdict.

HTML (a single self-contained file; the assistant replies with its path):

• A verdict and pass / fail / skipped / not-applicable counts.
• A Findings tab: results per file, the offending lines, and suggested fixes shown as a code diff.
• A Rules tab: every rule key with its full text and source.
• Filters by status and by text; light and dark mode.

Where rules come from

These are found automatically. A rule file you keep out of git (a personal CLAUDE.md, an ignored .cursor/ folder) is still used. Only AGENTS.md / CLAUDE.md files found inside ignored subfolders, such as a virtualenv or vendored package, are skipped.

Also:

• Notes that only describe the project, such as a list of build commands or a folder layout, are not treated as rules. A bullet in those sections still counts when it is worded as a rule ("always", "never", "must", "only", ...).
• An AGENTS.md or CLAUDE.md inside a subfolder applies only to files in that subfolder.
• If a rule file points at another one ("follow the guidelines in docs/standards/"), that target is read too.
• Scoping written in the files is respected: Cursor globs / alwaysApply, Copilot applyTo, Kiro inclusion / fileMatchPattern, Windsurf trigger / globs.
• Rules kept somewhere else? Name them in setup question 3, or in the request: "audit my changes, also use docs/engineering-rules.md".

How it works

1. Reads the git diff for the scope you chose.
2. Finds the rule files and splits them into single rules.
3. Maps each changed file to the rules that apply to it, by language, path, glob and the content of the changed lines.
4. Hands the diff, the rules and the mapping to your AI assistant, with instructions to judge every pair strictly.
5. For HTML, the assistant sends its verdicts back and the server writes the report.

A change too large for one result goes through steps 4 and 5 once per part; see Large changes.

Steps 1 to 3 and the report are plain code and take well under a second. The judging in step 4 is done by your assistant's model, so its speed and quality depend on the model you use.

Tools

You do not normally call these yourself; the assistant picks them.

Settings

Optional environment variables, set in the env block of your MCP config.

If your client accepts larger tool results, raise MCP_REPO_AUDITOR_MAX_CHARS and big changes need fewer parts. The older line and file limits (MAX_FILES, MAX_LINES_PER_FILE, MAX_TOTAL_LINES) are gone: they cut the diff, and parts replace them.

Two things are still left out, and the audit says so each time: more than 80 rules for one file (the highest-priority 80 are kept), and the tail of a single line longer than 2,000 characters.

Troubleshooting

To update, restart your client; npx -y mcp-repo-auditor@latest in the config always fetches the newest version.

Privacy

The server itself sends nothing anywhere. The diff and the rules it returns go to whichever AI assistant you are using, as with any other code you show it.

Development

npm install        # installs and builds
npm run build      # -> dist/
npm test           # builds, then runs the end-to-end tests
npm run inspect    # try the tools in the MCP Inspector

License

MIT