feat(mcp): auto-expand message list to include full details in single tool call

[priorwave]

Problem

The Gmail API requires two steps to get message details:

1. users.messages.list — returns only message IDs
2. users.messages.get — returns details for a single message

When used via MCP, this means the LLM client must make N+1 tool calls (1 list + N gets) to display a useful inbox view. This wastes context window tokens and round trips.

Proposal

Add server-side auto-expansion in the MCP server: when a users.messages.list response contains message IDs, automatically fan out parallel users.messages.get calls internally and return the combined result in a single MCP tool response.

This could be controlled by an optional parameter like expand: true or format: "metadata" on the list call, so the default behavior remains unchanged.

Example

{
  "resource": "users.messages",
  "method": "list",
  "params": {"userId": "me", "q": "is:unread in:inbox"},
  "expand": true,
  "expand_format": "metadata"
}

Would return the list response with each message's metadata headers (From, Subject, Date) inline, instead of just IDs.

Benefits

• Single MCP tool call instead of N+1
• Reduces LLM context window usage
• The MCP server already has access to auth and the executor — this is just orchestration
• Any MCP client (Claude Desktop, Claude Code, etc.) benefits automatically

Scope

This pattern could apply to other list endpoints too (e.g., drive.files.list with file metadata), but Gmail messages is the most impactful starting point since list only returns IDs.