Quickstart

Complete installation and client setup first. The examples below show MCP tool arguments and representative structured results—not shell commands. IDs and paths will differ in your project.

1. Confirm the project with ping

Ask your agent to call ping with an empty object:

{}

The text response is pong. In the default both mode its structuredContent confirms the canonical project root (text mode omits it):

{
  "pong": true,
  "projectRoot": "/path/to/your-project"
}

Check the path before editing. If it names another repository, fix the client configuration using the multiple-projects guide.

2. Check the project

Call check_project:

{
  "paths": ["."]
}

Omitting paths also checks .. A representative result looks like this:

{
  "schemaVersion": "1.4",
  "status": "issues_found",
  "projectRoot": "/path/to/your-project",
  "engines": {
    "oxlint": { "status": "ok" },
    "tsc": { "status": "ok" }
  },
  "totalIssues": 21,
  "clusters": [
    {
      "clusterId": "c4588ddaf",
      "rootCauseSummary": "21 TS2322 issues across 11 files",
      "ruleIds": ["TS2322"],
      "issueCount": 21,
      "fileCount": 11,
      "priority": 1,
      "sampleIssueIds": [
        "b2dbbc348dd5"
      ]
    }
  ],
  "remainingIssues": [],
  "omittedIssueCount": 0,
  "truncated": false,
  "checkId": "7e3c2bd2"
}

Start with the lowest priority number: 1 is most urgent, 5 is least urgent. Always read status and each engine’s outcome; an engine failure can coexist with useful diagnostics from completed engines.

3. Request the details you need

Single-rule occurrences appear in remainingIssues, and clusters containing only 2 issues omit sample IDs. Use a returned clusterId or issueId as appropriate. Call get_issue_detail with an issueId from sampleIssueIds when present. checkId is required in 1.2.1 and selects the originating retained snapshot. It is not a unique invocation ID; identical diagnostic fields can produce the same value across calls:

{
  "issueId": "b2dbbc348dd5",
  "checkId": "7e3c2bd2"
}

The structured result wraps the matching diagnostics in issues:

{
  "issues": [
    {
      "issueId": "b2dbbc348dd564e942cc317d434c39d4ac3a1a925d3d53fe23d5d184ce8b820a",
      "file": "src/file01.ts",
      "line": 3,
      "col": 14,
      "engine": "tsc",
      "rule": "TS2322",
      "severity": "error",
      "message": "Type 'string' is not assignable to type 'number'.",
      "fixable": false,
      "clusterId": "c4588ddaf"
    }
  ]
}

Use clusterId instead of issueId to retrieve matching normalized diagnostics for a cluster. Supply exactly one of the two. In both/structured, the first JSON text block mirrors the { issues: [...] } wrapper; only text mode returns the array itself; see the MCP tool reference for transport details.

References are not guaranteed unique or permanent; see ID limitations. Pin the originating checkId to query an older retained snapshot; unknown/expired snapshots or unmatched IDs are stale. An unpinned detail request is refused; there is no latest-snapshot fallback.

4. Edit, then recheck

Signalint reports diagnostics; your agent or editor makes the changes. After an edit, call check_files with every changed file:

{
  "files": ["src/file01.ts", "src/shared-types.ts"]
}

File-local engines reuse unchanged snapshots. TypeScript still runs its configured program, then check_files filters displayed diagnostics to requested paths. Positive filtered-count aliases and nextStep point to other diagnostics you should inspect with check_project.

The TypeScript metadata fingerprint introduced in 1.2.0 can invalidate cache for unrequested source edits inside its walk. It does not track every external dependency, symlink, nested-config input, or same-size/mtime edit; see caching.

Use check_project when you need a broader snapshot that fits the current scan limits, and follow the cache caveats after changes outside tracked inputs.

5. Watch for a recurring issue

Check responses may include loopWarning or fileRuleChurnWarning. To inspect the current session state, call get_loop_status with {}:

{
  "looping": false,
  "signatures": [],
  "fileChurning": false,
  "fileRuleChurns": []
}

A warning is a reason to investigate the approach, not a guarantee that Signalint knows the correct fix. Read loop and churn detection for the exact behavior.

Next steps

• MCP tools — accepted arguments, outputs, and error codes.
• Configuration — engine selection and timeouts.
• Clustering and priorities — how findings are grouped and ordered.

Retain a baseline for your next edit

Save the check ID, engine outcomes and scope in the current 1.2.1 workflow. After an edit, after_edit_check can run a configured file check and compare it to the baseline. Read snapshots & delta: scoped absence is not proof of resolution, and delta advice does not certify engine coverage.

Checking still does not edit source. The separate preview/apply tools accept caller-provided replacement content and can explicitly write it; do not enable apply without reviewing its permissions and limitations.