mcp-inspector

MCPJam CLI 调查

在分析来自 mcpjam 或 MCP Inspector 输出的 MCP 服务行为时使用此技能。目标是区分：

• 真正的协议问题
• 互操作性警告
• 实现方面的完善度
• mcpjam 或 SDK 产生的伪象

交互式使用

当用户希望连接到服务并使用它时：

1. 先探测服务：server probe --url <url> --quiet --format json。

• 使用探测结果了解身份验证状况、资源元数据、授权服务器元数据和注册策略，再判断已连接的接口是否公开。

2. 如果探测结果显示 oauth_required，请使用 oauth login --credentials-out <path> 进行身份验证；如果任务是专门测试 OAuth 流程，则运行 oauth conformance --credentials-out <path>。
3. 发现工具：tools list --url <url> --credentials-file <path> --quiet --format json。

• toolsMetadata 中含有 _meta.ui.resourceUri、已弃用的 _meta["ui/resourceUri"] 或 openai/outputTemplate 的工具具有交互式 UI。
• 对于特定工具，请检查 toolsMetadata.<toolName>._meta.ui.resourceUri、toolsMetadata.<toolName>._meta["ui/resourceUri"] 或 toolsMetadata.<toolName>["openai/outputTemplate"]。

4. 执行工具：tools call --url <url> --tool-name <name> --tool-args <json> --credentials-file <path>。
5. 使用 UI 执行：tools call --url <url> --tool-name <name> --tool-args <json> --credentials-file <path> --ui。

• --ui 会启动或连接到本地 Inspector 后端，并在 App Builder 中呈现已完成的结果。
• 在非 TTY、Agent 和 CI 运行中，--ui 默认不会打开浏览器。需要 CLI 自行打开 App Builder 时，请传入 --open。
• --open 会打开系统浏览器 URL；它不会连接到已受控的自动化浏览器，也不会让新标签页加载注入的渲染内容。如果浏览器自动化已打开 Inspector App Builder，请使用 --no-open。如果必须禁止启动、打开浏览器和发现操作，请使用 --attach-only。
• no_active_client 表示 Inspector 后端可能正在运行，但没有浏览器客户端连接。如需手动恢复，请使用 mcpjam inspector open，而非 mcpjam inspector start。
• 根级 error.code 或 inspectorRender.commands.*.error.code 中的 unknown_server 表示 Inspector 无法匹配所请求的服务。如果消息表明 App Builder 当前聚焦于另一个服务，请使用 --server-name <focused-name> 重试。
• UI 成功应以 inspectorRender.status === "rendered" 为准，而不能只看退出代码 0。如果渲染状态为 skipped，请根据 inspectorRender.remediation 或稳定的根级 warning.code 采取不同处理。
• 不要要求提供外部截图来证明渲染成功；iframe/canvas 内容可能导致浏览器快照工具无法正常工作。应优先参考 inspectorRender.status、命令响应和快照证据。
• 仅当工具具有 UI 元数据或用户明确要求查看 UI 时，才使用 --ui。

当用户要求调查、审计或分流处理时，请使用下面的调查工作流。

默认立场

• 相比经过规范化处理的 CLI 便捷输出，应更信任原始请求/响应证据。
• 应区分观察结果、合规性问题和安全发现。它们彼此相关，但不能互换。
• 根据规范强度评估声明：MUST 和 MUST NOT 是强有力的符合性信号；SHOULD 和 RECOMMENDED 是较宽松的指导；MAY 和可选字段通常仅供参考。
• 除非能证明攻击者可获得具体收益或存在明确的破坏路径，否则不要将安全发现标为 high。
• 证据模糊时，应降低置信度或使用 pending，不要夸大结论。

调查工作流

