passmcp

passmcp-server

passmcp 是 Model Context Protocol 服务诊断工具，现在以 MCP 工具的形式提供，因此 Agent 可以在编辑器中评估服务，或检查相关证明。它只读、采用允许列表，且绝不会发送凭据。

---

目录

快速开始

• 安装 — 发布压缩包、go install、make install、容器映像和 MCP 主机配置
• 要求 — passmcp 本身，以及从源码构建所需的 Go 最低版本
• 快速入门 — 让 Agent 评估本地服务

passmcp-server 生态

• passmcp-server 生态 — passmcp、passmcp-reporting、passmcp-server、passmcp-action、passmcp-graph、passmcp-registry、passmcp-lsp、passmcp-census、satellion.com

库参考

• 功能一览 — 按主题划分的当前功能范围
• 生态比较 — 简要矩阵；完整表格见 docs/COMPARISON.md
• 基准测试 — 主要数据；完整表格见 docs/BENCHMARKS.md
• 功能 — 允许列表、不使用凭据、只读
• 配置 — 两个标志及其环境变量
• 示例 — 工具调用和结果

运维

• 不适合使用 passmcp-server 的情况 — 局限性
• 开发 — make 目标、安装约定、CI
• 安全性 — Agent 能让它做什么、不能让它做什么
• 文档 — 所有参考文档
• 稳定性保证 — 工具名称、参数和结果
• 许可证

---

安装

passmcp_check 会运行 passmcp 程序。要让该工具正常工作，必须安装 passmcp 并将其加入 PATH，或使用 --passmcp 指定其名称；容器镜像中已包含该程序。 passmcp_verify_attestation 除 passmcp-server 外无需其他内容。

作为 Go 程序

go install satellion.com/passmcp-server/cmd/[email protected]
go install satellion.com/passmcp/cmd/[email protected]

Linux、macOS 和 Windows 的 amd64 与 arm64 版本发布二进制文件可在 发布页面获取， 其中包含签名校验和与 SLSA 来源证明。

从源代码使用 make install 安装

git clone https://github.com/sebastienrousseau/passmcp-server
cd passmcp-server
make install PREFIX="$HOME/.local"

make install 会构建二进制文件及其 bash、zsh 和 fish 补全，并将它们安装到 PREFIX 下（默认为 /usr/local）；打包程序设置 DESTDIR 时，会将文件暂存到该目录。 make uninstall 会将它们移除。 GNUmakefile 定义了安装约定，CI 会在每次推送时检查暂存目录树。

作为容器镜像

docker pull ghcr.io/sebastienrousseau/passmcp-server:0.0.8

该镜像基于 passmcp 自己的发布镜像，并添加了 passmcp-server：采用 distroless、 非 root 用户运行，支持 linux/amd64 和 linux/arm64；passmcp 位于 /usr/local/bin/passmcp， passmcp-server 启动时会通过 --passmcp 指向该程序。

在 MCP 宿主中使用

passmcp-server 通过 stdio 使用 MCP，因此宿主会将其作为子进程启动。 对于 Claude Desktop（claude_desktop_config.json）、Claude Code（.mcp.json） 以及其他读取 mcpServers 区块的宿主：

{
  "mcpServers": {
    "passmcp": {
      "command": "passmcp-server",
      "args": ["--allow", ".internal.example.com"]
    }
  }
}

改用容器镜像时：

{
  "mcpServers": {
    "passmcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/sebastienrousseau/passmcp-server:0.0.8"]
    }
  }
}

在容器内，loopback 指向容器自身。要评估宿主机上的服务，请在 Linux 上使用 --network host 运行容器，或指向 host.docker.internal，并在参数中添加 -e PASSMCP_SERVER_ALLOW=host.docker.internal。

该服务已列入官方 MCP Registry，名称为 com.sebastienrousseau/passmcp-server；server.json 即为 该条目。

---

要求

要求	最低要求	强制方式
passmcp	已加入 PATH，或使用 --passmcp 指定；版本需与本项目保持同步	CI 会在该标签下构建 passmcp，并使用它评估此服务
Go（从源代码构建）	go.mod 中的 go 指令	CI 会在 Linux、macOS 和 Windows 上使用该版本及最新稳定版本进行测试
MCP 宿主	能启动 stdio 服务并支持 2025-03-26 或更高版本协议修订的任意宿主	握手会协商使用 2025-11-25、2025-06-18 或 2025-03-26，并通过 server/discover 支持 2026-07-28
被测服务	位于允许列表中的 Streamable HTTP 端点	passmcp_check 会在运行 passmcp 前拒绝其他 URL

