# mcp-auditor (`@roots-rs/mcp-auditor`)

> **Enforce mandatory pre-implementation audits for AI coding agents before writing code.**

`mcp-auditor` is a high-performance Rust CLI binary and multi-agent plugin system designed to prevent AI coding agents (Claude Code, Antigravity, Cursor) from writing redundant code or reinventing existing components.

---

## Quickstart

### 1. Installation & Initialization

#### Option A: via `npx` (Zero Rust Setup Required)
```bash
# Auto-detect and configure mcp-auditor for all agents in current workspace
npx @roots-rs/mcp-auditor init

# Target a specific agent platform
npx @roots-rs/mcp-auditor init --agent claude
npx @roots-rs/mcp-auditor init --agent antigravity
npx @roots-rs/mcp-auditor init --agent cursor
```

#### Option B: via Cargo (Rust Crate)
```bash
cargo install mcp-auditor

# Run initialization in target directory
mcp-auditor init
```

### 2. Usage in AI Agent Interface

Trigger the audit workflow by using the `/mcp-audit` command followed by your task description:

```bash
/mcp-audit build a user authentication service
```

---

## The Problem

AI coding agents often jump straight to writing new files or custom utilities without checking:
1. Active **Model Context Protocol (MCP)** tools and servers connected to the environment.
2. Pre-existing helper modules, schemas, and utility functions in the codebase.

This leads to code duplication, unused dependencies, and architectural drift.

## The Solution

`mcp-auditor` intercepts the development workflow with a mandatory **Pre-Implementation Audit Phase**:
1. **Inspects**: Queries connected MCP servers/tools and local workspace components.
2. **Reports**: Generates a structured **Component & MCP Reuse Report**.
3. **Hard Stop**: Enforces an explicit hard stop requiring human approval before any files are created, modified, or executed.

---

## Features

- **Audit Connected MCP Tools**: Automatically discovers active MCP tools (databases, external APIs, cloud services) relevant to the task.
- **Audit Workspace Components**: Inspects existing utility libraries, domain models, and dependencies to maximize code reuse.
- **Hard Stop Enforcement**: Mandates that the AI agent MUST NOT write code or run state-modifying shell commands until explicit permission is granted.
- **Multi-Agent Support**: Compatible with Claude Code, Antigravity / Gemini Code Assist, Cursor, and Aider.
- **Dual Distribution**: Installable via `npx` (Node/TypeScript launcher) or `cargo` (compiled Rust binary).

---

## Compatibility

`@roots-rs/mcp-auditor` provides **First-Class Support** for the following agent environments:

| Agent / Framework | Integration Path | Support Level |
| :--- | :--- | :---: |
| **Claude Code** | `.claude-plugin/plugin.json` & `skills/mcp-audit/SKILL.md` | First-Class |
| **Antigravity / Gemini** | `.agents/skills/mcp-audit/SKILL.md` | First-Class |
| **Cursor** | `.cursorrules` / `AGENTS.md` | First-Class |
| **Aider & AGENTS.md Standard** | `AGENTS.md` | First-Class |

---

## Example Generated Audit Report

When `/mcp-audit` is invoked, the agent produces a structured report before asking for approval:

```markdown
# Component & MCP Reuse Report

## Task Overview
Build a user authentication service with JWT handling.

## Reusable Components & MCP Tools
- **MCP Tools**: `firebase-mcp-server` (auth provider & user store integration)
- **Project Modules / APIs**: `src/auth/jwt.rs` (pre-existing token parsing utility)

## Gaps Requiring Custom Implementation
- Password hashing validator module (`src/auth/password.rs`)

## Proposed Step-by-Step Strategy
1. Re-use `src/auth/jwt.rs` for token verification.
2. Delegate user lookup to connected `firebase-mcp-server`.
3. Implement missing password validation helper.

---
What would you like me to do next?
1. Proceed with implementation using firebase-mcp-server + JWT token helper (Recommended)
2. Review detailed API schema before granting permission
3. Other (specify)
```

## License

[MIT](LICENSE) © roots-rs