PR Guardian MCP

Servidor Model Context Protocol (MCP) open-source que analisa diffs de Pull Requests do GitHub com foco em segurança e vazamento de dados.

A arquitetura prioriza economia de tokens: a maioria dos PRs (docs, CSS, formatação) é aprovada por lógica nativa TypeScript, sem chamar a LLM. Apenas mudanças em arquivos de lógica disparam análise via LangGraph + Claude 3.5 Haiku.

Arquitetura

flowchart TD
    A[MCP Tool: analyze_pr_diff] --> B[LangGraph: classify]
    B --> C{Filtro Determinístico}
    C -->|docs / css / formatação| D[auto_approve]
    C -->|.ts / .tsx / outros riscos| E[ai_analyze]
    E --> F[Claude 3.5 Haiku]
    F --> G[Zod Validation]
    D --> G
    G --> H[Resposta MCP estruturada]

    subgraph Observabilidade
        F -.->|trace| LS[LangSmith]
    end

1. Filtro Determinístico (custo zero)

Antes de qualquer chamada à API da Anthropic, o nó classify executa regras nativas em TypeScript:

Por que isso importa? Em repositórios reais, uma parcela significativa dos PRs altera apenas documentação, estilos ou formatação. Enviar esses diffs para uma LLM gera:

• Custo desnecessário — tokens de entrada/saída cobrados sem valor de segurança

• Latência — 1–3s adicionais por PR trivial

• Ruído — falsos positivos em conteúdo que não executa código

O filtro determinístico responde em microssegundos, com custo $0.00.

2. Filtro de IA (LangGraph)

Quando arquivos de lógica são detectados, o grafo aciona o nó ai_analyze:

• Modelo: Claude 3.5 Haiku (claude-3-5-haiku-20241022)

• Escopo: apenas riscos de segurança e vazamento de dados

• Saída: JSON estruturado via withStructuredOutput

Categorias analisadas: secret_leak, injection, auth_bypass, data_exposure, dependency_risk.

3. Validação (Zod)

Toda resposta — determinística ou da LLM — passa pelo nó validate_result e é parseada com PrAnalysisResultSchema antes de retornar ao cliente MCP. Respostas malformadas da LLM são rejeitadas com erro explícito.

4. Observabilidade (LangSmith)

Chamadas LLM são rastreadas automaticamente quando:

LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_...
LANGCHAIN_PROJECT=pr-guardian-mcp

No dashboard do LangSmith você visualiza latência, tokens consumidos e custo estimado por execução do grafo.

Related MCP server: gitlumen-mcp

Estrutura do Projeto

pr-guardian-mcp/
├── src/
│   ├── index.ts                 # Servidor MCP (stdio)
│   ├── graph.ts                 # LangGraph: classify → auto_approve | ai_analyze → validate
│   ├── schema.ts                # Schemas Zod (input, output, LLM)
│   ├── deterministic-filter.ts  # Lógica de filtro nativo (custo zero)
│   └── langsmith.ts             # Configuração de observabilidade
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── package.json
└── tsconfig.json

Pré-requisitos

• Node.js ≥ 20

• Chave da API Anthropic (apenas para PRs com arquivos de lógica)

• Chave do LangSmith (opcional, recomendado)

Instalação

git clone https://github.com/seu-usuario/pr-guardian-mcp.git
cd pr-guardian-mcp
npm install
cp .env.example .env
# Edite .env com suas chaves

Uso Local

# Desenvolvimento
npm run dev

# Build + produção
npm run build
npm start

Configuração no Cursor / Claude Desktop

Adicione ao arquivo de configuração MCP:

{
  "mcpServers": {
    "pr-guardian-mcp": {
      "command": "node",
      "args": ["/caminho/absoluto/pr-guardian-mcp/dist/index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "LANGCHAIN_TRACING_V2": "true",
        "LANGCHAIN_API_KEY": "lsv2_...",
        "LANGCHAIN_PROJECT": "pr-guardian-mcp"
      }
    }
  }
}

Ferramenta MCP

analyze_pr_diff

Exemplo de resposta:

{
  "approved": true,
  "path": "deterministic",
  "reason": "Alterações exclusivas em documentação (.md) ou estilos (.css) — aprovado sem chamada à LLM.",
  "findings": [],
  "metadata": {
    "analyzedAt": "2026-07-15T18:00:00.000Z",
    "filesChanged": ["README.md", "docs/guide.md"],
    "tokenCostSaved": true
  }
}

Docker

Build e execução

docker build -t pr-guardian-mcp .
docker run -i --rm \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e LANGCHAIN_TRACING_V2=true \
  -e LANGCHAIN_API_KEY=lsv2_... \
  -e LANGCHAIN_PROJECT=pr-guardian-mcp \
  pr-guardian-mcp

Docker Compose

cp .env.example .env
docker compose up --build

O container expõe o servidor via stdio (-i), compatível com clientes MCP que lançam processos filhos.

Stack

Licença

MIT