Signalint

Signalint is a local MCP server for JavaScript and TypeScript diagnostics. It runs Oxlint, TypeScript, and optionally Biome; caches unchanged checks; clusters repeated issues; and warns when the same diagnostic disappears and repeatedly returns. Loop history is restored from valid .signalint/session.jsonl entries when the MCP server restarts; malformed or crash-truncated lines are skipped.

Listed on:

• 
• mcpservers.org
• 
• Official MCP Registry (API listing)

Diagnostic compression example

When a coding agent requests diagnostics on a project, raw compiler and linter outputs quickly flood the context window with repetitive errors across multiple files. Signalint normalizes issues and clusters them by root cause before returning a bounded, priority-ranked response:

Raw diagnostics (40 issues across 10 files · 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
]

Clustered response returned to agent (4 clusters · 1,233 bytes · 86.5% reduction)

{
  "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
}

The agent receives a concise summary with priority-ordered clusters and sample issue IDs. When deeper detail is needed for a specific cluster or issue, the agent calls get_issue_detail without re-running the whole-project scan.

Requirements

• Node.js 20.19 or later in the Node 20 line, or Node.js 22.12 or later
• A JavaScript or TypeScript project; TypeScript checks require a tsconfig.json
• pnpm 11.9.0 for source development

Install

Install Signalint in the project it should check:

npm install --save-dev signalint-mcp

Run the setup command from that project root. It detects TypeScript, Oxlint, and Biome configuration, writes signalint.config.json, and offers to update a nearby Claude Code, Cursor, Codex CLI, or Antigravity MCP configuration:

npx signalint-mcp init

If no MCP client can be selected safely, the command prints exact configuration snippets to copy. TypeScript is enabled only when a root tsconfig.json exists; Biome is enabled when its config exists; Oxlint is the fallback when no configured linter is detected. To configure Signalint manually, create signalint.config.json:

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

Claude Code setup

Run this from the checked project. Project scope writes a shareable .mcp.json:

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

On native Windows, wrap npx as required by Claude Code:

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

Restart Claude Code if it was already open. Ask it to call Signalint's ping tool, then call check_project with { "paths": ["."] }.

See the Claude Code MCP documentation for scope and troubleshooting details.

Cursor setup

Create .cursor/mcp.json in the checked project:

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

On native Windows use "command": "cmd" and "args": ["/c", "npx", "--no-install", "signalint-mcp"]. Open Cursor's MCP settings, enable signalint, and call ping followed by check_project.

See the Cursor MCP documentation for configuration locations and status controls.

Codex CLI setup

The ChatGPT desktop app, Codex CLI, and IDE extension share a single configuration file. The quick-add command writes to ~/.codex/config.toml (global) automatically:

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

For project-scoped configuration (trusted projects only), add to .codex/config.toml in the project root:

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

On native Windows, use cmd and pass npx as an argument:

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

See the Codex MCP documentation for all configuration options including cwd, env, and per-tool approval settings.

Setting up with Antigravity

Antigravity uses its own MCP configuration file. The path that has been verified through dogfooding on Windows is: %USERPROFILE%\.gemini\antigravity\mcp_config.json.

The init command can update this file after confirmation. The equivalent Windows configuration is:

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

On macOS or Linux, use "command": "npx" and "args": ["--no-install", "signalint-mcp"]. Restart or reconnect Antigravity after updating the configuration.

Note on Antigravity product variants: Antigravity has split into separate products (IDE, CLI, SDK). Each variant may use a different config path — the IDE path above is the one confirmed working; other variants may use ~/.gemini/config/mcp_config.json or a project-scoped .agents/mcp_config.json. See antigravity.google/docs/mcp for the authoritative list per product.

Windows troubleshooting

Windows .cmd shims created by npm link can expose a junction path to Node. If signalint-mcp ends with an initialize/EOF error or signalint stats exits with code 0 but prints nothing, bypass the shim with the compiled entrypoint paths:

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

Current builds canonicalize linked paths before deciding whether to start, but direct Node invocation remains the reliable fallback for older builds or unusual npm setups.

Configuration

engines.oxlint, engines.tsc, and engines.biome are booleans. Defaults are Oxlint and tsc enabled, Biome disabled. Omitted engine keys retain those defaults. Unknown keys and incorrectly typed values fail with a configuration error.

ignore is an array of project-relative globs. Signalint supports *, **, and ?, normalizes Windows separators, and excludes matching requested paths and diagnostics. Because tsc is a whole-program engine, it still receives the complete tsconfig.json program when invoked; ignored TypeScript paths do not trigger an incremental check_files run and their diagnostics are removed from the response.

Engine-native configuration remains in native files. The v1 cache hash recognizes root .oxlintrc, .oxlintrc.json, oxlint.json, tsconfig.json, biome.json, and biome.jsonc. Changing one invalidates the related engine cache. Other valid sources—including .oxlintrc.jsonc, extended configs, and nested package configs— are not part of v1 cache hashing; clear .signalint/ after changing one of them.