test-by-mcpc-cli

使用 mcpc 测试 MCP 服务

将 mcpc 0.7.x 作为面向操作者的测试工具，用于驱动任意 MCP 服务——无论是 stdio 还是 Streamable HTTP。此技能涵盖已发布的 CLI 契约、以会话为先的命令形式、JSON 脚本编写、任务执行、协议版本探测、skills 扩展验证和清理操作；不负责编写服务或客户端本身。

何时使用此技能

• 通过 stdio 或 Streamable HTTP 连接到实际 MCP 服务，并使用 mcpc connect … @session 验证其实时功能
• 使用 mcpc 检查工具、提示词、资源、目录资源、模板、skills、日志记录、订阅或指令
• 使用已发布的 mcpc 0.7.x CLI 重现身份验证、代理、清理、任务、协议版本或传输故障
• 在 --json 模式下编写可重复执行的冒烟测试，包括对退出码和 isError 的 CI 断言
• 在发布验证期间，将本地 stdio 服务与已部署的 Streamable HTTP 目标进行比较
• 将早于 0.2.0 的目标优先示例或已移除的 0.2.x 时代命令转换为当前语法

不要在以下情况使用此技能

• 构建或重构服务端代码 → mcp-use 服务请使用 build-mcp-use-server；原始 @modelcontextprotocol/sdk 服务请遵循 SDK 自身的文档
• 构建或重构客户端／Agent 代码 → 不在范围内；此技能仅用于驱动 mcpc
• 运行超出 CLI 测试范围的 Agent 质量／加固／上下文预算审计 → 请使用 audit-agentic-mcp
• 将现有 v1 服务迁移到 v2 → 不在范围内；请遵循 SDK 自身的迁移指南

信息来源

1. 确认正在运行的 CLI：mcpc --version 必须报告 0.7.x。较旧的 0.2.x–0.6.x 语法虽有重叠，但在 skills、补全、目录资源、x402 回执、退出码和登录标志方面有所不同；早于 0.2.0 的语法在结构上也不同。
2. 如果文档与 mcpc --help 不一致，请以实际安装版本的 mcpc help <command> 为准。mcpc help --skill（或 mcpc --skill）会输出上游自带的 Agent 指南。
3. 此技能已针对 0.7.0 验证，并通过 https://research-mcp.yigitkonur.com/mcp（mcp-researchpowerpack v9）以及通过 stdio 和 Streamable HTTP 运行的 @modelcontextprotocol/server-everything 进行了实测。
4. 如果缺少 mcpc、版本较旧，或配置格式有误，请从 references/guides/installation.md 开始。先确认纯 CLI 路径可用；只有原始命令路径正常后，再逐步加入封装层。

关键规则

以下规则适用于下方的每个工作流。每条都已针对 0.7.0 进行实时验证；违反这些规则是最常见的失败原因。

