Documentação do CodeHero

Briefing para CTO e líder técnico: detecção peer-competitive, loop fechado depois do finding e um quality gate auditável — na pipeline, no editor e nas IDEs de IA — sem IA no gate do PR e sem o time operar cluster.

Missão e valor

O CodeHero existe para o líder que já paga o custo do ruído: falso positivo que atrasa merge, finding sem dono, e agente que gera patch sem prova. Elevamos qualidade e segurança com motor determinístico (reproduzível, auditável) e um ciclo que não para no alerta: regras evoluem offline, a correção nasce com contrato (SDD) e o agente (MCP) prova o fix no rescaneio.

Princípio que passa em due diligence

Inspeção = regras + motor determinístico. IA = planejamento de correção e evolução de políticas — nunca no lugar do quality gate do PR.

Na prática, o time usa o CodeHero em três frentes que o board entende:

  • Pipeline — GitHub Action bloqueia merge quando a política falha.
  • Shift left — plugin VS Code/Cursor: saúde, compliance e grafo do código no workspace.
  • Agentes de IA — MCP no Cursor, Claude e Copilot para corrigir com prova.

Posicionamento e métricas

Categoria: plataforma de qualidade AI-native com loop de prova determinístico — a conversa certa para CTO/TL, não “mais um SAST” nem clone de suite enterprise por amplitude de catálogo.

Headline

CodeHero: detecção peer-competitive, loop fechado depois do finding — sem IA no quality gate.

Uma frase para o comitê

Peer-competitive em detecção de vulnerabilidades (OWASP); líder no ciclo pós-finding (evolução + SDD + MCP); complementar — não substituto — em amplitude de smells enterprise.

Três provas

  1. OWASP BenchmarkJava — F1 75,1% · precisão 75,6% · score 48,9 (benchmarks/owasp-baseline.json).
  2. Sonar way VULN live — ~69% (330/479) na curadoria, com esteira F1; smells via Presence/SARIF.
  3. Correção com prova — SDD → agente MCP → scanner confirma que a finding sumiu.
OWASP BenchmarkJavaF1 75,1% · precisão 75,6% · recall 74,6% · score 48,9 (TPR − FPR). Baseline em benchmarks/owasp-baseline.json (2026-08-09).
Vs peers públicosEstudos recentes colocam CodeQL/Semgrep com F1 OWASP ~69–74% e FPR muito alto. O CodeHero prioriza gate estável (menos ruído), sem reivindicar o maior recall do mercado.
Sonar way / smells~19% semântica (core) · VULN live ~69% · smells live ~7%. Não revendemos substituição 1:1 do catálogo enterprise.
LatênciaL0 em microssegundos/arquivo; L1 (árvore ~25 KB) ~13 ms/arquivo; sem LLM no hot path do PR.
Liderar o pitch com
  • Loop fechado: finding → SDD → agente → prova
  • Precisão / score OWASP calibrado
  • MCP nativo + regras no contexto de geração
  • COBOL/DB2 sem add-on enterprise
  • Orquestração CodeQL/Semgrep/Trivy
  • Esteira de promoção com F1 auditável
  • Grafo estrutural sem Gen AI (priorização)
Anti-claims — não dizer
  • “Temos mais regras que o Sonar”
  • Substituição 1:1 de suite enterprise em smells
  • “LLM analisa cada arquivo”
  • Taint interprocedural maduro em todas as langs
  • Catálogo nativo como única cobertura
  • “Melhor SAST do mercado” só pelo F1
  • Contar stub de catálogo como cobertura live

Para quem falar (GTM · Sim)

Early access e conversas com CTO / líder técnico focam nestes ICPs — não em “troque o Sonar por amplitude de smells”.

