RepoGuard MCP Server

Servidor MCP de linter de Clean Architecture e gerador de contexto sem dependências para Claude Desktop, Claude Code e Cursor.

GitHub

Experimente este MCPPatrocinado

Documentação

🛡️ RepoGuard

RepoGuard Banner

O Guardião de Arquitetura para Bases de Código Assistidas por IA.
Impedir que a IA transforme seu repositório em espaguete arquitetural em TypeScript, Python e Golang em ~12ms.

🎮 Experimente no seu navegador: Playground Interativo do RepoGuard — Audite trechos de código em tempo real sem instalação.

⚡ O Problema

Assistentes de codificação com IA (Cursor, GitHub Copilot, Claude Code, Windsurf) escrevem 300 linhas de código em segundos. No entanto, sem guardrails rigorosos de repositório, eles frequentemente introduzem Podridão de Código por IA:

Ignoram Camadas Arquiteturais: Executam consultas brutas de banco de dados (Prisma, Drizzle, SQLAlchemy, GORM) diretamente dentro de componentes de UI ou manipuladores HTTP.
Reinventam Helpers Existentes: Escrevem utilitários duplicados de data/string em vez de importar de /utils ou pacotes compartilhados.
Fogem da Segurança de Tipos e Tratamento de Erros: Espalham : any em TypeScript ou descartam erros com _ = err em Go para passar na compilação rapidamente.
Vazam Segredos Sensíveis: Codificam chaves de API fictícias ou prefixam segredos privados com NEXT_PUBLIC_, empacotando-os em JS do lado do cliente.

O RepoGuard atua como um supervisor de arquitetura automatizado: ele gera arquivos de contexto .cursorrules, CLAUDE.md e .windsurfrules estritos e personalizados, verifica diffs de pré-commit em ~12ms, executa um servidor MCP para consulta ao agente em tempo real e realiza auditorias inline em cada Pull Request.

🚀 Início Rápido

Execute diretamente em qualquer repositório (sem necessidade de instalação):

npx repoguard-rules init

Ou instale globalmente:

npm install -g repoguard-rules
repoguard init

O que acontece em 2 segundos:

🔍 Detecta automaticamente sua stack tecnológica (Next.js, NestJS, Express, FastAPI, Django, Gin, Fiber, Prisma, GORM, etc.).
📝 Gera .cursorrules personalizado (para Cursor AI).
🤖 Gera um CLAUDE.md abrangente (para Claude Code).
🌊 Gera .windsurfrules (para Windsurf IDE).
🛡️ Gera .github/copilot-instructions.md (para GitHub Copilot).
⚙️ Configura hooks de guarda de pré-commit e fluxo de trabalho de CI.

🤖 Servidor MCP Nativo (Model Context Protocol)

O RepoGuard v1.6.1 apresenta um Servidor MCP stdio JSON-RPC 2.0 sem dependências. Conecte-o ao Cursor, Claude Desktop ou qualquer cliente de codificação compatível com MCP para que seu agente de IA possa auditar código e verificar guardrails de forma autônoma:

1. Configuração do Cursor (`~/.cursor/mcp.json` ou `.cursor/mcp.json`):

{
  "mcpServers": {
    "repoguard": {
      "command": "npx",
      "args": ["-y", "repoguard-rules@1.6.1", "mcp"]
    }
  }
}

2. Configuração do Claude Desktop (`claude_desktop_config.json`):

{
  "mcpServers": {
    "repoguard": {
      "command": "npx",
      "args": ["-y", "repoguard-rules@1.6.1", "mcp"]
    }
  }
}

Ferramentas MCP Disponíveis:

repoguard_audit: Realiza uma auditoria arquitetural abrangente da raiz do projeto e retorna métricas de saúde e nota (A+ a F).
repoguard_get_rules: Recupera todos os guardrails integrados para TypeScript, Python e Go para injeção de contexto em prompts de LLM.
repoguard_analyze_diff: Analisa um diff ou trecho de código antes de gravar em disco, detectando violações antes que aconteçam.

🛠️ Comandos CLI e Formatos

Comando	Descrição
`npx repoguard-rules init`	Escaneia a base de código e gera arquivos de contexto de IA personalizados.
`npx repoguard-rules audit`	Avalia toda a base de código e retorna uma Pontuação de Saúde Arquitetural (A+ a F).
`npx repoguard-rules mcp`	Inicia o servidor stdio Model Context Protocol para Claude e Cursor.
`npx repoguard-rules fix`	Inspeciona interativamente violações e gera planos de refatoração.
`npx repoguard-rules audit --format=sarif`	Gera SARIF OASIS v2.1.0 padrão para integração com GitHub Code Scanning.
`npx repoguard-rules audit --format=json`	Gera JSON legível por máquina para pipelines de CI/CD personalizados.
`npx repoguard-rules diff`	Audita diffs de git não commitados contra regras arquiteturais em tempo real.
`npx repoguard-rules hook install`	Configura `.git/hooks/pre-commit` local para prevenir violações de regras.
`npx repoguard-rules rules`	Exibe todas as 12 regras arquiteturais integradas e suas descrições.

