Hook Conformance

StudioMeyer MCP Stack 的一部分 — 于马略卡岛打造 🌴 · 如果你在使用，请点个 ⭐

mcp-hook-conformance

用于测试的 CLI，可审计任意 MCP 服务是否已准备好支持 Claude Code v2.1.118 的 mcp_tool 生命周期钩子。

第三块基石：

• mcp-protocol-conformance 回答：服务是否支持该协议？
• mcp-server-attestation 回答：谁为这个服务签名？
• mcp-hook-conformance 回答：从 Stop、PreCompact 或 UserPromptSubmit 钩子调用这个工具是否安全？

我们想说的话

过去两年，我们一直在为自己打造工具和系统。这个仓库规模小、星标少，并不是因为它刚刚创建，而是因为我们直到最近才决定分享已构建的成果。这不是一次全新的尝试，而是一段漫长历程，最近才有了提交记录。

我们喜欢构建和分享，不喜欢社交媒体策略、增长技巧，也不热衷于追逐星标和关注者。所以这个仓库规模不大。代码是真实的，确实有人在用，问题也会得到答复。欢迎自行判断。

如果它对你有帮助，分享、测试和反馈都能帮到我们。如果你觉得它还有改进空间，提交 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 审计至少发现一项 FAIL
• 2 配置错误（缺少文件、架构无效、套件名称未知）

子命令

子命令	参数	说明
check	<config-path> [--output=human|json|junit] [--suite=...] [--tool=<name>] [--tries=<n>]	运行审计；将报告输出到 stdout。
init	[--server-name=<name>] [--force]	将示例 hook-conformance.config.json 写入当前工作目录。
explain	<finding-code>	输出某项发现的完整说明和修复方法（例如 IDEMP-001）。
version-info	—	输出工具版本和支持的 MCP-spec 范围。（别名：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	响应包含 UUID／随机 ID，但未标注 nondeterministic
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 规范	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，我们无法通过黑盒证明只读工具是纯函数。我们会返回 INDETERMINATE，而不是误报 FAIL。
• 延迟是 stdio 端到端往返延迟。 包含 JSON-RPC 封装，不只是纯计算耗时。
• DSGVO 套件采用关键词启发式检测。 它能可靠地发现文档缺失；“看起来合规”并非法律建议。
• 不会自动修复。 此工具只报告发现的问题；需要你自行修复。

关于 StudioMeyer

StudioMeyer 是一家位于马略卡岛帕尔马的 AI 与设计工作室，为全球客户提供服务。我们为中小型企业打造定制网站和 AI 基础设施。生产技术栈基于 Claude Agent SDK、MCP 和 n8n，并使用 Sentry、Langfuse 和 LangGraph 进行可观测性管理，同时配备自研的防护层。

许可证

MIT © 2026 Matthias Meyer（StudioMeyer）