Skip to main content
Glama

Signalint

CI npm version M8ven Score

Signalint 是一个用于 JavaScript 和 TypeScript 诊断的本地 MCP 服务器。它运行 Oxlint、TypeScript,并可选择运行 Biome;缓存未更改的检查;对重复出现的问题进行聚类; 并在同一诊断消失后又反复出现时发出警告。 当 MCP 服务器重启时,循环历史会从有效的 .signalint/session.jsonl 条目中恢复; 格式错误或崩溃截断的行会被跳过。

已收录于:

诊断压缩示例

当编码代理请求项目诊断时,原始编译器和 linter 输出会迅速用跨多个文件的重复错误淹没上下文窗口。Signalint 会规范化问题,并按根本原因进行聚类,然后返回有界、按优先级排序的响应:

原始诊断(10 个文件中的 40 个问题 · 9,151 字节)

[
  {
    "issueId": "ts-01",
    "file": "src/file01.ts",
    "line": 10,
    "col": 5,
    "engine": "tsc",
    "rule": "TS2322",
    "severity": "error",
    "message": "Type 'string' is not assignable to type 'number' in fixture assignment 01.",
    "fixable": false
  },
  // ... 39 more raw normalized issues
]

返回给代理的聚类响应(4 个聚类 · 1,233 字节 · 减少 86.5%)

{
  "schemaVersion": "1.1",
  "status": "issues_found",
  "engines": {
    "oxlint": { "status": "ok" },
    "tsc": { "status": "ok" },
    "biome": { "status": "disabled" }
  },
  "totalIssues": 40,
  "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"]
    },
    {
      "clusterId": "c2",
      "rootCauseSummary": "10 no-unused-vars issues across 10 files",
      "ruleIds": ["no-unused-vars"],
      "issueCount": 10,
      "fileCount": 10,
      "priority": 2,
      "suggestedAction": "Review the shared cause of no-unused-vars across 10 files",
      "sampleIssueIds": ["unused-01", "unused-02"]
    },
    {
      "clusterId": "c3",
      "rootCauseSummary": "10 eqeqeq issues across 10 files",
      "ruleIds": ["eqeqeq"],
      "issueCount": 10,
      "fileCount": 10,
      "priority": 5,
      "suggestedAction": "Apply structured fixes for eqeqeq across 10 files",
      "sampleIssueIds": ["eqeqeq-01", "eqeqeq-02"]
    },
    {
      "clusterId": "c4",
      "rootCauseSummary": "10 prefer-const issues across 10 files",
      "ruleIds": ["prefer-const"],
      "issueCount": 10,
      "fileCount": 10,
      "priority": 5,
      "suggestedAction": "Apply structured fixes for prefer-const across 10 files",
      "sampleIssueIds": ["const-01", "const-02"]
    }
  ],
  "truncated": false,
  "loopWarning": null
}

代理会收到一个简洁的摘要,其中包含按优先级排序的聚类和示例问题 ID。当需要针对特定聚类或问题的更详细信息时,代理会调用 get_issue_detail,而无需重新运行整个项目扫描。

Related MCP server: agent-workspace-mcp

要求

  • Node.js 20.19 或更高版本(Node 20 系列),或 Node.js 22.12 或更高版本

  • 一个 JavaScript 或 TypeScript 项目;TypeScript 检查需要 tsconfig.json

  • 用于源码开发的 pnpm 11.9.0

安装

在要检查的项目中安装 Signalint:

npm install --save-dev signalint-mcp

从该项目根目录运行设置命令。它会检测 TypeScript、Oxlint 和 Biome 配置,写入 signalint.config.json,并提供更新附近的 Claude Code、Cursor、Codex CLI 或 Antigravity MCP 配置的选项:

npx signalint-mcp init

如果无法安全选择 MCP 客户端,该命令会打印要复制的确切配置片段。仅当根目录存在 tsconfig.json 时才启用 TypeScript;当存在 Biome 配置时启用 Biome;当未检测到配置的 linter 时,Oxlint 是回退选项。要手动配置 Signalint,请创建 signalint.config.json:

{
  "engines": {
    "oxlint": true,
    "tsc": true,
    "biome": false
  },
  "ignore": ["node_modules/**", "dist/**", ".signalint/**"],
  "timeoutsMs": {
    "oxlint": 30000,
    "tsc": 120000,
    "biome": 30000
  }
}

Claude Code 设置

从被检查的项目中运行此命令。项目范围会写入一个可共享的 .mcp.json:

claude mcp add --scope project signalint -- npx --no-install signalint-mcp
claude mcp get signalint

在原生 Windows 上,按 Claude Code 的要求包装 npx:

