Hook Conformance

StudioMeyer MCP Stack の一部 — マヨルカ島で開発 🌴 · 使用したら ⭐ をお願いします

mcp-hook-conformance

Claude Code v2.1.118 の mcp_tool ライフサイクルフックへの対応状況を、あらゆる MCP サーバーについて監査するテストハーネス CLI です。

3つ目の基盤となる柱です。

• mcp-protocol-conformance は、サーバーがプロトコルに準拠しているかを示します。
• mcp-server-attestation は、このサーバーに署名したのは誰かを示します。
• mcp-hook-conformance は、Stop、PreCompact、UserPromptSubmit フックからこのツールを安全に呼び出せるかを示します。

私たちからひとこと

私たちは過去2年間、自分たちのためにツールやシステムを作ってきました。このリポジトリが小さく、スターが少ないのは、新しいからではありません。これまでに作ってきたものを公開することにしたのが、つい最近だからです。これは新しい実験ではなく、最近のコミットへと続く長い物語です。

私たちはものづくりと共有が好きです。ソーシャルメディアの戦術やグロースハック、スターやフォロワー集めには興味がありません。そのため、このリポジトリは小規模です。コードは実際に使われており、Issue には回答しています。ご自身で判断してください。

役に立った場合は、共有やテスト、フィードバックで応援していただけるとうれしいです。改善できそうな点があれば、Issue を作成していただくと助かります。このツールを使って何かを作ったら、[email protected] までお知らせください。本当にうれしいです。

マヨルカ島パルマの小さなスタジオより。

インストール

npm install -g mcp-hook-conformance

インストールせずに実行する場合：

npx mcp-hook-conformance check ./hook-conformance.config.json

クイックスタート

# 1. Scaffold a config
npx mcp-hook-conformance init --server-name my-mcp-server

# 2. Edit hook-conformance.config.json (point command/args at your server)

# 3. Run the audit
npx mcp-hook-conformance check ./hook-conformance.config.json

終了コード：

• 0 監査に合格（FAIL なし）
• 1 監査で1件以上の FAIL が発生
• 2 設定エラー（ファイルがない、スキーマが無効、スイート名が不明）

サブコマンド

サブコマンド	引数	説明
check	<config-path> [--output=human|json|junit] [--suite=...] [--tool=<name>] [--tries=<n>]	監査を実行し、レポートを標準出力に出力します。
init	[--server-name=<name>] [--force]	サンプルの hook-conformance.config.json を cwd に書き込みます。
explain	<finding-code>	検出結果の詳細な説明と修正方法を出力します（例：IDEMP-001）。
version-info	—	ツールのバージョンと、対応する MCP 仕様の範囲を出力します。（エイリアス：version。）

これは CLI であり、MCP サーバーではありません。 mcp-inspector 経由で mcp-hook-conformance を実行しないでください。このパッケージで mcp.specVersion を宣言しているのは、監査対象に関するものであり、パッケージ自体が MCP を話すためではありません。設計上、Inspector は dist/index.js（ライブラリのエクスポート）に対して EACCES を返します。

監査スイート

スイート	チェック内容	重み
idempotency	同じ入力を N 回与えると同じ出力になること。注釈がない限り UUID やタイムスタンプを含まないこと。	30
side-effects	読み取り専用ツールがサーバーの状態を変更しないこと。stateProbe の設定が必要です。	25
latency	p50 < 30s、p95 < 60s（設定可能）。ウォームアップ呼び出し1回の後、5回サンプリングします。	20
determinism	呼び出しごとにレスポンスの構造が安定していること。浮動小数点値にずれがないこと。	15
dsgvo	ツールの説明に、データの流れ、保持、削除についての記述があること（単語全体を対象とするヒューリスティック）。	10

スイートのスコア：PASS = 100、WARN = 60、INDETERMINATE = 50、FAIL = 0。 ツールのスコア = 設定されたスイート全体の加重平均。 総合スコア = 各ツールのスコアの平均。

設定形式

