mcp-gee-sweet 0.8.2.dev258__tar.gz → 0.8.2.dev259__tar.gz

{mcp_gee_sweet-0.8.2.dev258 → mcp_gee_sweet-0.8.2.dev259}/CLAUDE.md

@@ -36,7 +36,7 @@ Logic is split across `src/mcp_gee_sweet/`: `server.py` (MCP setup, tool decorat
 - `tools/sheets/helpers.py` — A1 notation helpers (`_parse_a1_notation`, `_column_index_to_letter`, etc.)
 - `tools/drive/files.py` — file/folder operations (`create_spreadsheet`, `import_csv_to_sheet`, `list_spreadsheets`, `list_files`, `search_files`, `create_folder`, `create_shortcut`, `copy_file`, `move_file`, `rename_file`, `star_file`, `unstar_file`, `delete_file`, `restore_file`, `empty_trash`, `list_shared_with_me`, `list_recent_files`, `get_storage_quota`, etc.). `star_file`/`unstar_file` (#139) set `starred` via `files().update` — neither `get_file_metadata` nor `list_files` currently exposes the `starred` field back, so live QA verification is round-trip only (see TC-D202/203 in `docs/qa/tests/drive.md`). Both `list_files` and `get_file_metadata` now surface Drive's `md5Checksum` field as `md5_checksum` (#274) — `None` for Google Workspace files (Docs/Sheets/Slides have no fixed byte content, so the Drive API omits the field for them), a real hash for binary files. Exists so callers can detect real content drift instead of inferring it from `modifiedTime`, which sync/upload paths don't always keep faithful to actual content (see `transfer.py`'s `sync_folder` `use_checksum` param below, the primary consumer of this).
 - `tools/drive/sharing.py` — permissions (`share_spreadsheet`, `share_file`, `list_permissions`, `update_permission`, `remove_permission`, `transfer_ownership`). `transfer_ownership` requires OAuth — service accounts have no personal Drive identity to transfer ownership to/from, so Drive's API rejects the transfer.
-- `tools/drive/transfer.py` — upload/download/sync/export/revisions; `_upload_local_file` (the core behind the `upload_local_file` tool) is a module-level helper so `docs/content.py`'s `insert_local_images` can call it directly, imported cross-package the same way `docs/content.py` imports `_SA_QUOTA_ERROR` from `tools/drive/__init__.py`. `upload_local_file`'s `convert` param (#188) requests Drive's *native* import conversion — CSV/XLSX→Sheets, DOCX/MD/HTML→Docs, PPTX→Slides — by uploading with the source format's mimeType while setting the destination's `mimeType` metadata to the target Google Workspace type (`_CONVERT_MIME` maps extension → (source mime, target mime)). This is a different mechanism from `docs/content.py`'s `create_doc_from_file`, which parses the file locally and rebuilds it via Docs API requests instead of Drive's importer — don't conflate the two when adding new conversion paths. `sync_folder`'s `convert_markdown` param (#211) applies the same native-conversion mechanism to local `.md` files during sync uploads. Because the converted Doc keeps its `.md` name in Drive, `_sync_level`'s drive_map-building loop matches it back to the local `.md` file directly (bypassing the export_format-suffix scheme normal Workspace files need) so resyncs settle into "in sync" instead of re-uploading a duplicate every run — this also reopens matching for a drive-only converted Doc with no local counterpart and no `export_format` (previously unreachable, since such files were always excluded from `drive_map`) — the plan-building loop classifies that case as a `conflict` (a convert_markdown Doc has no reverse conversion) before it ever reaches the download branch, so the download branch's own `_EXPORT_MIME[None]` guard is defensive-only dead code in the current implementation, not a reachable path (confirmed live: TC-D221). There is no reverse conversion (Doc → markdown). A converted Doc is recognized on every later sync via a Drive `properties` marker (`_CONVERT_MARKDOWN_SOURCE_PROP`) stamped at creation time by both `_sync_level`'s own upload path and `_upload_local_file`'s `convert=True` path (#414 rounds 2-3) — recognition is deliberately independent of whether the *current* call passes `convert_markdown`/`convert`, since the Doc's own persisted property is what matters, not this call's flag. Three further edge cases from that round-3 review shipped as issue #422: the `drive_map`-building loop now detects (rather than silently resolving) a name collision between a plain file and a converted Doc, reporting it under `failed` instead of letting whichever is listed last win the slot and make the other invisible to the sync; `_upload_local_file` now stamps `modifiedTime` from the local file's mtime on a converted Doc (via `create()` then a metadata-only `update()`, mirroring `_sync_level`'s own create() branch, since Drive's native import-conversion overwrites the create()-time value once conversion finishes) so a subsequent `sync_folder` lands in `skipped` rather than `conflicts`; and the drive-only branch now checks `direction` before `_is_converted_md`, so `direction='upload'` reports a plain `skip` like any other drive-only file instead of always reporting `conflict`. PR #433's own review round found the collision guard needed to go further: it originally only fired when the two colliding entries' `_is_converted_md` differed (a plain file vs. a converted Doc, #422's own reported shape), silently overwriting a same-type collision (two plain files, or two converted Docs, sharing a name) the exact same way; it now fires on any duplicate name regardless of type. The collision case is also now routed through the normal `plan`/`action` machinery (a new `"collision"` action, mapped to `conflict` during `dry_run` and to a real `failed` entry — `kind: "collision_fail"` — once execution is actually attempted) rather than writing to `failed` directly from the `drive_map`-building loop: that direct write both leaked into `failed` during `dry_run` (breaking the "dry_run never reports failures, only previews" invariant the pre-existing folder-collision failure path already upholds) and silently dropped a *local* file sharing the colliding name from every result list, since the plan loop's bare `continue` skipped it with zero acknowledgment. Separately, `_upload_local_file`'s `create()`+`update()` pair now shares one broad `except Exception` returning `{"error": ...}` (matching `_sync_level._run_one`'s own create+update pattern) instead of only catching quota `HttpError`s and letting everything else — including a failure in the new metadata-only restamp `update()`, after `create()` already succeeded — propagate uncaught to `upload_local_file`, which has no try/except of its own. `sync_folder`'s `use_checksum` param (#274) adds a content check ahead of `_sync_level`'s mtime comparison for names present on both sides: when the local file's md5 (`_local_md5`, streamed in 1 MiB chunks) matches Drive's own `md5Checksum` (now fetched by `_list_drive_children`), the pair is treated as in sync regardless of `modifiedTime` drift — this is what actually fixes `upload_local_file` not stamping `modifiedTime` (unlike `_sync_level`'s own upload path) causing a spurious re-download of identical content on the next sync, not just a same-mtime coincidence. Only applies where Drive returns a real `md5Checksum` — Workspace files and `convert_markdown` Docs have none and always fall back to mtime-only comparison, flag or no flag. A checksum *mismatch* doesn't force any decision by itself; it just falls through to the same mtime-based upload/download/conflict logic used when `use_checksum=False`, since content differing doesn't by itself say which side is newer. PR #472's own review round found four issues in this first version: the checksum comparison ran unconditionally, before the (cheap) mtime diff, including for pairs already within `_SYNC_MTIME_TOLERANCE` and even during `dry_run=True` — fixed by moving the mtime diff first and gating the hash read on `use_checksum and not dry_run and abs(diff) > _SYNC_MTIME_TOLERANCE`, so an already-in-sync pair or a dry_run preview never pays for a read it can't change the outcome of; `_local_md5` had no try/except unlike every other per-item operation in this module, so a file that became unreadable (deleted, permission-denied) between the directory scan and the hash read raised uncaught out of the whole `sync_folder` call instead of degrading to one `failed` entry — fixed via a new `"checksum_read_fail"` plan action mirroring the existing `"collision"` pattern; and `_upload_local_file`'s plain (non-`convert`) branch was identified as the actual root cause worth fixing directly — it never stamped `modifiedTime` the way the `convert_mime` branch three lines above already did (and `#422` already established for that branch), so a file uploaded through it always read as "Drive newer" on the very next `sync_folder` regardless of content — now stamped unconditionally in the `create()` body for every upload (no follow-up `update()` needed for the plain case, since Drive only overwrites `modifiedTime` when import-conversion is involved). `use_checksum` remains valuable beyond that root-cause fix for causes of drift the mtime stamp doesn't cover (e.g. a local overwrite that happens to preserve mtime). One review finding was accepted as a known tradeoff rather than fixed: a checksum mismatch that resolves to `'upload'` reads the local file twice (once to hash, once via `MediaFileUpload` for the actual transfer) — avoiding it would mean buffering the whole file in memory to share across both reads, a worse tradeoff for large files than one extra (likely page-cache-warm) disk read. `upload_local_folder` (#411) used to have its own independent inline upload loop with no `convert` param, unreachable from `_upload_local_file`'s conversion mechanism — bulk-importing a folder of CSV/DOCX/PPTX into native Workspace formats required falling back to per-file `upload_local_file` calls. Fixed by routing each candidate through `_upload_local_file` itself, gaining the same `convert` param and its semantics (an unsupported extension lands in `failed` rather than uploading as-is, matching `upload_local_file`'s own error-not-silent-fallback behavior). The existing bulk `skip_if_exists` pre-check (one `list()` call for the whole folder, not one per file — TC-D100) is preserved rather than replaced by `_upload_local_file`'s own per-call check: the folder loop now fetches each existing file's `mimeType` alongside its name in that same single call, decides skip-worthiness itself (name-only match when `convert=False`; name *and* target-mimeType match when `convert=True`, mirroring `_upload_local_file`'s own convert-aware duplicate check), and then calls `_upload_local_file` with `skip_if_exists=False` for whatever survives — so existence is never checked twice. `sync_folder(dry_run=True)`'s response used to duplicate every `skip`/`conflict` name into both a flat list (`skipped`/`conflicts`) and a full `{name, action, reason}` entry in `actions`, deterministically tripping the response-size cap on a moderately-sized, mostly-in-sync folder even though `actions` alone (name + action-type + reason for every item, including upload/download entries the flat lists never populated during `dry_run` in the first place) was already a complete, non-redundant picture (issue #512). Fixed by leaving `uploaded`/`downloaded`/`skipped`/`conflicts`/`failed` empty during `dry_run` rather than trimming or toggling `actions` itself. Separately, `sync_folder` previously had no response-size-cap bypass at all (`local_path_available=False`) unlike every other capped tool except `export_file`/`list_file_activity` (both deliberately, per the decision doc below) — its own `local_path` param already means the sync destination, so it can't double as a dump target the way `get_sheet_data`'s `local_path` does. Fixed by adding a separate `result_local_path` param following the same unconditional-if-passed `write_capped_result_to_disk` pattern as every other capped tool with a bypass; `enforce_response_size_cap` gained a `local_path_param` override so its error message names the right parameter instead of hardcoding `local_path`. PR #518's own QA review round live-caught a gap in that first version: `result_local_path` had no guard against pointing at or inside `local_path` — since `local_path` is scanned as sync input on every call (unlike every other capped tool's local_path/result_local_path, which are pure output destinations), a manifest written there showed up as a new local-only file on the very next sync and would have been uploaded to Drive on a real run. Fixed by rejecting the call up front (`ValueError`, before any Drive API call) when `Path(result_local_path).resolve()` equals or is a descendant of the resolved `local_path`.
+- `tools/drive/transfer.py` — upload/download/sync/export/revisions; `_upload_local_file` (the core behind the `upload_local_file` tool) is a module-level helper so `docs/content.py`'s `insert_local_images` can call it directly, imported cross-package the same way `docs/content.py` imports `_SA_QUOTA_ERROR` from `tools/drive/__init__.py`. `upload_local_file`'s `convert` param (#188) requests Drive's *native* import conversion — CSV/XLSX→Sheets, DOCX/MD/HTML→Docs, PPTX→Slides — by uploading with the source format's mimeType while setting the destination's `mimeType` metadata to the target Google Workspace type (`_CONVERT_MIME` maps extension → (source mime, target mime)). This is a different mechanism from `docs/content.py`'s `create_doc_from_file`, which parses the file locally and rebuilds it via Docs API requests instead of Drive's importer — don't conflate the two when adding new conversion paths. `sync_folder`'s `convert_markdown` param (#211) applies the same native-conversion mechanism to local `.md` files during sync uploads. Because the converted Doc keeps its `.md` name in Drive, `_sync_level`'s drive_map-building loop matches it back to the local `.md` file directly (bypassing the export_format-suffix scheme normal Workspace files need) so resyncs settle into "in sync" instead of re-uploading a duplicate every run — this also reopens matching for a drive-only converted Doc with no local counterpart and no `export_format` (previously unreachable, since such files were always excluded from `drive_map`) — the plan-building loop classifies that case as a `conflict` (a convert_markdown Doc has no reverse conversion) before it ever reaches the download branch, so the download branch's own `_EXPORT_MIME[None]` guard is defensive-only dead code in the current implementation, not a reachable path (confirmed live: TC-D221). There is no reverse conversion (Doc → markdown). A converted Doc is recognized on every later sync via a Drive `properties` marker (`_CONVERT_MARKDOWN_SOURCE_PROP`) stamped at creation time by both `_sync_level`'s own upload path and `_upload_local_file`'s `convert=True` path (#414 rounds 2-3) — recognition is deliberately independent of whether the *current* call passes `convert_markdown`/`convert`, since the Doc's own persisted property is what matters, not this call's flag. Three further edge cases from that round-3 review shipped as issue #422: the `drive_map`-building loop now detects (rather than silently resolving) a name collision between a plain file and a converted Doc, reporting it under `failed` instead of letting whichever is listed last win the slot and make the other invisible to the sync; `_upload_local_file` now stamps `modifiedTime` from the local file's mtime on a converted Doc (via `create()` then a metadata-only `update()`, mirroring `_sync_level`'s own create() branch, since Drive's native import-conversion overwrites the create()-time value once conversion finishes) so a subsequent `sync_folder` lands in `skipped` rather than `conflicts`; and the drive-only branch now checks `direction` before `_is_converted_md`, so `direction='upload'` reports a plain `skip` like any other drive-only file instead of always reporting `conflict`. PR #433's own review round found the collision guard needed to go further: it originally only fired when the two colliding entries' `_is_converted_md` differed (a plain file vs. a converted Doc, #422's own reported shape), silently overwriting a same-type collision (two plain files, or two converted Docs, sharing a name) the exact same way; it now fires on any duplicate name regardless of type. The collision case is also now routed through the normal `plan`/`action` machinery (a new `"collision"` action, mapped to `conflict` during `dry_run` and to a real `failed` entry — `kind: "collision_fail"` — once execution is actually attempted) rather than writing to `failed` directly from the `drive_map`-building loop: that direct write both leaked into `failed` during `dry_run` (breaking the "dry_run never reports failures, only previews" invariant the pre-existing folder-collision failure path already upholds) and silently dropped a *local* file sharing the colliding name from every result list, since the plan loop's bare `continue` skipped it with zero acknowledgment. Separately, `_upload_local_file`'s `create()`+`update()` pair now shares one broad `except Exception` returning `{"error": ...}` (matching `_sync_level._run_one`'s own create+update pattern) instead of only catching quota `HttpError`s and letting everything else — including a failure in the new metadata-only restamp `update()`, after `create()` already succeeded — propagate uncaught to `upload_local_file`, which has no try/except of its own. `sync_folder`'s `use_checksum` param (#274) adds a content check ahead of `_sync_level`'s mtime comparison for names present on both sides: when the local file's md5 (`_local_md5`, streamed in 1 MiB chunks) matches Drive's own `md5Checksum` (now fetched by `_list_drive_children`), the pair is treated as in sync regardless of `modifiedTime` drift — this is what actually fixes `upload_local_file` not stamping `modifiedTime` (unlike `_sync_level`'s own upload path) causing a spurious re-download of identical content on the next sync, not just a same-mtime coincidence. Only applies where Drive returns a real `md5Checksum` — Workspace files and `convert_markdown` Docs have none and always fall back to mtime-only comparison, flag or no flag. A checksum *mismatch* doesn't force any decision by itself; it just falls through to the same mtime-based upload/download/conflict logic used when `use_checksum=False`, since content differing doesn't by itself say which side is newer. PR #472's own review round found four issues in this first version: the checksum comparison ran unconditionally, before the (cheap) mtime diff, including for pairs already within `_SYNC_MTIME_TOLERANCE` and even during `dry_run=True` — fixed by moving the mtime diff first and gating the hash read on `use_checksum and not dry_run and abs(diff) > _SYNC_MTIME_TOLERANCE`, so an already-in-sync pair or a dry_run preview never pays for a read it can't change the outcome of; `_local_md5` had no try/except unlike every other per-item operation in this module, so a file that became unreadable (deleted, permission-denied) between the directory scan and the hash read raised uncaught out of the whole `sync_folder` call instead of degrading to one `failed` entry — fixed via a new `"checksum_read_fail"` plan action mirroring the existing `"collision"` pattern; and `_upload_local_file`'s plain (non-`convert`) branch was identified as the actual root cause worth fixing directly — it never stamped `modifiedTime` the way the `convert_mime` branch three lines above already did (and `#422` already established for that branch), so a file uploaded through it always read as "Drive newer" on the very next `sync_folder` regardless of content — now stamped unconditionally in the `create()` body for every upload (no follow-up `update()` needed for the plain case, since Drive only overwrites `modifiedTime` when import-conversion is involved). `use_checksum` remains valuable beyond that root-cause fix for causes of drift the mtime stamp doesn't cover (e.g. a local overwrite that happens to preserve mtime). One review finding was accepted as a known tradeoff rather than fixed: a checksum mismatch that resolves to `'upload'` reads the local file twice (once to hash, once via `MediaFileUpload` for the actual transfer) — avoiding it would mean buffering the whole file in memory to share across both reads, a worse tradeoff for large files than one extra (likely page-cache-warm) disk read. `upload_local_folder` (#411) used to have its own independent inline upload loop with no `convert` param, unreachable from `_upload_local_file`'s conversion mechanism — bulk-importing a folder of CSV/DOCX/PPTX into native Workspace formats required falling back to per-file `upload_local_file` calls. Fixed by routing each candidate through `_upload_local_file` itself, gaining the same `convert` param and its semantics (an unsupported extension lands in `failed` rather than uploading as-is, matching `upload_local_file`'s own error-not-silent-fallback behavior). The existing bulk `skip_if_exists` pre-check (one `list()` call for the whole folder, not one per file — TC-D100) is preserved rather than replaced by `_upload_local_file`'s own per-call check: the folder loop now fetches each existing file's `mimeType` alongside its name in that same single call, decides skip-worthiness itself (name-only match when `convert=False`; name *and* target-mimeType match when `convert=True`, mirroring `_upload_local_file`'s own convert-aware duplicate check), and then calls `_upload_local_file` with `skip_if_exists=False` for whatever survives — so existence is never checked twice. `sync_folder(dry_run=True)`'s response used to duplicate every `skip`/`conflict` name into both a flat list (`skipped`/`conflicts`) and a full `{name, action, reason}` entry in `actions`, deterministically tripping the response-size cap on a moderately-sized, mostly-in-sync folder even though `actions` alone (name + action-type + reason for every item, including upload/download entries the flat lists never populated during `dry_run` in the first place) was already a complete, non-redundant picture (issue #512). Fixed by leaving `uploaded`/`downloaded`/`skipped`/`conflicts`/`failed` empty during `dry_run` rather than trimming or toggling `actions` itself. Separately, `sync_folder` previously had no response-size-cap bypass at all (`local_path_available=False`) unlike every other capped tool except `export_file`/`list_file_activity` (both deliberately, per the decision doc below) — its own `local_path` param already means the sync destination, so it can't double as a dump target the way `get_sheet_data`'s `local_path` does. Fixed by adding a separate `result_local_path` param following the same unconditional-if-passed `write_capped_result_to_disk` pattern as every other capped tool with a bypass; `enforce_response_size_cap` gained a `local_path_param` override so its error message names the right parameter instead of hardcoding `local_path`. PR #518's own QA review round live-caught a gap in that first version: `result_local_path` had no guard against pointing at or inside `local_path` — since `local_path` is scanned as sync input on every call (unlike every other capped tool's local_path/result_local_path, which are pure output destinations), a manifest written there showed up as a new local-only file on the very next sync and would have been uploaded to Drive on a real run. Fixed by rejecting the call up front (`ValueError`, before any Drive API call) when `Path(result_local_path).resolve()` equals or is a descendant of the resolved `local_path`. `upload_file`'s `convert_to_doc` param implements the identical native-import-conversion trick as `_upload_local_file`'s `convert`/`_CONVERT_MIME` above, independently — raw text/markdown/html content instead of a local file, always targeting a Doc since there's no file extension to dispatch Sheets/Slides on — with no cross-reference between the two (issue #412). Fixed by sharing `_GOOGLE_DOC_MIME` as the single source of truth for the target mimeType literal both mechanisms write, plus explicit docstring cross-references at both call sites; the two code paths themselves stayed separate rather than being merged, since their actual upload semantics (raw content vs. local file, single target vs. extension-dispatched) differ enough that unifying them would cost more complexity than it'd save.
 - `tools/drive/activity.py` — `list_file_activity` (Drive Activity API v2; requires `drive.activity.readonly` scope)
 - `tools/docs/` — Google Docs package; `__init__.py` is a thin dispatcher that delegates to four submodules:
   - `docs/content.py` — helpers (`_html_to_text`, `_md_to_html`, `_to_doc_requests`, `_html_to_doc_requests`, `_collect_doc_paragraphs`) and tools (`create_doc`, `get_doc_content`, `write_doc_content`, `create_doc_from_file`, `insert_doc_text`, `delete_doc_range`, `get_doc_structure`, `find_in_doc`, `insert_inline_image`, `insert_page_break`, `insert_softbreak_paragraph`, `insert_local_images`, `create_named_range`, `create_bookmark`). The Docs API has no bookmark-creation endpoint — `create_bookmark` is a thin wrapper over `createNamedRange` spanning a single character; neither tool's output is a link target (only UI-created bookmarks/headings are). `find_in_doc` searches paragraph text (including table cells) and returns `start_index`/`end_index` offsets in UTF-16 code units usable directly with `style_doc_range` — `_collect_doc_paragraphs` is a generator (so a caller can stop early once `max_results` is hit) that walks the Docs API body, trusting each `ParagraphElement`'s own `startIndex` when present and otherwise carrying the running offset forward rather than dropping that element, since the API doesn't always populate it (seen on a document's first element). `insert_softbreak_paragraph` joins multiple lines with a literal `"\v"` (vertical tab) character in a single `insertText` call — confirmed live that the Docs API stores this as one paragraph element rather than splitting it, matching the Docs UI's own Shift+Enter soft-break convention — and sets `namedStyleType` explicitly over the inserted span rather than leaving it to whatever the insertion point would otherwise inherit. `insert_local_images` uploads local image files and swaps each into the doc at a plain-text marker in one call; confirmed live that `insertInlineImage` with a `drive_file_id` fails with "There was a problem retrieving the image" unless the file is first shared `anyone`/`reader` — the Docs backend fetches the image as an anonymous HTTP request, so being accessible to the authenticated user alone is not enough (this also applies to the existing `insert_inline_image` tool's `drive_file_id` path, not just the new one; its docstring now says so). `get_doc_structure` now also surfaces each paragraph's `headingId` (`paragraphStyle.headingId`) — confirmed live present on the default single-tab `documents.get()` response for both `TITLE`/`SUBTITLE` and `HEADING_1`..`6` paragraphs, no `includeTabsContent` needed. `create_doc`/`create_doc_from_file`/`write_doc_content` now run an automatic second pass (`_resolve_heading_anchors`, gated by the cheap `_has_pending_anchor_links` check so content with no `#`-links skips the extra API round trip entirely) after any conversion that left a GitHub/GitLab-style `#slug` heading-anchor link behind (issue #409): it resolves the anchor against the doc's own real headings via `anchors.resolve_heading_anchor` and rewrites it to a working `.../edit?tab=t.0#heading=<headingId>` jump link (an ordinary URL is sufficient — no `Link.headingId` API field needed, confirmed live), or strips the link (keeping the text plain) when no heading matches with reasonable confidence — a link silently pointing at the wrong section is worse than a plain, unlinked mention. This was a deliberate product decision to resolve anchors automatically rather than only exposing `headingId` and leaving matching to the calling agent — see `docs/design/heading-anchor-resolution.md` for the full rationale. PR #453's own QA round (`/code-review high` + live testing against a fixture with no table and no anchor on the doc's first element) caught two correctness bugs the first version's hand-rolled body walk had: it only inspected top-level `paragraph` elements (a heading or anchor link living inside a table cell was invisible to both `_has_pending_anchor_links` and `_resolve_heading_anchors`), and it required a run's own `pe.get("startIndex")`/`endIndex` to both be non-`None` (silently dropping an anchor that is, or is part of, the document's first body element — the Docs API omits `startIndex` there, the same quirk `_collect_doc_paragraphs` already handles). Fixed by `_walk_headings_and_anchor_runs`, a dedicated recursive walker mirroring `_collect_doc_paragraphs`'s own two correctness properties (table-cell recursion; carrying the running offset forward via character-by-character advance rather than trusting a run's own possibly-inconsistent `endIndex`) rather than reusing `_collect_doc_paragraphs` itself, since that generator's yielded shape (text + char-indices only) doesn't carry per-run link URLs or heading-paragraph style info and is used elsewhere (`find_in_doc`) in a way not worth risking a signature change for. `_has_pending_anchor_links` gained a second parameter (`tables: list[Table]`, walked via `_table_has_pending_anchor_link`, recursing into nested tables) since `fill_tables()` builds and executes table-cell requests separately from `content_requests`, invisible to the original single-argument guard. `create_doc`/`create_doc_from_file`/`write_doc_content` now support inline images in markdown (`![alt](src)`) and HTML (`<img>`) conversion (issue #333) via a shared `_apply_doc_content` helper: `src` may be a local filesystem path (uploaded to Drive), a `drive:<file_id>` reference to an already-uploaded file, or a public `http(s)://` URL (used directly) — resolved by `_resolve_image_source`, sharing local-path/`drive:` sources `anyone:reader` the same way `insert_local_images` already does, then (per explicit product decision, and now also `insert_local_images`'s own default — a behavior change from its original #332 shipped version) revoking that temporary share once the image is embedded, unless `revoke_sharing=False`. The Docs API rejects an entire `batchUpdate` atomically if any one `insertInlineImage` request in it can't be fetched (confirmed live via TC-DOC102's own deliberately-unreachable-URL case) — `_apply_doc_content` retries with the failing request stripped (its index is parsed directly out of Google's own error message) rather than losing every other request in the same call; see `docs/design/image-conversion.md` for the full design, including why `Image` is a zero-width AST node (not a marker) and the deliberate table-cell-image gap.

{mcp_gee_sweet-0.8.2.dev258 → mcp_gee_sweet-0.8.2.dev259}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-gee-sweet
-Version: 0.8.2.dev258
+Version: 0.8.2.dev259
 Summary: MCP server for Google Workspace — Sheets, Drive, Docs (HTML or Markdown), and Calendar. 60+ tools for AI clients.
 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.8.2.dev258 → mcp_gee_sweet-0.8.2.dev259}/src/mcp_gee_sweet/tools/drive/transfer.py

@@ -49,6 +49,16 @@ _SYNC_MTIME_TOLERANCE = 5  # seconds — absorbs clock skew and upload-time drif
 # (#414 QA review, findings #2 and #7).
 _CONVERT_MARKDOWN_SOURCE_PROP = "geeSweetConvertMarkdownSource"
 
+# Google Workspace Doc mimeType, requested via Drive's native import-conversion
+# trick (upload with the source format's mimeType while setting the destination
+# file's own mimeType to this target) from two independent places: _CONVERT_MIME
+# below (local-file uploads, dispatched by extension, also covers Sheets/Slides
+# targets) and upload_file's convert_to_doc param (raw text/markdown/html content,
+# always targets a Doc since it has no extension to dispatch on). Shared here as
+# the single source of truth for the literal so the two can't drift apart on it —
+# see upload_file's own convert_to_doc branch for the other call site (#412).
+_GOOGLE_DOC_MIME = "application/vnd.google-apps.document"
+
 # extension -> (source mimeType to upload as, target Google Workspace mimeType to
 # request via Drive's native import conversion). Distinct from _EXPORT_MIME above,
 # which maps the other direction (Google type -> downloadable export format).
@@ -60,11 +70,11 @@ _CONVERT_MIME: dict[str, tuple[str, str]] = {
     ),
     ".docx": (
         "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-        "application/vnd.google-apps.document",
+        _GOOGLE_DOC_MIME,
     ),
-    ".md": ("text/markdown", "application/vnd.google-apps.document"),
-    ".html": ("text/html", "application/vnd.google-apps.document"),
-    ".htm": ("text/html", "application/vnd.google-apps.document"),
+    ".md": ("text/markdown", _GOOGLE_DOC_MIME),
+    ".html": ("text/html", _GOOGLE_DOC_MIME),
+    ".htm": ("text/html", _GOOGLE_DOC_MIME),
     ".pptx": (
         "application/vnd.openxmlformats-officedocument.presentationml.presentation",
         "application/vnd.google-apps.presentation",
@@ -88,7 +98,10 @@ async def _upload_local_file(
     DOCX/MD/HTML -> Docs, PPTX -> Slides) by uploading with the source format's
     mimeType while setting the destination file's mimeType to the target Google
     Workspace type — this is distinct from create_doc_from_file, which parses the
-    file locally and rebuilds it via Docs API requests instead of Drive's importer."""
+    file locally and rebuilds it via Docs API requests instead of Drive's importer.
+    upload_file's convert_to_doc param implements the identical trick for raw
+    text/markdown/html content instead of a local file — see _GOOGLE_DOC_MIME
+    above, shared by both so they can't drift apart on the target mimeType (#412)."""
     path = Path(local_path)
     if not path.is_file():
         raise ValueError(f"No file found at {local_path!r}")
@@ -1212,7 +1225,10 @@ def register(tool):
             convert_to_doc: If True, create a Google Doc instead of a raw file.
                             'markdown' and 'html' sources retain heading, list, and link
                             formatting via Drive's HTML import. 'text' uploads as plain text
-                            and Drive converts it (no formatting preserved).
+                            and Drive converts it (no formatting preserved). Uses the same
+                            Drive native-import-conversion trick as upload_local_file's
+                            convert param, simplified to always target a Doc since this
+                            tool has no file extension to dispatch Sheets/Slides on.
 
         Returns:
             fileId, name, parent folder ID, and webViewLink of the created file.
@@ -1245,7 +1261,13 @@ def register(tool):
             file_body["parents"] = [target_folder_id]
 
         if convert_to_doc:
-            file_body["mimeType"] = "application/vnd.google-apps.document"
+            # Same Drive native-import-conversion trick as _upload_local_file's
+            # convert/_CONVERT_MIME path above (upload with the source mimeType,
+            # override the destination mimeType to request conversion) — simpler
+            # here since this tool only ever targets a Doc, never Sheets/Slides.
+            # Shares _GOOGLE_DOC_MIME as the single source of truth for that
+            # value so the two mechanisms can't drift apart on it (#412).
+            file_body["mimeType"] = _GOOGLE_DOC_MIME
 
         media = MediaInMemoryUpload(upload_content, mimetype=upload_mime, resumable=False)
         try: