Signalint

Diagnósticos compactos, em cache e cientes de loops de lint/tipos para agentes de codificação JS/TS. Encapsula Oxlint, tsc e Biome.

GitHub

Experimente este MCPPatrocinado

Documentação

Signalint

Signalint é um servidor MCP local para diagnósticos de JavaScript e TypeScript. Ele executa Oxlint, TypeScript e, opcionalmente, Biome; armazena em cache verificações inalteradas; agrupa problemas recorrentes; e avisa quando o mesmo diagnóstico desaparece e retorna repetidamente. O histórico de loops é restaurado a partir de entradas .signalint/session.jsonl válidas quando o servidor MCP reinicia; linhas malformadas ou truncadas por falha são ignoradas.

Listado em:

mcpservers.org
Registro Oficial de MCP (listagem da API)

Exemplo de compressão de diagnósticos

Quando um agente de codificação solicita diagnósticos em um projeto, as saídas brutas do compilador e do linter rapidamente inundam a janela de contexto com erros repetitivos em vários arquivos. O Signalint normaliza problemas e os agrupa por causa raiz antes de retornar uma resposta limitada e ordenada por prioridade:

Diagnósticos brutos (40 problemas em 10 arquivos · 9.151 bytes)

[
  {
    "issueId": "ts-01",
    "file": "src/file01.ts",
    "line": 10,
    "col": 5,
    "engine": "tsc",
    "rule": "TS2322",
    "severity": "error",
    "message": "Type 'string' is not assignable to type 'number' in fixture assignment 01.",
    "fixable": false
  },
  // ... 39 more raw normalized issues
]

Resposta agrupada retornada ao agente (4 grupos · 1.233 bytes · redução de 86,5%)

{
  "schemaVersion": "1.1",
  "status": "issues_found",
  "engines": {
    "oxlint": { "status": "ok" },
    "tsc": { "status": "ok" },
    "biome": { "status": "disabled" }
  },
  "totalIssues": 40,
  "clusters": [
    {
      "clusterId": "c1",
      "rootCauseSummary": "10 TS2322 issues across 10 files",
      "ruleIds": ["TS2322"],
      "issueCount": 10,
      "fileCount": 10,
      "priority": 1,
      "suggestedAction": "Review the shared cause of TS2322 across 10 files",
      "sampleIssueIds": ["ts-01", "ts-02"]
    },
    {
      "clusterId": "c2",
      "rootCauseSummary": "10 no-unused-vars issues across 10 files",
      "ruleIds": ["no-unused-vars"],
      "issueCount": 10,
      "fileCount": 10,
      "priority": 2,
      "suggestedAction": "Review the shared cause of no-unused-vars across 10 files",
      "sampleIssueIds": ["unused-01", "unused-02"]
    },
    {
      "clusterId": "c3",
      "rootCauseSummary": "10 eqeqeq issues across 10 files",
      "ruleIds": ["eqeqeq"],
      "issueCount": 10,
      "fileCount": 10,
      "priority": 5,
      "suggestedAction": "Apply structured fixes for eqeqeq across 10 files",
      "sampleIssueIds": ["eqeqeq-01", "eqeqeq-02"]
    },
    {
      "clusterId": "c4",
      "rootCauseSummary": "10 prefer-const issues across 10 files",
      "ruleIds": ["prefer-const"],
      "issueCount": 10,
      "fileCount": 10,
      "priority": 5,
      "suggestedAction": "Apply structured fixes for prefer-const across 10 files",
      "sampleIssueIds": ["const-01", "const-02"]
    }
  ],
  "truncated": false,
  "loopWarning": null
}

O agente recebe um resumo conciso com grupos ordenados por prioridade e IDs de exemplo de problemas. Quando um detalhe mais profundo é necessário para um grupo ou problema específico, o agente chama get_issue_detail sem reexecutar a verificação de todo o projeto.

Requisitos

Node.js 20.19 ou posterior na linha Node 20, ou Node.js 22.12 ou posterior
Um projeto JavaScript ou TypeScript; verificações TypeScript exigem um tsconfig.json
pnpm 11.9.0 para desenvolvimento de código-fonte

