Skip to main content
Glama

Signalint

CI npm version License: MIT Node.js

Signalint is a reliable, read-only-by-default diagnostic intelligence layer for AI coding agents (Claude Code, Cursor, Codex, VS Code) and CI workflows.

Instead of flooding an agent's context window with thousands of raw compiler lines, Signalint normalizes diagnostics across compilers, linters, and language servers into bounded, priority-clustered issue summaries, calculates verification deltas against explicit baselines, and detects oscillating fix loops.


Key Differentiators

  • 13 Complete MCP Tools: From incremental checks and immutable snapshots to live diagnostic ingestion and journaled transactional fix application.

  • Verification Deltas: Exact arithmetic on introduced, resolved, and unchanged diagnostics with semantic identity matching that survives line shifts.

  • Immutable Snapshots & Concurrency Safety: Isolated in-memory snapshot store keyed by checkId eliminates race collisions during concurrent checks.

  • Monorepo-Aware Planning: Unites package manifests (pnpm-workspace.yaml) parsed via pure-JS YAML with glob negation exclusions and TypeScript Project References, ordering checks topologically.

  • Multi-Source Provenance: Distinguishes compiler, linter, and editor/LSP diagnostics across JavaScript, TypeScript, Python (Ruff/Mypy), Rust (Clippy), and Go (GolangCI-Lint).

  • Portable Host Hooks: Native verify-after-change adapters for Claude Code, Cursor, Codex, and VS Code.

  • In-Memory Previews & In-Process Rollback: In-memory previews never touch disk; apply uses per-file adjacent temporary-file replacement, pre-write drift detection, and in-process best-effort rollback for multi-file writes (does not claim persistent crash recovery if aborted abruptly).


Related MCP server: agent-workspace-mcp

Quick Start

1. Requirements

  • Node.js >= 22.12.0 (utilizes native node:sqlite).

  • Your project installs its own diagnostic engines (typescript, oxlint, eslint, and/or @biomejs/biome). Signalint detects project-local installations and ships no bundled engines.

2. Initialize in your repository

npx signalint init

This detects your project's linters/compilers, generates signalint.config.json, and configures your installed MCP clients.

3. Add to MCP Clients

Add Signalint to your MCP configuration (e.g. claude_desktop_config.json, .cursor/mcp.json):

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

Complete MCP Tools Catalog

Signalint exposes 13 strictly typed MCP tools over stdio:

Tool

Category

Safety Annotation

Description

ping

Diagnostics

Read-only (idempotent)

Verifies server responsiveness and canonical project root path.

check_project

Diagnostics

Read-only (idempotent)

Full project/workspace scan across all enabled engines.

check_files

Diagnostics

Read-only (idempotent)

Fast incremental check on specific files using content-hash caching.

get_issue_detail

Diagnostics

Read-only (idempotent)

Retrieves full, unomitted issue records anchored to an immutable checkId.

get_loop_status

Diagnostics

Read-only (idempotent)

Returns oscillating fix signatures and rule churn detected in the session.

get_diagnostic_snapshot

Snapshots

Read-only (idempotent)

Retrieves complete state and metrics for an immutable check snapshot.

compare_diagnostics

Deltas

Read-only (idempotent)

Computes verification delta between a baseline check and a current check.

after_edit_check

Deltas

Read-only (idempotent)

Runs incremental check on edited files and diffs against a baseline check.

ingest_diagnostics

Live / LSP

Read-only (openWorld: false)

Ingests external LSP or compiler diagnostics into Signalint's clustering model.

get_live_diagnostics

Live / LSP

Read-only (idempotent)

Returns active buffered diagnostics with source provenance.

preview_diagnostic_fix

Transactions

Read-only (destructive: false)

Stages proposed code fixes in-memory. Does not write to disk.

apply_diagnostic_fix

Transactions

Mutating (destructive: true)

Per-file adjacent temp replacement, pre-write drift check, and in-process best-effort rollback.

discard_diagnostic_fix

Transactions

Read-only (idempotent)

Drops an in-memory fix transaction without touching disk.

See docs/mcp-contract.md for full JSON Schemas and error codes.


CLI Commands

Signalint includes a comprehensive command-line interface:

# Run a project diagnostic scan:
npx signalint check .
npx signalint check src/ --format github    # GitHub Actions annotations

# View session statistics and cache economics:
npx signalint stats