ICPAberturaFecho
AppSec (odeia FP)Mesmo patamar de F1, score OWASP mais calibrado.Gate estável; FP vira estatística da regra.
Times com agentes
Cursor / Copilot / Claude		SAST que fala MCP e prova o fix.Regras no contexto de geração; rescaneio fecha o ciclo.
Legado / bancoCOBOL + DB2 na junta, sem SKU Enterprise.Host var × coluna, cursor, COMMIT no laço.
Já tem Sonar/CodeQLNão troque o detector — unifique o gate e a correção.Presence Pack no mesmo juiz.
Para quem não liderar com troca total

Quem só quer amplitude de code smells enterprise e não usa agentes/SDD — Sonar (ou Presence) continua no papel de catálogo; o CodeHero não vende “mais regras de smell”.

Quando usar o quê

CenárioEscolha
Gate + legado + agentes + evolução de regrasCodeHero sozinho (perfil native / Action)
Amplitude de smells/SAST e loop de fixCodeHero + Sonar/Semgrep/CodeQL (Presence Pack)
Só catálogo de smells, sem agentes/SDDSonar (ou import SARIF) — CodeHero não é o substituto
CI rápido no PR + profundidade à noiteSemgrep/Opengrep no Presence + CodeQL importado no mesmo gate

Wiki completa: Posicionamento-e-metricas.md. Esteira Sonar way (VULN → golden → F1 → live): Esteira-Sonar-Way.md · npm run sonar:engenharia -- all.

Modelos matemáticos

Três famílias de fórmulas sustentam o produto: débito técnico (manutenibilidade), pior severidade (segurança) e precisão/recall/F1 (portão de promoção de regras). Elas são as mesmas no CI, no portal e no plugin.

Figura A — Três modelos: TDR → rating de manutenibilidade; pior severidade → rating de segurança; F1 → promoção de regras.
Manutenibilidade (TDR)TechnicalDebt = Σ effortMin dos code smells. DevelopmentCost = LOC × 30 min. TDR = Debt / Cost → rating A–E (A se TDR ≤ 5%).
SegurançaRating = mapeamento da pior severidade presente (BLOCKER→E … sem issues→A). Não usa média: um único BLOCKER derruba o índice.
Portão F1P = TP/(TP+FP), R = TP/(TP+FN), F1 = 2PR/(P+R). Só promove regra se ΔF1 > 0, P ≥ 0,85 e zero regressão no corpus.
Figura B — Como o corpus classifica uma regra candidata (TP/FP/FN) antes de ela tocar o CI.
Figura C — Do relatório de análise aos índices A–E e ao Quality Gate.

Como o sistema aprende de forma contínua

O aprendizado não é “um LLM lê cada arquivo no PR”. É um ciclo com prova: observar → propor → provar no corpus → publicar só o que melhora precisão.

  1. Observar

    Action, IDE e prévia geram findings. Quando alguém marca falso positivo ou confirma um achado, isso vira telemetria rotulada — combustível do próximo ciclo.

  2. Propor

    Em lote (fora do PR), Dress Code Tools e a orquestração de agentes sugerem mutações ou regras novas a partir de política do time, gaps e feedback. A IA não fecha o gate.

  3. Provar

    Busca evolutiva reproduzível mede precisão, recall e F1 no corpus golden. Candidata ruim sai com motivo auditável — sem “opinião” do modelo.

  4. Publicar

    Só entra no RuleSet ativo se ΔF1 > 0, P ≥ 0,85 e zero regressão. No próximo scan o time já usa a regra — sem republicar plugin.

Figura — Esteira completa: a IA alimenta o pool; o corpus e o F1 decidem o que chega ao CI.

Por que isso é diferente

Outras ferramentas ou esperam release do vendor, ou colocam LLM no caminho crítico do PR.

Figura — À esquerda, ciclo opaco ou instável; à direita, proposta offline + prova determinística.
No PR / CICodeHeroSuite enterpriseScanner só de IA
Quem decide a regraCorpus + F1 (auditável)Release do vendorPrompt / modelo
LLM no arquivo do PR?NãoNão (em geral)Sim
Mesmo commit, mesmo resultadoSimSimNão garantido
Política do time em PTDress code → regraRaroNão estruturado