#	规则	原因
1	执行任何 MCP 操作前，始终先连接到一个已命名的 @session	mcpc 以会话为先；不存在以目标为先的一次性命令
2	会话按名称而非 URL 复用	connect <url> @existing 会复用；connect <url> @new 会创建第二个独立会话；省略 @name 时会自动生成并复用每个服务对应的名称（在 0.7.0 中会去除开头和结尾的下划线）
3	结合输出形式解读退出码：1 = CLI／会话失败（以及 grep 未匹配）；2 = MCP 的 isError:true 结果输出到 stdout，或超时／无结果 {error,code} 输出到 stderr；3／4 是有文档记录的网络／身份验证代码，但本次审计未能复现	退出码表示的是大致类别，而非确切原因；请捕获两个流并解析 JSON
4	连接无法访问的目标时，可能以 0 退出，同时创建一个非活动的 connecting 或 reconnecting 会话	connect 成功可能意味着“已创建记录”，而非“握手已完成”；请检查指定名称的状态并运行实际命令
5	不带参数的 mcpc clean 只会移除陈旧数据；具名目标（clean sessions、clean logs、clean profiles）会删除该类型的所有记录，包括活动记录	在共享计算机上，mcpc clean all 和具名目标都会造成破坏性影响
6	仅使用 stdio 或 Streamable HTTP 目标	mcpc 0.7.x 未提供一流的 HTTP+SSE 测试路径
7	对 HTTP 测试使用 --no-profile，以强制匿名测试，避免已保存的 OAuth 影响结果	配置文件会静默注入身份验证；要复现匿名情形，必须显式选择退出
8	如果工具是 task:required，普通的 tools-call 会失败，除非添加 --task 或 --detach；并且 0.7.x 会明确报错，而不会静默回退到非任务工具／服务	错误信息就是约定；请先阅读，而不是重试
9	使用 tasks-result <taskId> 获取已分离任务的结果——它在不同进程调用之间也有效；tasks-get 仅用于查看状态	已取消的任务会正确地使 tasks-result 失败，并提示“has no result stored”（退出码 2）
10	区分桥接故障与 stdio 子进程故障：桥接进程退出后会在下一条命令执行时自行恢复；stdio 子进程退出后只会通过 ping 自行恢复；其他命令会失败并提示 Not connected（退出码 2），直到执行 mcpc restart @session	JSON 中的 pid 是桥接进程；状态可能会误导性地保持为 live；重启会丢失任务和已添加的工具，但会恢复订阅
11	仅当端点确实使用不受信任的证书时才使用 --insecure	它会掩盖合理的 TLS 回归问题
12	相比 tools-get 打印的 “Call example”，应优先信任其中的 Input: 类型注释——示例可能会将数组参数显示为普通字符串	对于 array<string> 字段，urls:='"x"' 会违反工具自身的架构
13	将 x402 钱包导入／移除、签名、批准和 --x402 调用视为金融／凭据操作：隔离状态，优先使用一次性 Base Sepolia 钱包执行 x402 init，并检查 _meta["x402/payment-response"] 中的结算回执	upto 可能会批准 MAX_UINT256，调用可能会花费资金／Gas；0.7.x 只能通过位置参数 argv 导入密钥，因此不要为了日常测试而导入真实的生产密钥

以下过时语法应直接拒绝：

mcpc mcp.example.com tools-list          # pre-0.2.0 target-first — drop
mcpc mcp.example.com connect @demo       # pre-0.2.0 — drop
mcpc --clean=sessions                    # pre-0.2.0 flag — use: mcpc clean sessions
mcpc @demo tools                         # shorthand aliases removed in 0.3.0 — use tools-list
mcpc shell @demo                         # shell removed in 0.4.0 — no replacement

使用 references/patterns/session-first-syntax.md 将其转换为当前格式。原始 JSON-RPC 方法名可用作命令别名（tools/list、logging/setLevel 等）。在 0.7.0 中，mcpc help tools/list 能正确解析命令帮助，而不会报错。请先讲解带连字符的 CLI 形式。

最小读取集

默认不要加载整个技能。先选择一个分支，只有任务需要时再扩大范围。

分支	先阅读
远程 Streamable HTTP	references/commands/quick-reference.md、references/guides/http-testing.md
本地 stdio	references/commands/quick-reference.md、references/guides/stdio-testing.md
工具、提示词、资源、模板或 grep 要求	references/guides/discovery-search.md、references/guides/tool-resource-testing.md
异步任务或 Everything-server 行为	references/guides/async-tasks.md、references/guides/everything-server.md
OAuth 或请求头	references/guides/authentication.md、references/patterns/auth-precedence.md
本地代理	references/guides/proxy-testing.md
x402 支付	references/guides/x402-payments.md、references/patterns/auth-precedence.md
CI / 脚本化冒烟测试	references/guides/ci-cd-integration.md、references/guides/scripting-automation.md、references/patterns/output-formatting.md
协议版本或技能扩展	references/guides/protocol-versions.md、references/guides/skills-testing.md
故障诊断或破坏性重置	references/troubleshooting/common-errors.md，只有在故障需要时再阅读 references/patterns/logging-debugging.md 或 references/guides/cleanup-maintenance.md

标准工作流

1. 验证语法系列

• mcpc --version 报告版本为 0.7.x。
• 示例采用 mcpc connect <server-or-file:entry> @session 形式。
• 使用原生 mcpc 验证约定，不要使用可能破坏引号、TTY 或会话状态的包装器。

2. 连接一个稳定会话

默认使用你选定的名称创建一个全新的 connect 会话。只有在任务确实涉及复用、清理或诊断陈旧状态时，才查看会话清单。

# Remote URL; https:// is added automatically for non-local hosts
mcpc connect research-mcp.yigitkonur.com/mcp @research

# Localhost keeps http:// by default
mcpc connect 127.0.0.1:3011/mcp @everything-http

# Stdio via mcpServers config entry
mcpc connect /tmp/everything-mcp.json:everything @everything-stdio