1. 从能够证实该说法的最精简命令开始。
2. 如果命令可能失败、你需要可复用的交接产物，或 CI 应保留证据，请在 server probe、server validate、tools call 或 oauth login 后添加 --debug-out <path>。
3. 如果探测结果显示 oauth_required，且任务是检查服务端界面，请继续使用 oauth login 或其他受支持的身份验证流程，获取可复用的凭据，然后再判断身份验证后的行为。对于多命令连接会话，使用 oauth login、oauth conformance 或 oauth conformance-suite 上的 --credentials-out <path> 持久化令牌，并在后续命令中使用 --credentials-file <path>；有关仅访问令牌的例外情况，请阅读 references/cli-surface-notes.md。如果令牌已可用（CI、M2M、环境变量），请尽可能优先使用凭据文件，仅在不得已时才传入 --access-token 或 --oauth-access-token。
4. 成功完成身份验证后，使用 server info、server capabilities、tools list、resources list/read/templates 和 prompts list/get 等直接命令检查已连接的界面。
5. 如果你需要一份广度优先的快照，而不是多个单一用途的命令输出，请使用 server doctor --out <path>。
6. 如果输出来自 server doctor 或 --debug-out 产物，请将其拆分为主要命令证据、探测证据和已连接扫描证据。
7. 如果说法具体涉及 MCP Apps 工具元数据或 ui:// 资源，请先运行 apps conformance --quiet --format json，再考虑改用 tools list 或 resources read。
8. 如果说法涉及工具结果在 Inspector 中的渲染，请使用 tools call --tool-name <name> --tool-args <json|@file|-> --ui --quiet --format json。

• 在非 TTY 运行中，如果尚未连接 Inspector 浏览器客户端，请添加 --open。
• 如果浏览器自动化已打开 http://127.0.0.1:6274/#app-builder，请添加 --no-open；--open 会启动系统浏览器，且目标可能不是由自动化控制的客户端。
• 使用 inspectorRender.status === "rendered" 确认 UI 已交付。将 inspectorRender.remediation 和稳定的跳过渲染 warning.code 值视为恢复提示，而不是 MCP 工具故障。
• 如果根错误或命令错误中出现 unknown_server，且消息中指出了目标服务，请使用 --server-name <focused-name> 重试。
• 如果跳过渲染时应报硬错误而不是警告，请使用 --require-render。

9. 如果某个字段可能由 CLI 添加或经 SDK 规范化，请在得出结论前阅读 references/cli-surface-notes.md。
10. 如果说法依赖 MCP 语义，请阅读 references/mcp-2025-11-25-interpretation.md。
11. 如果任务涉及 Cross-App Access、ID-JAG 或企业管理的授权，请在分析 xaa run 输出前阅读 references/xaa-id-jag-interpretation.md。
12. 如果任务涉及安全审查，请阅读 references/security-best-practices.md 中的完整清单，并遵循下方的安全审查工作流。
13. 按照下方的输出约定撰写结果。

安全审查工作流

当任务是评估 MCP 服务的安全状况时，请使用此工作流。所有检查都使用现有 CLI 命令，无需特殊安全工具。不要假设每个服务都应要求身份验证。

阶段 1：观察（只读）

首先运行 server probe --url <target> --quiet --format json。只有在有助于厘清情况时，才添加 oauth metadata 或 server doctor --out <path>。

• 记录初始身份验证信号：
  • full-auth candidate：探测 status 为 oauth_required
  • public-or-mixed candidate：探测 status 为 ready
  • unknown：探测结果仅为 reachable、error 或其他不明确状态
• 收集发现信息：
  • OAuth 元数据 URL，以及它们指向公开、私有还是可疑目标
  • scopes_supported、WWW-Authenticate 和 PKCE 方法
  • dcr、cimd 和 preregistered 等注册策略
• 记录你所依据的证据。原始探测/RPC 证据优于 doctor 摘要或便捷字段。
• 阶段 1 可形成观察结果和合规性说明。仅凭阶段 1 不应评定为 high 安全严重级别。

阶段 2：触发行为（仍以未认证为主）

在行为确认之前，应将阶段 1 的身份验证信号视为暂定结论。

• 对于 full-auth candidate：
  • 如果支持 DCR，则运行 DCR 结构探测
  • 在可行时，抽查有代表性的未认证 tools list 或 tools call 行为
  • 检查对格式错误、已过期或受众明显错误的令牌的处理方式，但不要夸大拒绝所能证明的内容
