Signalint

Diagnósticos de lint/tipos compactos, en caché y conscientes de bucles para agentes de codificación JS/TS. Envuelve Oxlint, tsc y Biome.

GitHub

Prueba este MCPPatrocinado

Documentación

Signalint

Signalint es un servidor MCP local para diagnósticos de JavaScript y TypeScript. Ejecuta Oxlint, TypeScript y opcionalmente Biome; almacena en caché las comprobaciones sin cambios; agrupa problemas repetidos; y advierte cuando el mismo diagnóstico desaparece y reaparece repetidamente. El historial de bucles se restaura desde entradas .signalint/session.jsonl válidas cuando el servidor MCP se reinicia; las líneas malformadas o truncadas por un bloqueo se omiten.

Listado en:

mcpservers.org
Registro oficial de MCP (listado de API)

Ejemplo de compresión de diagnósticos

Cuando un agente de codificación solicita diagnósticos en un proyecto, las salidas sin procesar del compilador y del linter rápidamente inundan la ventana de contexto con errores repetitivos en múltiples archivos. Signalint normaliza los problemas y los agrupa por causa raíz antes de devolver una respuesta acotada y ordenada por prioridad:

Diagnósticos sin procesar (40 problemas en 10 archivos · 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
]

Respuesta agrupada devuelta al agente (4 grupos · 1,233 bytes · reducción del 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
}

El agente recibe un resumen conciso con grupos ordenados por prioridad e IDs de problemas de muestra. Cuando se necesita un detalle más profundo para un grupo o problema específico, el agente llama a get_issue_detail sin volver a ejecutar el escaneo de todo el proyecto.

Requisitos

Node.js 20.19 o posterior en la línea Node 20, o Node.js 22.12 o posterior
Un proyecto de JavaScript o TypeScript; las comprobaciones de TypeScript requieren un tsconfig.json
pnpm 11.9.0 para el desarrollo de fuentes

Instalación

Instala Signalint en el proyecto que debe comprobar:

npm install --save-dev signalint-mcp

Ejecuta el comando de configuración desde la raíz de ese proyecto. Detecta la configuración de TypeScript, Oxlint y Biome, escribe signalint.config.json y ofrece actualizar una configuración MCP cercana de Claude Code, Cursor, Codex CLI o Antigravity:

npx signalint-mcp init

Si no se puede seleccionar ningún cliente MCP de forma segura, el comando imprime fragmentos de configuración exactos para copiar. TypeScript se habilita solo cuando existe un tsconfig.json raíz; Biome se habilita cuando existe su configuración; Oxlint es la alternativa cuando no se detecta ningún linter configurado. Para configurar Signalint manualmente, crea signalint.config.json:

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

Configuración de Claude Code

Ejecuta esto desde el proyecto comprobado. El ámbito del proyecto escribe un .mcp.json compartible:

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

En Windows nativo, envuelve npx según lo requerido por Claude Code:

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

Reinicia Claude Code si ya estaba abierto. Pídele que llame a la herramienta ping de Signalint, luego llama a check_project con { "paths": ["."] }.

Consulta la documentación de MCP de Claude Code para obtener detalles sobre el ámbito y la resolución de problemas.

Configuración de Cursor

Crea .cursor/mcp.json en el proyecto comprobado:

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

En Windows nativo usa "command": "cmd" y "args": ["/c", "npx", "--no-install", "signalint-mcp"]. Abre la configuración de MCP de Cursor, habilita signalint y llama a ping seguido de check_project.

Consulta la documentación de MCP de Cursor para conocer las ubicaciones de configuración y los controles de estado.

Configuración de Codex CLI

La aplicación de escritorio de ChatGPT, Codex CLI y la extensión del IDE comparten un único archivo de configuración. El comando de adición rápida escribe en ~/.codex/config.toml (global) automáticamente:

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

Para una configuración con ámbito de proyecto (solo proyectos de confianza), agrega a .codex/config.toml en la raíz del proyecto:

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

En Windows nativo, usa cmd y pasa npx como argumento:

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

Consulta la documentación de MCP de Codex para conocer todas las opciones de configuración, incluyendo cwd, env y la configuración de aprobación por herramienta.

Configuración con Antigravity

Antigravity usa su propio archivo de configuración de MCP. La ruta que ha sido verificada mediante dogfooding en Windows es: %USERPROFILE%\.gemini\antigravity\mcp_config.json.

