MCP adapter should fall back to parsing text-JSON when structuredContent is absent

[bokelley]

Problem

The MCP adapter in `src/adcp/protocols/mcp.py` raises an error on successful responses that lack `structuredContent`:

```python
if not hasattr(result, "structuredContent") or result.structuredContent is None:
raise ValueError(
f"MCP tool {tool_name} did not return structuredContent. "
f"This SDK requires MCP tools to provide structured responses for successful calls."
)
```

The AdCP reference training agent (the source-of-truth implementation we validate against) does NOT return `structuredContent`. It returns JSON encoded as `text` inside a `TextContent` item:

```python

Typical response from test-agent.adcontextprotocol.org/mcp/ get_adcp_capabilities:

TextContent(type='text', text='{"adcp":{"major_versions":[3],"idempotency":{"replay_ttl_seconds":86400}}, ...}')

structuredContent is None

```

Every successful MCP call against the training agent fails in our SDK today.

Evidence

From a live probe (2026-04-18) — see [upstream issue adcontextprotocol/adcp#XXXX] for the full trace:

```
MCP tool get_adcp_capabilities did not return structuredContent.
Got content: [TextContent(type='text', text='{"adcp":{...}}', ...)]
```

MCP spec permits servers to return structured data either as a dedicated `structuredContent` field (newer) or as JSON inside a `TextContent` (older, still valid). Our adapter is stricter than the spec.

Suggested fix

In `src/adcp/protocols/mcp.py` where we raise for missing `structuredContent`, fall back to parsing the first `TextContent` item as JSON:

```python

After extracting message_text / before the raise:

if not hasattr(result, "structuredContent") or result.structuredContent is None:
# Fall back to text-JSON for servers that don't emit structuredContent
for item in serialized_content:
text = item.get("text") if isinstance(item, dict) else None
if text:
try:
parsed = json.loads(text)
if isinstance(parsed, dict):
data_to_return = parsed
break
except json.JSONDecodeError:
pass
else:
raise ValueError(f"MCP tool {tool_name} returned neither structuredContent nor JSON text")
else:
data_to_return = result.structuredContent
```

Impact

Without this fix, the Python SDK cannot talk to the AdCP reference implementation (training agent) end-to-end. Integration tests against the hosted test-agent fail at every successful call.

Workaround (used in live idempotency test today)

Monkey-patch the session at test time to inject a synthetic `structuredContent` built from text content — see `.context/live_idempotency_test.py` on branch `bokelley/issue-181-idempotency`.

Related

• Add idempotency_key auto-generation and IdempotencyConflictError #181 — idempotency work that exposed this gap during live testing
• AdCP training agent: adcontextprotocol/adcp (reference implementation)

[bokelley]

Update: this is a spec-mandated path, not a training-agent quirk

The AdCP spec at docs/building/implementation/mcp-response-extraction.mdx explicitly defines the normative extraction algorithm:

Clients MUST extract AdCP data from MCP tool results in this order:

1. Guard: reject error responses (isError truthy) — error extraction is a separate path
2. structuredContent — if present and a non-array object, return it
3. Text fallback — iterate content[] items in array order. For each type === 'text', enforce a 1MB size limit, JSON.parse, return if it's a non-array object
4. No structured data found — return null

Our MCP adapter implements only path 2 and raises on everything that reaches path 3. This is a real spec-compliance bug, not a tolerance feature — the training agent (AdCP reference implementation) uses path 3 exclusively.

Normative requirements from the spec to implement

• 1MB size limit on text items before json.loads (DoS guard — malicious/misconfigured servers can't OOM the client)
• Skip adcp_error-only payloads in text items (these are errors missing the isError flag — a spec edge case)
• Skip items that fail to parse, parse as non-objects, or are arrays
• Iterate content[] in order; return the first valid object

Suggested implementation shape (Python equivalent of the spec's reference JS)

def _extract_adcp_response(self, mcp_result) -> dict | None:
    if getattr(mcp_result, "isError", False):
        return None
    sc = getattr(mcp_result, "structuredContent", None)
    if isinstance(sc, dict) and not (len(sc) == 1 and "adcp_error" in sc):
        return sc
    for item in getattr(mcp_result, "content", None) or []:
        text = getattr(item, "text", None) or (item.get("text") if isinstance(item, dict) else None)
        if not text or len(text) > 1_048_576:
            continue
        try:
            parsed = json.loads(text)
        except json.JSONDecodeError:
            continue
        if isinstance(parsed, dict) and not (len(parsed) == 1 and "adcp_error" in parsed):
            return parsed
    return None

Error-path counterpart

Per docs/building/implementation/transport-errors.mdx, the error-extraction path is a separate spec with its own algorithm — relevant for the existing MCP is_error=true branch too. Fix should cover both.