• 对于 public-or-mixed candidate：
  • 运行未认证的 tools list
  • 将暴露的工具分类为只读、写入或有副作用
  • 未认证地调用有代表性的公开工具
  • 检查受限工具是否会明确返回身份验证质询，而不是静默返回空数据或部分数据
• 匿名访问层级、速率限制或受限的公开访问属于安全状况说明，不应单独构成一种安全状况类别。
• 阶段 2 行为明确后，重新归类为 no-auth、full-auth、mixed-auth 或 unknown 之一。如果阶段 2 与阶段 1 矛盾，应更新安全状况并重新运行相关检查，而不是强行沿用旧分类。
• 在阶段 3 证实攻击者获益之前，阶段 2 的输入验证问题最高只能评为 medium 安全严重级别。
• 阶段 2 中，设计或安全状况方面的问题可能构成真实的安全问题，但不要自动提升严重级别。在评为 medium 或 high 之前，应记录不安全行为、滥用路径以及对所有者意图的不确定性。

阶段 3：利用或确认攻击者获益

如果证据依赖用户同意或 Cookie，请使用 oauth login 和同一浏览器会话。

• 使用阶段 3，将合理的安全疑虑转化为真实的端到端安全问题：
  • 证明 DCR 与授权流程的组合问题
  • 证明重定向 URI 精确匹配检查可被绕过
  • 证明接受外部令牌或传递令牌
  • 捕获代码、令牌或跨租户数据
• 跳过用户同意是评为 high 的一种途径，但并非唯一途径。任何能够证明攻击者获得具体利益的链条都可支持 high 评级。

阶段 4：盘点影响范围

• 身份验证成功后，解码 JWT 声明，使用原始日志检查 Mcp-Session-Id，并枚举工具、资源、提示词、作用域和租户上下文。
• 阶段 4 主要用于评估影响范围。除非同时证明了滥用行为，否则应将其视为背景信息。

安全严重级别校准

• high：有直接证据证明攻击者获益，或符合规范的客户端遭到破坏
• medium：存在可信的安全问题和具体攻击场景，但端到端证据仍不完整
• low：加固方面的缺口或影响有限的安全隐患
• pending：存在合理的安全隐患，且缺少某项具体证据；补足该证据可能显著提高或降低严重级别
• info：真实的观察结果，但尚无可信的攻击者获益

如果清单中的某项检查命中，但证据不足，请使用 pending，不要人为评定为 medium 或 high 安全严重级别。

命令选择