如果需要在已保存 OAuth 配置的机器上进行匿名 HTTP 测试，请使用 --no-profile。使用相同的 @name 重新运行 connect 会复用会话；使用新的 @name 则始终会创建第二个会话（规则 2）。由于无法访问的目标仍可能返回退出码 0，因此在将连接视为就绪之前，请确认对应名称的会话状态为 live（规则 4）。

要检查现有会话，请将查询范围缩小到单个名称，而不是转储整个清单：

mcpc
mcpc --json | jq '.sessions[] | select(.name == "@research")'

如果旧会话的状态不是 live，请勿将其用于冒烟测试。可以运行 mcpc restart @session，或使用新名称创建全新会话。如果 mcpc restart @session 返回 Session not found（退出码 1），请停止重试该名称，并立即创建全新会话。

3. 深入测试前先检查

mcpc @research
mcpc @research help
mcpc @research grep search
mcpc @research tools-list --full
mcpc @research resources-list
mcpc @research resources-directory-read <uri>
mcpc @research prompts-list
mcpc @research skills-list
mcpc @research skills-get <skill> [file]

在使用复杂的 jq 管道之前，优先使用 help 和 grep。mcpc @research 横幅会显示服务器元数据（title、description、websiteUrl）和协商出的 MCP 协议版本——在 2026-07-28 连接中，server-discover 也可用（references/guides/protocol-versions.md）。如果验收标准明确提及提示词、资源或模板，请在第一轮中添加相应的列表调用，而不是之后再扩大读取集。

4. 验证架构和参数形式

mcpc @research tools-get web-search
mcpc --json @research tools-get web-search | jq '.inputSchema'
mcpc @research tools-get web-search --schema ./expected-tool-schema.json

--schema/--schema-mode 仅适用于 tools-get 和 tools-call——prompts-get 没有架构标志。客户端架构不匹配时会以退出码 1 结束（请求不会到达服务器）。key:=value 仍可使用，但数组和对象应以行内 JSON 字面量或完整 JSON 负载的形式发送。引号边界情况请参阅 references/patterns/argument-parsing.md。

5. 核实宣传的功能

不要只相信 capabilities。检查服务信息、工具元数据，并实际调用一次。

mcpc --json @research | jq '.capabilities'
mcpc --json @everything-http tools-list | jq '.[] | {name, taskSupport: (.execution.taskSupport // "unspecified")}'

• 当服务信息中出现 completions 时，表示服务支持补全（completion/complete）。上游 mcpc 提供专用的会话命令：mcpc @session completion-complete prompt|resource <ref> [arg:=val ...]。
• mcpc 不会声明支持 sampling、roots 或 elicitation，因此有条件注册演示工具的服务（如 Everything）根本不会公开这些工具。
• 如果功能中出现 tasks，仍要检查每个工具的 execution.taskSupport，并在围绕它编写自动化之前，先用一次 --task 或 --detach 调用验证 task:required。

6. 测试你关心的功能

mcpc --json @research tools-call web-search 'queries:=["OpenAI MCP"]'
mcpc @everything-http prompts-get args-prompt city:=Paris state:=Texas
mcpc @everything-http resources-read demo://resource/static/document/features.md
mcpc @everything-http resources-directory-read demo://resource/directory/
mcpc @everything-http resources-subscribe demo://resource/dynamic/text/1 /tmp/text-sync.json
mcpc @everything-http logging-set-level debug

resources-subscribe 需要指定目标文件，并会将更新同步到该文件。logging-set-level 可能会输出一条关于 MCP 2026-07-28 的弃用警告——当前调用仍然成功（退出码为 0）；请略过 ⚠ 继续阅读。在 0.7.0 中，人类可读输出会合并重复的结构化内容，并贴心提示使用 --json。

7. 将 JSON 负载视为事实

RESULT=$(mcpc --json @research tools-call web-search 'queries:=["mcpc"]') || echo "exit=$?"
echo "$RESULT" | jq '.isError // false'

从 0.5.0 起，isError:true 结果也会以退出码 2 退出，因此脚本可以根据退出码作出判断——但仍应检查负载中的失败详情。付费工具调用会在 _meta["x402/payment-response"] 下包含结算回执。JSON 模式还会公开人类可读输出可能省略的字段（例如活动任务、订阅状态和实验性功能负载）；不要假设其中一种模式在结构上严格包含另一种模式。超时也可能以退出码 2 退出，但错误会以 {error,code} 的形式写入 stderr，而不是以 isError 负载的形式写入 stdout（规则 3）。

