code-auditor-mcp

Code Auditor

AI エージェントの編集ループ内でアーキテクチャ上の不変条件を適用します。エージェントがプロジェクトのルールに違反するコードを書くと、Code Auditor がそれを検出して編集をブロックします。エージェントにはルールのメッセージが表示され、自ら修正します。

インストール

npm install -g code-auditor-mcp
code-audit install --agent all

どこでも使えるように、2 つのコマンドでインストールできます。code-audit install --agent all は、マシン上のすべての AI コーディングツールにスキルをコピーします。特定のツールを指定するには --agent を使用してください。

各ツールにインストールされるもの：スキル（SKILL.md）、MCP サーバーへのアクセス、そしてツールが対応している場合はフックの設定（Claude Code と Codex ではブロック、Cursor では助言）。

code-audit install --list   # see the support matrix

Claude Code ユーザーは、プラグインからインストールすることもできます。

claude plugin marketplace add BenAHammond/code-auditor-mcp
claude plugin install code-auditor

フックは初回使用時に npx 経由で監査ツールを自動インストールします。

要件

• 実行には Node 18+ が必要です。Node 23.4+ では、ネイティブ依存関係のインストールが不要な方法を利用できます。Code Auditor は組み込みの node:sqlite モジュールを使用するため、インストール時のコンパイルや、ビルド済みバイナリのダウンロードは不要です。
• 古い Node（18～23.3）では、Code Auditor は better-sqlite3 にフォールバックします。これはオプションの依存関係です。npm 11.2+/12 では、依存関係のインストールスクリプトがデフォルトでブロックされるため、一度承認する必要があります。 npm install-scripts approve better-sqlite3 && npm rebuild better-sqlite3 （pnpm の場合は pnpm approve-builds を実行し、次に better-sqlite3 を選択します）。

設定

プロジェクトレベルの設定は .codeauditor.json に記述します（不変条件ルール、アナライザーの設定、しきい値）。さらに 11 個の環境変数で、ワーカープールのサイズ、デーモンとジョブキューのタイムアウト、インデックスの保存場所、SQLite バックエンド、UI のポートなど、プロセス単位の動作を調整できます。

変数	用途	指定できる値	デフォルト
CODE_AUDITOR_WORKERS	ファイル単位の分配に使用するフェーズモデルのワーカープールサイズです。1 にすると、バイト単位で同一のレポートを生成する直列処理になります。	正の整数	max(1, cpus − 1)
CODE_AUDITOR_RULE_TIMING	ルールごとの実時間の計測です（ルール ID ごとに累積タイマーを 1 つ使用し、レポートに表示します）。	1 で有効、未設定で無効	オフ
CODE_AUDITOR_DAEMON_IDLE_MS	デーモンが終了するまでのアイドルタイムアウトです。	0 より大きい有限のミリ秒数。不正な値の場合はデフォルト	300000（5 分）
CODE_AUDITOR_DAEMON_LEASE_TTL_MS	デーモンのハートビートリース TTL です。	有限のミリ秒数。空欄／0 の場合はデフォルト	60000（60 秒）
CODE_AUDITOR_DATA_DIR	コードインデックスのデータベースディレクトリを上書きします。	ディレクトリパス（前後の空白を除去。空欄の場合はデフォルト）	ユーザーレベルの OS キャッシュ
CODE_AUDITOR_EXIT_ON_FATAL	捕捉されない例外／未処理の拒否が発生した場合に MCP サーバーを終了します。	1 または true	オフ
CODE_AUDITOR_JOB_TIMEOUT_MS	キューに登録された監査ジョブごとのタイムアウトです。	有限のミリ秒数。60s～4h の範囲に制限されます。下限未満の場合はデフォルト	1800000（30 分）
CODE_AUDITOR_JOB_LEASE_TTL_MS	古い running ジョブの行を再取得するためのハートビートリース TTL です。	0 より大きい有限のミリ秒数。不正な値の場合はデフォルト	30000（30 秒）
CODE_AUDITOR_MAX_RUNNING_JOBS	同時に実行できる、キュー登録済み監査ジョブの最大数です。	1 以上の整数。不正な値の場合はデフォルト	1
CODE_AUDITOR_SQLITE_BACKEND	SQLite バックエンドを強制的に指定します。不正な値は不正として報告され、拒否されます。暗黙的に別のバックエンドを検索することはありません。	node-sqlite | better-sqlite3	自動（プローブ）
MCP_UI_PORT	HTTP UI サーバーのポート（--ui）です。	ポート番号。不正な値の場合はデフォルト	3001