• server probe：检查 HTTP 传输的可达性、初始化行为和 OAuth 发现提示。
• server doctor：生成综合诊断材料，涵盖探测和连接后的行为。适合广泛排查，但单独使用时未必足以证明线路级行为。
• oauth metadata、oauth proxy、oauth debug-proxy：当一致性检查结果出乎意料时，精确检查端点和元数据。
• oauth login：获取可重复使用的凭据，并验证通过身份验证的 MCP 路径。使用 --credentials-out <path> 将令牌保存到磁盘（权限模式为 0600），以便后续连接命令使用 --credentials-file <path>，无需手动提取令牌；需要未过期访问令牌的命令，请查看 references/cli-surface-notes.md。当目标是检查需要 OAuth 的服务时，请使用此命令，然后继续执行连接命令，而不要停留在登录结果上。
• oauth conformance、oauth conformance-suite：进行流程级身份验证检查。请将其视为针对性探测，而非完整的安全审查。若通过的流程应将凭据交给后续连接命令，请使用 --credentials-out <path>；之后使用 --credentials-file <path>，而不要从 JSON 输出中提取令牌。默认情况下，原始 JSON 输出会隐藏 OAuth 密钥。启用 --conformance-checks 后，该命令可以直接探测 DCR 对非回环 http:// 重定向的处理、对无效客户端的拒绝、授权端点对重定向 URI 不匹配的处理、MCP 服务对无效承载令牌的拒绝，以及令牌端点对重定向 URI 不匹配的处理。
• xaa run：针对授权服务和 MCP 服务执行无头 Cross-App Access（ID-JAG）流程——签发令牌、通过 JWT 承载授权授予进行兑换，并执行通过身份验证的 MCP 初始化。当任务涉及企业管理的授权或 ID-JAG 信任排查时，请使用此命令。需要 --issuer-base-url 指向发布 CLI 本地签名密钥的源（通常为 mcpjam inspector start）；排查输出前，请阅读 references/xaa-id-jag-interpretation.md。这些是针对当前 ID-JAG 草案的定向检查，并非一致性测试套件；负向测试评分卡（篡改后的 ID-JAG）位于 Inspector UI 中，而非 CLI 中。
• apps conformance：执行服务端 MCP Apps 检查，涵盖 _meta.ui.resourceUri、ui:// 资源、resources/read、HTML MIME 类型和载荷结构，以及 _meta.ui 元数据。使用此命令排查 MCP Apps 接口问题。
• server info、server capabilities、server validate、server ping、server export：检查初始化和身份验证后的连接行为。
• tools list 和 tools call、resources list/read/templates、prompts list/get/list-multi：直接检查连接后的能力。使用 --ui 时，tools call 会在 Inspector 中渲染已完成的工具结果，并将 inspectorRender 报告为 UI 命令/渲染证据。
• 优先使用 --quiet --format json。如需请求和响应证据，而非摘要，请在支持时添加 --rpc。如需确保失败时仍能生成材料，请添加 --debug-out，但不要用它替代原始证据。
• 在一致性检查和差异命令中，使用 --reporter junit-xml 或 --reporter json-summary 生成 CI 报告材料。server validate 不接受 --reporter；验证材料请使用 --debug-out。不要使用 --format junit-xml；--format 仅用于原始 json 或 human 输出。
• 对于 JSON 值选项，当载荷由程序生成或包含引号时，优先使用 @path 或 - 标准输入，而不是在 Shell 中转义内联 JSON。例如：mcpjam tools call --url <target> --tool-name <name> --tool-args @params.json --quiet --format json。

输出约定

常规分类输出

对于非安全任务，返回：

• Verdict：real issue、interop warning、implementation polish 或 scanner/client artifact
• Severity：high、medium、low 或 info
• Confidence：high、medium 或 low
• Why it matters：用一段简短说明，联系互操作性、安全性或用户影响
• Evidence：支持该结论的确切命令行行为
• Missing evidence：在提高严重性或置信度之前需要确认的内容

安全审查输出

对于每项声称的安全审查发现，返回：

• Verdict：real issue、interop warning、implementation polish 或 scanner/client artifact
• Compliance severity：high、medium、low 或 info
• Security severity：high、medium、low、info 或 pending
• Confidence：high、medium 或 low
• Attack scenario or pending rationale：如果 Security severity 为 medium 或 high，开头用 2-3 句话说明攻击者是谁、需要什么条件以及能获得什么；如果为 pending，准确说明缺少什么证据
• Verified via：支持该结论的阶段及确切命令或结果
• Evidence：支持该结论的确切命令行行为
• Missing evidence：在提高严重性或置信度之前需要确认的内容

硬性规则

