Repository navigation
docs: document a reusable CLI smoke-testing workflow for v2 #1886
Description
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/listand assert an expected tool exists; - run one representative
tools/callwith safe arguments; - consume machine-readable output with
--format jsonandjq; - 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.
Activity
cliffhall commentedon Aug 1, 2026
Triage: Priority = Low
Scored 4/16 with the priority rubric added to
AGENTS.mdin #1891, as part of the backlog triage in #1872. Added to project board #28 with Status Incoming — meaning filed and scored but not yet approved for work. A maintainer decides whether it moves to Todo.Related issues. None found in the open backlog; this one stands alone.
Scores are a starting point, not a verdict — the rubric is meant to be overruled when it's plainly wrong, provided the reason is written down.
cliffhall commentedon Sep 6, 2026
Shipped in #2275, merged to
v2/mainas8bca4821.Delivers
docs/cli-smoke-testing.md— the connect → list → call → assert workflow this issue asked for — plus index entries in the root README andclients/cli/README.md.All seven points from the proposed scope are covered: stdio/HTTP/SSE connect,
tools/listassertions, a representativetools/call,--format json+jq, the exit-code map, non-interactive OAuth via--stored-auth-only, and negative assertions (refusals, a secret-shape scan, and--strictschema portability). Every command and output shape was verified against the bundled composable test servers rather than transcribed, which corrected several claims before they shipped.Closing by hand:
Closes #Nonly auto-closes for PRs targeting the default branch, and this targetedv2/main.docs: add a reusable CLI smoke-testing guide for v2 (modelcontextprot…