8. 有选择地使用任务模式

mcpc @everything-http tools-list --full
mcpc @everything-http tools-call simulate-research-query topic:='"mcpc tasks"' ambiguous:=false --task
mcpc @everything-http tools-call simulate-research-query topic:='"mcpc tasks"' ambiguous:=false --detach
mcpc @everything-http tasks-get <taskId>
mcpc @everything-http tasks-result <taskId>

需要将最终结果直接内联返回时，请使用 --task。需要立即获取 taskId，并稍后通过 tasks-result 获取正文时，请使用 --detach——即使在不同进程中也可以使用。对于不支持任务的工具或服务，这两个标志都会明确报错，而不会回退到同步调用。

9. 明确关闭或清理

mcpc close @research
mcpc clean

mcpc clean（不带参数）只会移除过期数据。任何指定目标的命令——包括 clean sessions logs——都会移除该类型的所有记录，只能在隔离的 MCPC_HOME_DIR 中有意重置时使用（规则 5）。不要并行对同一会话运行 close 和 clean；重复运行 close 会返回退出码 1，而不是作为空操作成功退出。

功能边界

mcpc 0.7.0 可以和不可以作为一流工作流进行测试的内容：

类别	覆盖范围
一流支持	stdio 和 Streamable HTTP 传输；工具、提示词、资源、目录资源（resources-directory-read）、资源模板、文件同步订阅、日志、grep、代理、x402 链上结算回执；具有可靠退出码约定的 JSON 脚本；完整任务生命周期（--task、--detach、tasks-list、tasks-get、tasks-result、tasks-cancel）；协议版本固定（--protocol-version，2024-10-07…2026-07-28）；官方 MCP skills 扩展（skills-list、skills-get <skill> [file]）；参数补全（completion-complete）
有限 / 部分支持	server-discover（仅适用于 2026-07-28 连接——其他情况会返回说明性错误）；roots/sampling（mcpc 刻意不声明支持，因此受功能门控的演示工具永远不会注册）；logging-set-level（在 ≤2025-11-25 上可用，2026-07-28 规范中已移除）
不支持一流测试	HTTP+SSE 传输测试；通过 CLI 使用 elicitation 命令

请参阅 references/guides/capability-coverage.md，将已声明的功能映射到实际 CLI 命令。

参考资料路由

根据你所处的分支，阅读最少且相关的资料。

核心指南

文件	适合阅读的情况
references/guides/installation.md	安装 mcpc（npm/bun/Homebrew/npx）、Node ≥22.12 要求、版本差异、钥匙串说明或配置格式疑问。
references/guides/stdio-testing.md	使用 file:entry 语法，根据 mcpServers 配置测试本地 stdio 服务、了解自动发现安全规则、捕获 stderr，或批量 --stdio 门控。
references/guides/http-testing.md	测试远程或本地主机上的 Streamable HTTP 端点、处理路径问题、TLS、标头或 --insecure。
references/guides/discovery-search.md	使用 help、grep 和列表调用发现工具、资源、目录资源、提示词、技能和指令。
references/guides/tool-resource-testing.md	运行工具、提示词、资源、目录资源、模板、文件同步订阅，以及检查日志。
references/guides/async-tasks.md	使用 --task、--detach 和 tasks-*（包括 tasks-result），或调试要求任务的工具。
references/guides/authentication.md	OAuth（授权码、客户端凭据、id-jag）、Bearer 标头、令牌刷新韧性、配置文件、回调标志和匿名模式。
references/guides/session-management.md	会话生命周期、按名称复用、去除下划线、无状态服务、桥接进程与子进程恢复，以及多会话工作流。
references/guides/cleanup-maintenance.md	安全清理、仅删除过期项与删除全部的区别、硬重置、logs 命令和本地 mcpc 维护。
references/guides/proxy-testing.md	将会话公开为本地 MCP 代理：/health、Bearer 强制校验、DNS 重绑定防护、沙盒使用和补全转发。
references/guides/x402-payments.md	钱包检查（mcpc x402）、支付方案（auto/upto/exact）、结算收据（_meta["x402/payment-response"]）、x402 sign 和 --x402 会话行为。
references/guides/ci-cd-integration.md	CI 冒烟测试、隔离的 MCPC_HOME_DIR、退出码断言、Node/CI 镜像要求（Node 20 已在 0.4.0 中移除）和清理陷阱。
references/guides/scripting-automation.md	Shell 自动化模式、退出码约定、JSON 解析和可复现脚本。
references/guides/everything-server.md	根据官方 Everything 参考服务验证当前 mcpc 行为，包括有条件的工具注册。
references/guides/capability-coverage.md	将声明的功能映射到实际的 mcpc 命令和已知缺口。
references/guides/skills-testing.md	测试官方 MCP 技能扩展（io.modelcontextprotocol/skills）：skills-list、skills-get <skill> [file]、清单验证和目录资源。
references/guides/protocol-versions.md	协议协商、--protocol-version 固定版本、server-discover 和 JSON-RPC 方法别名（包括 help 解析）。
references/guides/architecture.md	mcpc 的高层设计、会话优先路由和功能协商。
references/guides/bridge-internals.md	桥接进程生命周期、内部派生模型、桥接进程与子进程恢复（包括 ping 例外）、重新连接注意事项和日志位置。