• 切勿将 toolsMetadata 称为 MCP 服务字段。
• 切勿使用已移除的 app/widget 命令渲染 UI。使用 tools call --ui；如需原始资源 HTML，则使用 resources read --resource-uri ui://...。
• 当 tools call --ui 可以驱动渲染时，切勿手动编排 Inspector API 调用。
• 用户指定了服务但未指定具体工具时，切勿跳过 tools list 发现步骤。
• 除非有原始 RPC 证据表明实际向服务器发送了 prompts/list 并收到响应，否则切勿根据空的提示词列表推断服务器支持提示词。
• 用户要求检查经过身份验证的服务器接口，而 CLI 可以完成登录时，切勿停留在 oauth_required。应进行身份验证，并在可行时继续执行登录后的命令。
• 切勿将 apps conformance 通过视为完全符合 SEP-1865。当前命令仅检查服务器端，无法证明主机生命周期、沙盒代理或 postMessage 桥接行为符合要求。
• 缺少 outputSchema、内容注释、scopes_supported 或 scope 提示等可选元数据时，除非存在 MUST 要求，否则切勿视为硬性失败。
• 将 OAuth RFC 违规与 MCP 配置文件偏好区分开来。
• 区分“服务器正确拒绝了错误请求”和“整体设计是安全的”。
• 将 --debug-out 生成的产物视为汇总证据包，而非纯粹的线上传输捕获记录。
• 切勿将缺少 scopes_supported 或 WWW-Authenticate 中缺少 scope 标记为安全问题。这两者都是可选项。
• 切勿仅凭服务器拒绝了某个特定的错误输入，就声称服务器“安全”。一次负向测试无法证明整体安全态势。
• 切勿将通过 oauth_invalid_token 或重定向不匹配探测视为整个授权设计安全的证明。这些检查只能证明所发送的确切用例。
• 切勿仅凭检查清单中的一项就将安全严重性定为 high。
• 除非能证明服务器接受了面向不同受众或资源签发的令牌，或以其他方式错误绑定令牌，否则 JWT aud 不匹配不能证明令牌透传。
• 支持 plain PKCE 通常只是加固措施。当攻击者拥有客户端的 DCR 流程由攻击者选择 verifier 时，这一点不能叠加成更严重的问题。
• 除非能证明服务器会获取这些值，否则恶意 redirect_uri 值不构成 SSRF。
• 未经身份验证的公开访问本身不构成问题。应检查实际行为是否符合所宣称的安全态势，以及暴露的接口在设计上是否安全。
• 匿名试用或速率限制访问属于安全态势说明，不应作为单独的严重性问题。
• 将多个问题合并分析时，应说明组合攻击路径。切勿只列出互不相关的问题，就称组合后的情况更糟。
• 如果 verify_issuer_publication 失败，或者错误是 steps 数组为空的纯连接失败，切勿将 xaa run 失败归咎于目标服务器。这些是本地 issuer 设置问题：--issuer-base-url 必须提供 CLI 的本地签名密钥。
• 当兑换成功时，切勿将 xaa run 输出中的 not_advertised 能力证据视为失败；也切勿将已公告视为兑换必定成功的证明。公告只是证据；令牌端点的响应才是判定结果。unknown（元数据键缺失）是比 not_advertised（键存在但不含该值）更弱的证据——切勿混为一谈。
• 切勿将 idJag.verified: true 视为授权服务器已验证断言的证明。这表示 CLI 使用自己的 issuer 验证自己签发的断言。
• 切勿根据一次完成的 xaa run 就声称符合 ID-JAG 或具备安全的 XAA 安全态势。它只能证明一种注册策略下的一条成功路径。
• 切勿描述 --assertion-format saml 会生成 SAML ID-JAG。它会改变身份断言环节和 sub_id 声明；ID-JAG 始终是 JWT。ID-JAG 是一份正在制定的 IETF Internet-Draft——引用 MUST/SHOULD 要求时，应注明草案修订版本，而非 RFC。
• 切勿将 xaa run 输出中的 [REDACTED] 值报告为缺失数据，也切勿索要未脱敏输出。脱敏是有意设计的，即使服务器反射了机密信息，脱敏仍会保留。

参考指南

• references/cli-surface-notes.md 用于了解特定命令的注意事项、产物结构、本地补充信息、合并后的错误以及规范化的空数组。
• references/mcp-2025-11-25-interpretation.md 用于根据最新 MCP 规范解读功能、生命周期、传输、授权、工具、资源和提示词。
• references/xaa-id-jag-interpretation.md 用于解读 xaa run 的输出：三方信任模型、颁发方前提条件、功能证据语义、注册警告分类、SAML 维度，以及 Cross-App Access 发现项的严重性校准。
• references/security-best-practices.md 用于将安全审查检查项映射到 CLI 命令。涵盖 SSRF、困惑代理、PKCE、令牌透传、范围最小化、授权态势检查和会话安全。来源：https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices