mcp-gee-sweet 0.9.2.dev212__tar.gz → 0.9.2.dev215__tar.gz

{mcp_gee_sweet-0.9.2.dev212 → mcp_gee_sweet-0.9.2.dev215}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-gee-sweet
-Version: 0.9.2.dev212
+Version: 0.9.2.dev215
 Summary: MCP server for Google Workspace — Sheets, Drive, Docs (HTML or Markdown), and Calendar.
 Project-URL: Homepage, https://github.com/khuisman/mcp-gee-sweet
 Project-URL: Bug Tracker, https://github.com/khuisman/mcp-gee-sweet/issues

{mcp_gee_sweet-0.9.2.dev212 → mcp_gee_sweet-0.9.2.dev215}/docs/qa/gmail-test-plan.md

@@ -73,7 +73,7 @@ Add `scripts/qa_gmail_fixtures.py` (new), modeled on the TC-GM23 setup snippet:
 |---|---|---|---|---|
 | `plain` | Sent | Single `text/plain` from the sender mailbox; lands `INBOX`+`UNREAD` | `TEST_MESSAGE_ID` | GM01, 03, 19 |
 | `alt-unicode` | Sent | `body` + `body_html`, non-ASCII subject and body, astral emoji | `TEST_GMAIL_UNICODE_ID` | GM27 |
