# mcp-repo-auditor [Health: Active]

**Category:** 🔄 Version Control  
**Repository:** https://github.com/nikhilgupta15/mcp-repo-auditor  
**GitHub Stars:** 0  
**npm Downloads (last month):** 658  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-repo-auditor

## Description
Local MCP server that audits your git changes against the repo's own AI rules (AGENTS.md, CLAUDE.md, .cursorrules, Copilot, Kiro, skills) and returns a compliance table or an HTML report.

## Tools
Capabilities this server exposes over MCP:

- **audit_repo_compliance** — Deterministically collects the local git diff (staged, working tree, or branch vs base), discovers the repo's steering/instruction files, extracts atomic rules, and maps only the relevant rules to each changed file. Returns a JSON payload {meta, changed_files, discovered_rules, file_rule_mappings, system_evaluator_prompt}. After calling, act as the compliance judge described in system_evaluator_prompt. A change too large for one result returns plan_required instead: show the user the plan, let them choose, then request the parts one at a time with `part`.
- **render_compliance_report** — Writes a self-contained HTML report for the most recent audit_repo_compliance call in this session from your verdicts, and returns its path. Rule text, offending code and N/A counts are filled in by the server. In a multi-part audit, call it once per part with `part`: each call adds that part's verdicts, rewrites the same report file (which states the parts still open) and returns next_step. The file goes to the report folder the user chose at setup, or the system temp directory if they chose none.
- **audit_status** — Reports where the most recent audit_repo_compliance audit of this session stands: which parts have verdicts, the totals and the verdict so far. After a parallel audit it also returns the combined result: the report path (HTML) or the finished Markdown table. Call it when the subagents of a parallel audit have returned, or when the user asks how far an audit got.
- **configure_audit** — Saves the user's audit preferences for one repository (report format, HTML report folder, extra rule files, base branch). Call it with the user's own answers after audit_repo_compliance returns setup_required, or when they ask to change a preference. Only the fields you pass are changed. Preferences are stored in the user's home directory, not in the repository.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What mcp-repo-auditor does

The mcp-repo-auditor MCP server audits repository changes against the instruction files already present in the project. It can discover guidance such as `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, Copilot instructions, Kiro steering files, and skills, while allowing additional rule paths to be supplied. Rules are applied selectively, so guidance intended for one language or file type is not automatically evaluated against unrelated files.

The server supports staged changes, working-tree changes, and the commits on a branch since its base branch. Audits can be narrowed to files, folders, or globs. Results can appear as a Markdown compliance matrix in the conversation or as a self-contained HTML report with verdict counts, findings, source rules, affected lines, and suggested fixes.

This places mcp-repo-auditor in the Developer Tools category for teams that want an AI assistant to check its own code changes against project-specific conventions before review.

## How it works

The MCP client starts the server with `npx`, and the server reads the selected Git diff plus applicable rule files from the repository. It does not require an API key, account, or network connection. On the first audit for a repository, the assistant asks for the preferred output format, an optional HTML report directory, extra rule files, and the base branch used for branch audits. These preferences are stored per repository in `~/.mcp-repo-auditor/preferences.json`, outside the repository.

Large changes are divided into parts after the server presents an audit plan. You can run every part sequentially, select particular parts or paths, or request parallel processing when the client can start subagents. `audit_status` reports completed parts and totals, while the server combines verdicts from parallel work. An incomplete audit remains explicitly incomplete rather than being reported as compliant.

## Setup and configuration

Requirements are Node.js 18.17 or newer, Git on `PATH`, and an MCP client. Installation uses `npx -y mcp-repo-auditor`; there is no manual download step. Claude Code, Cursor, VS Code, Kiro, Windsurf, and Claude Desktop configuration examples are provided by the project.

Claude Desktop may need `MCP_REPO_AUDITOR_ROOT` because it does not run inside the repository. Alternatively, the repository path can be included in the request. On Windows, configurations that cannot launch `npx` directly should invoke it through `cmd /c`.

## Tools and capabilities

The mcp-repo-auditor MCP server exposes four tools:

- `audit_repo_compliance` runs an audit or returns the plan for a large change. It accepts the change scope, branch, paths, audit part, parallel mode, extra rule paths, repository path, and report preference.
- `render_compliance_report` writes or refreshes the HTML report from the assistant’s findings.
- `audit_status` shows which parts have verdicts and the accumulated totals, including the combined result after parallel auditing.
- `configure_audit` saves or updates repository-specific preferences.

Markdown output includes one row per file and rule, violations with locations and fixes, the rules considered, counts, and an overall verdict. HTML output includes verdict counts, findings, rule details, and suggested code changes.

## Limitations and notes

The server audits the Git snapshot selected when the plan is created. Later edits do not move files between planned parts. Lockfiles, binaries, generated files, and deleted files may be excluded from large-audit parts, and a file may be only partly covered when its content spans multiple parts.

Parallel auditing depends on the MCP client’s ability to start subagents that can use the tools. If that is unavailable, the assistant falls back to sequential processing. Parallel mode can reduce elapsed time but uses more tokens at once. Large changes also take more time and tokens; narrowing the audit by path can reduce that cost.

_Full upstream README: https://allmcps.com/mcp/mcp-repo-auditor/readme_