# Verify local engine availability and configuration:
npx signalint doctor

# Manage host verify-after-change hooks:
npx signalint hooks preview --runtime claude
npx signalint hooks install --runtime cursor --confirm
npx signalint hooks run --runtime claude --payload '<json-event>'

Monorepo Support

Signalint natively understands multi-package monorepos:

  • Configure "monorepoMode": "auto" in signalint.config.json to detect pnpm-workspace.yaml via pure-JS YAML parsing with glob negation exclusions (!).

  • Strictly differentiates local workspace packages (workspace:*) from external npm registry dependencies.

  • Builds a topological dependency graph uniting package manifests and TypeScript project references.

  • Caches whole-program TypeScript builds in isolated per-package directories (.signalint/cache/tsc/<project-id>/).

  • Changes to a shared package automatically invalidate dependent packages while keeping independent siblings cached.

See docs/monorepo.md for configuration and architecture.


Verify-After-Change Hooks

Automate post-edit verification without creating infinite agent loops:

  • Native adapters for Claude Code, Cursor, Codex, and VS Code.

  • Emits bounded context into prompt windows and blocks only on unresolved syntax/type errors.

See docs/hooks.md for setup instructions.


Documentation Index


License

MIT © 2026 Tran Trong Qui

Available Tools

13 tools
after_edit_checkA
Read-onlyIdempotent

Runs incremental diagnostics on specified edited files and computes a verification delta against an optional baselineCheckId. Read-only; no files are written or modified. Use this after modifying files to verify whether edits introduced or resolved diagnostics relative to the baseline check.

Inputs: files (required), baselineCheckId. Returns: code, delta, engine, status, +16 more

apply_diagnostic_fixA
Destructive

Applies diagnostic modifications using per-file adjacent temporary-file replacement, pre-write drift detection, and in-process best-effort rollback for multi-file writes. Requires explicit confirm: true. If baselineCheckId is provided, it must be valid and active in the snapshot store; unknown or expired baselines abort immediately without modifying files. Does not provide persistent crash recovery if the process terminates abruptly.

Inputs: confirm (required), transactionId (required), baselineCheckId. Returns: code, delta, error, status, +4 more

check_filesA
Read-onlyIdempotent

Runs Oxlint and TypeScript (and optionally Biome) lint and type diagnostics on a specific list of files, using per-engine content-hash caching to skip unchanged files. Read-only; no files are written or modified. Use this for incremental checks after editing specific files; use check_project for a full project scan. The files parameter expects relative file paths (not glob patterns) within the project directory — absolute paths or paths outside the root return an error response. Caching is file-content-hash-based: a file is re-checked only when its content or the engine's config file (e.g., .oxlintrc, tsconfig.json) has changed since the last call, not based on git status. TypeScript is a whole-program engine: it re-runs whenever any TypeScript file in the request has changed content.

Inputs: files (required). Returns: code, engine, status, checkId, +16 more

check_projectA
Read-onlyIdempotent

Runs and clusters Oxlint and TypeScript (and optionally Biome) lint and type diagnostics for one or more project paths. Read-only; no files are written or modified. Paths default to the project root (".") when omitted; paths must be relative and within the project directory — absolute paths or paths outside the root return an error response. Use this for a full project scan; use check_files instead for faster incremental checks after editing specific files. Each call re-runs all enabled engines with no caching.

Inputs: paths. Returns: code, engine, status, checkId, +16 more

compare_diagnosticsA
Read-onlyIdempotent

Computes a deterministic diagnostic delta between two checks (baselineCheckId and currentCheckId). Read-only; no files are modified. Identifies introduced errors, resolved errors, unchanged issues, and net error delta, resilient to line shifts.

Inputs: currentCheckId (required), baselineCheckId (required). Returns: code, status, message, netDelta, +10 more

discard_diagnostic_fixB
Idempotent

Discards an in-memory diagnostic fix preview by transactionId, dropping it from server storage.

Inputs: transactionId (required). Returns: discarded, transactionId

get_diagnostic_snapshotA
Read-onlyIdempotent

Retrieves the immutable diagnostic snapshot recorded for a specific checkId. Read-only; no files are modified. Returns full metadata, engine statuses, clusters, remaining issues, and performance metrics for that check run.

Inputs: checkId (required). Returns: code, cache, source, status, +11 more

get_issue_detailA
Read-onlyIdempotent