只有当某个版本需要使用语言功能时才会提高 Go 最低版本要求；和所有 1.0 之前的版本一样，这会在补丁版本中进行，变更日志也会说明。

---

快速开始

go install satellion.com/passmcp-server/cmd/[email protected]
go install satellion.com/passmcp/cmd/[email protected]
claude mcp add passmcp -- passmcp-server

接着，确保你自己的 MCP 服务正在 http://127.0.0.1:3000/mcp 上监听，然后向 Agent 提出请求：

使用 passmcp 评估我的 MCP 服务 http://127.0.0.1:3000/mcp，并修复未通过的项目。

Agent 会调用 passmcp_check，该工具会运行 passmcp check http://127.0.0.1:3000/mcp --auth none --output json，并返回评分、 等级，以及每项失败检查的详情和修复链接。loopback 无需配置；其他任何主机都必须先使用 --allow 指定。

---

passmcp-server 生态

每个组件均以 0.0.8 发布，并保持同步：整个系列使用同一个版本，并同时发布（docs/ecosystem.md）。

组件	用途	使用场景
passmcp	MCP 服务诊断工具：分九个阶段进行检查，每项发现都与触发它的请求关联，并提供签名证明	在 Agent 信任服务之前对其进行测试，并在 CI 中设置准入门槛
passmcp-reporting	证明格式、JSON Schemas 和离线验证器、图模型，以及 agentgateway 处理器	在网关、注册表或流水线中验证证明
passmcp-server	将 passmcp 的诊断功能作为只读 MCP 工具提供	在 Agent 内评估服务或检查证明
passmcp-action	在 GitHub Actions 和 GitLab CI 中使用 passmcp，并通过摘要固定镜像	根据你选择的发现结果使构建失败
passmcp-graph	根据证明构建的 Agent、服务、工具和身份的本地图谱	发现继承风险和权限过高问题，并根据策略设置准入门槛
passmcp-registry	MCP Registry 远程服务的签名公开评分卡	连接公开服务之前，检查其状态
passmcp-lsp	MCP 工件语言服务，可在悬停时显示指导目录中的检查 ID	编辑时发现 server.json、工具架构和客户端配置中的错误
passmcp-census	已发布的可靠性普查：数据集、方法、披露日志和复现命令	引用整个生态的可靠性数据，并复现这些数据
satellion.com	网站、Go 模块路径和格式 URI	阅读手册，并解析 satellion.com/... 导入

此仓库是分发入口：其交付物是注册表列表，因此 Agent 会在 passmcp 中查找工具。它封装了 passmcp 的发布版本，因此自身版本始终与 passmcp 的最新版本完全一致；make lockstep 会检查这一点，make family 会检查此仓库在系列清单中的条目，而 make versions 会检查所有注明版本的文件以及 go.mod 中的 passmcp-reporting 模块是否一致。

---

功能一览

领域	功能	状态
评估	passmcp_check：为已列入允许列表的 Streamable HTTP 端点评分、评级、统计数量，并列出最多 25 项未通过的检查；还可选择 passmcp 九个阶段中的部分阶段进行评估	已在 0.0.1 中发布
验证	passmcp_verify_attestation：离线验证 passmcp 证明的结构、主体摘要和目标	已在 0.0.1 中发布
识别	passmcp_version：passmcp-server 的版本及其运行的 passmcp 版本	已在 0.0.1 中发布
结果	提供给 Agent 的文本，以及与各工具 outputSchema 相匹配的 structuredContent	已在 0.0.1 中发布
协议	stdio；支持握手版本 2025-11-25、2025-06-18、2025-03-26；支持 2026-07-28 版本的 server/discover；ping	已在 0.0.1 中发布
作为程序运行的服务（--stdio）	不通过工具运行；请自行运行 passmcp check --stdio	不在范围内
凭据	从不发送；每次运行都使用 --auth none	设计上不在范围内

---

生态对比

另一种方式是在终端中运行 passmcp，然后将报告粘贴到对话中；也可以在检查器中手动探测服务。passmcp-server 替 Agent 做出它不应做的决定：允许访问哪些主机、确保不传输任何凭据，以及生成适合上下文窗口长度的结果。

