Como Configurar Portas de Qualidade Automatizadas para Claude Code com MCP

Este artigo foi publicado originalmente no Blog LucidShark.

Você tem o Claude Code aberto, um servidor MCP em execução e uma base de código que continua crescendo. Sempre que um agente de IA toca em um arquivo, você confia que a saída é boa. Mas "boa" para uma IA significa "compilou e passou nos testes que você pediu." A deterioração estrutural, o aumento da complexidade e a deriva de estilo se acumulam silenciosamente até sua próxima dolorosa revisão de sprint.

A solução não é mais revisão de código. A solução é conectar um portão de qualidade determinístico diretamente ao fluxo de trabalho do Claude Code, para que cada arquivo gerado ou modificado pela IA seja analisado antes de chegar ao seu histórico de commits. Este tutorial mostra exatamente como fazer isso com LucidShark e MCP.

Por que agentes de codificação de IA precisam de um portão de qualidade na junção

Claude Code é uma ferramenta agente. Ele não apenas sugere mudanças, ele as faz. Quando você pede para ele implementar um recurso ou refatorar um módulo, ele escreverá arquivos, executará comandos e iterará. O ciclo de feedback do qual depende é funcional: o código compila, os testes passam, a saída corresponde à especificação?

Nenhum desses sinais mede a qualidade estrutural. Uma função com uma complexidade ciclomática de 28 passa em todos os testes. Um módulo com 340 linhas de lógica duplicada compila sem problemas. Um arquivo com zero de cobertura de ramificação em um caminho crítico de erro é mesclado sem protesto. A IA completou a tarefa pela sua própria definição de "pronto", que é uma definição muito diferente da sua equipe.

⚠️ Aviso: Agentes de codificação de IA otimizam para o feedback que recebem. Se seus únicos sinais de feedback são "sucesso na compilação" e "teste aprovado", você obterá código que compila e passa em testes. Você não obterá automaticamente código que seja sustentável, bem coberto ou arquitetonicamente sólido.

O ponto de integração do MCP (Modelo de Contexto de Protocolo) é a junção onde você pode interceptar isso. Antes que o Claude Code finalize uma mudança, ou imediatamente após produzir uma saída, você pode invocar uma ferramenta de análise de qualidade local e apresentar os resultados de volta ao contexto do agente. O agente pode então corrigir problemas antes que você os veja.

O que o LucidShark mede e por que isso é importante aqui

LucidShark é uma ferramenta de análise estática local-first projetada especificamente para fluxos de trabalho de desenvolvimento assistidos por IA. Ela é executada inteiramente em sua máquina, não envia dados externamente e produz uma saída JSON estruturada que o MCP pode consumir. As verificações que realiza cobrem as lacunas que os agentes de IA deixam abertas:

• Complexidade ciclomática: Marca funções que ultrapassaram o ponto em que um humano pode raciocinar sobre elas, mesmo que funcionem corretamente hoje.

• Duplicação de código: Detecta padrões de copiar-colar que os agentes de IA produzem quando não têm contexto suficiente para extrair lógica compartilhada.

• Mapeamento de cobertura de testes: Mostra quais linhas, ramificações e caminhos sua suíte de testes não exercita, para que você possa ver o que "100% dos testes passando" realmente significa em termos de cobertura.

• Avaliação de risco de dependência: Verifica seu manifesto de pacotes contra dados de vulnerabilidade conhecidos e sinaliza pacotes com proveniência suspeita ou não licenciada.

• SAST (Teste de Segurança de Aplicação Estática): Identifica padrões de injeção, credenciais codificadas e uso inseguro de APIs em código gerado.

• Conformidade de estilo e lint: Impõe as regras do seu projeto para que a saída da IA não se desvie das convenções da equipe ao longo do tempo.

📝 Nota: O design local-first do LucidShark não é apenas uma escolha de privacidade. Isso significa que a ferramenta pode ser invocada dentro das chamadas de ferramentas MCP sem latência de rede, sem limites de taxa de API e sem dependência da disponibilidade de serviços externos. As verificações de qualidade acontecem na velocidade do seu disco local.

Configurando o servidor MCP

O LucidShark vem com um modo de servidor MCP embutido. Quando você o inicia nesse modo, ele expõe um conjunto de ferramentas que o Claude Code pode chamar durante uma sessão agente. As ferramentas envolvem o mesmo mecanismo de análise que a CLI, mas retornam resultados estruturados projetados para uma IA ler e agir.

Passo 1: Instalar o LucidShark

npm install -g lucidshark

Verifique a instalação:

lucidshark --version
lucidshark doctor

O comando doctor verifica se seu ambiente local possui as dependências de análise necessárias (runtime do ESLint, ferramentas de cobertura e o mecanismo de regras do LucidShark). Corrija quaisquer avisos que ele apresente antes de prosseguir.

Passo 2: Inicializar uma configuração de projeto

Execute isso na raiz do repositório que você deseja proteger:

lucidshark init

Isso cria um arquivo lucidshark.config.json. Os padrões são sensatos para a maioria dos projetos em TypeScript ou JavaScript. As configurações principais a revisar para um projeto assistido por IA:

{
  "complexity": {
    "maxCyclomatic": 10,
    "maxCognitive": 15
  },
  "coverage": {
    "minLineCoverage": 70,
    "minBranchCoverage": 60,
    "failOnUncoveredCriticalPaths": true
  },
  "duplication": {
    "minTokens": 50,
    "maxDuplicationRatio": 0.05
  },
  "sast": {
    "enabled": true,
    "blockOnHighSeverity": true
  },
  "mcp": {
    "enabled":