RepoGuard MCP Server
Zero-dependency Clean Architecture linter and context generator MCP server for Claude Desktop, Claude Code, and Cursor.
Documentation
๐ก๏ธ RepoGuard
The Architecture Guardian for AI-Assisted Codebases.
Stop AI from turning your repository into architectural spaghetti across TypeScript, Python, Golang, and Rust.
v1.7.1:
initis temporarily unavailable while its filesystem safety is being redesigned. Other commands remain available.New in v1.7.0: Rust panic safety, expanded secret detection, and MCP Tools + Resources + Prompts.
๐ฎ Try it in your browser: RepoGuard Interactive Playground โ Audit code snippets in real-time with zero install.
โก The Problem
AI coding assistants (Cursor, GitHub Copilot, Claude Code, Windsurf) write 300 lines of code in seconds. However, without strict repository guardrails, they frequently introduce AI Code Rot:
- Bypass Architectural Layers: Run raw database queries (Prisma, Drizzle, SQLAlchemy, GORM, SQLx, Diesel) directly inside UI components or HTTP handlers.
- Reinvent Existing Helpers: Write duplicate date/string utilities instead of importing from
/utilsor shared packages. - Escape Type Safety & Error Handling: Scatter
: anyin TypeScript, discard errors with_ = errin Go, or use panic-prone.unwrap()in Rust production code. - Leak Sensitive Secrets: Hardcode AI/cloud provider tokens, embed database credentials in connection URLs, or expose secrets with the
NEXT_PUBLIC_prefix.
RepoGuard acts as an automated architecture supervisor: it analyzes code and diffs, runs an MCP server with Tools, Resources, and Prompts, and can audit Pull Requests with a manually configured workflow. Context-file generation is temporarily unavailable in v1.7.1.
๐ Quickstart
Audit a repository (zero installation required):
npx repoguard-rules audit
init is temporarily unavailable in v1.7.1, including --dry-run, --force, and --with-ci. It exits with an error before scanning or changing project files. It does not generate context files or a CI workflow. Safe initialization will be addressed separately.
You can also install globally with npm install -g repoguard-rules, then run repoguard audit. Review results locally. Hook installation is a separate command and modifies the repository.
๐ค Native Model Context Protocol (MCP) Server
RepoGuard ships with a built-in, zero-dependency MCP Server implementing the full 3-pillar standard (Tools, Resources, and Prompts) for Claude Desktop, Claude Code, Cursor, and Windsurf.
Connect to Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"repoguard": {
"command": "npx",
"args": ["-y", "repoguard-rules@1.7.1", "mcp"]
}
}
}
Connect to Cursor (~/.cursor/mcp.json or .cursor/mcp.json):
{
"mcpServers": {
"repoguard": {
"command": "npx",
"args": ["-y", "repoguard-rules@1.7.1", "mcp"]
}
}
}
MCP Capabilities:
- ๐ ๏ธ Tools:
repoguard_audit: Full repository audit against 16 architectural guardrails.repoguard_diff: Real-time audit of uncommitted git changes to catch AI drift before commit.repoguard_get_rules: Returns all 16 active architectural rules to prevent AI hallucination.repoguard_fix: Analyzes code snippets and returns actionable refactoring plans.
- ๐ฆ Resources:
repoguard://rules: Direct JSON access to all architectural rules and remediation advice.repoguard://health: Real-time codebase health score and violation breakdown.
- ๐ก Prompts:
architectural_review: Pre-configured prompt instructing AI agents to review diffs against Clean Architecture.clean_architecture_refactor: Pre-configured prompt to decouple controllers into Service and Repository layers.
๐ ๏ธ CLI Commands & Formats
| Command | Description |
|---|---|
npx repoguard-rules init | Temporarily unavailable, including all options. |
npx repoguard-rules audit | Evaluates entire codebase and returns an Architectural Health Score (A+ to F). |
npx repoguard-rules audit --format=sarif | Generates standard OASIS SARIF v2.1.0 for GitHub Code Scanning integration. |
npx repoguard-rules audit --format=json | Outputs machine-readable JSON for custom CI/CD pipelines. |
npx repoguard-rules diff | Audits uncommitted git diffs against architectural rules in real-time. |
npx repoguard-rules fix | Analyzes codebase and generates actionable before/after architectural refactoring suggestions. |
npx repoguard-rules mcp | Launches the Model Context Protocol stdio server for AI agents. |
npx repoguard-rules hook install | Configures local .git/hooks/pre-commit to prevent rule breaches. |
npx repoguard-rules rules | Displays all 16 built-in architectural rules and descriptions. |
Sensitive diagnostic output
RepoGuard scans source locally but does not echo raw source excerpts in CLI audit/fix reports, PR review comments, JSON, or MCP health results. JSON retains the codeSnippet field for compatibility, with a fixed [source excerpt withheld to avoid exposing credentials] value. Rule IDs, file paths, line numbers, severity, and safe explanations and suggestions remain available (paths that match a credential pattern are withheld); open the referenced line in your own editor to inspect it. This reduces the risk of copying a detected credential into logs or a persistent PR comment; it does not guarantee that every possible secret will be detected in source code.
MCP prompt templates omit user-provided code when they recognize a credential pattern. Do not paste credentials into prompts, filenames, or third-party services; revoke any real credential already committed to a repository. No scan removes secrets from git history.
Ignoring Files & Folders (.repoguardignore)
Add a .repoguardignore file to your root directory to skip specific files or directories:
# .repoguardignore
legacy/
migrations/
test/fixtures/
๐ก๏ธ Built-in Architectural Rules (16 Active Guardrails)
| Rule ID | Category | Severity | Guardrail Enforced |
|---|---|---|---|
| RULE-01 | Architecture | Error | Prohibits raw ORM/DB queries in UI components and Controllers (TS/JS). |
| RULE-PY-01 | Architecture | Warning / Critical | Enforces FastAPI layer separation; forbids direct DB queries and raw commits (db.commit()) inside route handlers. |
| RULE-GO-01 | Architecture | Warning / Critical | Enforces Clean Architecture in Go; prohibits raw database/GORM operations inside Gin, Fiber, or Echo HTTP handlers. |
| RULE-GO-02 | Error Handling | Warning | Flags unchecked errors silenced via blank identifier (_ = err) in Go. |
| RULE-RS-01 | Error Handling | Warning | Flags unsafe .unwrap() or .expect() in production Rust logic that cause thread crashes and panics. |
| RULE-RS-02 | Architecture | Warning | Enforces Clean Architecture in Rust (Axum, Actix-web, Rocket); forbids direct SQLx / Diesel queries inside route handlers. |
| RULE-02 | Security | Critical | Flags hardcoded secrets, private keys, and API tokens. |
| RULE-SEC-01 | Security | Critical | Detects provider-format AI/cloud tokens and credential-bearing database URLs in source and supported config files. |
| RULE-SEC-02 | Security | Critical | Flags unencrypted private cryptographic key headers (BEGIN PRIVATE KEY). |
| RULE-09 | Security | Critical | Flags private secrets exposed via public prefixes (NEXT_PUBLIC_*SECRET*, VITE_*SECRET*). |
| RULE-03 | Type Safety | Warning | Forbids lazy : any and as any escape hatches in TypeScript. |
| RULE-04 | Code Quality | Info | Enforces structured logging instead of raw console.log. |
| RULE-05 | Next.js / SSR | Error | Prevents hydration mismatch from browser globals (window/localStorage). |
| RULE-06 | Security | Critical | Detects SQL injection hazards in raw query string interpolations. |
| RULE-07 | API Design | Warning | Enforces schema validation (Zod/Pydantic) on incoming request payloads. |
| RULE-08 | DRY Principle | Info | Prevents AI assistants from duplicating existing common utility helpers. |
๐ค GitHub Action & Security Integration
RepoGuard dogfoods its own architecture on every push. Workflow generation via init is unavailable in v1.7.1. Do not use the v1.7.0 Action for PR comments containing sensitive code. The example below is this repository's own CI job:
# .github/workflows/ci.yml
name: CI & Architecture Guard
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
audit:
name: Unit Tests & Dogfood Audit
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
- name: Run Architecture & Stack Tests
run: npm test
- name: Dogfood Audit (RepoGuard on RepoGuard)
run: node bin/repoguard.js audit --strict
GitHub Code Scanning (SARIF v2.1.0):
- run: npx repoguard-rules audit --format=sarif > repoguard.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: repoguard.sarif
๐ Plans & Enterprise Upgrades
RepoGuard is 100% free and open-source for public repositories and local development. For automated CI/CD PR enforcement, private teams, and custom architectural rule engines:
| Tier | Price | Ideal For | What's Included |
|---|---|---|---|
| Open Source | $0 (Free Forever) | Solo builders & public repos | Unlimited local CLI scans, .cursorrules, CLAUDE.md, MCP Server, pre-commit hooks, all 16 built-in rules |
| Developer Pro | $12 / month | Independent engineers & contractors | Unlimited private repositories, automated PR Review Bot, custom rules engine, secret leak detector |
| Engineering Team | $39 / month | Startups & engineering orgs | Up to 5 devs, GitHub Org-wide CI/CD merge blocker, SOC2 architecture audit logs, Slack/Discord alerts |
๐ Subscribe to Developer Pro ($12/mo) โข Upgrade Team ($39/mo) โข ๐ง๐ท Pagar no PIX (R$ 67 ร vista)
๐ Star History
๐ฅ Contributors & Community
Special thanks to the open source engineers contributing to RepoGuard:
- @taylormatematica-beep (Lead Maintainer & Author)
- @NihalPN โ Authored
RULE-PY-01& FastAPI architectural guardrails (PR #3)
๐ Support & Community
- ๐ Documentation & Live Hub: https://taylormatematica-beep.github.io/repoguard/
- ๐ฆ NPM Registry: https://www.npmjs.com/package/repoguard-rules
- ๐ฑ Product Hunt: https://www.producthunt.com/products/repoguard
If RepoGuard helps keep your AI coding clean, consider giving this repository a โญ Star!