MCP tools

Signalint exposes 13 tools over stdio MCP. Checks do not edit source, but can write cache, session and compiler artifacts. apply_diagnostic_fix explicitly writes source files; configure your host permissions accordingly. Tool annotations are hints, not a filesystem sandbox or proof of human consent.

All 13 tools

Every input object rejects unknown keys. File/path arrays are limited to 512 where the shared path-array schema is used; this is not a bound on every diagnostic or patch array.

Tool	Accepted arguments	Result / use
ping	{}	Connection and canonical project root
check_project	Optional paths: string[], default ["."]	Clustered project check
check_files	Required files: string[]	Configured scoped file check
get_issue_detail	Exactly one of clusterId / issueId; required checkId	Matching normalized records from a retained snapshot
get_loop_status	{}	Oscillation and file/rule churn state
get_diagnostic_snapshot	Required checkId	Metadata, clusters and bounded remaining records; not full issues
compare_diagnostics	Required baselineCheckId, currentCheckId	Introduced, resolved and unchanged issues; error counters
after_edit_check	Required files; optional baselineCheckId	New configured file check, plus optional delta
ingest_diagnostics	Required LSP-shaped diagnostics; optional source, serverName	Batch snapshot and buffered external issues
get_live_diagnostics	Optional files, `severity: “error”	“warning”`
preview_diagnostic_fix	Required nonempty patches with file, originalContent, patchedContent; optional per-patch description	In-memory transaction and character-length summary
apply_diagnostic_fix	Required transactionId, confirm: boolean; optional baselineCheckId	Source writes only when confirm: true; post-check and optional delta
discard_diagnostic_fix	Required transactionId	{ transactionId, discarded: boolean }; not an undo tool

The native subprocess engine set remains Oxlint, TypeScript, Biome and ESLint. External report normalization is not registration of additional native engines.

Ping

Call ping with {}. Text content is the literal string pong, not a JSON string. In both and structured mode the result also includes:

{ "pong": true, "projectRoot": "/work/my-project" }

Text mode omits that structured root. MCP initialize now advertises the installed package version through resolveSignalintVersion(); the old hardcoded 0.4.2 discrepancy is fixed in 1.2.0.

Project and file checks

Call check_project:

{ "paths": ["."] }

Or check_files:

{ "files": ["src/main.ts", "src/util.ts"] }

The file checker filters displayed issues to those paths. TypeScript can still compile the selected program; filtered-count aliases describe diagnostics removed by the display scope. Input paths are not native engine command-line arguments, and arbitrary priority/filter arguments are rejected.

Check results use schema 1.4. Inspect both status and engines: clean, issues_found, error, and stale have different meanings. All-disabled checks produce nothing_checked, not a successful clean native check. Settled native task failures can remain in status/engine data without isError: true. Thrown provider/engine failures now become classified tool errors with isError: true, code, engine, message, retryable and nextStep; these are a different response path.

Project root and state

By default the server uses its launch working directory. SIGNALINT_PROJECT_ROOT can select a canonical root; an invalid override logs a warning and falls back to the launch directory. Embedders can pass an explicit cwd option. Verify the effective root with ping.

The project must have recognized JS/TS ecosystem markers. Without signalint.config.json, MCP checks are refused unless SIGNALINT_ALLOW_UNINITIALIZED=1. Even with that override, a recognized project marker is still needed. Native engine configuration remains trusted executable context, not an OS sandbox.

Cache/session/project-mode TypeScript state defaults beneath .signalint/. SIGNALINT_STATE_DIR redirects supported state paths; do not share one override directory indiscriminately between unrelated projects.

Issue detail is snapshot-aware

Call get_issue_detail with a known ID and, when possible, its originating check:

{ "clusterId": "cluster-id", "checkId": "check-id" }

checkId is mandatory in 1.2.1; missing it is an invalid-arguments refusal, not latest-result lookup. An issue reference can be a full hash or returned short prefix. Multiple matching records are possible because issue IDs omit engine and column. Unknown, expired or unmatched references are stale; an older retained snapshot remains queryable.

In both and structured, successful detail mirrors the { "issues": [...] } wrapper in the first JSON text block and structured object. In text, it remains a serialized array. structured adds a second user-facing summary block. Normalized messages remain bounded—not the original unabridged engine messages.

Snapshots, delta and live ingestion

• Snapshots & edit verification: retention, semantic matching, scope and coverage limits.
• Live & external diagnostics: LSP input shape, accumulated buffer behavior and the full live array.
• get_live_diagnostics can enumerate latest internal/buffered issue IDs even when the check summary omitted flat records. It is not pagination of every historical snapshot.

Source-writing tools

Read preview & apply transactions before enabling apply. Preview supplies lengths rather than a unified diff. Apply performs path revalidation and SHA-256/content drift preflight, then sequential adjacent temp-file replacements with in-process best-effort rollback. It is not an all-files atomic commit or persistent crash journal. An optional supplied baseline is validated before writes; unknown/expired baselines refuse without consuming an active preview. Without a baseline, no delta is requested. Failed post-verification does not undo successful writes.

apply_diagnostic_fix advertises readOnlyHint: false, destructiveHint: true, and idempotentHint: false. Preview is non-idempotent in-memory preparation; discard mutates in-memory state. Other read-only annotations do not eliminate check artifacts or ingestion’s buffer mutation.

Payload modes

• both (default): minified JSON text plus structured data, with the literal-pong exception; successful detail is wrapped consistently in both channels.
• text: text only; advertised output schemas are omitted.
• structured: the same JSON text fallback and structured object, plus a second user-facing summary. It is larger than both on the audited fixtures.

See payload modes for measured wire costs and compact-key limitations. Schema 1.4 describes native check summaries; it is not a version field present on every tool result.

Errors and cancellation

Unknown tool names and non-object argument containers throw JSON-RPC -32602. Missing fields, unknown keys and path refusals are handled as tool-result refusals (isError: true) where caught by the server. This distinction is narrower than “all invalid arguments are protocol errors.”

Normal engine fan-out can preserve successful peers and return status: error; inspect engines as well as isError. Thrown check-provider failures are classified as engine_timeout (retryable), output_limit_exceeded, or engine_execution_failed, with actionable next steps. The engine-failure helper sanitizes wire messages with path/env/stack patterns; stderr still logs the original detail, and input/transaction errors are not all processed by that helper. No universal secret-redaction guarantee is implied. Check-request cancellation propagates to native providers/processes; it does not imply every tool, transaction write or rollback has equivalent cancellation semantics.

Source: tools.ts, toolArguments.ts, and createServer.ts.

Schema-validation scope

Inputs are parsed by strict Zod objects; output schemas are advertised in both/structured modes and exercised by upstream Ajv tests and validating clients. The server’s low-level handlers do not add a per-tool Ajv validation gate for every return. Compact aliases and thrown post-apply verification remain known schema gaps; test the specific client/path rather than treating the release prose as a universal runtime guarantee.