cenário exercitado

O que aconteceu de verdade no motor

Rodamos npm run ruleforge:evaluate e npm run ruleforge:evolve-all no corpus golden. Vinte regras de segurança/smell (ex.: HERO-SEC-0798-hardcoded-secret, HERO-SEC-0089-sql-injection) mediram P = R = F1 = 1,00 — zero falso positivo no corpus.

  1. Observar / baseline — o evaluate listou TP/FP/FN por regra; o catálogo já estava “no teto” de precisão nos casos rotulados.
  2. Propor — o evolve montou população de mutações (máscaras sobre o padrão) por 5 gerações, seed fixo, sem chamar LLM no caminho crítico.
  3. Provar — o melhor candidato ficou com F1 = 1,000, igual ao baseline. O portão exige ganho (ΔF1 > 0) e P ≥ 0,85.
  4. Publicar — REJECTED — decisão registrada: “sem ganho de F1 (baseline=1.000, melhor=1.000)” ou “sem mutações registradas para esta regra”. Nenhuma regra “quase boa” entrou no RuleSet.

Em paralelo, o cenário de produto completa o ciclo: o time escreve dress code (“proibido console.log em produção”) → a orquestração de agentes propõe a regra → casos entram no corpus → se F1 subir com P ≥ 0,85, aí sim promove. O reject do evolve-all prova a metade crítica: o motor sabe dizer não — o que suites só-IA e releases opacos raramente mostram.

Cenário narrado — do dress code ao CI

Além do run real de evolve-all (rejeição correta quando F1 já é 1,00), o fluxo de produto que o time sente no dia a dia é este:

Figura — Sequência do cenário de produto: feedback e dress code alimentam o lote; só o portão F1 publica.
Diferença prática vs outras ferramentas

Em suite enterprise, o time espera o vendor; em scanner só-IA, o “julgamento” muda com o modelo. No CodeHero o PR sempre vê o mesmo RuleSet, e a esteira offline é a única porta de entrada de regra nova — com rejeição explícita quando não há ganho (como no evolve-all que rodamos).

Wiki (markdown no repo): docs/wiki/Esteira-de-aprendizado-de-regras.md.

Fluxo automatizado de criação de regras

Manutenibilidade e segurança compartilham o mesmo pipeline de promoção. O que muda é a categoria da regra promovida: code smells alimentam o TDR; vulnerabilidades/hotspots alimentam o rating de segurança.

Figura E — Da política/telemetria ao RuleSet: candidatos → corpus → portão → impacto em manutenibilidade ou segurança.
Regras de manutenibilidade
  • Tipo CODE_SMELL com effortMin
  • Sobe Σ débito quando disparam
  • Baixar TDR = melhorar rating A–E
  • Ex.: debug em produção, TODO abandonado, GO TO
Regras de segurança
  • Tipo VULNERABILITY / HOTSPOT / BUG
  • Sobe a pior severidade do projeto
  • Portão exige P ≥ 0,85 (menos FP)
  • Ex.: secret hardcoded, XSS, SQL injection
Figura F — Detalhe do ciclo diário: propostas → busca evolutiva → PROMOTED / REJECTED.

Modelos: GenAI + motor de prova (o mix)

O CodeHero não escolhe “só IA” nem “só regras fixas”. Ele separa dois tipos de modelo com responsabilidades distintas — scanners clássicos + detecções complementares, mas com um contrato explícito: a IA nunca é o juiz do quality gate.

Modelo generativo (GenAI)Interpreta linguagem natural (dress code), propõe mutações de regra (Dress Code Tools) e redige contratos de correção (SDD) para agentes. Bom em exploração e síntese; ruim como única fonte de verdade em CI.
Modelo determinísticoMatcher (regex/AST/dataflow), avaliação F1 no corpus, débito técnico e quality gate. Mesma entrada → mesma saída. Roda na borda (CI/IDE) sem rede e sem custo de inferência por arquivo.
Figura 1 — GenAI propõe; o motor determinístico decide, mede e prova.

