Huge JSON responses

[JonathanGodley]

Hi!

I've done some pretty significant refactoring on my fork: https://github.com/JonathanGodley/fastmail-mcp with the aim of cutting down response sizes due to how they're impacting my token usage when I'm using this with claude in my workflows.

I had one email be 148k characters, and a 20 message thread hit 194k, making email parsing a token heavy nightmare.

I've done a pretty significant rework of what the responses look like, aiming to cut it down to the essentials while still allowing the raw responses to be obtained.

Would this be something you're interested in me packaging as PR's for you to review, or would you rather keep your MCP operating returning authentic jmap json to the callers?

I don't want to try and package everything if you're ideologically opposed.

[MadLlama25]

Thanks for raising this @JonathanGodley — this is a real problem, especially for AI clients where every extra field burns context tokens and adds noise.

The plan

We're going to address this tool-by-tool rather than a single sweeping change, since different tools need different strategies:

1. Trim default property sets — Most tools request every field Fastmail returns. For example, list_mailboxes dumps 648 lines including myRights, sortOrder, and other internal metadata. Each tool will get a curated "summary" property set that returns only what's typically useful.

2. Add an optional verbose parameter — For tools like get_email where the full response is sometimes needed (e.g., debugging headers, inspecting raw body parts), an opt-in verbose: true flag will return the full payload. The default will be the lean summary.

3. Tool-specific considerations:

• list_mailboxes → drop myRights, internal sort/role metadata
• list_emails / search_emails / advanced_search → return subject, from, date, preview by default; full body only with verbose
• get_email → summary vs full body/headers
• list_identities → drop SMTP config blocks, keep just name/email/replyTo
• list_contacts → trim to name, email, phone basics

This is going to take some time to design, implement, and test properly — the response shapes affect every tool and we want to avoid breaking existing workflows. It's on the roadmap but likely a few releases out. We'll update here as progress is made.

[JonathanGodley]

Awesome. I'll leave you to it.

Thanks for the work you've put into this, and I'll continue to push any bug fixes etc I think are worthwhile upstream.

I've also determined that my solution is implemented ... not well ... and needs a rework regardless.

[JonathanGodley]

Hey, just a heads up - I've finished reworking my fork's simplification. It's at JonathanGodley/fastmail-mcp (v1.9.1-fork.1) if you want to take a look.

It covers 11 tools with two opt-in params: verbose (additional fields, still in the cleaned-up shape) and raw (original JMAP, no transformation).

The big wins are omitting the HTML body on get_email by default (a bodyHtmlSize hint is provided so the caller can decide whether to fetch it), and cleaning up contacts - JMAP's ContactCard format is absurdly verbose with the hash-keyed maps, so the simplifier flattens those to plain arrays and drops the noise fields. Mailboxes and identities get a similar treatment, dropping things like myRights, SMTP config, signatures etc down to the essentials (though I haven't really played with these enough to tell if I've missed something actually important yet).

On emails, my implementation actually exposes more fields than upstream (18 per email vs 8-11 depending on the tool), but dramatically offsets that by culling the HTML content and dropping any null values. I'd considered moving away from JSON entirely to cut structural overhead, but the savings from field curation and HTML omission are the real wins so it didn't seem worth the complexity.

This probably diverges quite a bit from what you had in mind - I just went off what I already had rather than specifically trying to perfectly capture the essentials for everything, so it could definitely use some additional refinement/consideration. get_email especially would likely differ significantly to what you proposed in your comment above, as I'm grabbing more fields but omitting HTML unless verbose is passed.

I figured I'd mention I'd completed this cleanup (and minor rework), and provide a rough overview - just in case you found any of it useful.

[MadLlama25]

Closing with v1.10.0, which delivers the response-size roadmap discussed here through a slightly different shape than originally sketched:

• Metadata variants across the read surface: get_email_metadata, list_emails_metadata, search_emails_metadata, get_thread_metadata, advanced_search_metadata (Add get_email_metadata — headers-only Email/get for least-privilege flows #68, Add *_metadata variants for search, list, and thread tools #70) — strict JMAP properties allowlists, no preview/body fields ever, with unit tests pinning that invariant.
• Slim list_mailboxes via a properties projection (Add targeted mailbox lookup, creation, and slim enumeration #66) — roughly halves payload on large accounts, addressing the myRights/sortOrder noise called out here.
• get_email's result budget raised via _meta for harnesses that honour it (Raise per-tool result size limit on get_email to 500KB #69).

The remaining idea from this thread — a verbose/raw flag flipping the default shape of get_email (HTML-body omission with a bodyHtmlSize hint) — is still a good one, and your fork's field-curation numbers made a solid case for it. If you'd like to upstream that as a focused PR against the current main, it'd be very welcome as a follow-up. Thanks @JonathanGodley and @Richyread for pushing this forward.