fix(mcp): tolerate unresolvable tool output-schema $refs

[Astro-Han]

Summary

When an MCP server advertises a tool whose outputSchema contains a $ref the SDK cannot resolve, the strict listTools() decode throws. defs() then returned undefined, the create flow closed the client, and the entire server was marked failed with zero tools — even when every other tool was valid.

This adds a fallback: on a schema-validation error, re-list tools via a raw tools/list request with output-schema validation relaxed (TolerantListToolsResultSchema), keeping only name/description/inputSchema. Genuine non-schema failures (e.g. transport closed) still fail exactly as before.

Why

Google Stitch and similar MCP servers ship outputSchema entries like { "screen": { "$ref": "#/$defs/ScreenInstance" } }. PawWork's defs() at mcp/index.ts is byte-identical to upstream's pre-fix version: a single strict listTools() whose failure collapses the whole server to failed. The result is a confusing "MCP server failed / no tools" with no usable tools for an otherwise-healthy server.

Related Issue

No PawWork issue. Re-implemented from upstream anomalyco/opencode 79d6b10d7c (PR #26614, thanks @kitlangton). dev and upstream/dev have no common ancestor, so this is a semantic re-implementation, not a cherry-pick — adapted to PawWork's withTimeout-based listTools and zod/v4 schemas. Scope matches upstream's index.ts change exactly (the upstream callbackPort-style features are unrelated and not present here).

Human Review Status

Pending

Review Focus

• The validation-error guard regex breadth (isOutputSchemaValidationError). Over-matching is low-risk: a wrongly-triggered fallback just attempts one extra tools/list request that, if the underlying failure is genuine, also fails and falls through to the same failed status — it can never mask a real failure, because TolerantToolSchema still validates inputSchema strictly.
• Type compatibility of the fallback-mapped { name, description, inputSchema } with MCPToolDef consumers (convertMcpTool reads only those three fields).

Risk Notes

Low. New code path runs only when the first listTools() throws a schema-shaped error. Local-only engine change, no platform/packaging/UI surface touched. None of the conditional checklist items apply (no UI/copy, no platform surface, no docs/deps/credentials).

How To Verify

```text
bun test test/mcp/lifecycle.test.ts → 21 pass / 0 fail (incl. 2 new: fallback path + non-schema-error path)
bun test test/mcp/ → 36 pass / 0 fail
bun run typecheck (packages/opencode) → clean
```

Screenshots or Recordings

N/A — no visible UI change.

Checklist

• Type label — this PR carries exactly one of bug, enhancement, task, documentation.
• Routing labels — this PR carries at least one of app, ui, platform, harness, ci. The labeler bot assigns these on PR open based on changed paths. Confirm the bot's choice (or override if wrong), then tick this.
• Priority label — this PR carries exactly one of P0, P1, P2, P3. The priority-triage bot suggests one on PR open. Confirm or override, then tick this.
• Human Review Status above is set to Pending, Approved by @<reviewer>, or Not required: <reason> (default is Pending; "not required" is restricted to bot-authored low-risk PRs).
• I linked the related issue, or stated in Summary why there is no issue.
• I described the review focus and any meaningful risks.
• I replaced the example block in How To Verify with the real verification steps and the key result for each.
• I did not introduce unrelated refactors, dependencies, generated files, or file changes beyond the stated scope.
• (conditional) I manually checked visible UI or copy changes when needed, with screenshots or recordings. Leave unticked only if no visible UI or copy changed.
• (conditional) I considered macOS and Windows impact for platform, packaging, updater, signing, paths, shell, or permissions changes. Leave unticked only if no platform/packaging surface was touched.
• (conditional) I called out docs, release notes, dependencies, permissions, credentials, deletion behavior, generated content, or local file changes when relevant. Leave unticked only if none of those surfaces was touched.
• I reviewed the final diff for unrelated changes and suspicious dependency changes.
• I am targeting dev, and my PR title and commit messages use Conventional Commits in English.

[coderabbitai]

Warning

Review limit reached

@Astro-Han, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 1 minute and 23 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d237ee2b-afaa-4add-915c-04aad1dfdb27

📥 Commits

Reviewing files that changed from the base of the PR and between 56652b9 and cdb1fd6.

📒 Files selected for processing (2)

• packages/opencode/src/mcp/index.ts
• packages/opencode/test/mcp/lifecycle.test.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/mcp-26614-output-schema-ref

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces a fallback mechanism in the Model Context Protocol (MCP) client to handle cases where tool output schemas contain unresolved references (e.g., $refs). Instead of failing the entire server connection, the client catches output schema validation errors and retries the tools/list request with a relaxed schema that ignores the outputSchema. Unit tests have been added to verify this tolerant fallback behavior and ensure that other non-schema errors still correctly trigger failures. There are no review comments, so no additional feedback is provided.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[github-actions]

Suggested priority: P2 (includes non-doc, non-test paths outside the low-risk bucket).

P1/P0 are reserved for maintainer confirmation. Please relabel manually if this is a release blocker, security issue, data-loss risk, or updater/runtime failure.