[leggetter]

Summary

Adds include=data to event and request listings, in both the MCP and the CLI. It returns each event's or request's payload (headers, body, path, parsed query) in the list response, so a caller that needs payloads makes one call instead of one per record.

• MCP: include on the list action of gateway_events_read and gateway_requests_read.
• CLI: --include data on gateway event list, gateway request list and gateway request events.

Why

The list actions and commands return IDs and metadata only. An agent or script that needs payloads fetches each record by ID, so listing 100 events means 100 more calls, and a fast agent runs into the API rate limit. The API already supports include=data on GET /events, GET /requests and GET /requests/{id}/events. It carries x-docs-hide in the spec, which is why the CLI and MCP left it out.

Changes

• MCP tools: new include property (enum data) on action list only, forwarded on all three routes. list_ignored refuses it, because GET /requests/{id}/ignored_events does not declare it.
• CLI commands: new --include flag. It requires --output json, because the list output prints IDs and a summary line and would discard the payloads. Unknown values are left for the API to reject.
• Default page size: when include is set without a limit, the limit defaults to 10, instead of the API's default page size in the MCP and instead of 100 in the CLI. An explicit limit is honoured.
• request events paging: this command's JSON is a bare array with no cursor, so a page the API cut short looked complete. When the API reports more events (pagination.next), a note on stderr now gives the cursor to pass to --next, with or without --include. A page that is merely full gets no note. The JSON on stdout is unchanged.
• Payload fields: EventData now keeps the documented url, method, query, appended_headers and is_large_payload, and RequestData (the spec's ShortEventData) keeps query and is_large_payload, instead of dropping them in decoding. headers and parsed_query accept a string or an object, as the spec allows; before, one record in the string form would fail the whole page.
• Telling the agent: the MCP tool description, the include property and the gateway_help topic all state the default, that a page of 10 does not mean there are no more (check pagination.next), and to pass limit for a bigger page.
• Hidden-parameter tests: TestPluralToolsOmitParametersHiddenFromTheAPIDocs and TestListCommandsOmitFlagsHiddenFromTheAPIDocs no longer list include; the other x-docs-hide parameters stay omitted.
• Docs: README paragraph in the MCP section; REFERENCE.md regenerated.

Testing

• go test ./... and go vet ./... pass.
• Unit tests for each MCP tool and each CLI command: forwarding, the default limit (applied, overridden by an explicit limit, absent without include), refusals (list_ignored; CLI without --output json), payload pass-through, the stderr note on request events, and decoding both shapes of headers and parsed_query plus is_large_payload. Reverted each fix in turn and watched only that call site's tests fail.
• New acceptance tests against the live API, each with a negative control (no data without include; data.body equals the payload sent with it):
  • TestMCPListIncludeData (-tags=mcp)
  • TestEventListIncludeData (-tags=event), which also checks the default limit, the --output json refusal, and that the API rejects an unknown value
  • TestRequestIncludeData (-tags=request), covering request list and request events
  • TestRequestEventsPointsAtTheNextPage (-tags=request): a request fanned out to two events; --limit 1 prints a --next cursor that reaches the second event, and --limit 2 (exactly full) prints no note
• -tags=mcp and -tags="request event" pass in full.

Not in this PR

• The API reference does not document include yet.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

No active review issues block approval of the opt-in payload inclusion change.

No open issues 🎉

What changed in this PR

Adds opt-in payloads to Event Gateway event and request listings in the CLI and MCP, reducing the need to fetch each record individually.

Changes:

• Exposes include=data on supported list routes, with a default page size of 10 and JSON-only output in the CLI.
• Expands payload models and supports string or object forms for headers and parsed queries.
• Adds unit and acceptance coverage, pagination guidance, and updated documentation.

File	Description
test/​acceptance/​request_include_data_test.go	Tests payload inclusion on request listings and request-scoped events.
test/​acceptance/​mcp_include_data_test.go	Tests payload inclusion through MCP against the live API.
test/​acceptance/​event_include_data_test.go	Tests event payloads, limits, and invalid options.
REFERENCE.md	Documents the new flags, defaults, and examples.
README.md	Explains MCP payload inclusion and CLI equivalents.
pkg/​hookdeck/​requests.go	Expands request payload fields and decoding support.
pkg/​hookdeck/​list_data_decode_test.go	Tests mixed payload shapes and large-payload indicators.
pkg/​hookdeck/​events.go	Expands event payload fields and decoding support.
pkg/​gateway/​mcp/​tools.go	Adds shared inclusion guidance and default-limit logic.
pkg/​gateway/​mcp/​tool_requests.go	Exposes and forwards inclusion for request listings.
pkg/​gateway/​mcp/​tool_requests_events_filters_test.go	Tests forwarding and rejection on ignored-event listings.
pkg/​gateway/​mcp/​tool_list_include_data_test.go	Tests MCP schemas, defaults, payload output, and guidance.
pkg/​gateway/​mcp/​tool_events.go	Exposes and forwards inclusion for event listings.
pkg/​gateway/​mcp/​server_test.go	Allows include while keeping other hidden parameters omitted.
pkg/​cmd/​request_list.go	Adds payload inclusion to the request list command.
pkg/​cmd/​request_events.go	Adds inclusion and a potentially incomplete-page warning.
pkg/​cmd/​request_events_filters_test.go	Tests request-event inclusion, limits, and stderr warnings.
pkg/​cmd/​list_include.go	Centralises CLI inclusion validation and default limits.
pkg/​cmd/​gateway_list_filters_test.go	Tests CLI inclusion forwarding, defaults, and JSON requirements.
pkg/​cmd/​event_list.go	Adds payload inclusion to the event list command.

_{Review effort: Balanced}