Por que misturar os dois?

  • Cobertura sem alucinação no caminho crítico — o PR não depende de um LLM “achar” o bug a cada arquivo.
  • Evolução contínua das regras — GenAI sugere padrões novos; o corpus + F1 só promove o que melhora precisão/recall sem regressão.
  • Correção assistida com prova — o agente MCP aplica o SDD; o scanner rescaneia e confirma objetivamente.
  • Custo e latência previsíveis no CI — scan = CPU local; GenAI fica offline (1×/dia) ou sob demanda (dress code / SDD).
Figura 2 — Caminho crítico do PR: scanner → métricas → gate → (opcional) fix verificado.
Figura 3 — Evolução de regras: Dress Code Tools propõe mutações; o motor determinístico promove ou rejeita.

Matemática por trás (débito técnico, F1, quality gate)

As fórmulas são as mesmas no scanner, na API e no portal. Assim o índice que o eng vê no dashboard é o mesmo que falhou (ou passou) no CI.

1. Débito técnico e manutenibilidade

Cada code smell carrega um esforço de remediação em minutos. O débito é a soma; o rating de manutenibilidade vem da razão entre débito e o custo de desenvolver o código (LOC × 30 min).

Débito e TDRTechnicalDebt = Σ remediationEffortMin (code smells) DevelopmentCost = LOC × 30 min TDR = TechnicalDebt / DevelopmentCost
TDR (debt ratio)Maintainability ratingLeitura prática
≤ 5%ADébito saudável — gate padrão exige A
≤ 10%BAtenção — ainda recuperável
≤ 20%CDébito material
≤ 50%DAlto custo de mudança
> 50%ECrítico — manutenibilidade comprometida

2. Rating de segurança

Segurança (e reliability no mesmo eixo) não usa TDR: usa a pior severidade presente entre as issues relevantes. Sem issues → A.

Pior severidadeSecurity rating
nenhuma / INFOA
MINORB
MAJORC
CRITICALD
BLOCKERE
Ordem de severidaderank(BLOCKER) > rank(CRITICAL) > rank(MAJOR) > rank(MINOR) > rank(INFO) SecurityRating = rating( argmax_i rank(severity_i) )
Figura 4 — Do relatório de análise aos índices A–E e ao Quality Gate.

3. Quality Gate (new code)

O gate padrão exige, entre outras condições: security rating ≤ A, maintainability rating ≤ A, zero blockers novos, cobertura e duplicação dentro dos limiares. Qualquer condição falha → FAILED (merge bloqueado na Action).

Gate (simplificado)PASSED ⇔ coverage_new ≥ 80% ∧ duplication_new ≤ 3% ∧ blockers_new = 0 ∧ security ≤ A ∧ maintainability ≤ A

4. Evolução de regras — precisão, recall e F1

Quando as Dress Code Tools propõem uma mutação de regra, o juiz é o corpus golden (casos match / no_match). Nada de “a IA achou bom”:

Classificação binária no corpusPrecision P = TP / (TP + FP) Recall R = TP / (TP + FN) F1 = 2 · P · R / (P + R)
Fitness do algoritmo genético + portãofitness ≈ 1000·F1 + 10·P + simplicidade (Occam) PROMOTED ⇔ ΔF1 > 0 ∧ P ≥ 0.85 ∧ zero regressões vs baseline

Resultado: o catálogo de regras melhora com ajuda de GenAI, mas só entra no scanner o que o corpus comprova — protegendo os índices de segurança (menos FP que “choram lobo”) e de manutenibilidade (regras que realmente capturam smells caros).

Como o mix sobe manutenibilidade e segurança

Índices A–E não são “notas de vibe”: são funções do que o scanner determinístico encontra. O mix GenAI + determinístico melhora esses índices de formas complementares:

O que o scanner conta hoje