El comando init puede actualizar este archivo después de la confirmación. La configuración equivalente de Windows es:

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

En macOS o Linux, usa "command": "npx" y "args": ["--no-install", "signalint-mcp"]. Reinicia o vuelve a conectar Antigravity después de actualizar la configuración.

Nota sobre las variantes del producto Antigravity: Antigravity se ha dividido en productos separados (IDE, CLI, SDK). Cada variante puede usar una ruta de configuración diferente: la ruta del IDE anterior es la confirmada como funcional; otras variantes pueden usar ~/.gemini/config/mcp_config.json o un .agents/mcp_config.json con ámbito de proyecto. Consulta antigravity.google/docs/mcp para obtener la lista autoritativa por producto.

Solución de problemas en Windows

Los shims de .cmd de Windows creados por npm link pueden exponer una ruta de unión a Node. Si signalint-mcp termina con un error de initialize/EOF o signalint stats sale con código 0 pero no imprime nada, evita el shim con las rutas de punto de entrada compiladas:

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

Las compilaciones actuales canonicalizan las rutas vinculadas antes de decidir si iniciar, pero la invocación directa de Node sigue siendo la alternativa confiable para compilaciones más antiguas o configuraciones inusuales de npm.

Configuración

engines.oxlint, engines.tsc y engines.biome son booleanos. Los valores predeterminados son Oxlint y tsc habilitados, Biome deshabilitado. Las claves de motor omitidas conservan esos valores predeterminados. Las claves desconocidas y los valores con tipo incorrecto fallan con un error de configuración.

ignore es una matriz de globs relativos al proyecto. Signalint admite *, ** y ?, normaliza los separadores de Windows y excluye las rutas y diagnósticos solicitados que coinciden. Debido a que tsc es un motor de programa completo, aún recibe el programa tsconfig.json completo cuando se invoca; las rutas de TypeScript ignoradas no activan una ejecución incremental de check_files y sus diagnósticos se eliminan de la respuesta.

La configuración nativa del motor permanece en archivos nativos. El hash de caché v1 reconoce .oxlintrc, .oxlintrc.json, oxlint.json, tsconfig.json, biome.json raíz y biome.jsonc. Cambiar uno invalida la caché del motor relacionado. Otras fuentes válidas—incluyendo .oxlintrc.jsonc, configuraciones extendidas y configuraciones de paquetes anidados— no forman parte del hash de caché v1; limpia .signalint/ después de cambiar una de ellas.

timeoutsMs establece plazos de subproceso de enteros positivos en milisegundos. Los valores predeterminados son 30 segundos para Oxlint, 120 segundos para tsc y 30 segundos para Biome. Un motor con tiempo agotado y sus procesos secundarios se terminan. En la respuesta de verificación del esquema 1.1, ese motor tiene { "status": "error", "message": "tsc did not complete within 120s" } bajo engines, mientras que los diagnósticos de los motores completados se conservan.

Limitaciones conocidas

Signalint admite solo proyectos de JavaScript y TypeScript.
Los motores integrados son Oxlint, TypeScript y Biome; v1 no admite motores personalizados arbitrarios.
Signalint informa si un problema tiene una corrección estructurada, pero v1 no aplica correcciones.
Signalint no es un escáner SAST ni de seguridad.
Aún no hay una extensión de IDE; las integraciones usan MCP o el cliente de línea de comandos.
La detección de bucles está deliberadamente limitada a firmas de problemas de lint, tipo y prueba; no detecta bucles generales de conversación de agentes.
El adaptador tsc requiere un tsconfig.json en la raíz del proyecto. Los monorepos deben proporcionar una configuración raíz de tipo solución usando Referencias de Proyecto de TypeScript; Signalint no descubre automáticamente configuraciones de paquetes independientes.
check_files trata solo los archivos pasados explícitamente a esa llamada como relevantes para la invalidación de caché de TypeScript. Si el archivo A cambia pero se omite mientras se verifica el archivo B sin cambios, y B depende de A, Signalint puede reutilizar un resultado tsc obsoleto. Incluye cada archivo de dependencia cambiado o ejecuta check_project; la invalidación basada en el grafo de dependencias no está implementada en v1.

Herramientas MCP