-| `attachments` | Sent + Inserted | Sent: body + small PDF + CSV. Inserted: a `multipart/related` inline PNG with `Content-ID` and **no filename** (`send_message` can't build `related`) | `TEST_GMAIL_ATTACH_ID`, `TEST_GMAIL_INLINE_ID` | GM28 |
+| `attachments` | Sent + Inserted | Sent: body + small PDF + CSV. Inserted: a `multipart/related` inline PNG with `Content-ID` and **no filename** (`send_message` can't build `related`) | `TEST_GMAIL_ATTACH_ID`, `TEST_GMAIL_INLINE_ID` | GM28, 46 |
 | `thread` | Sent (both sides) | Sender sends; the QA mailbox replies; the sender replies again. A real two-party, 3-message thread with Gmail-generated `Message-ID`/`References` | `TEST_THREAD_ID` | GM05, 07, 33, 43 |
 | `reply-to` | Inserted | Foreign `From: noreply@example.invalid`, `Reply-To` = `+tc-gm23` (`send_message` has no `Reply-To` param) | `TEST_GMAIL_REPLYTO_ID` | GM23 (replaces its inline setup) |
 | `forwarded` | Sent | Outer body, then a forwarded message as a real `message/rfc822` part named `forwarded.eml` | `TEST_GMAIL_FWD_ID` | GM29 |
@@ -112,7 +112,7 @@ Keep the IDs and intent. Rewrite each to name the exact tool and params and to r
 | GM28 | `get_message` | Both attachments (PDF, CSV) listed with filename, MIME type, size, `attachment_id`. The inline PNG (`inline` fixture) is listed with `filename: null`; Gmail stores it by `attachmentId` (§5, P3: not a defect). | read |
 | GM29 | `get_message` | `body_plain` is the *outer* message's body; the `.eml` is listed as a `message/rfc822` attachment (§5, P2: not a defect with Gmail's real layout) | read |
 | GM30 | `get_message`, `get_thread` | `large-body` (Gmail delivers both 3 MB parts by `attachmentId`, #825). Without `local_path`: the size-cap error, naming `local_path`, since ~6 MB exceeds the default cap. With `local_path`: the written JSON has `body_plain` (3,000,002 chars) and `body_html` (3,037,987 chars) filled, `attachments: []`, no `body_fetch_errors`. Same for `get_thread` on its thread. Written in the #825 PR (#829). | read |
-| GM31 | `get_thread` | Over-cap thread returns the size-cap error, not a dropped connection or a truncated body. Captures #793's motivating failure live. | read |
+| GM31 | `get_thread` | Over-cap thread returns the size-cap error, not a dropped connection or a truncated body, and the error points at `include_body=False`. With `include_body=False` the same thread lists its 3 message IDs and headers with no bodies (#793). | read |
 | GM32 | `get_message` | Latin-1 body decodes correctly. A zero-setup regression companion to TC-GM26: #792 closed with the finding that Gmail transcodes every text part to UTF-8, so this is expected to **pass**. | read |
 | GM33 | `get_thread` | 3 messages in chronological order, each shaped like `get_message`, `in_reply_to`/`references` populated | read |
 | GM34 | `list_messages`, `list_threads` | `max_results=3` over the 7 `page` fixtures: `next_page_token` present, page 2 has no overlap with page 1, final page has no token. Also `max_results=0` and `9999` clamp without error. | read |
@@ -127,6 +127,7 @@ Keep the IDs and intent. Rewrite each to name the exact tool and params and to r
 | GM43 | `reply_to_message` | Reply into the 3-message `thread` from its middle message: `references` chains all prior IDs, reply lands in the same thread. M2 was sent by the QA mailbox, so the reply is delivered to the sender mailbox | write, cross-mailbox |
 | GM44 | `reply_to_message` (QA) → `list_messages` (sender) | End-to-end delivery. The QA mailbox replies to the `plain` fixture. On the sender side, `list_messages(query='subject:"[mcp-qa:plain]"')` shows the reply arrived in the **same thread** as the original. Proves `In-Reply-To`/`References` thread correctly in the recipient's mailbox, not just in ours. Plus-address cases can't show this. | write, cross-mailbox |
 | GM45 | `send_message` (QA) → `get_message` (sender) | QA sends to the sender mailbox with `cc` = a QA plus-address and `bcc` = another. On the sender side, `get_message` shows `cc` present and **no** `bcc` header. Bcc must be stripped from delivered copies; GM39 only sees the sender's copy. | write, cross-mailbox |
+| GM46 | `get_message` | `include_body=False` on the `attachments` fixture: headers, snippet, labels, and `size_estimate` present; no `body_plain`, `body_html`, or `attachments` key, since Gmail's `metadata` format returns no payload parts (#793) | read |
 
 Every write case uses a `+tc-gmNN` plus-address and an `[mcp-qa:tc-gmNN]` subject (so `reset` sweeps it), and ends with a **Cleanup** step.
 

{mcp_gee_sweet-0.9.2.dev212 → mcp_gee_sweet-0.9.2.dev215}/docs/qa/tests/gmail.md

@@ -333,6 +333,24 @@ Record the printed ID as `{UTF16_ID}`.
 
 ---
 
+### TC-GM46: `include_body: false` returns headers without body or attachments (issue #793)
+
+**Background:** `include_body: false` fetches with Gmail's `format='metadata'`, which returns headers but no payload parts (confirmed live 2026-10-04). So the result omits attachment metadata as well as the body.
+
+**Action**
+1. `get_message` with `message_id: "{TEST_GMAIL_ATTACH_ID}"`, `include_body: false`
+
+**Checks**
+- `id` is `{TEST_GMAIL_ATTACH_ID}`; `thread_id`, `snippet`, `label_ids`, `internal_date`, and a positive `size_estimate` are present
+- `headers.subject` starts `[mcp-qa:`, `headers.from` contains `{SENDER}`, `headers.message_id` is non-empty
+- No `body_plain`, `body_html`, `attachments`, `body_decode_errors`, `body_fetch_errors`, or `error` key
+
+**Result** (2026-10-04, PR #885 round 1 at `47937d8`, `mcp-gee-sweet-kit`, OAuth token with `gmail.modify`): **PASS**. `id`, `thread_id`, `snippet` (`mcp-gee-sweet attachments fixture: a PDF and a CSV.`), `label_ids`, `internal_date` and `size_estimate` = 7893 present. `headers.subject` = `[mcp-qa:attachments] PDF + CSV`, `headers.from` = `{SENDER}`, `headers.message_id` non-empty. No body, attachment, error-list or `error` keys. The PR still went back to the Dev for code-review findings this case doesn't exercise; see the PR #885 comment.
+
+**Result** (2026-10-04, PR #885 round 2 at `48bf23f`, `mcp-gee-sweet-kit`, OAuth token with `gmail.modify`): **PASS (regression)**. The output matches round 1 field for field. The fix's `metadataHeaders` filter can't be seen through shaping, so it was checked against the raw API instead (see TC-GM31's round 2 result).
+
+---
+
 ## `list_threads`
 
 ### TC-GM05: List the fixture threads
@@ -381,18 +399,25 @@ Record the printed ID as `{UTF16_ID}`.
 
 ---
 
-### TC-GM31: An over-cap thread returns the size-cap error
+### TC-GM31: An over-cap thread returns the size-cap error, and `include_body: false` lists it (issue #793)
 
-**Background:** the `over-cap-thread` fixture is 3 messages of ~400 KB each, which is over the default `MAX_TOOL_RESPONSE_CHARS` in full format but under it per message. This is the failure #793 wants a lighter option for. Today the tool should refuse cleanly rather than drop the connection or truncate.
+**Background:** the `over-cap-thread` fixture is 3 messages of ~400 KB each, which is over the default `MAX_TOOL_RESPONSE_CHARS` in full format but under it per message. The full fetch should refuse cleanly rather than drop the connection or truncate. Since #793, `include_body: false` fetches only metadata, which is small enough to list the thread's message IDs.
 
 **Action**
 1. `get_thread` with `thread_id: "{TEST_GMAIL_BIG_THREAD_ID}"`
-2. `list_messages` with `query: "label:mcp-qa-fixture subject:(mcp-qa over-cap-thread)"`, then `get_message` on any one returned ID
+2. `get_thread` with `thread_id: "{TEST_GMAIL_BIG_THREAD_ID}"`, `include_body: false`
+3. `get_message` with `message_id` set to the first message ID from step 2
 
 **Checks**
-- Step 1: the tool call fails with an error containing `get_thread: the response is` and `safety cap`, and the error suggests `get_message` on individual IDs. The session stays connected: the next call works.
+- Step 1: the tool call fails with an error containing `get_thread: the response is` and `safety cap`. The error suggests `include_body=False` followed by `get_message` on individual IDs. The session stays connected: the next call works.
 - Step 1: no partial or truncated thread is returned
-- Step 2: 3 messages listed; `get_message` succeeds, with a `body_plain` that starts `mcp-gee-sweet over-cap-thread message`
+- Step 2: no `error`. `id` is `{TEST_GMAIL_BIG_THREAD_ID}`, and `messages` has 3 entries, each with `id`, `thread_id`, `snippet`, `label_ids`, `size_estimate`, and `headers` (`headers.subject` contains `[mcp-qa:over-cap-thread]`)
+- Step 2: no message has a `body_plain`, `body_html`, or `attachments` key, and the whole response is a few KB, not ~1.2 MB
+- Step 3: succeeds, with a `body_plain` that starts `mcp-gee-sweet over-cap-thread message`
+
+**Result** (2026-10-04, PR #885 round 1 at `47937d8`, `mcp-gee-sweet-kit`, OAuth token with `gmail.modify`): **PASS**. Step 1: `get_thread: the response is 1275124 characters, over the 1000000-character safety cap`, with the hint naming `include_body=False` then `get_message` on individual IDs; no partial thread, and the next call worked. Step 2: no `error`, 3 messages, each with `id`, `thread_id`, `snippet`, `label_ids`, `size_estimate` (~412 KB each) and `headers` (subjects contain `[mcp-qa:over-cap-thread]`; `in_reply_to`/`references` chain correctly), no body or attachment keys; the response was about 3 KB. Step 3: run with `local_path` to keep ~425 KB out of the QA session's context (424,899 bytes written); `body_plain` starts `mcp-gee-sweet over-cap-thread message 1.`. The thread-level `snippet` is `null`, the same as the full format (`threads.get` returns none).
+
+**Result** (2026-10-04, PR #885 round 2 at `48bf23f`, `mcp-gee-sweet-kit`, OAuth token with `gmail.modify`): **PASS**. Steps 1–3 matched round 1 exactly (1,275,124-character cap error with the `include_body=False` hint; 3 metadata-only messages; step 3 via `local_path`, 424,899 bytes). The `metadataHeaders` filter was checked with a fresh-interpreter raw `threads.get` on the same thread using this slot's token. Plain `format=metadata` returned 24,591 bytes and 88 headers (ARC-*, DKIM-Signature, Received, X-Gm-*, and others). `_get_format_kwargs(False)` returned 3,003 bytes and 19 headers, all from the shaped set (Date, From, In-Reply-To, Message-ID, References, Subject, To).
 
 ---
 

{mcp_gee_sweet-0.9.2.dev212 → mcp_gee_sweet-0.9.2.dev215}/docs/roadmap.md

@@ -196,6 +196,8 @@ Same shape as v0.8.1 — stabilize on defects that surfaced since v0.9.0 shipped
 - [ ] `_timed` logs a `200` status for tool calls that catch their own exception and return `{error: ...}` — observability reports success for a call that actually failed ([#579](https://github.com/khuisman/mcp-gee-sweet/issues/579))
 - [ ] `emitter.py` table-cell images have no cursor-advance handling — latent infinite loop if that code path is ever reached ([#509](https://github.com/khuisman/mcp-gee-sweet/issues/509))
 - [ ] Calendar ACL tools use a bare `except Exception` instead of the `HttpError` friendly-error pattern used elsewhere in `calendar.py` ([#459](https://github.com/khuisman/mcp-gee-sweet/issues/459))
+- [ ] `delete_file(permanent=True)` surfaces a misleading 404 when the caller can trash but not permanently delete (Shared Drive Content manager) — an agent can read it as "already gone" and skip cleanup; check `capabilities.canDelete` first — lane B ([#876](https://github.com/khuisman/mcp-gee-sweet/issues/876))
+- [ ] SSE: SIGTERM with an SSE stream open logs an "Exception in ASGI application" traceback; the server still exits cleanly, pre-existing before #833 — lane A ([#868](https://github.com/khuisman/mcp-gee-sweet/issues/868))
 - [x] `sync_folder`'s `convert_markdown` restamp-failure handling: quota-message gap, duplicated create()+update() try/except, test fixture isolation — companion to #420 (PR #669) ([#650](https://github.com/khuisman/mcp-gee-sweet/issues/650))
 - [x] `sync_folder convert_markdown`'s `modifiedTime` restamp fires for all convert types (over-broad), and its create()+update() pattern is duplicated across two call sites ([#435](https://github.com/khuisman/mcp-gee-sweet/issues/435)) (PR #817)
 - [ ] Harden `tests/integration`'s local-fs live QA harness — error surfacing on API failures, subprocess/handshake timeouts, cleanup-masking a real test failure, per-test subprocess overhead ([#648](https://github.com/khuisman/mcp-gee-sweet/issues/648))
@@ -242,6 +244,8 @@ Same shape as v0.8.1 — stabilize on defects that surfaced since v0.9.0 shipped
 - [ ] `ast_to_markdown.py`: image-render duplication + falsy-based code-block buffer flush ([#600](https://github.com/khuisman/mcp-gee-sweet/issues/600))
 - [ ] `html_parser.py` `handle_data`: a SIM114 lint merge conflates two structurally distinct buffering triggers ([#638](https://github.com/khuisman/mcp-gee-sweet/issues/638))
 - [ ] Docs image-sharing failure paths: unrevocable `anyone:reader` grant + missing folder-cache invalidation in `_replace_doc_content` ([#666](https://github.com/khuisman/mcp-gee-sweet/issues/666))
+- [ ] `write_doc_content`/`update_doc_from_file` leave the doc empty when the replacement fails after the clear — decided 2026-10-04: record the pre-clear revision ID and name it in the error so the caller can recover via `export_revision` ([#878](https://github.com/khuisman/mcp-gee-sweet/issues/878))
+- [ ] `insert_local_images`: temporary `anyone:reader` image shares aren't revoked when the call is cancelled — apply PR #877's shielded-cleanup pattern — lane B ([#883](https://github.com/khuisman/mcp-gee-sweet/issues/883))
 - [x] `_apply_doc_content`: temporary `anyone:reader` image shares aren't revoked when the doc edit raises — revoke pass should run in a `finally`. Same share/revoke surface as #666 and #511 ([#789](https://github.com/khuisman/mcp-gee-sweet/issues/789)) (PR #877)
 - [ ] Docstrings: `create_paragraph_bullets` carries internal API-quirk mechanics plus residual bare issue refs in `style.py` tool docstrings ([#683](https://github.com/khuisman/mcp-gee-sweet/issues/683))
 - [ ] `TestIsolatedDepthRunGlyph` asserts request shape, not rendered nesting outcome (PR #711) ([#715](https://github.com/khuisman/mcp-gee-sweet/issues/715))
@@ -270,6 +274,7 @@ Same shape as v0.8.1 — stabilize on defects that surfaced since v0.9.0 shipped
 - [x] Deduplicate the `max_results` clamp expression, hand-copied 8x across `drive/files.py` with inconsistent caps (PR #736 follow-up) ([#737](https://github.com/khuisman/mcp-gee-sweet/issues/737)) (PR #781)
 - [x] `download_file`: one pre-flight `local_path` check before any Drive call, for both trailing-slash and plain branches, naming the blocking path (#724/#827 follow-up; on-deck, `good first issue`) (PR #855) ([#836](https://github.com/khuisman/mcp-gee-sweet/issues/836))
 - [ ] `sync_folder`: a failed mid-stream download leaves a truncated local file with a fresh mtime, which the next sync uploads over the intact Drive copy — download to a temp file and `os.replace` on success; check `download_file`/`download_folder` too. Found by code review, not yet observed live (lane-a, after #814 since both touch `_run_one`) ([#844](https://github.com/khuisman/mcp-gee-sweet/issues/844))
+- [ ] `download_file` local-path preflight follow-ups (#836/PR #855): mkdir-race fallback, trailing `/.` treated as a file destination, dangling-symlink inconsistency — lane A ([#874](https://github.com/khuisman/mcp-gee-sweet/issues/874))
 
 **Calendar hardening** _(triaged out of `backlog` 2026-09-11)_
 - [ ] `list_calendar_acl` pagination fix (#460) needs a response-size cap, loop safety bound, and partial-failure handling ([#615](https://github.com/khuisman/mcp-gee-sweet/issues/615))
@@ -379,6 +384,9 @@ Follows the design in [`docs/decisions/decision-comments-first-class.md`](decisi
 - [ ] Decide handling of ASYNC240 findings — sync `pathlib` calls in async tool functions (16 sites); **decision needed** ([#378](https://github.com/khuisman/mcp-gee-sweet/issues/378))
 - [ ] Investigate other MCP clients' response-overflow handling for platform-specific `MAX_TOOL_RESPONSE_CHARS` guidance ([#555](https://github.com/khuisman/mcp-gee-sweet/issues/555))
 
+**QA**
+- [ ] Dedicated QA calendar, teardown for creation-only tests, and a `cleanup_stray_artifacts` sweep — split from #304, no second account needed — Aziz ([#886](https://github.com/khuisman/mcp-gee-sweet/issues/886))
+
 ### Tier 3 — Advanced / occasionally needed _(target: [v1.0.0](https://github.com/khuisman/mcp-gee-sweet/issues?q=is%3Aissue+label%3Av1.0))_
 
 **Sheets**
@@ -509,7 +517,7 @@ The test expected the API to silently truncate a 2D array that's wider than the
 - [x] Google Docs tools (all 13) — `docs.md`
 - [x] Calendar tools — `calendar.md`
 - [x] Infrastructure — `infra.md`
-- [ ] QA gaps targeted for v0.9 — disposition of v0.8.0 SKIP entries, done, triaged the rest below ([x] [#227](https://github.com/khuisman/mcp-gee-sweet/issues/227), PR #493); dedicated QA Google account + calendar + pollution root-cause fixes, consolidates #225/#226/#249 — deferred out of v0.9.0 (2026-09-02, paid-account cost not justified for the volume); revisit via alternate OAuth client configs ([#304](https://github.com/khuisman/mcp-gee-sweet/issues/304)); second Drive folder + shared drive fixtures, consolidates #44/#48 — done as a full fixture-set re-provision into the `mcp-gee-sweet-shared` Shared Drive (Workspace-org migration overtook the original scope); `TEST_FOLDER_2_ID` half retired, TC-D123 permanently skipped ([x] [#305](https://github.com/khuisman/mcp-gee-sweet/issues/305), PR #677); two Aziz-routed test-doc fixups surfaced by PR #677's fixture re-provisioning, both to be handled during Full Regression pass prep — TC-DOC80 can no longer trip the response cap post-#519, needs a per-case low-cap override ([#678](https://github.com/khuisman/mcp-gee-sweet/issues/678)); several `drive_files.md` cases assume My-Drive semantics now that fixtures live in a Shared Drive (TC-D58/D61/D03/D59/D27/D04/D175), and TC-D27 may expose a real `list_folders` Shared-Drive tool gap ([#680](https://github.com/khuisman/mcp-gee-sweet/issues/680)); domain/public sharing coverage — moved to v0.9.1 (2026-09-02) ([#49](https://github.com/khuisman/mcp-gee-sweet/issues/49)); local-filesystem coverage ([x] [#50](https://github.com/khuisman/mcp-gee-sweet/issues/50), PR #644); environment-constraint coverage — closed 2026-09-02 as duplicate, untangled into #305 (shared drives) / #49 (external + public sharing) / #304 (second account, deferred) / #673 (concurrent-session procedure) ([x] [#53](https://github.com/khuisman/mcp-gee-sweet/issues/53)); concurrent-session test procedure — 2 subagents + `mkdir` barrier against a main-checkout server, split from #53 — procedure + pre-approved-SKIP retirement via PR #675, `aziz.md` release-pass wiring via PR #674; live TC-I24/TC-I02/TC-R36 runs happen in the v0.9.0 Full Regression pass (tracked in `docs/qa/runs/v0.9.0.md`), not a standalone issue ([x] [#673](https://github.com/khuisman/mcp-gee-sweet/issues/673), PRs #674/#675); split `drive.md`/`docs.md` test files by submodule, do before #264/#224 to avoid a file-rename conflict ([x] [#233](https://github.com/khuisman/mcp-gee-sweet/issues/233), PR #582); Playwright tag consistency audit + formalize the required/spot-check/skip tiers, raised while fixing #248, sequenced after #233 ([x] [#264](https://github.com/khuisman/mcp-gee-sweet/issues/264), PR #592, #598); image fixtures for `insert_inline_image`, sequenced after #233 ([x] [#224](https://github.com/khuisman/mcp-gee-sweet/issues/224), PR #639); dedicated screenshots folder, independent of the rest ([x] [#231](https://github.com/khuisman/mcp-gee-sweet/issues/231), PR #583); `add_chart` test cases leave charts behind with no teardown, polluting the shared Sales fixture across every QA run — same pollution-cluster shape as #304/#305 ([x] [#322](https://github.com/khuisman/mcp-gee-sweet/issues/322), PR #633); plus 7 small unit-test-coverage gaps filed 2026-08-02/08, each self-contained/ad hoc pickup — [x] [#487](https://github.com/khuisman/mcp-gee-sweet/issues/487) (PR #559), [x] [#488](https://github.com/khuisman/mcp-gee-sweet/issues/488) (PR #563), [x] [#489](https://github.com/khuisman/mcp-gee-sweet/issues/489) (PR #569), [x] [#490](https://github.com/khuisman/mcp-gee-sweet/issues/490) (PR #572), [x] [#491](https://github.com/khuisman/mcp-gee-sweet/issues/491) (PR #575), [x] [#494](https://github.com/khuisman/mcp-gee-sweet/issues/494) (PR #577), [x] [#495](https://github.com/khuisman/mcp-gee-sweet/issues/495) (PR #634)
+- [ ] QA gaps targeted for v0.9 — disposition of v0.8.0 SKIP entries, done, triaged the rest below ([x] [#227](https://github.com/khuisman/mcp-gee-sweet/issues/227), PR #493); dedicated QA Google account + calendar + pollution root-cause fixes, consolidates #225/#226/#249 — deferred out of v0.9.0 (2026-09-02, paid-account cost not justified for the volume); revisit via alternate OAuth client configs; split 2026-10-04: multi-user testing stays here at v1.0, pollution cleanup moved to [#886](https://github.com/khuisman/mcp-gee-sweet/issues/886) (v0.9.3) ([#304](https://github.com/khuisman/mcp-gee-sweet/issues/304)); second Drive folder + shared drive fixtures, consolidates #44/#48 — done as a full fixture-set re-provision into the `mcp-gee-sweet-shared` Shared Drive (Workspace-org migration overtook the original scope); `TEST_FOLDER_2_ID` half retired, TC-D123 permanently skipped ([x] [#305](https://github.com/khuisman/mcp-gee-sweet/issues/305), PR #677); two Aziz-routed test-doc fixups surfaced by PR #677's fixture re-provisioning, both to be handled during Full Regression pass prep — TC-DOC80 can no longer trip the response cap post-#519, needs a per-case low-cap override ([#678](https://github.com/khuisman/mcp-gee-sweet/issues/678)); several `drive_files.md` cases assume My-Drive semantics now that fixtures live in a Shared Drive (TC-D58/D61/D03/D59/D27/D04/D175), and TC-D27 may expose a real `list_folders` Shared-Drive tool gap ([#680](https://github.com/khuisman/mcp-gee-sweet/issues/680)); domain/public sharing coverage — moved to v0.9.1 (2026-09-02) ([#49](https://github.com/khuisman/mcp-gee-sweet/issues/49)); local-filesystem coverage ([x] [#50](https://github.com/khuisman/mcp-gee-sweet/issues/50), PR #644); environment-constraint coverage — closed 2026-09-02 as duplicate, untangled into #305 (shared drives) / #49 (external + public sharing) / #304 (second account, deferred) / #673 (concurrent-session procedure) ([x] [#53](https://github.com/khuisman/mcp-gee-sweet/issues/53)); concurrent-session test procedure — 2 subagents + `mkdir` barrier against a main-checkout server, split from #53 — procedure + pre-approved-SKIP retirement via PR #675, `aziz.md` release-pass wiring via PR #674; live TC-I24/TC-I02/TC-R36 runs happen in the v0.9.0 Full Regression pass (tracked in `docs/qa/runs/v0.9.0.md`), not a standalone issue ([x] [#673](https://github.com/khuisman/mcp-gee-sweet/issues/673), PRs #674/#675); split `drive.md`/`docs.md` test files by submodule, do before #264/#224 to avoid a file-rename conflict ([x] [#233](https://github.com/khuisman/mcp-gee-sweet/issues/233), PR #582); Playwright tag consistency audit + formalize the required/spot-check/skip tiers, raised while fixing #248, sequenced after #233 ([x] [#264](https://github.com/khuisman/mcp-gee-sweet/issues/264), PR #592, #598); image fixtures for `insert_inline_image`, sequenced after #233 ([x] [#224](https://github.com/khuisman/mcp-gee-sweet/issues/224), PR #639); dedicated screenshots folder, independent of the rest ([x] [#231](https://github.com/khuisman/mcp-gee-sweet/issues/231), PR #583); `add_chart` test cases leave charts behind with no teardown, polluting the shared Sales fixture across every QA run — same pollution-cluster shape as #304/#305 ([x] [#322](https://github.com/khuisman/mcp-gee-sweet/issues/322), PR #633); plus 7 small unit-test-coverage gaps filed 2026-08-02/08, each self-contained/ad hoc pickup — [x] [#487](https://github.com/khuisman/mcp-gee-sweet/issues/487) (PR #559), [x] [#488](https://github.com/khuisman/mcp-gee-sweet/issues/488) (PR #563), [x] [#489](https://github.com/khuisman/mcp-gee-sweet/issues/489) (PR #569), [x] [#490](https://github.com/khuisman/mcp-gee-sweet/issues/490) (PR #572), [x] [#491](https://github.com/khuisman/mcp-gee-sweet/issues/491) (PR #575), [x] [#494](https://github.com/khuisman/mcp-gee-sweet/issues/494) (PR #577), [x] [#495](https://github.com/khuisman/mcp-gee-sweet/issues/495) (PR #634)
 - See [GitHub Issues (label: qa)](https://github.com/khuisman/mcp-gee-sweet/issues?q=label%3Aqa) for open QA gaps and fixture issues
 
 ---

{mcp_gee_sweet-0.9.2.dev212 → mcp_gee_sweet-0.9.2.dev215}/docs/tools.md

@@ -197,9 +197,9 @@ Requires the `drive.activity.readonly` scope; uses the Drive Activity API v2.
 | Tool | Description | Key parameters |
 |---|---|---|
 | `list_messages` | List messages in the authenticated user's mailbox. | `query?`, `label_ids?`, `max_results?`, `page_token?`, `include_spam_trash?` |
-| `get_message` | Fetch a single message by ID, including headers, body, and attachment metadata. | `message_id`, `local_path?` |
+| `get_message` | Fetch a single message by ID, including headers, body, and attachment metadata. | `message_id`, `local_path?`, `include_body?` |
 | `list_threads` | List conversation threads in the authenticated user's mailbox. | `query?`, `label_ids?`, `max_results?`, `page_token?`, `include_spam_trash?` |
-| `get_thread` | Fetch all messages in a conversation thread. | `thread_id`, `local_path?` |
+| `get_thread` | Fetch all messages in a conversation thread. | `thread_id`, `local_path?`, `include_body?` |
 | `list_labels` | List all labels in the authenticated user's mailbox (system and user-defined). | — |
 | `send_message` | Send a new email message. | `to`, `subject`, `body`, `cc?`, `bcc?`, `body_html?`, `attachments?` |
 | `create_draft` | Create a draft email without sending it. | `to`, `subject`, `body`, `cc?`, `bcc?`, `body_html?`, `attachments?` |

{mcp_gee_sweet-0.9.2.dev212 → mcp_gee_sweet-0.9.2.dev215}/src/mcp_gee_sweet/tools/gmail.py

@@ -398,6 +398,34 @@ class _PendingMessage:
     parts: _PayloadParts | None
 
 
+# The headers a shaped message surfaces, as (result key, header name). Also the
+# metadataHeaders filter for a body-less fetch, so it requests exactly these (#793).
+_SHAPED_HEADERS = (
+    ("from", "From"),
+    # Surfaced because reply_to_message prefers it over From when replying to
+    # someone else's message (#791).
+    ("reply_to", "Reply-To"),
+    ("to", "To"),
+    ("cc", "Cc"),
+    ("bcc", "Bcc"),
+    ("subject", "Subject"),
+    ("date", "Date"),
+    ("message_id", "Message-ID"),
+    ("in_reply_to", "In-Reply-To"),
+    ("references", "References"),
+)
+
+
+def _get_format_kwargs(include_body: bool) -> dict[str, Any]:
+    """The format kwargs for messages.get / threads.get. 'metadata' returns headers,
+    snippet, labels, and size but no payload parts, so no body or attachment data;
+    metadataHeaders keeps it from also returning every Received/ARC/DKIM header
+    that shaping would drop (#793)."""
+    if include_body:
+        return {"format": "full"}
+    return {"format": "metadata", "metadataHeaders": [name for _, name in _SHAPED_HEADERS]}
+
+
 def _start_shaping(msg: dict[str, Any], *, include_body: bool = True) -> _PendingMessage:
     payload = msg.get("payload") or {}
     headers = _header_map(payload.get("headers"))
@@ -408,20 +436,7 @@ def _start_shaping(msg: dict[str, Any], *, include_body: bool = True) -> _Pendin
         "label_ids": msg.get("labelIds") or [],
         "internal_date": msg.get("internalDate"),
         "size_estimate": msg.get("sizeEstimate"),
-        "headers": {
-            "from": headers.get("from"),
-            # Surfaced because reply_to_message prefers it over From when replying
-            # to someone else's message (#791).
-            "reply_to": headers.get("reply-to"),
-            "to": headers.get("to"),
-            "cc": headers.get("cc"),
-            "bcc": headers.get("bcc"),
-            "subject": headers.get("subject"),
-            "date": headers.get("date"),
-            "message_id": headers.get("message-id"),
-            "in_reply_to": headers.get("in-reply-to"),
-            "references": headers.get("references"),
-        },
+        "headers": {key: headers.get(name.lower()) for key, name in _SHAPED_HEADERS},
     }
     parts = _extract_bodies_and_attachments(payload) if include_body else None
     return _PendingMessage(shaped, parts)
@@ -653,7 +668,10 @@ def register(tool):
 
     @tool(annotations=ToolAnnotations(title="Get Message", readOnlyHint=True))
     async def get_message(
-        message_id: str, local_path: str | None = None, ctx: Context = None
+        message_id: str,
+        local_path: str | None = None,
+        include_body: bool = True,
+        ctx: Context = None,
     ) -> dict[str, Any]:
         """
         Fetch a single message by ID, including headers, body, and attachment metadata.
@@ -663,6 +681,9 @@ def register(tool):
             local_path: Optional local filesystem path (file or directory) to write the
                         message JSON to instead of returning it inline. Bypasses the
                         response-size cap, for messages with very large bodies.
+            include_body: When False, fetch only metadata (Gmail's format='metadata'):
+                          no body is downloaded, and body_plain, body_html, and
+                          attachments are left out of the result.
 
         Returns:
             Message with id, thread_id, snippet, label_ids, headers (from/to/cc/bcc/
@@ -678,8 +699,9 @@ def register(tool):
             set; a separately delivered body already over the cap raises before
             being downloaded. If local_path is set, returns {local_path, message_id,
             bytes_written} instead, plus body_fetch_errors / body_decode_errors
-            (each entry with message_id) when present. On API failure,
-            {"error": "..."}.
+            (each entry with message_id) when present. With include_body=False, only
+            id, thread_id, snippet, label_ids, internal_date, size_estimate, and
+            headers. On API failure, {"error": "..."}.
         """
         if unauthorized := get_gmail_unauthorized_message():
             return {"error": unauthorized}
@@ -688,15 +710,16 @@ def register(tool):
             msg = await execute_in_thread(
                 lc.gmail_service.users()
                 .messages()
-                .get(userId=_USER, id=message_id, format="full")
+                .get(userId=_USER, id=message_id, **_get_format_kwargs(include_body))
                 .execute,
                 lc.gmail_service,
             )
         except Exception as e:
             return {"error": str(e)}
 
-        hint = "The message body is large. "
-        pending = [_start_shaping(msg, include_body=True)]
+        # No body is fetched with include_body=False, so only headers can be large.
+        hint = "The message body is large. " if include_body else "The message headers are large. "
+        pending = [_start_shaping(msg, include_body=include_body)]
         if not local_path:
             enforce_response_size_floor(
                 _deferred_body_bytes(pending), tool_name="get_message", hint=hint
@@ -784,7 +807,10 @@ def register(tool):
 
     @tool(annotations=ToolAnnotations(title="Get Thread", readOnlyHint=True))
     async def get_thread(
-        thread_id: str, local_path: str | None = None, ctx: Context = None
+        thread_id: str,
+        local_path: str | None = None,
+        include_body: bool = True,
+        ctx: Context = None,
     ) -> dict[str, Any]:
         """
         Fetch all messages in a conversation thread.
@@ -794,9 +820,14 @@ def register(tool):
             local_path: Optional local filesystem path (file or directory) to write the
                         thread JSON to instead of returning it inline. Bypasses the
                         response-size cap, for threads with very large bodies.
+            include_body: When False, fetch only each message's metadata (Gmail's
+                          format='metadata'): no body is downloaded, and body_plain,
+                          body_html, and attachments are left out. Use it to list a
+                          thread too large to read whole, then get_message each ID.
 
         Returns:
-            Thread with id, snippet, history_id, and messages (same shape as get_message).
+            Thread with id, snippet, history_id, and messages (same shape as get_message,
+            including its include_body=False shape).
             Raises an error naming the size if the thread is over the response-size cap
             and local_path is not set. If local_path is set, returns {local_path,
             thread_id, message_count, bytes_written} instead, plus body_fetch_errors /
@@ -810,15 +841,20 @@ def register(tool):
             thread = await execute_in_thread(
                 lc.gmail_service.users()
                 .threads()
-                .get(userId=_USER, id=thread_id, format="full")
+                .get(userId=_USER, id=thread_id, **_get_format_kwargs(include_body))
                 .execute,
                 lc.gmail_service,
             )
         except Exception as e:
             return {"error": str(e)}
 
-        hint = "The thread is large; use get_message on individual IDs. "
-        pending = [_start_shaping(m, include_body=True) for m in thread.get("messages", [])]
+        hint = (
+            "The thread is large; call get_thread with include_body=False to list its "
+            "message IDs and headers, then get_message on individual IDs. "
+            if include_body
+            else "The thread has too many messages to list inline. "
+        )
+        pending = [_start_shaping(m, include_body=include_body) for m in thread.get("messages", [])]
         if not local_path:
             enforce_response_size_floor(
                 _deferred_body_bytes(pending), tool_name="get_thread", hint=hint

{mcp_gee_sweet-0.9.2.dev212 → mcp_gee_sweet-0.9.2.dev215}/tests/test_gmail.py

@@ -49,6 +49,22 @@ def _raw_payload_from_send_call(gmail_svc) -> bytes:
 _gmail_tool, _gmail_tools = _make_tool_registry()
 gmail_module.register(_gmail_tool)
 
+# Every header a shaped message surfaces, which a body-less fetch requests via
+# metadataHeaders (#793). Spelled out rather than imported from gmail.py, so a
+# change to the filter has to be made here too.
+_SHAPED_HEADER_NAMES = [
+    "From",
+    "Reply-To",
+    "To",
+    "Cc",
+    "Bcc",
+    "Subject",
+    "Date",
+    "Message-ID",
+    "In-Reply-To",
+    "References",
+]
+
 
 class TestGmailNotAuthorized:
     """#790 / PR #807 QA round 1: when the OAuth token lacks only the Gmail scope,
@@ -189,6 +205,42 @@ class TestGetMessage:
 
         assert "error" in result
 
+    async def test_include_body_false_fetches_metadata_only(self):
+        """#793: metadata format has no payload parts, so no body keys and no fetches."""
+        gmail_svc = MagicMock()
+        messages = gmail_svc.users.return_value.messages.return_value
+        messages.get.return_value.execute.return_value = {
+            "id": "m1",
+            "threadId": "t1",
+            "snippet": "Hello",
+            "labelIds": ["INBOX"],
+            "internalDate": "1700000000000",
+            "sizeEstimate": 162270,
+            "payload": {
+                "mimeType": "multipart/mixed",
+                "headers": [
+                    {"name": "From", "value": "a@example.com"},
+                    {"name": "Subject", "value": "Hi"},
+                ],
+            },
+        }
+        ctx = _make_ctx(gmail_service=gmail_svc)
+
+        result = await _gmail_tools["get_message"](message_id="m1", include_body=False, ctx=ctx)
+
+        messages.get.assert_called_once_with(
+            userId="me", id="m1", format="metadata", metadataHeaders=_SHAPED_HEADER_NAMES
+        )
+        assert result["id"] == "m1"
+        assert result["thread_id"] == "t1"
+        assert result["snippet"] == "Hello"
+        assert result["size_estimate"] == 162270
+        assert result["headers"]["from"] == "a@example.com"
+        assert result["headers"]["subject"] == "Hi"
+        for key in ("body_plain", "body_html", "attachments"):
+            assert key not in result
+        messages.attachments.return_value.get.assert_not_called()
+
 
 def _b64(raw: bytes, *, pad: bool = True) -> str:
     encoded = base64.urlsafe_b64encode(raw).decode()
@@ -837,9 +889,40 @@ class TestMessageSizeCap:
         }
         ctx = _make_ctx(gmail_service=gmail_svc)
 
-        with pytest.raises(ValueError, match=r"get_thread.*Pass local_path"):
+        with pytest.raises(ValueError, match=r"get_thread.*include_body=False.*Pass local_path"):
             await _gmail_tools["get_thread"](thread_id="t1", ctx=ctx)
 
+    async def test_get_message_body_less_over_cap_blames_headers_not_body(self, small_cap):
+        """#793 QA: no body is fetched with include_body=False, so the hint can't
+        call the body large."""
+        gmail_svc = MagicMock()
+        gmail_svc.users.return_value.messages.return_value.get.return_value.execute.return_value = {
+            "id": "m1",
+            "threadId": "t1",
+            "payload": {"headers": [{"name": "References", "value": "<r@x> " * 100}]},
+        }
+        ctx = _make_ctx(gmail_service=gmail_svc)
+
+        with pytest.raises(ValueError, match=r"get_message.*headers are large") as exc:
+            await _gmail_tools["get_message"](message_id="m1", include_body=False, ctx=ctx)
+        assert "body" not in str(exc.value)
+
+    async def test_get_thread_body_less_over_cap_drops_include_body_hint(self, small_cap):
+        """#793: suggesting include_body=False to a call already using it is useless."""
+        gmail_svc = MagicMock()
+        gmail_svc.users.return_value.threads.return_value.get.return_value.execute.return_value = {
+            "id": "t1",
+            "messages": [
+                {"id": f"m{i}", "threadId": "t1", "snippet": "s" * 50, "payload": {}}
+                for i in range(5)
+            ],
+        }
+        ctx = _make_ctx(gmail_service=gmail_svc)
+
+        with pytest.raises(ValueError, match=r"get_thread.*Pass local_path") as exc:
+            await _gmail_tools["get_thread"](thread_id="t1", include_body=False, ctx=ctx)
+        assert "include_body" not in str(exc.value)
+
     async def test_get_thread_local_path_writes_full_thread(self, small_cap, tmp_path):
         gmail_svc = self._large()
         gmail_svc.users.return_value.threads.return_value.get.return_value.execute.return_value = {
@@ -970,6 +1053,50 @@ class TestGetThread:
 
         assert "error" in result
 
+    async def test_default_fetches_full_format(self):
+        gmail_svc = MagicMock()
+        threads = gmail_svc.users.return_value.threads.return_value
+        threads.get.return_value.execute.return_value = {"id": "t1", "messages": []}
+        ctx = _make_ctx(gmail_service=gmail_svc)
+
+        await _gmail_tools["get_thread"](thread_id="t1", ctx=ctx)
+
+        threads.get.assert_called_once_with(userId="me", id="t1", format="full")
+
+    async def test_include_body_false_lists_ids_and_headers_only(self):
+        """#793: a thread too large to read whole can still be listed by message ID."""
+        gmail_svc = MagicMock()
+        threads = gmail_svc.users.return_value.threads.return_value
+        threads.get.return_value.execute.return_value = {
+            "id": "t1",
+            "historyId": "5",
+            "messages": [
+                {
+                    "id": f"m{i}",
+                    "threadId": "t1",
+                    "snippet": f"snippet {i}",
+                    "payload": {
+                        "mimeType": "multipart/mixed",
+                        "headers": [{"name": "Subject", "value": f"Re: {i}"}],
+                    },
+                }
+                for i in (1, 2)
+            ],
+        }
+        ctx = _make_ctx(gmail_service=gmail_svc)
+
+        result = await _gmail_tools["get_thread"](thread_id="t1", include_body=False, ctx=ctx)
+
+        threads.get.assert_called_once_with(
+            userId="me", id="t1", format="metadata", metadataHeaders=_SHAPED_HEADER_NAMES
+        )
+        assert [m["id"] for m in result["messages"]] == ["m1", "m2"]
+        assert result["messages"][1]["headers"]["subject"] == "Re: 2"
+        for message in result["messages"]:
+            for key in ("body_plain", "body_html", "attachments"):
+                assert key not in message
+        gmail_svc.users.return_value.messages.return_value.attachments.assert_not_called()
+
 
 class TestListLabels:
     async def test_maps_system_and_user_labels(self):