方式	Agent 可以调用	目标受操作者限制	提供评分和修复链接
passmcp-server	可以	可以——除非使用 --allow，否则仅限环回地址	可以
在终端中运行 passmcp check	不可以	操作者输入 URL	可以
MCP Inspector	不可以——这是供人使用的 UI	操作者输入 URL	不可以

有关证据和完整对比表，请参阅 docs/COMPARISON.md。

---

基准测试

此服务会为每次运行增加一个进程启动和一次 JSON 往返；实际运行由 passmcp 执行，最长不超过五分钟。测试使用从此代码树和 passmcp 0.0.1 构建的二进制文件，并通过 hyperfine 测量。测试机器当时正在运行其他构建任务，因此结果范围较宽，最低值更具参考意义。

场景	结果	环境
启动、initialize、tools/list、passmcp_version、退出	平均 27.2 ms ± 22.2 ms，最低 6.2 ms（50 次运行）	Apple A18 Pro，Go 1.27.1，2026-09-29，平均负载 19
passmcp 对 passmcp-server 进行完整的 stdio 评估	平均 242.3 ms ± 80.5 ms，最低 148.5 ms（30 次运行）	同上
针对某个服务运行 passmcp_check	passmcp 自身的计时数据，见其报告	目标服务

有关测试方法和完整结果，请参阅 docs/BENCHMARKS.md。

---

功能

默认启用且范围严格的允许列表。 未进行任何配置时，passmcp_check 只评估环回地址：localhost、任何 *.localhost 名称以及环回 IP。--allow 可指定更多主机，可以精确指定，也可以使用 .example.com 匹配所有子域（不包括根域）。passmcp 会向指定的端点发出真实请求，而 Agent 根据提示词选择该端点，正是请求不应发往操作者未指定位置的情形。对于非 http 或 https 的 URL，或包含凭据的 URL，passmcp 会在运行前拒绝。

不使用凭据。 每次运行都会执行 passmcp check <endpoint> --auth none，并将 PASSMCP_CONFIG 指向空配置文件，因此操作者为自己使用而写入的任何配置文件或默认设置都无法添加凭据、启用修改操作或重定向报告。操作者的机密不会被发送到 Agent 指定 passmcp 前往的任何位置。

双重只读。 这里的每个工具都标注了 readOnlyHint: true。并且不会向 passmcp 传递任何允许修改操作的标志，因此 passmcp 只会调用被评估服务中声明了 readOnlyHint 的工具。

运行 passmcp，而不是复制它。 passmcp-server 会运行 passmcp 程序并读取其输出的 JSON 报告；它不会链接 passmcp 的引擎。passmcp_version 报告的版本就是 passmcp version 输出的版本，而且 passmcp 的每项安全属性都有效，因为服务只能请求 passmcp 自身标志所允许的内容。

提供 Agent 可据以采取行动的答案。 检查失败时会附带其 ID、严重程度、详情和文档链接。无法验证的声明会返回说明原因的结果，而不是工具错误。如果服务的所有检查都失败，则会返回前 25 项失败结果，并说明结果已截断。

---

配置

标志	环境变量	默认值	含义
--allow	PASSMCP_SERVER_ALLOW	空：仅限环回地址	除环回地址外，passmcp_check 可以评估的主机，以逗号分隔；前置点号表示允许子域
--passmcp	PASSMCP_SERVER_PASSMCP	PATH 中的 passmcp	passmcp 程序的路径
--version	—	—	打印版本并退出
--completion	—	—	打印 bash、zsh 或 fish 的补全脚本并退出

标志优先于其对应的环境变量。不会读取其他任何内容：无论操作者自己的 passmcp 配置如何，passmcp 本身都会使用空配置文件运行。

Shell 补全由标志集生成，因此会列出所有标志：

passmcp-server --completion bash > /etc/bash_completion.d/passmcp-server
passmcp-server --completion zsh > "${fpath[1]}/_passmcp-server"
passmcp-server --completion fish > ~/.config/fish/completions/passmcp-server.fish

---

示例

对 passmcp_check 的 tools/call 请求：

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"passmcp_check","arguments":{"endpoint":"http://127.0.0.1:3000/mcp","phases":["handshake","catalog"]}}}

另外两个工具的 arguments：

{"statement": "<the attestation's JSON text>", "endpoint": "https://mcp.example.com/mcp"}

{}

第一个是 passmcp_verify_attestation，其中 endpoint 为可选参数；第二个是 passmcp_version，不接受任何参数。未知参数会被拒绝，而不是忽略，因此拼写错误会得到报告。

无需指定主机即可查看握手和工具列表：