CODE_AUDITOR_DATA_DIR を設定すると、インデックスはプロジェクトごとに分離されます（<dir>/projects/<sha256(root)[:16]>/index.db）。そのため、プロジェクト間でデータが漏れることはありません。未設定の場合、インデックスはユーザーレベルの OS キャッシュ（<os_cache>/code-auditor/projects/<hash>/index.db）に保存されるため、監査対象のリポジトリ内に作成されることはありません。

プロンプトの例

「コードベースをインデックス化して完全な監査を実行し、code-audit next-file を使って違反をファイルごとに確認してください。」

「lodash のインポートを禁止し、src/languages/ から src/analyzers/ 内のものをインポートできないようにする .codeauditor.json を作成してください。」

「完全な監査を実行し、最優先のファイルを修正して、ツリーがクリーンになるまで code-audit next-file を繰り返してください。」

「コードインデックスを同期して、main と比べて変更された箇所のみを監査してください。」

「new Function(...) をブロックする ast-pattern ルールを追加してください。」

「src/hooks/ 内のフック名が use で始まることを必須にする命名ルールを追加してください。」

「src/services/payment.ts 内の chargeCustomer() を src/api/ からのみ呼び出せるようにする call-constraint を追加してください。」

ルールの種類

7 種類あります。エージェントはこれらを .codeauditor.json に書き込みます。不正な設定は監査に失敗し、黙って無視されることはありません。

種類	ブロックするもの
import-ban	禁止されたモジュールのインポート
call-constraint	許可されていないファイルからの関数呼び出し
module-boundary	モジュール境界を越えたインポート
naming	パターンに一致しないエクスポートされたシンボル
ast-pattern	ast-grep パターンに一致する AST ノード
style-mechanism	ファイル／glob ごとに承認されていないスタイル機構
no-raw-values	特定の CSS プロパティに設定されたハードコード値

エージェントで使えます

スキルは 1 つ、CLI は 1 つ、MCP サーバーは 1 つです。どのエージェントも同じ監査エンジンを使用します。違いはフックの契約だけです。

エージェント	スキル	フック／ブロック	MCP	検証済み
Claude Code	プラグインまたは code-audit install	はい — ブロック	はい	2026-07-19
Cursor	code-audit install --agent cursor（プロジェクトのみ）	アドバイザリー	はい	2026-07-19
Codex	code-audit install --agent codex ＋ プラグイン	はい — ブロック	はい	2026-07-19
Gemini CLI	code-audit install --agent gemini	いいえ	はい	2026-07-19
VS Code / Copilot	code-audit install --agent agents	いいえ	はい	2026-07-19
その他の SKILL.md ツール	code-audit install --agent agents	いいえ	はい	2026-07-19
ZCode	code-audit install --agent zcode	いいえ（プラグインの範囲内）	はい	2026-09-10

MCP 設定の生成は、スキルのインストールよりも幅広い対象に対応しています。 MCP サーバーの generate ツールは、claude、codex、cursor、gemini、copilot、continue、awsq（AWS Q Developer）、codeium（Codeium/Windsurf）、vscode、cline、zcode のいずれかに対応するクライアント設定ファイルを書き込みます。そのうち Continue、AWS Q Developer、Codeium/Windsurf、Cline の 4 つは MCP 専用です。ファイルベースのスキルやフックの経路がないため、code-audit install ではなく generate ツールを介して接続します。

フックの動作：ブロックとは、差分を対象とする changed ゲートが作動することを意味します。gating: true（重要度とは無関係の、ルールごとのバイナリーフラグ）を宣言する不変条件ルールは、編集内容が反映されるのをブロックします（エージェントは違反を確認し、その場で修正します）。アドバイザリーとは、利用可能な最も強力なフィードバックチャネルを通じて違反が報告されますが、編集はすでに行われていることを意味します。Cursor の afterFileEdit フックは、出力を消費せず、実行を待たない方式です。シェルを使わない場合も、どこでも MCP を利用できます。