Contam no gate e nos índices: regras L0 (CORE), ports Sonar live, regras estruturais (HERO-ST-*, tree-sitter com --metrics) e achados importados via SARIF (CodeQL, Semgrep, Trivy…). Stubs do catálogo Sonar Way são metadados/política — não inventam findings. Procedência (tool / engine) fica no apontamento.

Movimentos 2 · 3 · 4

2 — CPG (Joern): --joern / Action joern: true (JDK ou Docker). Achados entram como EXT:joern:*. Opt-in — JVM no scan é escolha consciente. 3 — Ranqueador FP: gradient boosting de stumps em features (teste/dist, taxa histórica, severidade…). Modelo versionado; confirmar/descartar no workspace gera rótulos; exportRuleforgeFeedback + hero-fp-ranker train. 4 — CVE mine: npm run cve:mine extrai pares antes/depois de GHSA/OSV para o corpus do ruleforge (orquestração de agentes propõe offline; F1/P≥0.85 decide).

Locksmith Loop (migração legado)

Validação determinística COBOL→Java no espírito AmEx (arXiv:2607.28271): Witness Search (pairwise / 3-way / LHS / ART / MAP-Elites / UCB1) → parágrafos travados → Mutation Skills (dispatcher-arm, call-injection) nos dois harnesses → Parity Gate (paragraphs_hit ∧ stub_log ∧ terminal_state). Mutação só fica se cobertura↑ e parity PASS. CLI: npm run locksmith -- run examples/legacy/sample.cbl (e locksmith-locked.cbl para forçar Mutation Skills). Hoje o runner é mock de CFG (não GnuCOBOL/JVM); plugue javaRunner para o alvo real.

Manutenibilidade (TDR ↓ → rating ↑)
  • Regras de code smell com effortMin realistas somam o débito
  • Dress code (GenAI → regra) captura políticas do time cedo
  • Shift left no VS Code reduz smells antes do PR
  • MCP + rescaneio remove issues e corta Σ effort
  • Gate exige rating A no new code — impede regressão silenciosa
Segurança (pior severidade ↓ → rating ↑)
  • Vulnerabilities/hotspots ranqueados por severidade
  • Evolução de regras só promove com P ≥ 0.85 (menos FP em segurança)
  • Action falha em CRITICAL/BLOCKER conforme fail-on
  • SDD guia o fix; scanner prova que a finding sumiu
  • Mesma régua no CI, IDE e portal — sem score paralelo
Vantagem prática do mix

Sistemas só-de-IA variam o resultado e não fecham gate de forma auditável. Sistemas só-de-regras engessam e atrasam políticas novas. O CodeHero usa GenAI para ampliar e acelerar o catálogo e as correções, e modelos determinísticos + débito/F1 para medir, promover e bloquear com reprodutibilidade — exatamente o que faz o índice de manutenibilidade e segurança subir de forma sustentável.

Quem usa o CodeHero

A documentação e o portal são para o time do projeto: quem provisiona a org, liga o repositório e escolhe os canais (Action, plugin, MCP). Não é necessário conhecer infraestrutura do CodeHero — só a conta no portal e o repositório GitHub.

Admin de projeto

Engenheiros, tech leads, donos do repo

Provisionam organização e projeto, conectam o GitHub, instalam o plugin e/ou o MCP, definem dress code do time e acompanham quality gate e issues.

Tudo isso acontece no portal e no repositório — sem configurar infraestrutura do fornecedor.

Membros do time

Quem abre PR e corrige findings

Usam a Action no CI, o plugin no editor e, se quiserem, o MCP no agente para aplicar o SDD e provar o fix.

Recebem o token/config do admin do projeto (aba Configurar) — não gerenciam a conta da organização sozinhos, salvo permissão no portal.

O que você faz no dia a dia

Admin de projeto
  • Criar org + projeto no portal
  • One-click da GitHub Action no repo
  • Plugin VS Code + prévia de repo + MCP
  • Dress code do próprio projeto
