mcp-gee-sweet 0.9.2.dev310__tar.gz → 0.9.2.dev313__tar.gz

{mcp_gee_sweet-0.9.2.dev310 → mcp_gee_sweet-0.9.2.dev313}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-gee-sweet
-Version: 0.9.2.dev310
+Version: 0.9.2.dev313
 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.dev313/docs/design/doc-revision-export.md

@@ -0,0 +1,126 @@
+# Design: Google Doc Revisions as Markdown (`export_revision`)
+
+**Status:** Implemented. Issue #959. Live-verified against real Drive/Docs API calls via scratch
+scripts per `CLAUDE.md`'s "Verify a ticket's API premise live" convention (2026-10-11).
+
+## Problem
+
+`export_revision` handled only Sheets (XLSX export → cell values). `list_revisions` already
+listed Doc revisions, but nothing could read one, so "what changed in this Doc since revision N"
+couldn't be answered through the server. The issue asked for a Doc revision as Markdown "through
+the same converter `get_doc_as_markdown` uses", so that diffing two revisions' exports shows only
+the edit.
+
+## The constraint
+
+`get_doc_as_markdown` walks `documents().get()` into the AST (`doc-to-markdown.md`). The Docs API
+reads only a document's **current** state; it has no revision parameter. Drive is the only source
+of an old revision, and only as a file from the revision's `exportLinks`. Measured on a Doc
+revision: `text/markdown`, `text/x-markdown`, `text/html`, `text/plain`, DOCX, ODT, RTF, PDF, EPUB,
+and a zipped HTML.
+
+## Options measured
+
+Each option was run against the same Doc, written through `write_doc_content` with headings, bold
+and italic, inline code, a fenced code block, a blockquote, nested ordered/bulleted lists, task
+items, a table, an image, and heading links.
+
+1. **Drive's own `text/markdown` export.** Lossy: inline code became plain text, the fenced code
+   block became soft-broken plain lines, the blockquote became a plain paragraph, a nested bullet
+   inside a numbered list became a separate numbered item with a literal `\-`, and the image was
+   inlined as a base64 `data:` URI (10KB for one small logo). It's a different dialect from
+   `get_doc_as_markdown`, and a much less faithful one.
+2. **`text/html` export → this project's `html_parser` → AST.** Google's export carries styling in
+   CSS classes (`.c3{font-weight:700}`), which `html_parser` doesn't read, so bold, italic and code
+   fonts would be lost without a CSS resolver. Importing that HTML back into a Doc (to reuse the
+   Docs-side converter) was also measured: it split the code block into one fence per line and
+   turned every list item after the blockquote into a quote.
+3. **DOCX export → import as a temporary Google Doc → `document_to_ast` → `ast_to_markdown`.**
+   The output was **identical** to `get_doc_as_markdown` on the live Doc, except for the two
+   import-specific values below. The zipped-HTML export can't be imported (400).
+
+**Chosen: (3).** It is the same converter, not an equivalent one, so everything
+`get_doc_as_markdown` supports and documents carries over unchanged.
+
+## What differs on every import, and how it's made stable
+
+Measured across two imports of the same DOCX:
+
+- **Inline image `contentUri`.** A new URL each import; the image bytes are identical (same
+  SHA-256). `_stabilize_images` fetches each image (concurrency 8) while the temporary Doc still
+  exists and replaces its `contentUri` with `image:sha256-<first 16 hex digits>`, so an unchanged
+  image doesn't show in a diff and a changed one does. A failed fetch renders
+  `image:unavailable`. No viewable URL is returned: PR #988's QA round found the temporary Doc's
+  image URLs 404 (anonymously and authenticated) once it's deleted, so a returned URL would be
+  dead on arrival. (One earlier probe got a 200 right after deletion; it doesn't hold.)
+- **Heading IDs and the document ID.** Every heading gets a new `headingId`, and
+  `doc_to_ast._link_url` rebuilds an ID-only heading link (the kind the Docs UI creates) as a URL
+  containing the temporary Doc's ID. That changes on every export and points at a deleted Doc.
+  `_stabilize_internal_links` rewrites a heading link to `#<slug>`, using anchors.py's GitHub-style
+  slug with `-1`/`-2` duplicate suffixes, so the link survives a round trip through the write
+  side's anchor resolver. The slug list holds only paragraphs that render as Markdown headings,
+  classified by `doc_to_ast._paragraph_to_node` itself (`Heading`, or a TITLE/SUBTITLE
+  `NamedBlock`): a bulleted heading renders as a list item and a heading in a table cell as cell
+  text, and counting them shifted every later duplicate's suffix onto the wrong heading (PR #988
+  QA round 1). A link to a heading that doesn't render as one is dropped, following the project's
+  rule that a wrong link is worse than none.
+- **Bookmark links are dropped.** A bookmark has no text to name it, and any `#fragment` made up
+  for one can be fuzzy-matched by `anchors.py` to a heading when the Markdown is written back
+  (`#bookmark-1` → the second heading titled "Bookmark"; PR #988 QA round 1).
+- URL links written by this project's own write side are already absolute URLs and pass through
+  unchanged.
+
+## The temporary Doc
+
+- Created in the default folder (`lc.folder_id`), like every other create path, so a service
+  account works when a Shared Drive is configured. A storageQuotaExceeded error renders with the
+  shared `_SA_QUOTA_ERROR` text. Who can see it there, and its 30 days in the trash when the
+  identity can only trash, is tracked in #989.
+- Uploaded resumable: Drive takes a multipart upload only up to 5 MB, and a revision with
+  embedded images can exceed it.
+- Named `export_revision temp (<file_id> r<revision_id>)`, so an orphan is identifiable.
+- Created inside `anyio.CancelScope(shield=True)`, per `CLAUDE.md`'s cancellation rule: a
+  cancellation can't land after Drive created the Doc but before its ID is recorded.
+- Removed in a shielded `finally`: deleted when `capabilities.canDelete` allows it, else trashed
+  (a Content manager on a Shared Drive can only trash, #876). The removal retries a 5xx or 429
+  (`num_retries=3`), since a failed removal leaves a copy of the revision in Drive. A failed removal
+  never hides the export: the result gets a `warning` naming the Doc's ID.
+- Because it writes to Drive, `export_revision` is no longer annotated `readOnlyHint`; it's
+  `destructiveHint=False`, since it changes nothing of the caller's.
+- About 5–6 seconds per call, measured, on top of the image fetches.
+
+## Errors found while measuring
+
+- The export endpoint answers rapid calls with HTTP 429 and an HTML page, without raising. The
+  Sheets path handed that page straight to openpyxl. `_fetch_revision_export` checks the status
+  for both paths.
+- Docs folds the latest revision into the next one while editing continues: revision 18 was
+  listed, an edit 90 seconds later produced 19, and 18 then returned 404. A second run with a
+  5-minute gap merged 19 into 20 the same way. `export_revision` turns a "Revision not found" 404
+  into an error telling the caller to call `list_revisions` again. Any other 404, such as a bad
+  file ID ("File not found"), is re-raised unchanged. A Doc created by Drive import keeps its
+  import revision separate (as #814 measured).
+- `revisions.list` returns at most 200 revisions per page by default (discovery document), and
+  `list_revisions` read only the first page. It now pages through every revision via the same
+  `_list_revisions` helper `sync_folder` uses.
+- A Doc `local_path` is checked with `_validate_local_destination` before the export, so a bad
+  destination fails before the temporary Doc round trip.
+
+## Live verification
+
+Against a Doc imported through `upload_file(convert_to_doc=True)`, then edited by inserting one
+word: exporting revision 1 (the import) and revision 2 and diffing the two `markdown` values gave
+exactly one changed line, the edited paragraph. On a `write_doc_content` Doc with every construct
+above plus two `Setup` headings linked by ID, the export matched `get_doc_as_markdown` except the
+image line and the two links (`#setup`, `#setup-1`). With the first `Setup` bulleted, it rendered
+as `- Setup`, the link to it was dropped, and the link to the second rendered as `#setup`.
+
+## What this does NOT do
+
+- **Comments.** They aren't part of a revision, so there's no `include_comments`.
+- **Match `get_doc_as_markdown` byte for byte.** Heading links and images differ by design (above).
+  Diff a revision against another revision's export, not against the live Doc's
+  `get_doc_as_markdown`.
+- **Show an old revision's images.** Only their hashes; see above.
+- **Multi-tab documents: not measured.** How Drive's DOCX export handles a Doc's extra tabs
+  wasn't checked; `document_to_ast` reads only the imported Doc's body.

{mcp_gee_sweet-0.9.2.dev310 → mcp_gee_sweet-0.9.2.dev313}/docs/design/index.md

@@ -15,3 +15,4 @@ These are more granular than the [decision records](../decisions/index.md), whic
 | [SSE OAuth Consent Off the Event Loop](sse-consent-off-event-loop.md) | 2026-10-01 | #833: the SSE consent wait on a daemon thread with a stoppable callback server, shared across connections, ended by sse_starlette's shutdown flag on SIGTERM |
 | [Re-authorizing OAuth from the Failing Tool Call](oauth-reauthorize-from-tool-call.md) | 2026-10-06 | #873/#906: a revoked or missing token offers the consent link from the failing call (URL elicitation, or the link in the `ToolError`), detected at `thread_http`'s transport so tools that catch errors are covered, adopted in place on every connection |
 | [Local-File Access Policy](local-file-access-policy.md) | 2026-10-10 | #796: `LOCAL_FILE_ACCESS=full\|roots\|off` resolved at import from argv (plus an HTTP-request tripwire for launches argv can't see), one `check_read`/`check_write` at each choke point and per entry in folder walks, an identity-based (`samefile`) deny-list of the server's own credential/config/cache/log files, `@tool(local_only=True)` unregistering nine tools in `off` mode, mode and roots reported in `server://auth-status` and the refusal |
+| [Google Doc Revisions as Markdown](doc-revision-export.md) | 2026-10-11 | #959: `export_revision` on a Doc via DOCX export → temporary Doc → `get_doc_as_markdown`'s own converter (Drive's Markdown and HTML exports measured lossy), heading links and image URLs rewritten so two exports diff cleanly, shielded temp-Doc cleanup |

{mcp_gee_sweet-0.9.2.dev310 → mcp_gee_sweet-0.9.2.dev313}/docs/known-limitations.md

@@ -120,6 +120,37 @@ raw Docs API via `batch_update` passthrough) instead. Related: docs/design/doc-t
 
 ---
 
+### `export_revision` on a Google Doc — links, images, and vanishing revision IDs
+
+**What:** `export_revision` (#959) returns a Doc revision as Markdown through the same converter
+as `get_doc_as_markdown`, with these differences and gaps:
+
+1. A link to a heading renders as a GitHub-style `#slug` anchor, not as a docs.google.com URL.
+   A link to a bookmark, or to a heading that doesn't render as one (a bulleted heading, or one
+   in a table cell), is dropped and leaves its text. An image renders as
+   `image:sha256-<hash>`, with no viewable URL: the temporary Doc's image URLs stop working
+   once it's deleted, so an old revision's images can't be viewed this way.
+2. The export doesn't include comments, which aren't part of a revision.
+3. A revision ID from `list_revisions` can stop existing: Docs folds a recent revision into the
+   next one while editing continues (measured: edits 90 seconds and 5 minutes later both merged it).
+   The export then fails with an error saying to list revisions again.
+4. Each call creates and removes a temporary Google Doc in the default folder, which takes
+   several seconds and needs storage there (a service account needs a Shared Drive default
+   folder). If removal fails, the result's `warning` names the Doc to delete by hand.
+
+**Why:** The Docs API reads only a document's current state, so the revision is exported as DOCX
+and imported into a temporary Doc to be read. That Doc's ID, heading IDs, and image URLs are new
+on every import, so (1) replaces them with values that stay the same between exports and keep
+diffs clean. A bookmark has no text to make a stable anchor from, and an invented one could be
+matched to the wrong heading if the Markdown is written back. (3) is how Drive keeps Docs
+revision history.
+
+**Workaround:** For (1), diff one revision's export against another's, not against
+`get_doc_as_markdown` output. For (3), export a revision only after editing has settled.
+Related: docs/design/doc-revision-export.md.
+
+---
+
 ## Google Drive
 
 ### Service account cannot create files in personal Drive

{mcp_gee_sweet-0.9.2.dev310 → mcp_gee_sweet-0.9.2.dev313}/docs/qa/tests/drive_transfer.md

@@ -1933,11 +1933,202 @@ export_revision(rev 6, no range) → sheet="Sheet1", range=null, values = full 5
 - Returns a clear error: "No XLSX export available for this revision"
 - Does not crash
 
+**Superseded by #959:** a Google Doc revision now exports as Markdown (TC-D280), so this case
+checks a file that is neither a Sheet nor a Doc. Run it as:
+
+**Setup:** Create a scratch Google Slides file named `qa-959-slides` in `DRIVE_FOLDER_ID`, and
+type one word on its first slide in the Slides UI (Playwright) so it has a revision.
+
+**Tool calls**
+1. `list_revisions(file_id="<slides-id>")`, then
+   `export_revision(file_id="<slides-id>", revision_id="<last revisionId>")`
+
+**Checks**
+- Raises a clear error: "No XLSX or DOCX export available for revision <id>. export_revision
+  supports Google Sheets and Google Docs files only."
+- Does not crash
+
+**Teardown:** `delete_file(file_id="<slides-id>")`.
+
+The 2026-09-04 Result below predates #959 and tested a Google Doc.
+
+**Result (2026-10-11, PR #988 round 1, `8b223c5`) ✅ PASS** — Ran via `mcp-gee-sweet-kit` (OAuth). The Slides file was created blank by a scratch-script `files().create(mimeType=presentation)` rather than through the Slides UI; `list_revisions` still listed revision 1. `export_revision` raised exactly "No XLSX or DOCX export available for revision 1. export_revision supports Google Sheets and Google Docs files only." Slides file trashed.
+
 **Result (2026-09-04) ✅ PASS**
 export_revision({DOC_ID}, rev 3) → error "No XLSX export available for revision 3. The file may not be a Google Sheets file." Clear error, no crash.
 
 ---
 
+### TC-D280: Export two Google Doc revisions as Markdown; the diff shows only the edit (issue #959) ⚠️ requires-oauth
+
+**Background:** The Docs API can't read an old revision, so `export_revision` exports it as DOCX,
+imports that into a temporary Doc, and converts it with `get_doc_as_markdown`'s own converter.
+Docs folds the latest revision into the next one while editing continues: during #959, edits 90
+seconds and 5 minutes later both merged it. A Doc created by Drive import keeps its import
+revision separate (#814), so the diff below uses one.
+
+**Setup**
+1. `create_doc(title="qa-959-rev", content_format="markdown", content=<below>)` with:
+   ````
+   # Release Notes
+
+   Intro with **bold**, *italic*, `inline code`, and [external](https://example.com).
+
+   ## Setup
+
+   ```
+   pip install thing
+   thing --init
+   ```
+
+   > A quoted note.
+
+   1. First step
+   2. Second step
+
+   - [ ] open task
+   - [x] done task
+
+   | Key | Value |
+   |-----|-------|
+   | a   | 1     |
+
+   ![logo](https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png)
+   ````
+   Then `list_revisions(file_id="<rev-id>")` and take the last `revisionId` as R.
+2. `upload_file(name="qa-959-diff.md", source_format="markdown", convert_to_doc=True,
+   content="# Notes\n\nIntro with **bold** text.\n\n## Next\n\nClosing paragraph.\n")`.
+   Then `find_in_doc(doc_id="<diff-id>", query="Intro with")` and
+   `insert_doc_text(doc_id="<diff-id>", insertions=[{"index": <start_index + 6>, "text": "EDITED "}])`.
+3. Wait about a minute, then `list_revisions(file_id="<diff-id>")`: A is the first revision
+   (the import), B the last. If only one revision is listed, wait another minute and re-list.
+
+**Tool calls**
+1. `export_revision(file_id="<rev-id>", revision_id="<R>")`
+2. `get_doc_as_markdown(doc_id="<rev-id>")`
+3. `export_revision(file_id="<diff-id>", revision_id="<A>")`
+4. `export_revision(file_id="<diff-id>", revision_id="<B>")`
+5. `search_files(query="export_revision temp")`
+
+**Checks**
+- Call 1's `markdown` has the heading, bold/italic, `` `inline code` ``, a fenced code block, a
+  `> ` blockquote, the numbered list, both task items, the table, and the image as
+  `![](image:sha256-<16 hex>)`. The result has no `images` key: the temporary Doc's image URLs
+  stop serving once it's deleted, so none is returned (PR #988 round 1).
+- Call 2's `markdown` equals call 1's except the image line (call 2 has a URL).
+- Diffing call 3's `markdown` against call 4's shows exactly one changed line: `Intro with` →
+  `Intro EDITED with`.
+- Call 5 returns no temporary Doc for `<rev-id>` or `<diff-id>`: each was removed. `search_files`
+  also lists trashed files, so a hit from an earlier run is fine if `get_file_metadata` shows
+  `trashed: true`.
+
+**Teardown:** `delete_file` on both `<rev-id>` and `<diff-id>`.
+
+**Result (2026-10-11, PR #988 round 1, `8b223c5`) ❌ FAIL (sent back)** — Ran via `mcp-gee-sweet-kit` (OAuth). `qa-959-rev` listed revisions 1 and 5; R=5. `qa-959-diff.md` listed revisions 1 and 2 about 10 seconds after the edit (no wait needed). Call 1's `markdown` had every listed construct and the image as `![](image:sha256-9237fdb37f9592f6)`. Call 2's `markdown` matched it byte for byte except the image line. Calls 3 and 4 differed in exactly one line, `Intro with` → `Intro EDITED with`. Call 5 returned `[]`. **Failed check:** the `images[0].url` from call 1 returned **HTTP 404** both to an anonymous `curl` and to an OAuth-authenticated `AuthorizedSession.get`, while the live Doc's own image URL from call 2 returned 200 `image/png` anonymously. A repeat export, fetched within seconds of the call returning, also returned 404. The temporary Doc's `contentUri` stops serving once that Doc is deleted, so every `images` URL is already dead when the tool returns (contradicts `docs/design/doc-revision-export.md`'s "the URL still serves after the temporary Doc is deleted"). Both Docs trashed.
+
+**Result (2026-10-11, PR #988 round 2, `15d778d`) ✅ PASS** — Ran via `mcp-gee-sweet-kit` (OAuth). `qa-959-rev` listed revisions 1 and 5; R=5. `qa-959-diff.md` listed 1 and 2 about 10 seconds after the edit. Call 1 returned `revisionId`, `modifiedTime`, `markdown` and no `images` key; `markdown` had every listed construct and the image as `![](image:sha256-9237fdb37f9592f6)` (same hash as round 1). Call 2 matched call 1 byte for byte except the image line. Calls 3 and 4 differed in exactly one line, `Intro with` → `Intro EDITED with`. Call 5 listed no temporary Doc from this pass; its one hit was a temporary Doc from the Dev's 15:15 probe of another Doc, already `trashed: true` (the trash branch working; `search_files` lists trashed files, so the check now says so). Both Docs trashed.
+
+---
+
+### TC-D281: Doc revision heading links render as `#slug` and stay stable (issue #959) ⚠️ requires-oauth
+
+**Setup**
+1. `create_doc(title="qa-959-links", content_format="markdown", content="# Top\n\n## Setup\n\nFirst.\n\n## Setup\n\nJump here and back here.\n")`
+2. Link text to the headings by ID, the way the Docs UI does. No tool sets an ID-only link
+   (`style_doc_range`'s `link_url` sets a URL), so use the Docs UI in Playwright (select "Jump",
+   Insert link → Headings → the first `Setup`; "back" → the second `Setup`), or a scratch script
+   per `CLAUDE.md`'s "MCP restart" note sending `updateTextStyle` with
+   `textStyle: {"link": {"headingId": "<id>"}}`. `get_doc_structure(doc_id="<id>")` gives both
+   headings' `headingId`s.
+3. `list_revisions(file_id="<id>")` and take the last `revisionId`.
+4. Make a second Doc, `qa-959-bullet`, the same way (steps 1–2), then turn its first `## Setup`
+   into a bulleted list item: `create_paragraph_bullets` over that heading's range (indices from
+   `get_doc_structure`). `list_revisions` on it and take the last `revisionId`.
+
+**Tool calls**
+1. `export_revision(file_id="<id>", revision_id="<last>")`
+2. The same call again.
+3. `export_revision(file_id="<bullet-id>", revision_id="<bullet last>")`
+
+**Checks**
+- Call 1's `markdown` contains `[Jump](#setup)` and `[back](#setup-1)`, and no
+  `docs.google.com` URL.
+- Call 2's `markdown` is identical to call 1's.
+- Call 3's `markdown` renders the first `Setup` as a list item (`- Setup`), leaves "Jump" as
+  plain text (its target doesn't render as a heading), and contains `[back](#setup)`: the
+  bulleted heading takes no slug (PR #988 round 1).
+
+**Teardown:** `delete_file` on both Docs.
+
+**Result (2026-10-11, PR #988 round 1, `8b223c5`) ✅ PASS** — Ran via `mcp-gee-sweet-kit` (OAuth). Links set by a scratch script (`updateTextStyle` with `link: {headingId}`). Revision 4: both calls returned `[Jump](#setup) here and [back](#setup-1) here.` with no `docs.google.com` URL, byte-identical. **Extra probe (sent back as a review finding):** a second Doc with the first `## Setup` turned into a bulleted list item (`createParagraphBullets`) and the same two links exported as `- Setup\n\n## Setup\n\n[Jump](#setup) here and [back](#setup-1) here.` The bulleted heading renders as a list item, not a heading, but still takes a slug. `#setup` now names the wrong heading and `#setup-1` names none. Both Docs trashed.
+
+**Result (2026-10-11, PR #988 round 2, `15d778d`) ✅ PASS** — Ran via `mcp-gee-sweet-kit` (OAuth). Links set by a scratch script (`updateTextStyle` with `link: {headingId}`). Calls 1 and 2 (revision 4) both returned `[Jump](#setup) here and [back](#setup-1) here.`, byte-identical, no `docs.google.com` URL. Call 3 (`qa-959-bullet`, revision 5) returned `# Top\n\n- Setup\n\nFirst.\n\n## Setup\n\nJump here and [back](#setup) here.`: the bulleted heading takes no slug and the link to it is dropped. **Extra probe:** a Doc with `## Setup`, then a table whose first cell is a HEADING_2 `Setup`, then a second body `## Setup`; "Jump" linked to the last body heading and "here" to the cell heading. The export was `[Jump](#setup-1) here.`: the cell heading is skipped when counting duplicates (it was `#setup-2` before the fix), and the link to it is dropped. All three Docs trashed.
+
+---
+
+### TC-D282: Doc revision `local_path`, and arguments that don't apply to the file's type (issue #959) ⚠️ local-filesystem ⚠️ requires-oauth
+
+**Setup:** `mkdir -p /tmp/qa-959` (the directory must exist: a `local_path` naming a missing
+directory, even with a trailing `/`, is written as a file of that name).
+`create_doc(title="qa-959-args", content="<p>Saved to disk</p>")`, then
+`list_revisions` on it and on `TEST_SPREADSHEET_ID`, taking each one's last `revisionId`.
+
+**Tool calls**
+1. `export_revision(file_id="<doc-id>", revision_id="<doc rev>", local_path="/tmp/qa-959/")`
+2. `export_revision(file_id="<doc-id>", revision_id="<doc rev>", range="A1:B2")`
+3. `export_revision(file_id="<TEST_SPREADSHEET_ID>", revision_id="<sheet rev>", local_path="/tmp/qa-959/")`
+4. `export_revision(file_id="<TEST_SPREADSHEET_ID>", revision_id="<sheet rev>", range="A1:B2")`
+5. `export_revision(file_id="<doc-id>", revision_id="999999")`
+6. `export_revision(file_id="<doc-id>_WRONG", revision_id="<doc rev>")`
+7. `export_revision(file_id="<doc-id>", revision_id="<doc rev>", local_path="/etc/hosts/x.md")`,
+   then `search_files(query="export_revision temp")`
+
+**Checks**
+- Call 1 returns `local_path` ending `/tmp/qa-959/<doc-id>-r<doc rev>.md`, `bytes_written`,
+  `revisionId`, `modifiedTime`, and no `markdown` or `images`. The file holds raw Markdown
+  (`Saved to disk`), not JSON.
+- Call 2 raises "…is a Google Doc; range and sheet apply only to Google Sheets."
+- Call 3 raises "…is a Google Sheet; local_path applies only to Google Docs."
+- Call 4 returns `sheet`, `range`, and `values` exactly as before #959.
+- Call 5 raises "Revision 999999 of <doc-id> not found…call list_revisions again…".
+- Call 6 raises Drive's own 404 ("File not found: <doc-id>_WRONG"), not the merged-revision
+  message (PR #988 round 1).
+- Call 7 raises "local_path '/etc/hosts/x.md' has a non-directory path component at
+  '/etc/hosts'", and `search_files` finds no temporary Doc for `<doc-id>`: the destination is checked
+  before the export (PR #988 round 1).
+
+**Teardown:** remove `/tmp/qa-959/`; `delete_file(file_id="<doc-id>")`.
+
+**Result (2026-10-11, PR #988 round 1, `8b223c5`) ✅ PASS** — Ran via `mcp-gee-sweet-kit` (OAuth). The first attempt at call 1 ran without `/tmp/qa-959` existing and wrote a 15-byte *file* named `/tmp/qa-959` (`local_path: "/tmp/qa-959"`); that comes from the shared `write_capped_result_to_disk`, which this PR doesn't touch, so it's ticketed separately and the setup now creates the directory. Rerun with the directory present: call 1 returned `local_path` `/tmp/qa-959/<doc-id>-r3.md`, `bytes_written: 15`, `revisionId`, `modifiedTime`, `images: []`, no `markdown`; the file held `Saved to disk\n\n`, raw Markdown. Calls 2, 3, and 5 raised the expected messages. Call 4 returned `sheet: "Sales"`, `range: "A1:B2"`, `values: [["Product", null], ["Widget", 100]]`. **Extra probe (sent back as a review finding):** `file_id="<doc-id>_WRONG"` raised the same "Revision 3 of … not found. Drive merges a recent revision…" message, misdiagnosing a bad file ID as a merged revision.
+
+**Result (2026-10-11, PR #988 round 2, `15d778d`) ✅ PASS** — Ran via `mcp-gee-sweet-kit` (OAuth), `/tmp/qa-959` created first. Call 1 returned `local_path` `/tmp/qa-959/<doc-id>-r3.md`, `bytes_written: 15`, `revisionId`, `modifiedTime`, and no `markdown` or `images`; the file held `Saved to disk\n\n`. Calls 2, 3, and 5 raised the expected messages. Call 4 returned `sheet: "Sales"`, `range: "A1:B2"`, `values: [["Product", null], ["Widget", 100]]` (revision 342). Call 6 raised Drive's own `HttpError 404 … "File not found: <doc-id>_WRONG."`, not the merged-revision message. Call 7 raised `local_path '/etc/hosts/x.md' has a non-directory path component at '/etc/hosts'`, and `search_files` found no temporary Doc for `<doc-id>` (only the earlier trashed one noted in TC-D280). Doc trashed, `/tmp/qa-959` removed.
+
+---
+
+### TC-D283: A service account (Content manager) exports a Doc revision; the temporary Doc is trashed (issue #959)
+
+**Background:** A Content manager on a Shared Drive can trash but not permanently delete (#876),
+so the temporary Doc is trashed instead. Use the `mcp-gee-sweet-sa` server, whose default folder
+is the Shared Drive.
+
+**Setup:** On the SA server, `create_doc(title="qa-959-sa", content="<p>SA revision</p>")`, then
+`list_revisions(file_id="<id>")` and take the last `revisionId`.
+
+**Tool calls**
+1. `export_revision(file_id="<id>", revision_id="<last>")` on the SA server
+2. `search_files(query="export_revision temp")` on the SA server
+
+**Checks**
+- Call 1 returns `markdown` containing `SA revision` and no `warning`.
+- Call 2 finds no live file. If the client can show trashed files, the temporary Doc is in the
+  Shared Drive's trash.
+
+**Teardown:** `delete_file(file_id="<id>")` on the SA server.
+
+**Result (2026-10-11, PR #988 round 1, `8b223c5`) ⏭️ SKIP** — Not run: a lane QA session may call only its own `mcp-gee-sweet-kit` server, and the case needs `mcp-gee-sweet-sa`. Pending for a release pass (Aziz may use the `-sa` slot). The trash branch is unit-tested only so far.
+
+---
+
 ### TC-D256: `download_folder`'s `progress_unit='bytes'` feeds byte totals into the structured progress fields, with a file-count fallback when sizes aren't fully known (issue #741) ⚠️ local-filesystem
 
 **Background:** TC-D255 (#352) confirmed the message text carries bytes-transferred-so-far as supplementary context, but the structured `progress`/`total` fields passed to `ctx.report_progress()` stayed file-count-based unconditionally — a client rendering a progress bar from those fields alone (not parsing message text) sees the same one-tick-per-file granularity regardless of individual file size. #741's maintainer decision: keep file-count as the default (`progress_unit='files'`), but add an opt-in `progress_unit='bytes'` so a caller can request byte-based structured fields when every candidate's size is known upfront (same `bytes_total_known` gate TC-D255's message-fallback logic already uses) — falling back to file-count when it isn't, since there's no reliable byte total to report against then. `sync_folder` is explicitly out of scope for this decision (recursive descent never has a full upfront size list). Unit-tested deterministically against a mocked `ctx` in `tests/drive/test_transfer.py::TestDownloadFolder::test_progress_unit_bytes_reports_byte_totals_when_sizes_known`/`test_progress_unit_bytes_falls_back_to_files_when_sizes_unknown`; this live check confirms both branches against a real API call.

{mcp_gee_sweet-0.9.2.dev310 → mcp_gee_sweet-0.9.2.dev313}/docs/roadmap.md

@@ -222,9 +222,11 @@ Same shape as v0.8.1 — stabilize on defects that surfaced since v0.9.0 shipped
 - [x] `get_doc_as_markdown`: plain text ending in `!` right before a linked run exports as `![…](…)`, which renders as an image. Affects every link, not just code; fix belongs in `_escape`'s cross-run handling. Found in PR #968 — lane B, after #951 (same file), ahead of #958 (PR #981) ([#969](https://github.com/khuisman/mcp-gee-sweet/issues/969))
 - [x] `get_doc_as_markdown(local_path=…)` writes the JSON result envelope, not the markdown: `markdown_export.py` routes through the generic JSON-to-disk helper — lane B, after #938 (same read-side area) (PR #982) ([#958](https://github.com/khuisman/mcp-gee-sweet/issues/958))
 - [x] `add_chart`: a cell-to-row (`B2:5`) or row-only (`1:5`) range silently charts one column — `_per_column_ranges` defaults `endColumnIndex` to start+1. Found reviewing #931 — lane A, after #917 (PR #983) ([#954](https://github.com/khuisman/mcp-gee-sweet/issues/954))
-- [ ] `_parse_a1_notation` hardening: one compiled grammar, index bounds, validate before the sheet-ID fetch. #931 review follow-ups, no behavior change for valid input — lane A, after #954 (same A1 area); its QA also runs #953's live checks for #931 (folded in) ([#955](https://github.com/khuisman/mcp-gee-sweet/issues/955))
+- [x] `_parse_a1_notation` hardening: one compiled grammar, index bounds, validate before the sheet-ID fetch. #931 review follow-ups, no behavior change for valid input — lane A, after #954 (same A1 area); its QA also runs #953's live checks for #931 (folded in) (PR #986) ([#955](https://github.com/khuisman/mcp-gee-sweet/issues/955))
 - [ ] Write side drops image links: `[![alt](src)](url)` (or `<a href><img></a>`) imports through `create_doc`/`create_doc_from_file`/`write_doc_content` without its URL, so it doesn't round-trip with #951's export. Found in PR #976 — lane A, after #955 ([#977](https://github.com/khuisman/mcp-gee-sweet/issues/977))
+- [ ] `_parse_a1_notation` rejects `A:B5`, which the Sheets values API accepts as `A5:B` — decided 2026-10-11: keep rejecting (a destructive GridRange tool acting on "row 5 onward" is worse than an error); document in the docstring that this is deliberately stricter than Sheets. Found in PR #986 — lane A, after #977 ([#987](https://github.com/khuisman/mcp-gee-sweet/issues/987))
 - [ ] Comment quoted text comes back HTML-escaped (`Caf&#233;`) from `add_doc_comment`, `list_doc_comments`, and `get_doc_as_markdown(include_comments=True)`: `comments.py` passes Drive's escaped `quotedFileContent.value` through unchanged. Found reviewing #958 — lane B, after #959 (defect, next pick) ([#984](https://github.com/khuisman/mcp-gee-sweet/issues/984))
+- [ ] `write_capped_result_to_disk` writes `dir/` as a file when the directory doesn't exist: a trailing separator should mean "directory" (create it, append `default_filename`). Shared by every `local_path` writer. Found in PR #988 — lane B, after #984 (defect) ([#990](https://github.com/khuisman/mcp-gee-sweet/issues/990))
 
 **Sheets hardening** _(triaged out of `backlog` 2026-09-11 — see the "Backlog triage" note below)_
 - [x] `update_sheet_properties`/dimension-tool hardening + dedup follow-ups from PR #321's review ([#323](https://github.com/khuisman/mcp-gee-sweet/issues/323)) (PR #734)
@@ -251,6 +253,7 @@ Same shape as v0.8.1 — stabilize on defects that surfaced since v0.9.0 shipped
 - [ ] `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))
 - [ ] `update_doc_from_file`: opt-in incremental (`mode="patch"`) update that diffs block by block and rewrites only changed blocks, so comment anchors and revision history survive — lane A, after #894 (same write-path files) ([#957](https://github.com/khuisman/mcp-gee-sweet/issues/957))
 - [ ] `export_revision`: support Google Docs revisions (returned as markdown), and fix `list_revisions`' docstring claim that native-file revisions are pruned after 30 days. Also what #878's recovery path points callers at — lane B, after #958 ([#959](https://github.com/khuisman/mcp-gee-sweet/issues/959))
+- [ ] `export_revision`'s temporary Doc exposes an old revision's content to the default folder's audience (a whole Shared Drive) — decided 2026-10-11: under OAuth create it in My Drive root; a service account keeps the default folder, and that remaining exposure goes in `docs/known-limitations.md`. Found in PR #988 — lane B, after #990 ([#989](https://github.com/khuisman/mcp-gee-sweet/issues/989))
 - [x] `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)) (PR #903)
 - [ ] **Bundle:** Docs image-share cancellation follow-ups (from PR #903), one PR closing [#904](https://github.com/khuisman/mcp-gee-sweet/issues/904), [#907](https://github.com/khuisman/mcp-gee-sweet/issues/907), [#908](https://github.com/khuisman/mcp-gee-sweet/issues/908), [#666](https://github.com/khuisman/mcp-gee-sweet/issues/666) — lane A ([#909](https://github.com/khuisman/mcp-gee-sweet/issues/909))
 - [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)

{mcp_gee_sweet-0.9.2.dev310 → mcp_gee_sweet-0.9.2.dev313}/docs/tools.md

@@ -94,7 +94,7 @@
 |---|---|---|
 | `export_file` | Export or download a file from Google Drive. | `file_id`, `export_format` |
 | `list_revisions` | List available revisions for a Google Drive file (Sheets, Docs, or any file). | `file_id` |
-| `export_revision` | Export a historical revision of a Google Sheets file and return its cell data. | `file_id`, `revision_id`, `range?`, `sheet?` |
+| `export_revision` | Export a historical revision of a Google Sheets file (cell data) or a Google Doc (Markdown). Use list_revisions to find the revision_id. | `file_id`, `revision_id`, `range?`, `sheet?`, `local_path?` |
 | `upload_file` | Upload a text file to Google Drive, optionally converting it to a Google Doc. | `name`, `content`, `source_format?`, `folder_id?`, `convert_to_doc?` |
 | `upload_local_file` | Upload a file from the local filesystem to a Google Drive folder. Handles binary and text files (images, PDFs, DOCX, XLSX, scripts, etc.). | `local_path`, `parent_folder_id`, `name?`, `skip_if_exists?`, `convert?` |
 | `upload_local_folder` | Upload all files in a local directory (non-recursive) to a Google Drive folder. | `local_path`, `parent_folder_id`, `skip_if_exists?`, `skip_system_files?`, `convert?` |