Context
PR #1635 proposed a reusable CLI smoke-testing guide, but it targeted the frozen v1 branch and was closed unmerged. The maintainer guidance was to report the underlying need against v2 as an issue rather than opening an external PR.
v2 already has useful CLI command examples in clients/cli/README.md and an internal end-to-end check in scripts/smoke-cli.mjs. The remaining documentation gap is a user-facing workflow for testing an arbitrary MCP server from a shell or CI job.
Proposed documentation scope
A short v2 guide could show how to:
- connect to a stdio or HTTP/SSE server;
- run
tools/list and assert an expected tool exists;
- run one representative
tools/call with safe arguments;
- consume machine-readable output with
--format json and jq;
- use the current exit-code behavior so failed tool calls and transport errors fail CI;
- avoid interactive OAuth in automation, using the documented non-interactive/stored-auth options where applicable; and
- add basic negative assertions, such as confirming a sensitive-path request is refused and captured output does not contain obvious secret patterns.
The examples should be generic and version-correct rather than porting the v1 document verbatim, because v2 has different output, authentication, catalog/config, and exit-code semantics.
Expected outcome
A concise guide or an expanded section of clients/cli/README.md containing a copyable connect → list → call → assert workflow for local development and CI.
Related closed v1 contribution: #1635.
Context
PR #1635 proposed a reusable CLI smoke-testing guide, but it targeted the frozen v1 branch and was closed unmerged. The maintainer guidance was to report the underlying need against v2 as an issue rather than opening an external PR.
v2 already has useful CLI command examples in
clients/cli/README.mdand an internal end-to-end check inscripts/smoke-cli.mjs. The remaining documentation gap is a user-facing workflow for testing an arbitrary MCP server from a shell or CI job.Proposed documentation scope
A short v2 guide could show how to:
tools/listand assert an expected tool exists;tools/callwith safe arguments;--format jsonandjq;The examples should be generic and version-correct rather than porting the v1 document verbatim, because v2 has different output, authentication, catalog/config, and exit-code semantics.
Expected outcome
A concise guide or an expanded section of
clients/cli/README.mdcontaining a copyable connect → list → call → assert workflow for local development and CI.Related closed v1 contribution: #1635.