Skip to content

fix(compliance): clarify MCP envelope binding in v3_envelope_integrity storyboard#4005

Merged
bokelley merged 1 commit into
mainfrom
claude/issue-3999-v3-envelope-integrity-mcp-narrative
May 3, 2026
Merged

fix(compliance): clarify MCP envelope binding in v3_envelope_integrity storyboard#4005
bokelley merged 1 commit into
mainfrom
claude/issue-3999-v3-envelope-integrity-mcp-narrative

Conversation

@bokelley

@bokelley bokelley commented May 3, 2026

Copy link
Copy Markdown
Contributor

Refs #3999

The v3_envelope_integrity/no_legacy_status_fields step narrative and expected block did not explain where status lives in MCP transport responses. Agent implementors reading only get-adcp-capabilities-response.json could include only the task-specific fields in their MCP structuredContent, omit status, pass the response_schema validation check, and then be confused by a failing envelope_field_present: status check.

Root cause (from expert review): The reporter's agent is non-conformant — it returns only the task payload in structuredContent without the required protocol envelope fields. The response_schema check passes because get-adcp-capabilities-response.json validates only the task-specific fields; status is a protocol envelope field not covered by that schema. The envelope_field_present check is correctly detecting the non-conformance. The fix is narrative clarification, not weakening the check.

The normative extraction algorithm at docs/building/implementation/mcp-response-extraction already shows status at the top level of structuredContent, but the storyboard didn't cross-reference it.

Non-breaking justification: Changes only narrative: and expected: text fields in the storyboard YAML. No check types, validation paths, or runner-contract fields are modified. The check remains severity: required — the conformance requirement is unchanged.

Pre-PR review:

  • code-reviewer: approved — 1 blocker fixed (changed content[0].textcontent[].text to match the normative extraction algorithm iterating all content items in order, not just item 0)
  • ad-tech-protocol-expert: approved — flat structuredContent shape description is accurate per static/test-vectors/mcp-response-extraction.json and mcp-response-extraction.mdx line 87; nit noted (the merge step of envelope+payload into a flat object is not explained) as follow-up documentation debt

Follow-up items (not in this PR):

  • Sibling-repo-fix-needed: adcp-client — the code reviewer noted that envelope_field_present may not correctly implement MCP extraction semantics (checking the extracted envelope vs. the raw JSON-RPC result). Should be verified in @adcp/client to confirm the check traverses the extracted structuredContent object per mcp-response-extraction.mdx. If the runner has a separate bug, a severity: advisory annotation may be needed in a follow-up.
  • lint-storyboard-validations-paths.cjsenvelope_field_present is absent from PATH_BEARING_CHECKS; a typo in an envelope_field_present path would not be caught. Follow-up lint improvement.
  • Seller integration guide could document the envelope+payload merge step that MCP agents must perform.

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

  • Push fixup commits directly: gh pr checkout <num>
    fix → push.
  • Or re-trigger: comment /triage execute on the source
    issue.

See #3121
for context.

Session: https://claude.ai/code/session_017QfEu3mAJG9SQk6JUiBGrx


Generated by Claude Code

…y storyboard

The no_legacy_status_fields step narrative didn't explain that for MCP
transport, status must appear at the top level of structuredContent
alongside task-specific fields — not at the JSON-RPC result level.
Agent implementors reading only the task response schema (get-adcp-capabilities-
response.json) could omit status and still pass response_schema validation,
creating a confusing false-negative from the envelope_field_present check.

Add explicit MCP transport note to the narrative and expected block,
referencing the normative extraction algorithm in
docs/building/implementation/mcp-response-extraction.

Refs #3999.

https://claude.ai/code/session_017QfEu3mAJG9SQk6JUiBGrx
@bokelley bokelley added the claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage. label May 3, 2026
@bokelley bokelley marked this pull request as ready for review May 3, 2026 23:32
@bokelley bokelley merged commit 6b47ccd into main May 3, 2026
19 checks passed
@bokelley bokelley deleted the claude/issue-3999-v3-envelope-integrity-mcp-narrative branch May 3, 2026 23:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants