feat(mcp): expose conservative tools list cache contract

[seonghobae]

Direct-main MCP discovery refinement after PR #168 merged into protected main.

Buyer-visible gap

Protected main now contains deterministic MCP 2026-07-28 tools/call routing and the reviewed tool-to-action catalog, but a transport adapter still needs a typed tools/list request/result boundary. Without it, an adapter could invent result disposition, freshness/shareability, accept pagination state OriginWeave never issued, or treat malformed routing metadata differently from tools/call.

Current implementation

The exact branch:

• derives discovery tools from the same reviewed MCP_TOOL_CATALOG used by routing;
• binds one fixed page to McpResultType::Complete, ttl_ms = 0, McpCacheScope::Private, and next_cursor = None;
• independently requires the transport protocol-version header and structured per-request protocol metadata;
• bounds each untrusted protocol-version value to the exact supported-version length before cross-field comparison;
• requires client-capabilities presence while treating contents as non-authoritative;
• validates each untrusted routing/body method against the shared 64-byte bounded ASCII syntax before cross-field comparison;
• requires exact tools/list routing/body agreement;
• rejects every supplied cursor because this fixed catalog issued none; and
• grants no tool capability, browser/network/origin authority, approval, secret access, or ambient JavaScript authority.

Current dependency / ancestry

Protected main: b05d5acca82b9d916ada2c8e82f59f92a89817e1.

Exact #170 head: 5bb5a7bb934d4282c30b0ea4f4b2efc9a00a1f2d.

After #168 merged, this branch was retargeted to main and reconstructed non-destructively from the protected-main tree. The shared tools/call hardening from main was preserved; only the intended tools/list boundary, tests, doctoring, changelog, and current-main MCP documentation reconciliation remain in the direct-main delta. GitHub currently reports the PR mergeable.

Repair lineage

An earlier audit found that tools/list compared arbitrary routing/body method strings without applying the same bounded method syntax as protected-main tools/call. A regression on test-only head 8b83eafe9579b4504044c0bed963430267c90408 required malformed and oversized method metadata to fail as InvalidMethod; no exact-head CI run was generated for that transient test-only head, so it remains structural RED evidence only. Production added the shared method bound and the error-contract test was strengthened after exact coverage exposed the new InvalidMethod display arm as otherwise unmeasured.

A fresh exact-current audit then found a second resource-validation-order defect: the required protocol-version header and structured request protocol metadata were compared to each other while still arbitrary-length attacker-controlled &str values. This allowed work proportional to both untrusted strings before the fixed supported-version guard.

The new regression reached exact test-only head 9d1cfd08a7aa4203f697a40fd3e5fb30bbbd4d31. CI run 32708025503, Rust job 97373217858, passed repository contracts and canonical formatting, then failed the semantic test mcp_tools_list_bounds_protocol_metadata_before_cross_field_comparison: the oversized protocol value produced ProtocolVersionHeaderBodyMismatch where the bounded contract required UnsupportedProtocolVersion.

Production repair head c25fb51d01ee318cc49d2fe8223e6427d7f8e1b0 now rejects either protocol-version value when its byte length exceeds MCP_PROTOCOL_VERSION.len() before comparing the two untrusted values. Normal bounded mismatch semantics remain unchanged. Subsequent documentation-only commits reconciled the MCP contract with current protected main without changing the repaired production boundary.

Exact-current evidence

On unchanged exact head 5bb5a7bb934d4282c30b0ea4f4b2efc9a00a1f2d:

• CI run 32709650376: success;
• Rust contracts job 97378116870: repository contracts, canonical formatting, locked workspace/all-target check, full tests, strict Clippy, and rustdoc success;
• Production coverage job 97378117285: exact owned-production function/line/region/branch enforcement success;
• the coverage job explicitly checked out exact SHA 5bb5a7bb934d4282c30b0ea4f4b2efc9a00a1f2d and ended with production functions, lines, regions, and branches are 100% covered;
• exact coverage artifact 9513635865, SHA-256 7db543011131d5f20639f619f0abcf83e244f5a6d8aa491d0a4e8eee0c9810e5;
• Manifest V3 Compatibility run 32709650277: success;
• SAST Semgrep run 32709650285: success;
• Security Scan run 32709650296: success;
• formal reviews: none at the latest refetch;
• inline review threads: none at the latest refetch.

Skipped/predecessor/status/model evidence is not promoted to success. All current-head native gates exposed for this branch are complete and successful, so the PR is ready for independent review; no approval is inferred from CI or scanner state.

Truth boundary

This is an adapter contract, not a complete MCP server. It does not serialize JSON-RPC/HTTP, authenticate a client/server, implement OAuth, invoke a tool, perform browser I/O, persist discovery state, or implement general pagination. A future transport adapter must serialize this reviewed value without widening routing, cache, metadata, or OriginWeave authority semantics.

This scheduled actor does not merge, self-approve, force-push, destructively rebase, alter workflows, add secrets, weaken checks, tag, or publish.

[coderabbitai]

Warning

Review limit reached

Next included review available in 7 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bc4828f7-7334-4197-b96c-b1487f742954

📥 Commits

Reviewing files that changed from the base of the PR and between b05d5ac and 5bb5a7b.

📒 Files selected for processing (7)

• CHANGELOG.md
• README.md
• crates/originweave-core/src/mcp.rs
• crates/originweave-core/tests/mcp_tools_list_cache.rs
• docs/adr/0107-browser-protocol-adapter-strategy.md
• docs/doctoring/browser-agent-protocols.md
• docs/traceability/mcp-authority-route.md

---

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.}

[devin-ai-integration]

Devin Review found 1 potential issue.