claude mcp add --scope project signalint -- cmd /c npx --no-install signalint-mcp
claude mcp get signalint

如果 Claude Code 已打开,请重启它。让它调用 Signalint 的 ping 工具, 然后使用 { "paths": ["."] } 调用 check_project。

有关范围和故障排除的详细信息,请参阅 Claude Code MCP 文档。

Cursor 设置

在被检查的项目中创建 .cursor/mcp.json:

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

在原生 Windows 上使用 "command": "cmd" 和 "args": ["/c", "npx", "--no-install", "signalint-mcp"]。打开 Cursor 的 MCP 设置,启用 signalint,然后调用 ping,接着调用 check_project。

有关配置位置和状态控制的详细信息,请参阅 Cursor MCP 文档。

Codex CLI 设置

ChatGPT 桌面应用、Codex CLI 和 IDE 扩展共享一个 配置文件。快速添加命令会自动写入 ~/.codex/config.toml (全局):

codex mcp add signalint -- npx --no-install signalint-mcp

对于项目范围的配置(仅限受信任的项目),请在项目根目录的 .codex/config.toml 中添加:

[mcp_servers.signalint]
command = "npx"
args = ["--no-install", "signalint-mcp"]

在原生 Windows 上,使用 cmd 并将 npx 作为参数传递:

[mcp_servers.signalint]
command = "cmd"
args = ["/c", "npx", "--no-install", "signalint-mcp"]

有关所有配置选项(包括 cwd、env 和每个工具批准 设置)的详细信息,请参阅 Codex MCP 文档。

使用 Antigravity 进行设置

Antigravity 使用自己的 MCP 配置文件。已在 Windows 上通过 dogfooding 验证的路径是: %USERPROFILE%\.gemini\antigravity\mcp_config.json。

init 命令可以在确认后更新此文件。等效的 Windows 配置是:

{
  "mcpServers": {
    "signalint": {
      "command": "cmd",
      "args": ["/c", "npx", "--no-install", "signalint-mcp"],
      "cwd": "<absolute-path-to-your-project>"
    }
  }
}

在 macOS 或 Linux 上,使用 "command": "npx" 和 "args": ["--no-install", "signalint-mcp"]。更新配置后,重启或重新连接 Antigravity。

关于 Antigravity 产品变体的说明: Antigravity 已拆分为多个 产品(IDE、CLI、SDK)。每个变体可能使用不同的配置路径——上述 IDE 路径是确认可用的路径;其他变体可能使用 ~/.gemini/config/mcp_config.json 或项目范围的 .agents/mcp_config.json。 请参阅 antigravity.google/docs/mcp 获取 每个产品的权威列表。

Windows 故障排除

npm link 创建的 Windows .cmd 垫片可能会向 Node 暴露一个连接点路径。如果 signalint-mcp 以 initialize/EOF 错误结束,或 signalint stats 以 代码 0 退出但未打印任何内容,请使用编译后的入口点路径绕过垫片:

node C:\absolute\path\to\Signalint\dist\src\index.js
node C:\absolute\path\to\Signalint\dist\src\cli.js stats

当前构建在决定是否启动之前会规范化链接路径,但直接调用 Node 仍然是旧构建或不常见的 npm 设置的可靠回退方案。

配置

engines.oxlint、engines.tsc 和 engines.biome 是布尔值。默认值为 启用 Oxlint 和 tsc,禁用 Biome。省略的引擎键保留这些默认值。 未知键和类型错误的值会导致配置错误。

ignore 是一个项目相对 glob 数组。Signalint 支持 *、** 和 ?,规范化 Windows 分隔符,并排除匹配的请求路径和 诊断。由于 tsc 是一个全程序引擎,在调用时它仍然接收完整的 tsconfig.json 程序;被忽略的 TypeScript 路径不会触发增量 check_files 运行,其诊断会从响应中移除。

引擎原生配置保留在原生文件中。v1 缓存哈希识别根目录的 .oxlintrc、.oxlintrc.json、oxlint.json、tsconfig.json、biome.json 和 biome.jsonc。更改其中一个会使相关引擎缓存失效。其他有效的 源——包括 .oxlintrc.jsonc、扩展配置和嵌套的包配置—— 不属于 v1 缓存哈希的一部分;更改其中一个后请清除 .signalint/。

timeoutsMs 以毫秒为单位设置正整数子进程截止时间。默认值为 Oxlint 30 秒、tsc 120 秒、Biome 30 秒。超时的引擎及其子进程会被终止。 在 schema 1.1 检查响应中,该引擎在 engines 下具有 { "status": "error", "message": "tsc did not complete within 120s" }, 而已完成引擎的诊断会被保留。

