MCP tools reference

ping

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.

check_project

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.

{
  "paths": ["src/"]
}

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

check_files

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. Incremental checks also track file-rule churn: if the same (file, rule) produces issues across 3+ separate calls, a fileRuleChurnWarning is raised.

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

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

get_issue_detail

Returns the full issue list for either one cluster ID or one issue ID from the most recent check_project or check_files call. Read-only; no files are written or modified. Supply exactly one non-empty reference — supplying both or neither returns an argument error. If the referenced cluster or issue no longer exists in the latest results (e.g., after re-running a check), returns a status: "stale" response instead of an error:

{
  "clusterId": "c1"
}

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

Returns all diagnostic issue signatures currently flagged as looping (repeatedly appearing and disappearing) and file/rule pairs flagged as churning across 3+ separate check_files calls. Read-only; no files are written or modified. History is accumulated across all check calls in this process lifetime, and is restored from .signalint/session.jsonl on startup. Accepts {} and reports the independent loop and churn state:

{
  "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"
  }],
  "fileChurning": false,
  "fileRuleChurns": []
}

CheckResponse · schema 1.2

{
  "schemaVersion": "1.2",
  "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,
  "fileRuleChurnWarning": null
}

Cluster

LoopWarning

FileRuleChurnWarning

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