Engenharia no repo
  • Push/PR com quality gate
  • Scan no editor antes do PR
  • Corrigir issues (manual ou via MCP)
  • Marcar falso positivo quando fizer sentido

Onde o CodeHero age

1. Pipeline (CI)GitHub Action em todo push/PR: scan → ingestão → quality gate. Merge só passa se o código estiver adequado.
2. IDE (shift left)Plugin VS Code/Cursor: varre o workspace, painel Avaliação, Problems, gráficos de manutenibilidade / segurança / compliance.
3. Prévia de repositórioNo portal: cole a URL do GitHub, rode a prévia na nuvem e veja findings + recomendações antes do PR.
4. MCP (agentes)Cursor, Claude Desktop e GitHub Copilot: o agente lê issues, aplica SDD, rescaneia e prova o fix.

Começar do zero (admin de projeto)

  1. Crie a conta

    Em codehero.web.app: email/senha ou Google. Em segundos você está no dashboard.

  2. Provisione org + projeto

    Novo projeto → nome da organização, nome do projeto e (recomendado) URL do repositório GitHub. O portal gera o token de ingestão usado por CI, IDE e MCP.

  3. Abra Configurar no projeto

    Quatro abas: Visão geral · Plugin VS Code · GitHub Action · MCP. Cada uma já vem com os dados doseu projeto preenchidos.

  4. Escolha o canal (pode usar todos)

    Action na esteira, plugin no editor, prévia no portal, MCP no agente. O workflow recomendado está mais abaixo.

GitHub Action — quality gate na pipeline

É o jeito mais simples de garantir que todo PR passa pelas regras do CodeHero. Você configura tudo a partir do portal e do próprio repositório GitHub.

Passo a passo (1 clique)

  1. Projeto com URL do repositório

    Na criação (ou edição) informe a URL https://github.com/org/repo.

  2. Aba GitHub Action → Configurar Action no GitHub (1 clique)

    Autorize o acesso pedido pelo portal. O CodeHero cria/atualiza .github/workflows/codehero.yml e os segredos/variáveis necessários no repositório (HERO_TOKEN e HERO_CORE_URL).

  3. Abra um PR ou faça push

    A Action roda o scanner com as regras ativas (canônicas + dress code), envia o relatório e avalia o quality gate. Severidades críticas podem falhar o job e bloquear o merge.

Alternativas (se preferir manual)

  • Script gh — copie na mesma aba do portal.
  • Deep link “new file” — abre o GitHub com o YAML pronto para commit.
  • Colar o YAML — em .github/workflows/codehero.yml.

VS Code / Cursor — shift left no editor

Antes do PR, o engenheiro vê compliance e non-compliance no próprio workspace: painel Avaliação, Problems e (quando ligado ao portal) o contexto do projeto.

Instalar o plugin

  1. Baixe o VSIX

    Na página do projeto → aba Plugin VS Code → Baixar plugin (.vsix), ou em /downloads/codehero-vscode.vsix.

  2. Instale no editor

    Extensions → ⋯ → Install from VSIX… → selecione o arquivo. Funciona no VS Code e no Cursor.

  3. Abra a pasta do repositório

    File → Open Folder no root do app que você quer analisar.

Rodar o scan no workspace (forma simples)

  1. Ícone CodeHero na Activity Bar

    Clique em Rodar scan no workspace. O scanner embutido varre os arquivos do workspace e aplica as regras ativas.

  2. Leia o resultado

    Painel Avaliação: lista de findings. Dashboard (ícone de gráfico): anéis de segurança e manutenibilidade, débito técnico e compliance. Também sobe para Problems. Status bar mostra o andamento.

  3. (Opcional) Ligar ao portal

    Cole o .vscode/settings.json gerado na aba do projeto (org, project, server, token). Assim o scan usa as mesmas regras/dress code do projeto na nuvem.

  4. Atalhos úteis

    Command Palette → CodeHero: Abrir configurações (scan ao salvar, cache, severidade mínima). Node.js no PATH é suficiente — CLI extra não é necessária.

