feat(server): response enhancer callback (JS #2161 parity)

[bokelley]

Gap

JS SDK adcp-client#2161 added a responseEnhancer server config option applied uniformly to: framework tool responses, custom tools (tasks_get), generated get_adcp_capabilities responses, and credential-policy error responses.

Python has no equivalent — grep for response_enhancer / finalizer / enhancer across decisioning/serve.py and server/serve.py returns nothing, and create_adcp_server_from_platform exposes no such hook. Adopters who want to stamp cross-cutting fields on every response must subclass each handler.

Scope

Add a response_enhancer callback to create_adcp_server_from_platform / create_mcp_server, applied at the same finalizer seam JS uses (framework + custom + generated + error responses).

Needs a seam-design decision before implementation — where exactly the callback runs in the response path, and the callback signature (response in → response out), so it covers all four response classes uniformly without breaking validation hooks.

Notes

• Reference: adcontextprotocol/adcp-client#2161.
• Single-agent triage verification.
• Filed no-triage.

[bokelley]

Triage

Classification: Feature request (JS parity — adcp-client#2161)
Bucket(s): middleware, handlers (no matching labels exist in repo — noting gap)
Status: ready-to-implement

What the experts said:

• code-reviewer: The proposed seam (after inject_context in mcp_tools.py) is valid for the success path. Two design constraints: idempotency replays will re-run the enhancer (cache stores pre-enhancement output — must be documented as a hard constraint); credential-policy error responses are caught before that seam in build_mcp_error_result / _send_adcp_error and are structurally unreachable without a separate wire.
• dx-expert: Rename the parameter to on_response (matches the existing on_startup/on_shutdown convention; response_enhancer is noun-phrase atypical for callbacks here). Thread via serve_kwargs, not through create_adcp_server_from_platform (which returns a handler tuple, not transport config). Single callback, success-path only. Accept both sync and async. Export ResponseEnhancer as a named type alias from adcp.server; add to ServeConfig alongside middleware.

My take: The seam-design question is settled — all four success-path response classes converge at create_tool_caller() in mcp_tools.py after inject_context (~line 2615), and that is the right insertion point. Credential-policy error responses are out of scope for v1 unless a second wire into build_mcp_error_result / _send_adcp_error is added deliberately.

Implementation scope:

• Signature & naming: ResponseEnhancer = Callable[[str, dict[str, Any], ToolContext], Awaitable[None] | None]; parameter named on_response; add to ServeConfig next to middleware; export ResponseEnhancer from adcp.server
• Insertion point: In create_tool_caller() (src/adcp/server/mcp_tools.py) after inject_context (~line 2615) and after strip_credentials_from_wire_result (src/adcp/decisioning/dispatch.py:1555); add if "adcp_error" not in result: guard matching the existing schema-validation guard at line 2617
• Threading: decisioning/serve.py:serve() → adcp.server.serve.serve() → create_mcp_server(on_response=...) → per-tool closure via serve_kwargs; do not add to create_adcp_server_from_platform (wrong layer — that returns (handler, executor, registry))
• Idempotency contract: Document that on_response fires on replay responses (cache commits pre-enhancement output; enhancement re-runs on replay) — non-idempotent enhancers will diverge replays; also note src/adcp/testing/decisioning.py:build_asgi_app needs the same parameter for test parity
• Required checks: pytest on affected dispatch paths; mypy src/; ruff check .; black --check .
• Non-breaking: New keyword-only parameter with default None on create_mcp_server; no existing signatures changed

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01YcNNprLzVqD8Kdgtax7z8H

---

Generated by Claude Code