調査結果：決定論的ルールと参考情報

Code Auditor の組み込みルールは、次の 2 つのカテゴリに分類されます。

カテゴリ	意味	例
決定論的	構造上の事実です。エンジニアはすべての検出結果に対応します	single-responsibility（300 行の関数）、solid/method-complexity（循環的複雑度が 20 を超える）、solid/class-size（メソッドが 40 個以上のクラス）、dependency-inversion（インターフェースが存在する箇所での具象インポート）
参考情報	ヒューリスティックによるシグナルです。ドメインによっては誤っている場合があります	sql-injection-risk（型情報を使わない AST レベルの文字列パターンマッチング）、missing-org-filter（ドメイン固有。SaaS のテナント分離を前提とする）、unknown-table（ユーザー提供のスキーマが必要）、dry/duplicate（トークンが同一のブロック）

決定論的ルールは critical または severe として提供されます。参考情報のルールは severe または high として提供されます。実際のコーパスで精度がほぼゼロと判明したルールは、デフォルトで無効（off）になっています。ユーザーは、そのルールが自分のドメインに適合する場合に有効化できます。

再調整

組み込みの重大度のデフォルト値は、実際のコーパスでのトリアージに基づいて再調整されています。現在のデフォルト値は、このツール自体のコードベース、Gin、Excalidraw の 3 つのコーパスでの測定結果を反映しています。3 つすべてのコーパスで精度がほぼゼロだった 6 つのデータアクセスルールは、デフォルトで無効になっています。

無効になっている各ルールには、どのようなコーパスで有用になるかが記載されています。ユーザーは .codeauditor.json の severityOverrides を使って、任意のルールを復元できます。

{
  "severityOverrides": {
    "sql-injection-risk": "critical",
    "missing-org-filter": "severe",
    "loop-query": "severe"
  }
}

重大度のオーバーライドはグローバルに適用されます（ディレクトリごとのパスプロファイルによる上限より前に適用）。ルールを "off" に設定すると、出力から完全に除外されます。

SQL インジェクションの検出

再調整後、sql-injection-risk ルールはデフォルトで無効（off）になっています。セルフ監査用コーパスでは精度が 0% でした。このルールは、TypeScript のパターンマッチングコード（このツール独自の SQL 検出に使用される 'SELECT'、'FROM'、'WHERE' などの文字列定数）をデータベースクエリと誤認していました。Gin と Excalidraw のコーパスでも、精度はほぼゼロでした。

再度有効にする場合：プロジェクトの SQL が、クエリの組み立てだけを目的とする関数内で文字列連結またはテンプレートリテラルを使って構築されている場合です。このルールはそうしたパターンを検出します。ORM またはパラメーター化クエリのみを使用するコードベースでは、このルールはノイズを発生させます。

再度有効にして SQL インジェクションをブロックするには：

{
  "severityOverrides": {
    "sql-injection-risk": "critical"
  }
}

sql-injection-risk: critical を設定し（さらにルールを gating としてマークすると）、エージェントのフックは AST レベルの SQL インジェクションパターンを持ち込む編集をブロックします。

棄却

すべての検出結果は判定ではなく測定値ですが、測定が誤っていることもあります。エージェントが誤検出（ルールは一般には正しいものの、この特定のコードには当てはまらない場合）に遭遇したときは、回避策を講じる代わりに、その該当する 1 件を棄却できます。

code-audit dismiss <fingerprint> --reason "generated code, not hand-written"

<fingerprint> は JSON レポートから取得します（違反にはすべて fingerprint フィールドが含まれます）。--reason には理由の記述が必須です。棄却によってクリアされるのは、ルール、ファイル、シンボルの組み合わせが一致する 1 件だけなので、同じルールは他のすべての箇所で引き続き検出されます。棄却情報はコミットされた .codeauditor.dismissals.json に保存され、差分でレビューできます。

