apache / apache/maka

Desktop: widen Client Capability tool-schema allowlist so MCP tools using prefixItems/not/patternProperties/contentEncoding/if-then-else/deprecated are offered

Open
#4,614 1 comment 0 reactions 1 assignee Claimed by @liuxiaocs7 View on GitHub
Dominant language
TypeScript
Stars
5.4k
Forks
502
Avg merge
1d 2h
Merged PRs (30d)
715

Description

### Summary

#4592 fixed two causes of "MCP tools fail to load on Desktop" (#4591): the native-capability offer now accepts `jsonSchema()` parameters, and each tool's descriptor is built and validated independently so one unrepresentable tool is skipped-and-warned instead of dropping **every** Desktop capability (Browser, Computer Use, Client settings, Rive, MCP) with it.

That isolation makes the outage survivable, but it does not make every MCP tool available: any tool whose JSON Schema uses a keyword outside the Client Capability allowlist is still **skipped** (offered to nobody). This issue tracks widening that allowlist so those tools are offered.

### Where

`packages/runtime-host/src/protocol/client-capability.ts` — `CLIENT_CAPABILITY_SCHEMA_KEYWORDS` (the allowlist) and `validateToolInputSchema` (the per-keyword validation/recursion). A tool schema containing any key not in the set is rejected with `Unsupported Client Capability tool schema keyword`.

### Missing keywords (from #4592 review)

Running real `buildMcpTools()` output through `decodeClientCapabilityReplaceInput` shows these ordinary keywords are absent and cause a skip:

- `prefixItems` — e.g. a pydantic `tuple[...]`
- `contentEncoding` (and typically `contentMediaType`) — e.g. pydantic `bytes`
- `not`, `patternProperties`, `if` / `then` / `else`
- `deprecated`

These are not exotic: `packages/mcp/src/index.ts` (`normalizeToolInputSchema`) already walks and **preserves** `prefixItems`, `patternProperties`, `not`, `if`/`then`/`else`, `dependentSchemas`, `contains`, `additionalItems`, `unevaluatedItems`/`unevaluatedProperties`, etc., so the repo already expects to receive them. The full gap between what the MCP normalizer preserves and what the protocol allowlist accepts is worth auditing in one pass.

### Scope / considerations

- This is a **protocol** change. Editing `packages/runtime-host/src/protocol/**` requires bumping `RUNTIME_HOST_COMPATIBILITY_EPOCH` (the `test` CI job fails fast otherwise), so it needs deliberate protocol review — which is why #4592 intentionally left it out.
- Each added keyword needs real validation, not just an allowlist entry: correct value type (`prefixItems` = non-empty array of schemas, `contentEncoding` = string, `deprecated` = boolean, `not`/`if`/`then`/`else`/`patternProperties` = schemas) and correct recursion in `validateToolInputSchema`, consistent with the existing `items`/`allOf`/`properties` handling.
- Keep the manifest size / tool-schema byte caps in mind.

### Acceptance

- MCP tools whose schemas use the keywords above are offered on Desktop and survive `decodeClientCapabilityReplaceInput`.
- Protocol tests cover accept + reject for each new keyword.

Follow-up to #4592. Related: #4591.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.