Documentationv0.2.0 / schema 1.1

MCP tools reference

Strict argument shapes and versioned response contracts for every Signalint MCP tool.

Tool arguments reject unknown properties. Path arrays accept at most 512 project-relative strings; absolute, escaping, NUL-containing, and leading-dash paths are refused.

ping

Confirms that the local stdio server completed its MCP handshake.

Arguments	Result
`{}`	`pong`

check_project

Checks the supplied project-relative paths through all configured engines. The optional paths field is a string array of at most 512 items and defaults to ["."].

{
  "paths": ["."]
}

Returns the CheckResponse shape. Built-in engine failures are retained under the corresponding engines status so other completed diagnostics survive.

check_files

Checks a required list of project-relative files. File-local engines receive cache misses; tsc is invoked against the whole configured program only when supplied TypeScript-relevant snapshots changed.

{
  "files": ["src/index.ts", "src/config.ts"]
}

The files array is required and accepts at most 512 strings.

get_issue_detail

Expands an issue or cluster from the latest successful check. Supply exactly one non-empty reference:

// Exactly one of these shapes
{ "clusterId": "c1" }
{ "issueId": "d7f6..." }

The successful result is an array of NormalizedIssue objects. An old reference returns:

{
  "status": "stale",
  "message": "This cluster/issue no longer exists; run check_project again."
}

get_loop_status

Accepts {} and reports issue signatures currently classified as oscillating:

{
  "looping": true,
  "signatures": [{
    "signature": "no-unused-vars:<identifier> is unused",
    "occurrences": 3,
    "hint": "This issue was fixed and reappeared 3 times — consider a different approach"
  }]
}

CheckResponse · schema 1.1

{
  "schemaVersion": "1.1",
  "status": "issues_found",
  "engines": {
    "oxlint": { "status": "ok" },
    "tsc": { "status": "ok" },
    "biome": { "status": "disabled" }
  },
  "totalIssues": 10,
  "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"]
  }],
  "truncated": false,
  "loopWarning": null
}

Field	Type	Contract
`schemaVersion`	`"1.1"`	Current response contract version.
`status`	`"clean" \| "issues_found"`	Whether normalized issues remain after filtering.
`engines`	record	Exactly `oxlint`, `tsc`, and `biome`; each is `ok`, `error`, or `disabled`, with optional message.
`totalIssues`	integer	Raw normalized issue count before cluster truncation.
`clusters`	Cluster[]	Priority-ascending clusters; priority 1 is highest. Ten are returned by default.
`truncated`	boolean	True when more clusters existed than the response limit.
`loopWarning`	LoopWarning \| null	The current oscillation warning, when applicable.

Cluster

Field	Type
`clusterId`	string
`rootCauseSummary`	string
`ruleIds`	string[]
`issueCount`	integer
`fileCount`	integer
`priority`	integer
`suggestedAction`	string
`sampleIssueIds`	string[]

NormalizedIssue

{
  "issueId": "d7f6...",
  "file": "src/index.ts",
  "line": 12,
  "col": 7,
  "engine": "tsc",
  "rule": "TS2322",
  "severity": "error",
  "message": "Type 'string' is not assignable to type 'number'.",
  "fixable": false,
  "clusterId": "c1"
}

engine is oxlint | tsc | biome; severity is error | warning; messages are normalized to at most 120 characters. clusterId is optional at the adapter boundary and present after clustering. fixable is true only when the engine supplies a structured fix.

Exceptional responses

These low-level structured contracts apply when a timeout or output-limit failure reaches the MCP handler directly. Normal built-in fan-out records the same message in that engine's status: "error" entry.

Engine timeout

{
  "status": "timeout",
  "engine": "tsc",
  "message": "tsc did not complete within 120s"
}

Engine output limit

{
  "status": "error",
  "code": "engine_output_exceeded",
  "engine": "oxlint",
  "message": "oxlint output exceeded the 10 MiB limit"
}