Instalação

Instale o Signalint no projeto que ele deve verificar:

npm install --save-dev signalint-mcp

Execute o comando de configuração a partir da raiz desse projeto. Ele detecta a configuração de TypeScript, Oxlint e Biome, escreve signalint.config.json e oferece atualizar uma configuração MCP próxima do Claude Code, Cursor, Codex CLI ou Antigravity:

npx signalint-mcp init

Se nenhum cliente MCP puder ser selecionado com segurança, o comando imprime trechos exatos de configuração para copiar. O TypeScript é habilitado somente quando existe um tsconfig.json raiz; o Biome é habilitado quando sua configuração existe; o Oxlint é o fallback quando nenhum linter configurado é detectado. Para configurar o Signalint manualmente, crie signalint.config.json:

{
  "engines": {
    "oxlint": true,
    "tsc": true,
    "biome": false
  },
  "ignore": ["node_modules/**", "dist/**", ".signalint/**"],
  "timeoutsMs": {
    "oxlint": 30000,
    "tsc": 120000,
    "biome": 30000
  }
}

Configuração do Claude Code

Execute isto a partir do projeto verificado. O escopo do projeto grava um .mcp.json compartilhável:

claude mcp add --scope project signalint -- npx --no-install signalint-mcp
claude mcp get signalint

No Windows nativo, envolva npx conforme exigido pelo Claude Code:

claude mcp add --scope project signalint -- cmd /c npx --no-install signalint-mcp
claude mcp get signalint

Reinicie o Claude Code se ele já estiver aberto. Peça para ele chamar a ferramenta ping do Signalint, e então chame check_project com { "paths": ["."] }.

Consulte a documentação MCP do Claude Code para detalhes de escopo e solução de problemas.

Configuração do Cursor

Crie .cursor/mcp.json no projeto verificado:

{
  "mcpServers": {
    "signalint": {
      "command": "npx",
      "args": ["--no-install", "signalint-mcp"]
    }
  }
}

No Windows nativo, use "command": "cmd" e "args": ["/c", "npx", "--no-install", "signalint-mcp"]. Abra as configurações MCP do Cursor, ative signalint e chame ping seguido de check_project.

Consulte a documentação MCP do Cursor para locais de configuração e controles de status.

Configuração do Codex CLI

O aplicativo de desktop do ChatGPT, o Codex CLI e a extensão IDE compartilham um único arquivo de configuração. O comando de adição rápida grava em ~/.codex/config.toml (global) automaticamente:

codex mcp add signalint -- npx --no-install signalint-mcp

Para configuração com escopo de projeto (somente projetos confiáveis), adicione a .codex/config.toml na raiz do projeto:

[mcp_servers.signalint]
command = "npx"
args = ["--no-install", "signalint-mcp"]

No Windows nativo, use cmd e passe npx como argumento:

[mcp_servers.signalint]
command = "cmd"
args = ["/c", "npx", "--no-install", "signalint-mcp"]

Consulte a documentação MCP do Codex para todas as opções de configuração, incluindo cwd, env e configurações de aprovação por ferramenta.

Configuração com Antigravity

O Antigravity usa seu próprio arquivo de configuração MCP. O caminho que foi verificado por meio de dogfooding no Windows é: %USERPROFILE%\.gemini\antigravity\mcp_config.json.

O comando init pode atualizar este arquivo após confirmação. A configuração equivalente para Windows é:

{
  "mcpServers": {
    "signalint": {
      "command": "cmd",
      "args": ["/c", "npx", "--no-install", "signalint-mcp"],
      "cwd": "<absolute-path-to-your-project>"
    }
  }
}

No macOS ou Linux, use "command": "npx" e "args": ["--no-install", "signalint-mcp"]. Reinicie ou reconecte o Antigravity após atualizar a configuração.

Observação sobre variantes do produto Antigravity: O Antigravity foi dividido em produtos separados (IDE, CLI, SDK). Cada variante pode usar um caminho de configuração diferente — o caminho da IDE acima é o confirmado como funcional; outras variantes podem usar ~/.gemini/config/mcp_config.json ou um .agents/mcp_config.json com escopo de projeto. Consulte antigravity.google/docs/mcp para a lista autoritativa por produto.