Por que shift left?

Corrigir no editor custa menos do que descobrir no PR. O mesmo motor da pipeline roda localmente — mesma linguagem de severidade e regras.

Varrer um repositório GitHub (prévia + recomendações)

Quando o objetivo é analisar o repo inteiro (não só a pasta aberta no editor), o fluxo recomendado é:

Opção A — Prévia no portal (rápida, ideal para demo e onboarding)

  1. No dashboard, use o bloco Prévia no runner.
  2. Cole a URL de um repositório GitHub público (https://github.com/org/repo).
  3. Associe ao projeto (opcional) para aplicar dress code / regras do projeto.
  4. Rode a prévia — o CodeHero baixa o código, aplica as regras e devolve contagem por severidade + top findings (arquivo, linha, mensagem).

Use isso para “mostrar o herói em ação” antes de ligar a Action. Hoje a prévia prioriza repos públicos; repos privados entram pelo caminho B.

Opção B — Repo completo na esteira (recomendado para produção)

  1. Configure a GitHub Action (seção acima) no repositório — público ou privado.
  2. Push / PR dispara o scan de todo o checkout do job (path . por padrão).
  3. Resultado no portal — issues, ratings, débito técnico e quality gate. No GitHub, o relatório de análise também pode aparecer em Security / Code scanning.
  4. Recomendações de correção — no portal ou via MCP, peça o SDD Spec da issue: localização, contexto e critérios de aceite para o agente/humano aplicar o fix e provar com um novo scan.

Opção C — Workspace local = clone do repo

Clone o repositório, abra no VS Code/Cursor e rode Rodar scan no workspace. É o mesmo motor, arquivo a arquivo, com feedback imediato — ótimo enquanto você prepara o PR.

Qual forma usar?

Demo / first look → Prévia no portal. Dia a dia do eng → VS Code. Gate de merge → GitHub Action. Correção assistida → MCP. Juntos formam o loop completo de qualidade.

MCP — Cursor, Claude, GitHub Copilot e Devin

O servidor MCP do CodeHero conecta agentes de IA às issues reais e ao catálogo de regras. O agente não “chuta” o fix: ele segue o contrato SDD e valida com evidência (get_issues / scan).

Guia completo versionado: Conectar-MCP-CodeHero.md. Exemplos JSON: integrations/mcp/.

Ferramentas expostas

  • get_generation_context — entrada em linguagem natural → bloco de regras/issues para o prompt
  • get_active_rules — catálogo ativo (core + dress code)
  • get_issues · get_sdd_spec · submit_fix_result — loop de correção
  • apply_sdd_workflow — roteiro verified-fix
  • run_scan — opcional (scanner local)

Antes de tudo (comum a todas)

  1. Portal

    codehero.web.app → projeto + repo → Integração MCP → copiar o JSON (já com token).

  2. Node ≥ 20

    O comando npx -y codehero-mcp@latest baixa o pacote na primeira execução.

  3. Teste no chat

    “Chame get_generation_context com as regras CodeHero e aplique no contexto.”

{
  "command": "npx",
  "args": ["-y", "codehero-mcp@latest"],
  "env": {
    "HERO_CORE_URL": "https://codehero.web.app/api",
    "HERO_TOKEN": "…",
    "HERO_ORG_ID": "…",
    "HERO_PROJECT_ID": "…",
    "HERO_REPO_ID": "…"
  }
}

MCP · Cursor

  1. Crie .cursor/mcp.json na raiz do seu repo com o JSON do portal (formato mcpServers).
  2. Opcional: cole a regra do agente em .cursor/rules/codehero-mcp.mdc.
  3. Settings → MCP — confirme codehero conectado; Refresh se preciso.
  4. No Agent Chat: peça get_generation_context, depois get_issues / get_sdd_spec.

MCP · Claude Desktop

  1. Edite claude_desktop_config.json:
    • macOS: ~/Library/Application Support/Claude/
    • Windows: %APPDATA%\Claude\
  2. Mesclar o bloco mcpServers.codehero (mesmo JSON do portal).
  3. Feche e reabra o Claude Desktop por completo.
  4. Verifique as tools MCP e chame get_generation_context.

MCP · GitHub Copilot

  1. Crie .vscode/mcp.json com o formato servers (exemplo no repo; o painel também gera).
  2. Ative Agent mode no Copilot Chat.
  3. Autorize as tools CodeHero na sessão.
  4. Prompt: use o texto “Prompt pronto” do painel Integração MCP.

Ambiente cloud do coding agent precisa de Node 20+ se for usar npx no runner. No editor local (VS Code) basta o Node da máquina.

MCP · Devin

Transport: STDIO com npx + codehero-mcp@latest.

  1. Web: Settings → Connections → MCP servers → Add a custom MCP → STDIO → command npx, args -y codehero-mcp@latest, env = variáveis do portal.
  2. CLI / Local: grave em .devin/mcp_config.local.json (token) ou %APPDATA%\devin\mcp_config.json (Windows). Exemplo: devin.example.json.
  3. Ou: devin mcp add codehero -t stdio --command npx -- -y codehero-mcp@latest -e HERO_TOKEN=…
  4. Na sessão Devin, peça para listar tools e chamar get_issues / get_generation_context.

Referência Devin: docs.devin.ai/work-with-devin/mcp.

Presença SARIF (orquestração)

CodeHero não substitui CodeQL/Semgrep: orquestra esses motores via SARIF e aplica a mesma política, gate e proveniência no portal. O nativo cobre o eixo de segurança com métricas peer-competitive (posicionamento); a amplitude de smells/SAST enterprise entra por import. No hot path do PR: scan nativo + imports; modelos só offline (triagem / ruleforge).

  • Pack recomendado: CodeQL + Semgrep + Oxlint + Trivy/OSV — veja matriz wiki e o workflow codehero-presence.example.yml.
  • Action inputs: oxlint, semgrep, sca, sca-tool, import-sarif, semantic, metrics (default on).
  • CLI: --with-oxlint / --with-semgrep / --with-sca (soft-fail se o binário não estiver no PATH) ou --import path.sarif.
  • Achados importados aparecem como EXT:<tool>:<rule> com badge via codeql / via oxlint no findings browser.

Dress code do time

Descreva a política em português (“sem console.log em produção”, “sem Math.random em token”). As Dress Code Tools interpretam; o motor determinístico aplica como regra auditável.

  • No projeto — políticas do seu time (escopo do projeto no portal).
  • Políticas da organização, quando existirem, aparecem junto das regras ativas no scan — sem configuração extra no repositório.

Scanners (Action, IDE, prévia, MCP) buscam as regras ativas no servidor antes de analisar — dress code novo passa a valer sem republicar o plugin.

Workflow recomendado (time de engenharia)

  1. Provisionar o projeto no portal com a URL do GitHub.
  2. Prévia (repo público) ou primeiro push com Action — baseline de issues.
  3. One-click Action — quality gate em todo PR.
  4. Plugin VS Code — cada eng roda scan no workspace antes de abrir PR.
  5. Dress code — políticas do time em linguagem natural.
  6. MCP — corrigir issues com agente + prova objetiva (rescaneio).

Resultado: menos surpresa no code review, menos débito silencioso, segurança e manutenibilidade medidas com o mesmo régua do CI até o editor.

Arquitetura (resumo)

Motor de inspeçãoScanner na borda (CI/IDE). Evolução de regras offline com Dress Code Tools + corpus golden.
Painel & SDDIngestão via API, débito técnico, quality gates, contratos de correção verificáveis.
IntegraçõesVS Code, GitHub Action e MCP — o portal e a aba Configurar entregam o que cada canal precisa.

Cada organização e projeto tem o próprio espaço no portal: regras, tokens de ingestão e quality gate ficam isolados por projeto.