fix(docs): use lowercase MCP tool id and surface MCP errors (#82702)

[hclsys]

Fixes #82702.

Problem

openclaw docs <query> always prints No results. and exits 0 even for valid queries, because the CLI is calling the docs MCP server with the wrong tool id. Per the issue and per mcporter list https://docs.openclaw.ai/mcp, the actual tool is named search_open_claw, but the CLI was sending SearchOpenClaw. The server replies with MCP error -32602: Tool SearchOpenClaw not found, but mcporter call ... --output text still exits 0, so the CLI happily parses an empty stdout into zero results.

Fix

src/commands/docs.ts:

1. Rename SEARCH_TOOL from https://docs.openclaw.ai/mcp.SearchOpenClaw to https://docs.openclaw.ai/mcp.search_open_claw.
2. Add an MCP_ERROR_PATTERN = /MCP error\s+-?\d+/i guard. After mcporter returns exit code 0, scan combined stdout+stderr for an MCP JSON-RPC error envelope and surface it as a hard CLI failure (runtime.error(...) + runtime.exit(1)) instead of silently returning No results..

docs/cli/docs.md: update the public CLI reference to the lowercase selector (addresses ClawSweeper P3 review finding — docs were still pointing users at the broken uppercase URL).

src/commands/docs.test.ts (new): three vitest cases covering selector value, MCP error surfacing as exit 1, and healthy payload still rendering.

Real behavior proof

Behavior or issue addressed: openclaw docs <query> silently returns No results. because the CLI calls the wrong MCP tool id (SearchOpenClaw vs. server-advertised search_open_claw); the server's MCP error -32602 is swallowed by mcporter's exit-0 envelope.

Real environment tested: Linux x86_64 (Ubuntu 24.04), Node v22.16, against the live public docs MCP endpoint at https://docs.openclaw.ai/mcp using npx -y mcporter@latest. Local checkout of openclaw/openclaw at branch fix-docs-search-tool-name (head beb9824e) rebased on origin/main. The probe runs mcporter call exactly the way src/commands/docs.ts invokes it.

Exact steps or command run after this patch:

npx -y mcporter call https://docs.openclaw.ai/mcp.search_open_claw \
  --args '{"query":"browser existing-session"}' --output text

Evidence after fix: live stdout from the lowercase selector returns real Title/Link/Content blocks — exactly the shape parseSearchOutput expects to render:

Title: Existing session via Chrome DevTools MCP
Link: https://docs.openclaw.ai/tools/browser#existing-session-via-chrome-devtools-mcp
Page: tools/browser
Content: Optional: create your own custom <mark><b>existing-session</b></mark> profile if you want a

Title: Chrome MCP / existing-session signatures
Link: https://docs.openclaw.ai/gateway/troubleshooting#chrome-mcp-/-existing-session-signatures
Page: gateway/troubleshooting
Content: Chrome MCP / <mark><b>existing-session</b></mark> signatures
Could not find DevToolsActivePort

Title: Session tools
Link: https://docs.openclaw.ai/concepts/session-tool#session-tools
Page: concepts/session-tool
Content: Session tools
OpenClaw gives agents tools to work across sessions, inspect status, and
orchestrate sub-agents.

Title: Existing Chrome via MCP
Link: https://docs.openclaw.ai/cli/browser#existing-chrome-via-mcp
Page: cli/browser
Content: profile, or create your own <mark><b>existing-session</b></mark> profile: This path is host-only.

For comparison, the unpatched uppercase selector reproducibly returns the error this PR now surfaces in the CLI:

$ npx -y mcporter call https://docs.openclaw.ai/mcp.SearchOpenClaw \
    --args '{"query":"browser existing-session"}' --output text
MCP error -32602: Tool SearchOpenClaw not found

Observed result after fix: the lowercase selector returns six real docs hits and the patched CLI parses them via parseSearchOutput into ranked results. When the server emits MCP error -<code>, the new MCP_ERROR_PATTERN branch routes through runtime.error(...) + runtime.exit(1) instead of swallowing it. Net behavior change: openclaw docs "browser existing-session" now renders the four+ hits above instead of No results..

What was not tested: I did not exercise the rich-terminal renderer path (isRich()) on a real TTY; the vitest case for that branch covers the rendering call sites but not real ANSI output. Source-checkout end-to-end inside a packaged install was not run because the change is confined to a constant + a regex guard and does not interact with the launcher's respawn logic.

[clawsweeper]

Codex review: needs maintainer review before merge.

Summary
The PR updates openclaw docs to call the lowercase docs MCP tool, fail on MCP error output, add focused regression tests, and update the CLI docs reference.

Reproducibility: yes. Current main passes the uppercase selector to mcporter, and live MCP calls show that selector returns MCP error -32602 while the lowercase selector returns docs results.

Real behavior proof
Sufficient (terminal): The PR body now includes copied terminal output from a Linux/Node 22 live mcporter call showing the lowercase selector returns Title/Link/Content results and the old selector returns the MCP error.

Next step before merge
No repair job is needed; the contributor PR already contains the narrow code/docs/test fix and remaining work is normal check and landing flow.

Security
Cleared: Cleared: the diff only changes a fixed docs MCP selector, CLI error handling, docs text, and tests; it adds no dependency, permission, secret, or code-execution surface.

Review details

Best possible solution:

Land the focused docs CLI fix after required checks are green, then close the linked bug through the PR’s closing reference.

Do we have a high-confidence way to reproduce the issue?

Yes. Current main passes the uppercase selector to mcporter, and live MCP calls show that selector returns MCP error -32602 while the lowercase selector returns docs results.

Is this the best way to solve the issue?

Yes. Updating the fixed selector and surfacing MCP error text before parsing is the narrow maintainable fix, and the PR keeps code, docs, and regression tests aligned.

What I checked:

• Current main still calls the obsolete tool id: Current main sets SEARCH_TOOL to https://docs.openclaw.ai/mcp.SearchOpenClaw, so the reported selector bug is still present on main. (src/commands/docs.ts:8, 6a1213448927)
• Current main still parses successful empty output without an MCP-error guard: After a zero exit code, current main directly parses res.stdout, so an MCP error emitted with exit 0 can still become an empty result set. (src/commands/docs.ts:191, 6a1213448927)
• PR implements the narrow runtime fix: The PR head changes the selector to search_open_claw and adds an MCP error-pattern guard before parsing output. (src/commands/docs.ts:8, 8f05faa3c698)
• Live MCP contract confirms lowercase tool: The live docs MCP tools/list response advertises search_open_claw; a SearchOpenClaw call returns MCP error -32602, while search_open_claw returns Title/Link/Content docs results.
• PR adds regression coverage: The new test covers the lowercase tool id, MCP error surfacing when exit code is 0, and healthy result rendering. (src/commands/docs.test.ts:1, 8f05faa3c698)
• Related bug remains open and is linked by closing syntax: The PR body uses Fixes #82702, and the linked bug is still open, so the issue should close only after a fix PR lands.

Likely related people:

• steipete: GitHub file history shows steipete introduced the docs search command and later maintained docs-search output/docs references. (role: introduced behavior and docs-search feature owner; confidence: high; commits: 1ae5e9a26b4f, 0ef429f53210, 545ecc63bdf4; files: src/commands/docs.ts, docs/cli/docs.md)
• vincentkoc: GitHub file history shows recent touches to the docs command and repeated recent maintenance of the CLI docs page. (role: recent adjacent CLI/docs contributor; confidence: medium; commits: f09bb6d75cc9, 33eb0b9eee16, 627c19c5cbbe; files: src/commands/docs.ts, docs/cli/docs.md)

Remaining risk / open question:

• Required CI was not fully green at review time; visible failure annotations were outside the PR diff in extensions/xai/onboard.test.ts, but landing still needs green required checks.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 6a1213448927.