feat(ENG-733): support flat_prefixed MCP param style

Merged
ST
4mo ago
+84-29

Problem

The SDK lists tools from /mcp without pinning a param-style, so the tool schema handed to the LLM follows the server default. Execution, however, goes through /actions/rpc with a hardcoded nested unwrap (path/query/headers/body). When the server default param-style flips nested → flat_prefixed, the LLM emits path_id/query_limit/… which the nested unwrap can't route: path and query params are dropped and the prefixed keys leak into the request body. The server-side MCP shim does not cover this — SDK execution bypasses the MCP transport and hits the actions RPC endpoint directly.

Fix

  • Pin ?param-style=flat_prefixed on the /mcp tool-listing endpoint, so the schema the LLM sees is stable regardless of the server default.
  • Replace the nested _extract_record unwrap with _split_envelope_params, which buckets <location>_<field> keys back into path/query/headers/body. The prefix carries the location, so no per-action schema is needed. Bare nested envelopes are still accepted (for clients holding a cached nested schema), and unprefixed keys fall through to the body.

Net effect: SDK tool calls use the higher-accuracy flat_prefixed schema and are immune to the server-side default flip.

Tests

  • test_fetch_tools_pins_flat_prefixed_param_style
  • test_routes_flat_prefixed_keys_by_location
  • test_buckets_nested_envelope_and_unprefixed_keys
  • Backward-compat preserved: existing nested/unprefixed execution tests unchanged. ty type-check and ruff (lint + format) clean.

Note

This protects SDK versions from this release forward. Already-published versions still break the moment the server default flips, so the server-side flip should be gated on quantifying old-version exposure by User-Agent.


Summary by cubic

Support the flat_prefixed MCP param style end-to-end so tool execution stays correct even if the server default changes. Addresses ENG-733 by pinning the /mcp schema and aligning RPC argument handling.

  • Bug Fixes
    • Pin /mcp?param-style=flat_prefixed so tools expose <location>_<field> args consistently; tests assert the exact endpoint.
    • Replace the nested unwrap with _split_envelope_params to bucket path_/query_/headers_/body_-prefixed keys into the RPC envelope; still accepts nested dicts and treats unprefixed keys as body for backward compatibility.