signalint

# Signalint

[![CI](https://github.com/TranQui004/signalint/actions/workflows/ci.yml/badge.svg)](https://github.com/TranQui004/signalint/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/signalint-mcp.svg)](https://www.npmjs.com/package/signalint-mcp)

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:**
- [![TranQui004/signalint MCP server](https://glama.ai/mcp/servers/TranQui004/signalint/badges/score.svg)](https://glama.ai/mcp/servers/TranQui004/signalint)
- [mcpservers.org](https://mcpservers.org/servers/tranqui004/signalint)
- Official MCP Registry ([API listing](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.TranQui004%2Fsignalint/versions/latest))

## 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)

```json
[
  {
    "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)

```json
{
  "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:

```sh
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:

```sh
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`:

```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`:

```sh
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:

```powershell
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](https://docs.anthropic.com/en/docs/claude-code/mcp)
for scope and troubleshooting details.

## Cursor setup

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

```json
{
  "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](https://docs.cursor.com/context/model-context-protocol)
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:

```sh
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:

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

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

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

See the [Codex MCP documentation](https://developers.openai.com/codex/mcp)
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:

```json
{
  "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](https://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:

```powershell
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.

`timeoutsMs` sets positive-integer subprocess deadlines in milliseconds. Defaults are
30 seconds for Oxlint, 120 seconds for tsc, and 30 seconds for Biome. A timed-out
engine and its child processes are terminated. In the schema 1.1 check response, that
engine has `{ "status": "error", "message": "tsc did not complete within 120s" }`
under `engines`, while completed engines' diagnostics are preserved.

## Known Limi