make smoke

---

何时不应使用 passmcp-server

• 用于以程序形式运行的服务。 passmcp_check 接受 Streamable HTTP URL。让 Agent 启动任意程序涉及不同的信任决策；请自行运行 passmcp check --stdio -- <command>。
• 用于需要凭据的服务。 每次运行都会使用 --auth none，因此评估结果反映的是未经身份验证的客户端所见内容。其余情况请在终端中使用提供给你的凭据运行 passmcp。
• 用作 CI 门禁。 请使用 passmcp-action，它会保留报告并使作业失败。
• 用于检查谁签署了证明。 passmcp_verify_attestation 会检查结构和完整性；签名属于信封本身，应使用 cosign 或 gh attestation verify 进行检查。
• 用于同时进行多项评估。 请求会依次处理；需要同时进行两项评估的主机应启动两个服务。

---

开发

make            # format, vet, lint, headers, tests, stdio smoke test
make test-race  # race detector, randomised order
make image      # the container image for this machine, without goreleaser
make family     # this repository's row in passmcp's family manifest
make lockstep   # the version is passmcp's latest release
make versions   # every version-bearing file, and go.mod, name that release
make coverage-json  # build/coverage.json, the document behind the badge
make install-smoke  # install and uninstall under a staged DESTDIR

CI 运行的每项门禁都有对应的本地运行方式；DEVELOPMENT.md 对它们进行了说明。CI 还会以锁步版本构建 passmcp，并通过 stdio 让它评估此服务；若得分低于 90，或除 supply.provenance 之外有任何检查未通过，就会失败。

---

安全

Agent 传入的端点会在 passmcp 运行前根据允许列表进行检查，被拒绝的端点绝不会传到 passmcp。passmcp 使用 --auth none 和空配置文件运行，且不会传入任何允许变更型工具的标志；这些行为都在 internal/runner 和 internal/server 中进行了测试。Agent 收到的内容有明确限制：每个结果最多包含 25 项失败信息，且 passmcp 的错误输出会截取最后 400 个字符。CI 会在每次推送时运行 govulncheck，发布版本则使用 cosign 无密钥签名，并附带 SLSA 构建来源证明。

请按照 SECURITY.md 报告漏洞。

---

文档

以下四个入口在该系列的每个仓库中都相同：

• 用户手册 — passmcp 的渲染版手册：各个阶段、检查项和报告
• API 参考 — 此模块的各个包
• 开发者文档 — 工具链、任务映射，以及如何在本地复现每项 CI 门禁
• 生态系统图 — 系列项目、已发布的制品以及锁步版本规则

文档	涵盖内容
docs/ARCHITECTURE.md	调用流程、各个包，以及每次运行所固定使用的设置
docs/adr/	此仓库的决策记录
docs/COMPARISON.md	passmcp-server 与其他运行 passmcp 的方式对比
docs/BENCHMARKS.md	此服务为运行增加的内容及其测量方式
docs/publishing.md	发布注册表条目
docs/releases/	发布亮点，每个版本对应一个文件
server.json	MCP 注册表条目
SECURITY.md	漏洞披露政策、受支持的版本以及保障范围
CONTRIBUTING.md	签名提交和 DCO 政策，以及变更要求
CHANGELOG.md	各版本说明及锁步版本规则
SUPPORT.md	提问渠道及相关预期

---

稳定性保证

passmcp-server 尚未达到 1.0 版本，与 passmcp 使用相同的版本号，并遵循 SemVer；在达到 1.0 之前，所有变更都递增补丁位。

破坏性变更的判断标准，是 Agent 或宿主所依赖的内容。 以下均属于破坏性变更：

• 移除或重命名工具、参数或结构化结果字段
• 将可选参数改为必填
• 扩大默认允许列表、发送凭据，或向 passmcp 传入允许变更型工具的标志
• 更改标志或环境变量的含义

新增工具、可选参数和结果字段，以及底层 passmcp 发布新版本，均不属于破坏性变更。运行报告的内容由 passmcp 决定，并遵循 passmcp 自身的稳定性规则。

弃用窗口。 弃用的工具或参数至少会在宣布弃用的版本发布后继续可用一个版本。

---

许可证

根据 GNU 通用公共许可证 v3.0（仅此版本） 授权。

passmcp-server 与其运行的程序 passmcp 一样，采用 GPL-3.0-only 许可证。它使用 Apache-2.0 许可证的 passmcp-reporting 验证器进行证明验证。

返回顶部