# claude-setup-audit-mcp

An MCP server that tells you why Claude Code keeps ignoring your instructions, then helps you fix it.

Three tools:

`audit_claude_setup` scores a repo's Claude Code setup from 0 to 100 and lists what to fix in order. It checks whether CLAUDE.md exists, whether it lists commands and do-not rules, whether it is short enough to be read, whether it leaks a credential, whether your subagents have proper frontmatter and restricted tools, whether you have skills, hooks, and an .mcp.json, and whether settings.local.json is git-ignored.

`scaffold_agent` writes a complete `.claude/agents/<name>.md` from a one-line job description, with frontmatter, a procedure, a report format, and do-not rules.

`hook_recipes` returns three settings.json hooks that work on Windows and macOS: a formatter after every edit, a guard that blocks destructive shell commands, and a bell when Claude stops and is waiting on you.

## Install

Add to `.mcp.json` in your repo (or to Claude Code with `claude mcp add`):

```json
{
  "mcpServers": {
    "claude-setup-audit": {
      "command": "npx",
      "args": ["-y", "claude-setup-audit-mcp"]
    }
  }
}
```

On Windows, use `"command": "cmd", "args": ["/c", "npx", "-y", "claude-setup-audit-mcp"]`.

Then in Claude Code: "audit this repo's Claude setup". It calls the tool and reads you the findings.

## Run from source

```
npm install
npm run build
npm run smoke   # audits ../claude-code-starter-pack and checks all three tools
```

No network calls, no telemetry. It reads files under the path you give it and nothing else.

## What the score means

Under 40: Claude is working from nothing. Start with CLAUDE.md and the commands section.
40 to 70: the basics exist but nothing is enforced. Add hooks and restrict agent tools.
Over 70: the setup is sound. The remaining gains come from agents written for your specific repeated jobs, which is what I do for teams. Details at github.com/shadrach16.

A ready-made starting point is the [claude-code-starter-pack](https://github.com/shadrach16/claude-code-starter-pack).

MIT licensed. Built by Tunde Oluwamo.