使用说明
mcp表面印刷
检查、指纹识别和区分MCP服务器声明的功能表面。
MCP服务器可以在现有工具名称下获得工具、参数、资源、提示或新操作。 mcp-surfaceprint 将客户端可见表面捕获为确定性快照，在检查完成时计算稳定的摘要，并显示随时间变化的结构差异。
将其用作：
- MCP服务器维护人员的接口兼容性检查
- 为使用第三方MCP服务器的团队提供能力变更审查门
如果你想要更深入的框架和实验，请参阅 你无法证明MCP服务器没有改变.
为什么
在安装MCP服务器之前，您需要对其进行检查。稍后，依赖性升级会在现有工具名称下添加一个破坏性操作。软件包版本发生了变化，但没有任何东西能为您提供您之前审查过的声明能力表面的持久、结构化记录。
mcp-surfaceprint 将该声明转换为可以提交、比较和审查的版本化工件。
快速启动（快照+检查）
pipx install mcp-surfaceprint
# Commit a baseline snapshot (one-time)
mcp-surfaceprint --save mcp-surface.json "uv run server.py"
git add mcp-surface.json
# Later, locally or in CI: check the live server against the baseline
mcp-surfaceprint check mcp-surface.json "uv run server.py"
改变的表面不会自动变得不安全； check 将其转化为明确的审查事件，而不是让它被忽视。
安全： 此命令在本地启动服务器。MCP发现不会调用其声明的工具，但服务器在处理任何请求时可以执行任意代码。使用
--isolate-home防止它使用你的正常HOME以及XDG目录；这不是沙盒。
示例更改
Surface changed.
Tools:
~ manage_items
inputSchema.properties.action.enum:
+ delete
Previous: sha256:...
Current: sha256:...
结构化输出：
mcp-surfaceprint check --json mcp-surface.json "uv run server.py" > check.json
它捕获和比较的内容
- 工具、描述和完整的输入模式
- 架构字段、必需参数和枚举值，包括未更改的工具名称下的更改
- 资源和资源模板
- 提示和提示论点
- 对于在一个工具后面复用操作的服务器，可选的每个工具清单操作（请参阅 docs/server-manifest.md)
集成
快照、表面摘要和结构化 check --json 输出可以被注册表、治理系统、代理运行时和安全网关使用。这些系统可以将批准锚定在特定的观察表面上，并在该表面发生变化时触发重新审查。
mcp-surfaceprint 提供检验工件；消费系统决定是允许、阻止、沙盒还是要求批准。
常见工作流程
# Inspect (human-readable)
mcp-surfaceprint "uv run server.py"
mcp-surfaceprint "npx my-mcp-server"
mcp-surfaceprint "python3 /path/to/server.py"
# Save a snapshot (JSON)
mcp-surfaceprint --save snapshot.json "uv run server.py"
# Check against a baseline snapshot
mcp-surfaceprint check mcp-surface.json "uv run server.py"
# Diff two saved snapshots
mcp-surfaceprint diff before.json after.json
# JSON output
mcp-surfaceprint --json "uv run server.py"
CI工作流程
check 将声明的表面更改转化为显式的审查步骤，具有稳定的退出代码和可选的结构化JSON(--json).
- 提交基线快照（一次性）。
- 跑
mcp-surfaceprint check ...在CI。 - 如果表面发生了变化，请查看PR中的差异，并有意更新基线快照。
退出代码：
- 0--未更改：检查已完成，表面消化物匹配
- 1--已更改：检查已完成，表面消化不同
- 2--检查失败：超时、需要身份验证、启动错误等。
- 3--未完成检查：飞行前无法建立可比的表面消化
- 4--无效基线：缺少/部分基线，快照版本不受支持，JSON无效
机器可读输出：
mcp-surfaceprint check --json mcp-surface.json "uv run server.py" > check.json
echo "exit_code=$?"
快照和身份
快照将观测元数据与声明的曲面分开。仅对归一化曲面进行哈希处理。
只有当每个支持的身份承载发现部分都成功完成时，才会发出摘要。不完整的检查不会产生摘要，而不是声称具有可比的身份。
看 快照格式和规范化.
交互式检查
交互式检查输出对于首次探索、调试和手动审查非常有用。
Example interactive inspection output
my-server (MCP 2025-03-26)
Caution: the server process runs locally without sandboxing.
Use --isolate-home to prevent access to your real HOME directory.
MCP Tools (client-visible):
🟢 list_items "List all items in the database"
🟢 get_item "Get a single item by ID"
🟡 create_item "Create a new item"
🟡 update_item "Update an existing item"
🔴 delete_item "Permanently delete an item"
Resources:
📄 my-server://items
📄 my-server://items/{id}
Additional declared operations (from server manifest, 12 across 3 tools):
Not represented as separate entries in tools/list.
These are server-declared actions multiplexed behind the tools above.
↳ items (8): list, get, create, update, delete, search, export, archive
↳ reports (3): daily, weekly, monthly
↳ auth_login (single action)
Prompts:
💬 analyze_items (project_name)
Auth-gated servers / custom env
一些MCP服务器仅在身份验证后显示工具/资源。 mcp-surfaceprint 不运行登录流，因此在提供凭据之前，它可能无法枚举部分或全部声明的表面。
# Pass a token via env
export MCP_SERVER_TOKEN=...
mcp-surfaceprint "npx -y my-mcp-server"
# Point HOME (and XDG_* dirs) somewhere else (useful for servers that read ~/.config, ~/.local, etc.)
mcp-surfaceprint --home /tmp/mcp-surfaceprint-home "npx -y my-mcp-server"
# Isolate HOME entirely to reduce side effects/pollution
mcp-surfaceprint --isolate-home "npx -y my-mcp-server"
Optional heuristic annotations
交互式检查可以根据工具名称和描述添加启发式信号，包括读/写/破坏性注释。这些只是提示：它们没有被强制执行，也没有参与表面消化。
通过以下方式禁用它们：
mcp-surfaceprint --no-signals "uv run server.py"
非目标
mcp-surfaceprint 不提供沙盒、策略执行或运行时分析。它描述了服务器声明的接口；它并不能证明声明是真实的、详尽的或安全的。
文档
- 快照：请参阅 docs/snapshots.md
- 服务器清单（可选）：请参阅 docs/server-manifest.md
- 设计原则：见 原则.md
- 更深入的框架/实验：见 你无法证明MCP服务器没有改变