Ignorando Arquivos e Pastas (`.repoguardignore`)

Adicione um arquivo .repoguardignore ao diretório raiz para pular arquivos ou diretórios específicos:

# .repoguardignore
legacy/
migrations/
test/fixtures/

🛡️ Regras Arquiteturais Integradas

ID da Regra	Categoria	Severidade	Guardrail Aplicado
RULE-01	Arquitetura	Erro	Proíbe consultas ORM/DB brutas em componentes de UI e Controllers (TS/JS).
RULE-PY-01	Arquitetura	Aviso / Crítico	Aplica separação de camadas FastAPI; proíbe consultas diretas ao banco e commits brutos (`db.commit()`) dentro de manipuladores de rota.
RULE-GO-01	Arquitetura	Aviso / Crítico	Aplica Clean Architecture em Go; proíbe operações brutas de banco/GORM dentro de manipuladores HTTP Gin, Fiber ou Echo.
RULE-GO-02	Tratamento de Erros	Aviso	Sinaliza erros não verificados silenciados via identificador em branco (`_ = err`) em Go.
RULE-02	Segurança	Crítico	Sinaliza segredos codificados, chaves privadas e tokens de API.
RULE-09	Segurança	Crítico	Sinaliza segredos privados expostos via prefixos públicos (`NEXT_PUBLIC_SECRET`, `VITE_SECRET`).
RULE-03	Segurança de Tipos	Aviso	Proíbe escapes preguiçosos `: any` e `as any` em TypeScript.
RULE-04	Qualidade de Código	Info	Aplica registro estruturado em vez de `console.log` bruto.
RULE-05	Next.js / SSR	Erro	Previne incompatibilidade de hidratação a partir de globais de navegador (`window`/`localStorage`).
RULE-06	Segurança	Crítico	Detecta riscos de injeção de SQL em interpolações brutas de strings de consulta.
RULE-07	Design de API	Aviso	Aplica validação de esquema (Zod/Pydantic) em payloads de requisições recebidas.
RULE-08	Princípio DRY	Info	Impede que assistentes de IA dupliquem utilitários comuns existentes.

🤖 GitHub Action e Integração de Segurança

O RepoGuard aplica sua própria arquitetura em cada push. Você pode adicionar aplicação arquitetural contínua ao seu pipeline de CI/CD usando a Action oficial:

# .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

💎 Planos e Upgrades Empresariais

O RepoGuard é 100% gratuito e de código aberto para repositórios públicos e desenvolvimento local. Para aplicação automatizada de PR em CI/CD, equipes privadas e mecanismos de regras arquiteturais personalizados:

Nível	Preço	Ideal Para	O que Inclui
Open Source	$0 (Grátis para Sempre)	Desenvolvedores solo e repositórios públicos	Escaneamentos CLI locais ilimitados, `.cursorrules`, `CLAUDE.md`, Servidor MCP, hooks de pré-commit, todas as 12 regras integradas
Developer Pro	$12 / mês	Engenheiros independentes e contratados	Repositórios privados ilimitados, Bot de Revisão de PR automatizado, mecanismo de regras personalizadas, detector de vazamento de segredos
Engineering Team	$39 / mês	Startups e organizações de engenharia	Até 5 desenvolvedores, bloqueador de merge de CI/CD em toda a organização do GitHub, logs de auditoria de arquitetura SOC2, alertas Slack/Discord

👉 Assine o Developer Pro ($12/mês) • Upgrade para Team ($39/mês) • 🇧🇷 Pagar no PIX (R$ 67 à vista)

📈 Histórico de Estrelas

👥 Contribuidores e Comunidade

Agradecimentos especiais aos engenheiros de código aberto que contribuem para o RepoGuard:

@taylormatematica-beep (Mantenedor Principal e Autor)
@NihalPN — Autor dos guardrails arquiteturais RULE-PY-01 e FastAPI (PR #3)

🌟 Suporte e Comunidade

🌐 Documentação e Hub ao Vivo: https://taylormatematica-beep.github.io/repoguard/
📦 Registro NPM: https://www.npmjs.com/package/repoguard-rules
🐱 Product Hunt: https://www.producthunt.com/products/repoguard

Se o RepoGuard ajuda a manter sua codificação com IA limpa, considere dar a este repositório uma ⭐ Estrela!