Returns the full issue list for either one cluster ID or one issue ID for a specific checkId. Read-only; no files are written or modified. Supply checkId (required) and exactly one of clusterId or issueId — supplying both or neither returns an argument error. If the referenced checkId is unknown/expired or the issue/cluster no longer exists in that check snapshot, returns a status: "stale" response instead of an error.

Inputs: checkId (required), issueId, clusterId. Returns: code, issues, status, message, +1 more

get_live_diagnosticsB
Read-onlyIdempotent

Returns current bounded active diagnostics and clusters merged from both internal engines and ingested LSP sources, with clear provenance per issue.

Inputs: files, severity. Returns: issues, status, clusters, totalIssues, +1 more

get_loop_statusA
Read-onlyIdempotent

Returns all diagnostic issue signatures currently flagged as looping (repeatedly appearing and disappearing) in this server session. Read-only; no files are written or modified. Loop history is accumulated across all check_project and check_files calls in this process lifetime, and is restored from .signalint/session.jsonl on startup. Takes no parameters. Use this to identify which diagnostics an agent is oscillating on; use check_project or check_files to run fresh diagnostics.

Returns: looping, signatures, fileChurning, fileRuleChurns

ingest_diagnosticsC
Read-onlyIdempotent

Ingests external LSP diagnostics (e.g., from VS Code or language servers), normalizes them to Signalint's unified schema, updates the active diagnostic buffer, and records an immutable snapshot.

Inputs: diagnostics (required), source, serverName. Returns: checkId, clusters, snapshotId, totalIssues, +1 more

pingA
Read-onlyIdempotent

Checks whether the Signalint MCP server is responsive. Read-only; returns the string "pong" with no side effects. Use this to verify the server is connected before running diagnostics. Invalid arguments return an error response; no authentication is required.

Returns: pong, projectRoot

preview_diagnostic_fixA
Read-only

Creates an in-memory preview of proposed diagnostic fixes without touching the filesystem. Validates paths against canonical project root containment and returns a preview with a unique transactionId.

Inputs: patches (required). Returns: error, status, summary, filesCount, +2 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (check_project vs check_files vs check_project are distinguished by scope and caching; fix lifecycle tools are separated). Three tools — after_edit_check, compare_diagnostics, and ingest_diagnostics — all compute deltas or ingest diagnostics and could be confused in an agent's workflow, but descriptions clarify usage contexts well. Overall boundaries are clear enough that misselection is unlikely.

    Naming Consistency4/5

    Names predominantly follow verb_noun (check_project, get_issue_detail, preview_diagnostic_fix, apply_diagnostic_fix, discard_diagnostic_fix, get_live_diagnostics), with a few noun_noun or truncated forms like after_edit_check, ping, and get_loop_status. The pattern is still very readable and mostly predictable, with minor deviations like ping (single verb) and snapshot retrieval names.

    Tool Count4/5

    13 tools is a reasonable size for a diagnostics server that supports checking, snapshotting, comparing, previewing fixes, applying fixes, and ingesting LSP data. No tool feels redundant or trivially unnecessary, though the fix preview/apply/discard trio adds complexity that could be consolidated if needed.

    Completeness5/5

    The surface covers the full diagnostic lifecycle: connectivity (ping), full/incremental checking (check_project, check_files, after_edit_check), snapshot retrieval, delta comparison, live merged diagnostics, loop detection, fix preview/apply/discard, and external LSP ingestion. CRUD-like coverage for fixes and diagnostics is complete with no obvious dead ends.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that integrates the high-performance Oxlint linter into AI-powered editors and development tools. It enables efficient JavaScript and TypeScript code analysis and linting through the Model Context Protocol.
      1
      10 npm
      1
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      A TypeScript-aware MCP server that provides coding agents with repository discovery, code intelligence, and web project context for local codebases. It enables deep symbol navigation, diagnostic reporting, and structural analysis of monorepos without requiring full IDE integration.
      7
      11 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A lightweight MCP server that provides 40 tools for TypeScript/JavaScript refactoring and code intelligence, directly mapping to TypeScript's tsserver protocol commands for accurate structural changes and workspace analysis.
      40
      29 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides TypeScript 7 native language server capabilities (go to definition, find references, hover types, diagnostics) to coding agents, using the Go-based tsc compiler for fast and accurate semantic analysis.
      2
      MIT