{
  "$schema": "https://studiomeyer-io.github.io/mcp-hook-conformance/config.schema.json",
  "server": {
    "name": "my-mcp-server",
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "my-mcp-server"],
    "env": {}
  },
  "suites": ["idempotency", "latency", "determinism", "side-effects", "dsgvo"],
  "tries": 3,
  "thresholds": {
    "latencyP50Ms": 30000,
    "latencyP95Ms": 60000
  },
  "probes": [
    {
      "name": "search_things",
      "args": { "query": "audit-fixed-input" },
      "stateProbe": {
        "tool": "list_things",
        "args": {}
      }
    }
  ],
  "toolFilter": ["search_things", "get_thing"]
}

probes を使うと、ツールごとに特定の引数を固定できます。また、読み取り専用ツールでは stateProbe を設定して、副作用スイートが変更を検出できるようにします。stateProbe がない場合、そのツールに対する副作用スイートの結果は INDETERMINATE になります。

検出コード

コード	スイート	重大度	タイトル
IDEMP-001	idempotency	FAIL	同一の呼び出し間でツールの出力が異なります
IDEMP-002	idempotency	WARN	応答に nondeterministic アノテーションのないタイムスタンプが含まれています
IDEMP-003	idempotency	WARN	応答に nondeterministic アノテーションのない UUID／ランダム ID が含まれています
LAT-001	latency	FAIL	ツールが p95 レイテンシの上限を超えました
LAT-002	latency	WARN	ツールの p50 レイテンシが 30 秒を超えています
DET-001	determinism	FAIL	呼び出し間で浮動小数点出力に差異があります
DET-002	determinism	WARN	呼び出し間で応答の形式が変化します
SIDE-001	side-effects	FAIL	読み取り専用ツールで状態の変化が発生しました
SIDE-002	side-effects	INDETERMINATE	副作用検出用の状態プローブが設定されていません
DSGVO-001	dsgvo	FAIL	破壊的なツールに削除／保持に関するドキュメントがありません
DSGVO-002	dsgvo	WARN	ツールの説明にデータフローに関するキーワードがありません

詳しい修正方法は、mcp-hook-conformance explain <code> を実行してください。

互換性

コンポーネント	バージョン
MCP spec	2025-06-18
Claude Code	>= 2.1.118 (mcp_tool lifecycle hooks)
Node	>= 20.0.0
@modelcontextprotocol/sdk	^1.29.0

テスト済みのトランスポート：

• stdio（主なトランスポート）
• HTTP streamable（実験的。監査の動作は stdio と同じです）

リファレンススモークテスト

tests/smoke/ スイートは、mcp-nex および mcp-crm の本番テナントに対して監査を実行します。オプトイン：

RUN_SMOKE_TESTS=1 npm run test:smoke

スナップショットの差異が見つかった場合は、CI の失敗ではなく、手動レビューが行われます。

制限事項（必ずお読みください）

• 副作用の検出は完全に隔離された環境では行われません。 stateProbe がない場合、読み取り専用ツールが純粋であることをブラックボックステストで証明することはできません。誤検出による FAIL の代わりに INDETERMINATE を返します。
• レイテンシは stdio のエンドツーエンドの往復時間です。 JSON-RPC のフレーミングが含まれ、純粋な計算時間ではありません。
• DSGVO スイートはキーワードに基づくヒューリスティックです。 ドキュメントの不足は確実に検出できますが、「準拠しているように見える」という判断は法的助言ではありません。
• 自動修正はありません。 このツールは検出結果を報告します。修正はご自身で行ってください。

StudioMeyer について

StudioMeyer は、パルマ・デ・マヨルカを拠点に、世界中のクライアントと仕事をする AI とデザインのスタジオです。中小企業向けに、カスタムウェブサイトと AI インフラストラクチャを構築しています。本番環境のスタックには Claude Agent SDK、MCP、n8n を採用し、可観測性には Sentry、Langfuse、LangGraph を使用しています。また、独自のガードレイヤーも備えています。

ライセンス

MIT © 2026 Matthias Meyer (StudioMeyer)