Solução de problemas no Windows

Os shims .cmd do Windows criados por npm link podem expor um caminho de junção ao Node. Se signalint-mcp terminar com um erro de initialize/EOF ou signalint stats sair com código 0 mas não imprimir nada, contorne o shim com os caminhos de ponto de entrada compilados:

node C:\absolute\path\to\Signalint\dist\src\index.js
node C:\absolute\path\to\Signalint\dist\src\cli.js stats

As versões atuais canonicalizam caminhos vinculados antes de decidir iniciar, mas a invocação direta do Node continua sendo o fallback confiável para versões mais antigas ou configurações npm incomuns.

Configuração

engines.oxlint, engines.tsc e engines.biome são booleanos. Os padrões são Oxlint e tsc habilitados, Biome desabilitado. Chaves de mecanismo omitidas mantêm esses padrões. Chaves desconhecidas e valores com tipo incorreto falham com um erro de configuração.

ignore é uma matriz de globs relativos ao projeto. O Signalint suporta *, ** e ?, normaliza separadores do Windows e exclui caminhos e diagnósticos solicitados correspondentes. Como o tsc é um mecanismo de programa inteiro, ele ainda recebe o programa tsconfig.json completo quando invocado; caminhos TypeScript ignorados não acionam uma execução incremental de check_files e seus diagnósticos são removidos da resposta.

A configuração nativa do mecanismo permanece em arquivos nativos. O hash de cache v1 reconhece .oxlintrc, .oxlintrc.json, oxlint.json, tsconfig.json, biome.json, e biome.jsonc na raiz. Alterar um deles invalida o cache do mecanismo relacionado. Outras fontes válidas — incluindo .oxlintrc.jsonc, configurações estendidas e configurações de pacotes aninhados — não fazem parte do hash de cache v1; limpe .signalint/ após alterar uma delas.

timeoutsMs define prazos de subprocesso de inteiros positivos em milissegundos. Os padrões são 30 segundos para Oxlint, 120 segundos para tsc e 30 segundos para Biome. Um mecanismo com tempo esgotado e seus processos filhos são encerrados. Na resposta de verificação do esquema 1.1, esse mecanismo tem { "status": "error", "message": "tsc did not complete within 120s" } sob engines, enquanto os diagnósticos dos mecanismos concluídos são preservados.

Limitações conhecidas

O Signalint suporta apenas projetos JavaScript e TypeScript.
Os mecanismos integrados são Oxlint, TypeScript e Biome; o v1 não suporta mecanismos personalizados arbitrários.
O Signalint informa se um problema tem uma correção estruturada, mas o v1 não aplica correções.
O Signalint não é um scanner SAST ou de segurança.
Ainda não há extensão de IDE; as integrações usam MCP ou o cliente de linha de comando.
A detecção de loops é deliberadamente limitada a assinaturas de problemas de lint, tipo e teste; ela não detecta loops gerais de conversa de agente.
O adaptador tsc exige um tsconfig.json na raiz do projeto. Monorepos devem fornecer uma configuração raiz no estilo solução usando Referências de Projeto TypeScript; o Signalint não descobre automaticamente configurações de pacotes independentes.
check_files trata apenas os arquivos explicitamente passados para essa chamada como relevantes para a invalidação de cache TypeScript. Se o arquivo A mudar, mas for omitido enquanto o arquivo inalterado B é verificado, e B depender de A, o Signalint pode reutilizar um resultado tsc obsoleto. Inclua cada arquivo de dependência alterado ou execute check_project; invalidação baseada em grafo de dependências não é implementada no v1.

Ferramentas MCP

ping verifica se o servidor local está conectado e retorna pong.
check_project aceita { "paths": ["."] } opcional e retorna diagnósticos agrupados.
check_files aceita { "files": ["src/file.ts"] } e usa cache incremental.
get_issue_detail aceita exatamente um clusterId ou issueId da verificação bem-sucedida mais recente e retorna seus problemas completos, ou uma resposta status: "stale".
get_loop_status retorna assinaturas de problemas atualmente sinalizadas como oscilantes.

