Signalint

Signalint

Signalint は、AI コーディングエージェント（Claude Code、Cursor、Codex、VS Code）と CI ワークフロー向けの、信頼性が高く、デフォルトで読み取り専用の診断インテリジェンスレイヤーです。

エージェントのコンテキストウィンドウに何千行もの生のコンパイラー出力を流し込む代わりに、Signalint はコンパイラー、リンター、言語サーバーの診断を正規化し、上限付きで優先度別に分類された問題の要約にまとめます。また、明示的なベースラインと照らし合わせた検証差分を計算し、修正ループの振動を検出します。

---

主な差別化要因

• 13 個の完全な MCP ツール： 差分チェックや不変スナップショットから、ライブ診断の取り込み、変更履歴を記録するトランザクション型の修正適用までを提供します。
• 検証差分： 行のずれをまたいで一致する意味的な識別を用いて、新規、解消済み、未変更の診断を正確に計算します。
• 不変スナップショットと並行処理の安全性： checkId をキーとする分離されたインメモリスナップショットストアにより、並行チェック中の競合を防ぎます。
• モノレポを考慮した計画： 純粋な JavaScript の YAML パーサーで解析したパッケージマニフェスト（pnpm-workspace.yaml）を、glob の否定による除外および TypeScript Project References と統合し、チェックをトポロジカル順に並べます。
• 複数ソースの来歴： JavaScript、TypeScript、Python（Ruff/Mypy）、Rust（Clippy）、Go（GolangCI-Lint）にわたり、コンパイラー、リンター、エディター/LSP の診断を区別します。
• 移植性の高いホストフック： Claude Code、Cursor、Codex、VS Code 向けに、変更後に検証を実行するネイティブアダプターを提供します。
• インメモリプレビューとプロセス内ロールバック： インメモリプレビューではディスクに一切触れません。適用時には、ファイルごとに隣接する一時ファイルへの置き換え、書き込み前の差分検出、および複数ファイルへの書き込みに対するプロセス内のベストエフォートロールバックを行います（異常終了時の永続的なクラッシュリカバリーを保証するものではありません）。

---

クイックスタート

1. 要件

• Node.js >= 22.12.0（ネイティブの node:sqlite を使用します）。
• プロジェクトで診断エンジン（typescript、oxlint、eslint、および／または @biomejs/biome）をインストールしてください。Signalint はプロジェクトローカルのインストールを検出し、エンジンを同梱しません。

2. リポジトリで初期化する

npx signalint init

これにより、プロジェクトのリンター／コンパイラーを検出し、signalint.config.json を生成して、インストール済みの MCP クライアントを設定します。

3. MCP クライアントに追加する

Signalint を MCP 設定（例：claude_desktop_config.json、.cursor/mcp.json）に追加します：

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

---

MCP ツールカタログの全容

Signalint は stdio 経由で 13 個の厳密に型付けされた MCP ツールを公開します。

ツール	カテゴリ	安全性の注釈	説明
ping	診断	読み取り専用（idempotent）	サーバーの応答性と正規のプロジェクトルートパスを確認します。
check_project	診断	読み取り専用（idempotent）	有効なすべてのエンジンを対象に、プロジェクト／ワークスペース全体をスキャンします。
check_files	診断	読み取り専用（idempotent）	コンテンツハッシュキャッシュを使って、指定ファイルを高速かつ増分的にチェックします。
get_issue_detail	診断	読み取り専用（idempotent）	不変の checkId に紐づく、省略のない完全な問題レコードを取得します。
get_loop_status	診断	読み取り専用（idempotent）	セッションで検出された、振動する修正シグネチャとルールの変動を返します。
get_diagnostic_snapshot	スナップショット	読み取り専用（idempotent）	不変のチェック用スナップショットの完全な状態とメトリクスを取得します。
compare_diagnostics	差分	読み取り専用（idempotent）	ベースラインチェックと現在のチェックの検証差分を算出します。
after_edit_check	差分	読み取り専用（idempotent）	編集したファイルを増分的にチェックし、ベースラインチェックとの差分を比較します。
ingest_diagnostics	ライブ／LSP	読み取り専用（openWorld: false）	外部の LSP またはコンパイラの診断を Signalint のクラスタリングモデルに取り込みます。
get_live_diagnostics	ライブ／LSP	読み取り専用（idempotent）	ソースの出所情報を含む、アクティブなバッファ済み診断を返します。
preview_diagnostic_fix	トランザクション	読み取り専用（destructive: false）	提案されたコード修正をメモリ上でステージングします。ディスクには書き込みません。
apply_diagnostic_fix	トランザクション	変更あり（destructive: true）	ファイルごとの隣接一時ファイルによる置換、書き込み前のドリフトチェック、プロセス内でのベストエフォートなロールバックを行います。
discard_diagnostic_fix	トランザクション	読み取り専用（idempotent）	ディスクに触れずに、メモリ上の修正トランザクションを破棄します。

完全な JSON Schema とエラーコードについては、docs/mcp-contract.md を参照してください。

---

CLI コマンド

Signalint には包括的なコマンドラインインターフェースが含まれています。

# Run a project diagnostic scan:
npx signalint check .
npx signalint check src/ --format github    # GitHub Actions annotations

# View session statistics and cache economics:
npx signalint stats

# Verify local engine availability and configuration:
npx signalint doctor

# Manage host verify-after-change hooks:
npx signalint hooks preview --runtime claude
npx signalint hooks install --runtime cursor --confirm
npx signalint hooks run --runtime claude --payload '<json-event>'

---

モノレポのサポート

Signalint はマルチパッケージのモノレポをネイティブに理解します。

• signalint.config.json で "monorepoMode": "auto" を設定すると、グロブの否定除外（!）に対応した純粋な JavaScript の YAML 解析によって pnpm-workspace.yaml を検出します。
• ローカルのワークスペースパッケージ（workspace:*）と、外部の npm レジストリ依存関係を厳密に区別します。
• パッケージマニフェストと TypeScript プロジェクト参照を統合した、トポロジカルな依存関係グラフを構築します。
• プログラム全体の TypeScript ビルドを、パッケージごとの分離されたディレクトリ（.signalint/cache/tsc/<project-id>/）にキャッシュします。
• 共有パッケージへの変更は依存パッケージを自動的に無効化する一方、独立した兄弟パッケージのキャッシュは維持します。

設定とアーキテクチャについては、docs/monorepo.md を参照してください。

---

変更後検証フック

エージェントの無限ループを発生させずに、編集後の検証を自動化します。

• Claude Code、Cursor、Codex、VS Code 用のネイティブアダプター。
• プロンプトウィンドウに上限付きのコンテキストを出力し、未解決の構文エラー／型エラーがある場合にのみ処理をブロックします。

セットアップ手順については、docs/hooks.md を参照してください。

---

ドキュメント一覧

• アーキテクチャとサブシステム
• MCP プロトコルの契約とスキーマ
• ホストフックアダプターガイド
• モノレポ計画と TypeScript の増分処理
• 既知の制限事項とリスクリスト
• ワイヤー削減ベンチマーク
• セキュリティと脅威モデル

---

ライセンス

MIT © 2026 Tran Trong Qui