RepoGuard MCP Server

Zero-dependency Clean Architecture linter and context generator MCP server for Claude Desktop, Claude Code, and Cursor.

Documentation

๐Ÿ›ก๏ธ RepoGuard

RepoGuard Banner

The Architecture Guardian for AI-Assisted Codebases.
Stop AI from turning your repository into architectural spaghetti across TypeScript, Python, Golang, and Rust.

RepoGuard on Product Hunt

GitHub Stars CI & Architecture Guard npm version downloads RepoGuard MCP server Listed on mcpservers.org Marketplace License Live Playground

v1.7.1: init is 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:

  1. Bypass Architectural Layers: Run raw database queries (Prisma, Drizzle, SQLAlchemy, GORM, SQLx, Diesel) directly inside UI components or HTTP handlers.
  2. Reinvent Existing Helpers: Write duplicate date/string utilities instead of importing from /utils or shared packages.
  3. Escape Type Safety & Error Handling: Scatter : any in TypeScript, discard errors with _ = err in Go, or use panic-prone .unwrap() in Rust production code.
  4. 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

CommandDescription
npx repoguard-rules initTemporarily unavailable, including all options.
npx repoguard-rules auditEvaluates entire codebase and returns an Architectural Health Score (A+ to F).
npx repoguard-rules audit --format=sarifGenerates standard OASIS SARIF v2.1.0 for GitHub Code Scanning integration.
npx repoguard-rules audit --format=jsonOutputs machine-readable JSON for custom CI/CD pipelines.
npx repoguard-rules diffAudits uncommitted git diffs against architectural rules in real-time.
npx repoguard-rules fixAnalyzes codebase and generates actionable before/after architectural refactoring suggestions.
npx repoguard-rules mcpLaunches the Model Context Protocol stdio server for AI agents.
npx repoguard-rules hook installConfigures local .git/hooks/pre-commit to prevent rule breaches.
npx repoguard-rules rulesDisplays 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 IDCategorySeverityGuardrail Enforced
RULE-01ArchitectureErrorProhibits raw ORM/DB queries in UI components and Controllers (TS/JS).
RULE-PY-01ArchitectureWarning / CriticalEnforces FastAPI layer separation; forbids direct DB queries and raw commits (db.commit()) inside route handlers.
RULE-GO-01ArchitectureWarning / CriticalEnforces Clean Architecture in Go; prohibits raw database/GORM operations inside Gin, Fiber, or Echo HTTP handlers.
RULE-GO-02Error HandlingWarningFlags unchecked errors silenced via blank identifier (_ = err) in Go.
RULE-RS-01Error HandlingWarningFlags unsafe .unwrap() or .expect() in production Rust logic that cause thread crashes and panics.
RULE-RS-02ArchitectureWarningEnforces Clean Architecture in Rust (Axum, Actix-web, Rocket); forbids direct SQLx / Diesel queries inside route handlers.
RULE-02SecurityCriticalFlags hardcoded secrets, private keys, and API tokens.
RULE-SEC-01SecurityCriticalDetects provider-format AI/cloud tokens and credential-bearing database URLs in source and supported config files.
RULE-SEC-02SecurityCriticalFlags unencrypted private cryptographic key headers (BEGIN PRIVATE KEY).
RULE-09SecurityCriticalFlags private secrets exposed via public prefixes (NEXT_PUBLIC_*SECRET*, VITE_*SECRET*).
RULE-03Type SafetyWarningForbids lazy : any and as any escape hatches in TypeScript.
RULE-04Code QualityInfoEnforces structured logging instead of raw console.log.
RULE-05Next.js / SSRErrorPrevents hydration mismatch from browser globals (window/localStorage).
RULE-06SecurityCriticalDetects SQL injection hazards in raw query string interpolations.
RULE-07API DesignWarningEnforces schema validation (Zod/Pydantic) on incoming request payloads.
RULE-08DRY PrincipleInfoPrevents 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:

TierPriceIdeal ForWhat's Included
Open Source$0 (Free Forever)Solo builders & public reposUnlimited local CLI scans, .cursorrules, CLAUDE.md, MCP Server, pre-commit hooks, all 16 built-in rules
Developer Pro$12 / monthIndependent engineers & contractorsUnlimited private repositories, automated PR Review Bot, custom rules engine, secret leak detector
Engineering Team$39 / monthStartups & engineering orgsUp 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

Star History Chart


๐Ÿ‘ฅ Contributors & Community

Special thanks to the open source engineers contributing to RepoGuard:

๐ŸŒŸ Support & Community

If RepoGuard helps keep your AI coding clean, consider giving this repository a โญ Star!