Artefatos de cache e sessão são gravados sob .signalint/ e não devem ser commitados.

Teste de fumaça de CLI e pacote

Execute a mesma verificação de projeto sem um cliente MCP:

npx --no-install signalint check .

Depois que as verificações MCP se acumularem em .signalint/session.jsonl, imprima o resumo de medição da Fase 6:

npx --no-install signalint stats

O relatório inclui a redução média de payload JSON de bruto-para-agrupado normalizado, taxa de acerto de cache de arquivo de mecanismo, latência média e máxima de verificação e o número de assinaturas de problemas distintas que acionaram avisos de loop. Uma consulta de arquivo de mecanismo conta cada mecanismo habilitado separadamente, então um arquivo TypeScript alterado pode errar uma vez para Oxlint e uma vez para tsc. A latência cobre o trabalho do manipulador desde a entrada da ferramenta MCP até o trabalho de mecanismo/cache, agrupamento e avaliação de loop; ela exclui o anexo de telemetria e o transporte stdio. As estatísticas incluem o log de sessão ativo e seu backup rotacionado .1, com a sobreposição retida contada uma vez. Verificações limpas com payload bruto zero são excluídas da média de redução, e verificações mais antigas com métricas ausentes permanecem contadas sem contribuir para o agregado indisponível.

O CLI sai com código 1 quando problemas são encontrados. Duas flags suportam uso em CI: --format github imprime uma anotação do GitHub Actions (::error file=...,line=...,col=...::message ou ::warning ...) por problema em vez de JSON, e --fail-on-priority <N> sai com código não zero somente se a prioridade de um grupo estiver em ou abaixo de N em vez de em qualquer problema encontrado.

Para exercitar uma chamada real de check_project do MCP contra o pacote instalado, execute:

node node_modules/signalint-mcp/examples/check-project.mjs .

GitHub Actions

action.yml na raiz do repositório envolve signalint check como uma ação composta para CI. Ela instala o Node, instala signalint-mcp do npm e executa a verificação com --format github para que os problemas apareçam como anotações inline no diff do pull request:

- uses: TranQui004/signalint@main
  with:
    fail-on-priority: "3"

fail-on-priority tem como padrão 5, que falha o job em qualquer problema encontrado, correspondendo ao comportamento padrão de signalint check sem a flag. Valores menores só falham o job quando um grupo é pelo menos tão urgente: prioridade 1 é um erro sem correção estruturada, e a prioridade aumenta em direção a 5 conforme os problemas se tornam mais corrigíveis ou mais sistêmicos (consulte scorePriority em src/cluster/clusterEngine.ts).

Desenvolvimento

O pnpm 11.9.0 é o gerenciador de pacotes canônico para desenvolvimento de código-fonte. O repositório commita pnpm-lock.yaml, declara pnpm em package.json e usa pnpm no CI.

pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm test
pnpm build

Se um shim npm global não conseguir encontrar npm-cli.js, compile diretamente com node node_modules/typescript/bin/tsc -p tsconfig.json.

Antes de preparar um release, use npm pack --dry-run e verifique o tarball empacotado em um projeto limpo. A publicação exige aprovação explícita de release.

Segurança

Consulte SECURITY.md para o aviso atual do npm audit, sua alcançabilidade de runtime avaliada e as condições que exigem reavaliação.

Documentação

Website — visão geral, documentação e exemplos ao vivo.
ARCHITECTURE.md — como as camadas se encaixam e o que cada módulo faz.
CONTRIBUTING.md — configuração de desenvolvimento, verificação e pull requests.
AGENTS.md — padrões de codificação para este repositório.
SECURITY.md — modelo de ameaça, limites de confiança e status de auditoria.
CHANGELOG.md — mudanças notáveis por release.
docs/history/ — plano de construção original e trilha de auditoria pré-lançamento.

Licença

O Signalint está disponível sob a Licença MIT.