已知限制

  • Signalint 仅支持 JavaScript 和 TypeScript 项目。

  • 内置引擎是 Oxlint、TypeScript 和 Biome;v1 不支持 任意自定义引擎。

  • Signalint 报告问题是否具有结构化修复,但 v1 不应用 修复。

  • Signalint 不是 SAST 或安全扫描器。

  • 目前没有 IDE 扩展;集成使用 MCP 或命令行客户端。

  • 循环检测有意仅限于 lint、类型和测试问题签名; 它不检测一般的代理对话循环。

  • tsc 适配器要求项目根目录有一个 tsconfig.json。Monorepo 必须 使用 TypeScript 项目引用提供解决方案样式的根配置; Signalint 不会自动发现独立的包配置。

  • check_files 仅将显式传递给该调用的文件视为与 TypeScript 缓存失效相关。如果文件 A 更改但被省略,而未更改的文件 B 被检查,并且 B 依赖于 A,Signalint 可能会重用过时的 tsc 结果。包含 每个更改的依赖文件或运行 check_project;基于依赖图的 失效在 v1 中未实现。

MCP 工具

  • ping 检查本地服务器是否已连接并返回 pong。

  • check_project 接受可选的 { "paths": ["."] } 并返回聚类诊断。

  • check_files 接受 { "files": ["src/file.ts"] } 并使用增量缓存。

  • get_issue_detail 接受来自最新成功检查的恰好一个 clusterId 或 issueId, 并返回其完整问题,或返回 status: "stale" 响应。

  • get_loop_status 返回当前被标记为振荡的问题签名。

缓存和会话工件写入 .signalint/ 下,不应提交。

CLI 和包冒烟测试

在没有 MCP 客户端的情况下运行相同的项目检查:

npx --no-install signalint check .

在 MCP 检查累积到 .signalint/session.jsonl 之后,打印 Phase 6 测量摘要:

npx --no-install signalint stats

报告包括平均规范化原始到聚类 JSON 负载减少、引擎文件缓存命中率、平均和最大检查延迟,以及触发循环警告的不同问题签名数量。引擎文件查找会分别计算每个启用的引擎,因此一个更改的 TypeScript 文件可能为 Oxlint 和 tsc 各错过一次。延迟涵盖从 MCP 工具入口到引擎/缓存工作、聚类和循环评估的处理程序工作;它排除遥测追加和 stdio 传输。统计包括活动会话日志及其轮换的 .1 备份,其保留的重叠部分只计算一次。零原始负载的干净检查被排除在 减少平均值之外,而缺少指标的旧检查仍被计数,但不计入不可用的聚合值。

CLI 在发现问题时以代码 1 退出。两个标志支持 CI 使用: --format github 为每个问题打印一条 GitHub Actions 注释 (::error file=...,line=...,col=...::message 或 ::warning ...) 而不是 JSON,--fail-on-priority <N> 仅在聚类的优先级等于或低于 N 时以非零退出,而不是在发现任何问题时。

要对已安装的包执行实际的 MCP check_project 调用, 请运行:

node node_modules/signalint-mcp/examples/check-project.mjs .

GitHub Actions

存储库根目录的 action.yml 将 signalint check 包装为复合 操作,用于 CI。它安装 Node,从 npm 安装 signalint-mcp,并 使用 --format github 运行检查,以便问题以内联注释的形式出现在 拉取请求差异上:

- uses: TranQui004/signalint@main
  with:
    fail-on-priority: "3"

fail-on-priority 默认为 5,这会在发现任何问题时使作业失败, 匹配不带标志的 signalint check 的默认行为。较低的值 仅在聚类至少达到该紧急程度时使作业失败:优先级 1 是 没有结构化修复的错误,优先级向 5 增加,因为问题变得 更可修复或更系统化(请参阅 src/cluster/clusterEngine.ts 中的 scorePriority)。

开发

pnpm 11.9.0 是源码开发的规范包管理器。存储库 提交 pnpm-lock.yaml,在 package.json 中声明 pnpm,并在 CI 中使用 pnpm。

pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm test
pnpm build

如果全局 npm 垫片找不到 npm-cli.js,请直接使用 node node_modules/typescript/bin/tsc -p tsconfig.json 构建。

在准备发布之前,使用 npm pack --dry-run 并在干净的项目中验证打包的 tarball。发布需要明确的发布批准。

安全

有关当前的 npm 审计公告、其评估的运行时可达性以及需要重新评估的条件,请参阅 SECURITY.md。

文档

许可证

Signalint 采用 MIT License 许可。

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
    ResponsivenessNo recent community issues

    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