匿名の却下フィードバック（オプトイン）

エージェントが指摘事項を却下する理由は、ルールの改善に最も役立つシグナルです。Code Auditor は、却下された指摘事項を収集する匿名フィードバックサービスに送信できます。

これはデフォルトではオフで、次の3つの方法のいずれかで明示的にオプトインした場合にのみ有効になります（優先順位順）。

1. 呼び出しごと — code-audit dismiss --telemetry … はその却下1件のみを送信します。--no-telemetry を指定すると、その1件の送信を抑制します。
2. 環境変数 — ヘッドレス実行やCI実行のマシンレベルのデフォルトとして、CODE_AUDITOR_TELEMETRY=1（または 0）を設定します。
3. 永続設定 — code-audit telemetry status|enable|disable（または telemetry MCP ツール）を使うと、ユーザー設定ディレクトリに選択内容が記録されます。

telemetry enable に引数は不要です。組み込みのサービスエンドポイント（セルフホスト用に変更可能）に対してオプトインします。オプトインすると匿名のインストール IDが生成されます。これはローカルで生成されるランダムな値で、マシン、ユーザー、プロジェクトに由来するものではなく、送信元ごとに送信内容をグループ化する目的にのみ使われます。

送信される情報 — ツールのバージョン、ルール ID、緊急度、入力されたままの却下理由、構造的な AST シグネチャ（文法上の種類のみで、内容は含みません）、大まかな言語のヒント、タイムスタンプ、匿名のインストール ID。送信されない情報 — ソースコード、識別子、リテラル、ファイルパス、またはコードや環境に由来する情報。送信はベストエフォートで行われます。オフラインの場合やエンドポイントに到達できない場合は、通知も行われず、編集をブロックしたりゲートを失敗させたりすることもありません。

スタイルインテリジェンス

Code Auditor は、プロジェクト内のすべてのスタイル宣言（CSS、SCSS、Tailwind、インラインスタイル、CSS-in-JS）をインデックス化します。スタイルルールはプロジェクト全体の分布を読み取り、単一ファイルのリンターでは検出できない断片化を指摘します。

7つの検出器、10個のルール ID：

検出器	検出内容
値の乖離	重複に近い色の値（delta-E < 2.0）と、1つの値が支配的な場合の完全一致する値の外れ値
スケール外	推定されたプロジェクトのスケールに沿っていないマージン／パディング／ギャップ／フォントサイズの値
未定義クラス	対応する CSS セレクターまたは Tailwind ユーティリティのない className の値
トークンの迂回	デザイントークンと一致するものの、そのトークンを参照していないハードコードされた値
実装方法の断片化	同じ (property, value) が3つ以上の実装方法（CSS、インライン、Tailwind）で指定されている状態
宣言セットの類似性	宣言の90%超が同一の2つの CSS ルールブロック
z-index の乱立	プロジェクト全体の z-index 一覧。異なる値が多すぎる状態、または単独で使われている値

スタイルルールはプロジェクト全体を対象とする SQLite インデックスを読み取るため、スコープを限定した実行（変更ファイルのみ）でも、プロジェクト全体のベースラインと比較されます。スコープを限定した実行で新たに現れた #273828 の色の乖離も、コーパス全体にある #1e2328 の値と比較して検出されます。

スタイル不変条件ルール：

{
  "rules": [
    {
      "kind": "style-mechanism",
      "message": "Only Tailwind in src/components/",
      "allow": ["tailwind"],
      "path": "src/components/**"
    },
    {
      "kind": "no-raw-values",
      "message": "No raw colors in src/pages/ — use design tokens",
      "properties": ["color", "background-color"],
      "path": "src/pages/**"
    }
  ]
}

スタイル検索演算子 — プロパティ、値、実装方法、トークンで検索します。

code-audit search "css:margin-top value:16px"          # specific value
code-audit search "mechanism:inline css:color"          # inline color declarations
code-audit search "token:--color-primary"                # bypassing a design token

React ルールには、生の要素の検出機能も加わります。プロジェクトに Button ラッパーがある場合、Button の定義外で使われている生の <button> が重大な指摘事項になります。

ライセンス

MIT