ping verifica que el servidor local esté conectado y devuelve pong.
check_project acepta { "paths": ["."] } opcional y devuelve diagnósticos agrupados.
check_files acepta { "files": ["src/file.ts"] } y usa caché incremental.
get_issue_detail acepta exactamente un clusterId o issueId de la última verificación exitosa y devuelve sus problemas completos, o una respuesta status: "stale".
get_loop_status devuelve las firmas de problemas actualmente marcadas como oscilantes.

Los artefactos de caché y sesión se escriben bajo .signalint/ y no deben confirmarse.

Prueba de humo del CLI y del paquete

Ejecuta la misma verificación de proyecto sin un cliente MCP:

npx --no-install signalint check .

Después de que las verificaciones MCP se hayan acumulado en .signalint/session.jsonl, imprime el resumen de medición de la Fase 6:

npx --no-install signalint stats

El informe incluye la reducción promedio de carga útil JSON de sin procesar a agrupado normalizado, la tasa de aciertos de caché de archivos de motor, la latencia promedio y máxima de verificación, y el número de firmas de problemas distintas que activaron advertencias de bucle. Una búsqueda de archivos de motor cuenta cada motor habilitado por separado, por lo que un archivo TypeScript cambiado puede fallar una vez para Oxlint y una vez para tsc. La latencia cubre el trabajo del manejador desde la entrada de la herramienta MCP hasta el trabajo de motor/caché, la agrupación y la evaluación de bucles; excluye el anexo de telemetría y el transporte stdio. Las estadísticas incluyen el registro de sesión activo y su copia de seguridad rotada .1, con su superposición retenida contada una vez. Las verificaciones limpias con carga útil sin procesar cero se excluyen del promedio de reducción, y las verificaciones más antiguas con métricas faltantes permanecen contadas sin contribuir al agregado no disponible.

El CLI sale con código 1 cuando se encuentran problemas. Dos banderas admiten el uso en CI: --format github imprime una anotación de GitHub Actions (::error file=...,line=...,col=...::message o ::warning ...) por problema en lugar de JSON, y --fail-on-priority <N> sale con código no cero solo si la prioridad de un grupo está en o por debajo de N en lugar de ante cualquier problema encontrado.

Para ejercitar una llamada real de MCP check_project contra el paquete instalado, ejecuta:

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

GitHub Actions

action.yml en la raíz del repositorio envuelve signalint check como una acción compuesta para CI. Instala Node, instala signalint-mcp desde npm y ejecuta la verificación con --format github para que los problemas aparezcan como anotaciones en línea en el diff de la solicitud de extracción:

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

fail-on-priority tiene como valor predeterminado 5, que falla el trabajo ante cualquier problema encontrado, coincidiendo con el comportamiento predeterminado de signalint check sin la bandera. Los valores más bajos solo fallan el trabajo cuando un grupo es al menos tan urgente: la prioridad 1 es un error sin corrección estructurada, y la prioridad aumenta hacia 5 a medida que los problemas se vuelven más corregibles o más sistémicos (consulta scorePriority en src/cluster/clusterEngine.ts).

Desarrollo

pnpm 11.9.0 es el administrador de paquetes canónico para el desarrollo de fuentes. El repositorio confirma pnpm-lock.yaml, declara pnpm en package.json y usa pnpm en CI.

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

Si un shim global de npm no puede encontrar npm-cli.js, compila directamente con node node_modules/typescript/bin/tsc -p tsconfig.json.

Antes de preparar un lanzamiento, usa npm pack --dry-run y verifica el tarball empaquetado en un proyecto limpio. La publicación requiere aprobación explícita del lanzamiento.

Seguridad

Consulta SECURITY.md para conocer el aviso actual de npm audit, su alcance de tiempo de ejecución evaluado y las condiciones que requieren una reevaluación.

Documentación

Sitio web — descripción general, documentación y ejemplos en vivo.
ARCHITECTURE.md — cómo encajan las capas y qué hace cada módulo.
CONTRIBUTING.md — configuración de desarrollo, verificación y solicitudes de extracción.
AGENTS.md — estándares de codificación para este repositorio.
SECURITY.md — modelo de amenazas, límites de confianza y estado de auditoría.
CHANGELOG.md — cambios notables por lanzamiento.
docs/history/ — plan de compilación original y rastro de auditoría previo al lanzamiento.

Licencia

Signalint está disponible bajo la Licencia MIT.