命令、示例和故障排除

文件	适合阅读的情况
references/commands/quick-reference.md	需要快速查找准确的 0.7.0 语法、标志、别名或清理形式。
references/examples/real-world-workflows.md	想查看针对 Research Powerpack 或 Everything 等真实目标的完整端到端工作流。
references/examples/testing-recipes.md	想要可直接复制粘贴的简短检查，用于冒烟测试、模式、任务、grep 或清理。
references/troubleshooting/common-errors.md	遇到过时语法、错误的配置结构、任务必需错误、会话过期或传输方式不匹配。

模式与高级细节

文件	阅读时机
references/patterns/session-first-syntax.md	将 0.2.0 之前的示例、已移除的别名或线协议方法名称转换为当前语法时。
references/patterns/argument-parsing.md	处理数组、对象、内联 JSON、stdin 和 key:=value 的边缘情况时。
references/patterns/schema-validation.md	在回归检查中使用 --schema/--schema-mode 验证工具架构时。
references/patterns/config-resolution.md	了解 mcpServers 配置结构、file:entry、自动发现、批量连接和 URL 规范化时。
references/patterns/auth-precedence.md	在显式标头、命名配置文件、默认配置文件、--no-profile 和 --x402 之间进行选择时。
references/patterns/output-formatting.md	了解人类可读模式与 JSON 模式、stdout/stderr 路由、退出代码约定和 isError 时。
references/patterns/jq-patterns.md	原生 grep 和 help 无法满足需求，需要进行高级 JSON 筛选时。
references/patterns/tool-filtering.md	结合 grep 使用 tools-list --json | jq 工作流时。
references/patterns/logging-debugging.md	使用 --verbose、logs 命令和桥接日志解释故障时。
references/patterns/notification-handling.md	测试列表变更通知、文件同步订阅和服务端日志消息时。
references/patterns/pagination-caching.md	了解自动分页、无状态缓存 TTL、工具缓存刷新和动态发现行为时。
references/patterns/python-integration.md	通过 Python 子进程工作流驱动 mcpc 并正确处理 returncode 时。
references/patterns/data-model.md	了解会话信息、任务状态、缓存元数据、配置文件和存储背后的 JSON 结构时。

注意事项

• 除非明确记录迁移过程，否则不要讲解 0.2.0 之前的目标优先语法、已移除的简写别名或已移除的 shell 命令。
• 不要告知用户使用 mcpc 测试 HTTP+SSE；应改用 Streamable HTTP 或 stdio。
• 不要将 tasks-get 的状态输出当作任务结果；应使用 tasks-result 获取分离的正文。
• 不要将 connect 退出代码为 0 或绿色横幅视为握手已建立的证明；无法访问的目标可能仍处于 connecting 状态或转为 reconnecting，因此应验证准确名称对应的状态并实际调用该能力。
• 不要假设服务所声明的能力总是意味着 CLI 支持完善，也不要认为缺少演示工具就表示服务已损坏——mcpc 未声明的 sampling/roots/elicitation 能力会按设计隐藏受其控制的工具。
• 在保存了配置文件或存在活动会话的机器上，不要随意运行 mcpc clean all 或任何指定名称的 clean 目标；只有不带参数的 clean 仅清理过期内容。
• 将代理 /health 仅视为无需身份验证的存活探测；应通过携带（或不携带）Bearer 令牌的真实 MCP 请求验证代理身份验证。
• 不要将 ⚠ 弃用警告视为调用失败；应检查当前调用的退出代码和载荷。