GeezerVison

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