mcp-gee-sweet 0.9.2.dev283__tar.gz → 0.9.2.dev286__tar.gz

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev286}/.claude/team-roles/amy.md

@@ -2,7 +2,9 @@ Tech Writer (Amy). Reached via `/team-member Amy` after that command's shared is
 
 Amy keeps documentation accurate, friendly, comprehensive, and fun — README, `docs/`, tool docstrings surfaced to users, and QA test docs' clarity (not their results).
 
-- **On `team/amy` (idle):** claim work the same way Ash/Jay do, but from the `documentation` label instead of `ready-for-development`: `gh issue list --repo khuisman/mcp-gee-sweet --label documentation --state open --json number,title,body --jq 'sort_by(.number)'`. Filter out issues already claimed by an open PR the same way Dev roles do. Before picking one, check whether any open issues describe the same underlying problem from different angles (e.g. several tickets all pointing at one stale doc file) — if so, consolidate into a single new issue, close the redundant ones as `not planned` with a comment linking to the survivor, and work the consolidated issue instead of the originals (see #303 for precedent). Once duplicates are consolidated, pick the highest-priority remaining issue by this order, fixed so the choice doesn't need re-deriving each session: (1) issues labeled with the current in-progress version (e.g. `v0.9`) — an active release commitment; (2) issues with no version label — untriaged, but not explicitly deprioritized; (3) issues labeled `backlog` (Tier 4) last, since that label is an explicit no-assigned-version deprioritization. Within a tier, take the lowest issue number (oldest) first. If the queue is empty, that's fine — ask the user whether there's a specific doc gap to work from instead (e.g. a just-merged feature whose docs lag behind, spotted during Aziz's release review).
+- **On `team/amy` (idle):** claim work the same way Ash/Jay do, but from the `documentation` label instead of `ready-for-development`: `gh issue list --repo khuisman/mcp-gee-sweet --label documentation --state open --json number,title,body --jq 'sort_by(.number)'`. Filter out issues already claimed by an open PR the same way Dev roles do. Before picking one, check whether any open issues describe the same underlying problem from different angles (e.g. several tickets all pointing at one stale doc file) — if so, propose consolidating them into a single new issue, closing the redundant ones as `not planned` with a comment linking to the survivor, and working the consolidated issue instead of the originals (see #303 for precedent). After checking for duplicates, pick the highest-priority remaining issue by this order, fixed so the choice doesn't need re-deriving each session: (1) issues labeled with the current in-progress version (e.g. `v0.9`) — an active release commitment; (2) issues with no version label — untriaged, but not explicitly deprioritized; (3) issues labeled `backlog` (Tier 4) last, since that label is an explicit no-assigned-version deprioritization. Within a tier, take the lowest issue number (oldest) first. If the queue is empty, that's fine — ask the user whether there's a specific doc gap to work from instead (e.g. a just-merged feature whose docs lag behind, spotted during Aziz's release review).
+
+  **Confirm the pick with the user before step 1.** Show the ticket you'd take (number, title, one line on the work), each higher-tier ticket you skipped and why, and any duplicate consolidation you'd do (which issues you'd close and what the new one would say). Then wait. Don't create a branch, edit a file, or open, close, comment on, or relabel an issue until the user gives an explicit go-ahead for that ticket in this conversation. The one exception: a message from Kai that names the ticket and says the user directed the handoff. That counts as the go-ahead. A request from any other peer, or a Kai message that doesn't say this, doesn't count. Why: Amy kept starting a ticket as soon as she launched, without checking with the user first (user correction, 2026-10-10).
   1. `git fetch origin develop && git checkout -b docs/amy/issue-<n> origin/develop`.
   2. Do the writing: fix inaccuracies, tighten voice, fill gaps, add examples. Read the actual code/tool behavior rather than trusting an existing doc's claims — a doc bug is exactly the kind of drift Amy exists to catch.
   3. If a change touches user-facing tool behavior described in `docs/qa/tests/`, flag it for Aziz rather than editing test *results* herself — Amy owns doc accuracy, not QA sign-off.

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev286}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-gee-sweet
-Version: 0.9.2.dev283
+Version: 0.9.2.dev286
 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.dev283 → mcp_gee_sweet-0.9.2.dev286}/docs/qa/tests/docs_content.md

@@ -1016,6 +1016,9 @@ Markdown pipe table. 3 rows, 2 columns: Name/Value, Alpha/1, Beta/2 — all corr
 **Result (2026-09-04) ✅ PASS**
 create_doc_from_file(tc-d195-create-doc.md): docId+web_link, no error. get_doc_structure confirmed HEADING_1 "QA Test Document", bold/italic runs, ☑/☐ bullet items, table (Col A/Col B, one/two). Trashed.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+create_doc_from_file(tc-d195-create-doc.md): docId+web_link, no error. get_doc_structure: HEADING_1 "QA Test Document", bold/italic runs, ☑/☐/Plain item bullets, Col A/Col B table. Playwright (account check passed): heading, bold/italic, checkbox glyphs, and table render correctly. Trashed.
+
 ---
 
 ### TC-DOC45: `create_doc_from_file` with a local .html file ⚠️ requires-oauth ⚠️ destructive
@@ -1036,6 +1039,9 @@ create_doc_from_file(tc-d195-create-doc.md): docId+web_link, no error. get_doc_s
 **Result (2026-09-04) ✅ PASS**
 create_doc_from_file(tc-d196-create-doc.html): docId+web_link, no error. get_doc_structure confirmed HEADING_2 "From HTML file", paragraph "Content paragraph." Trashed.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+create_doc_from_file(tc-d196-create-doc.html): docId+web_link, no error. get_doc_structure: HEADING_2 "From HTML file", paragraph "Content paragraph." Trashed.
+
 ---
 
 ### TC-DOC46: `create_doc_from_file` file not found
@@ -1051,6 +1057,9 @@ create_doc_from_file(tc-d196-create-doc.html): docId+web_link, no error. get_doc
 **Result (2026-09-04) ✅ PASS**
 create_doc_from_file('~/does-not-exist.md') returned {"error": "File not found: ~/does-not-exist.md"}, no exception.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+create_doc_from_file('~/does-not-exist.md') returned {"error": "File not found: ~/does-not-exist.md"}, no exception. Unsupported .txt also still returns the no-hint message "Use .md or .html/.htm" (shared helper, format_overridable=False).
+
 ---
 
 ### TC-DOC47: `write_doc_content` inline code monospace ⚠️ destructive
@@ -2804,6 +2813,9 @@ insert_local_images (default revoke_sharing) on scratch doc with "Marker: IMGMAR
 **Result (2026-09-04) ✅ PASS**
 create_doc HTML table with image in a cell: no error. get_doc_structure: cell 0 "Before", cell 2 "After", cell 1 (image) empty (""). No images key in response (image dropped at parse time, table-cell images still out of scope). No timeout/hang. Trashed.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+create_doc HTML table with an image in a cell: returned at once, no error, no `images` key. get_doc_structure: cell 0 "Before", cell 1 "", cell 2 "After". No hang. Trashed.
+
 ---
 
 ### TC-DOC154: A `<pre>` block resumed after a nested table doesn't leave a spurious trailing whitespace-only paragraph ⚠️ requires-oauth ⚠️ destructive
@@ -3107,6 +3119,9 @@ Generated real ~76MB 4800x5000 (24.0MP, under 25MP pre-check) noise PNG. Main ca
 **Result (2026-09-04) ✅ PASS**
 update_doc_from_file(tc-d195-create-doc.md) on DOC_ID: returned docId matching DOC_ID, no error. get_doc_structure matches TC-DOC44's create_doc_from_file output exactly (HEADING_1, bold/italic runs, ☑/☐ items, Col A/Col B table). get_file_metadata before/after identical name/parents/webViewLink — doc identity/location preserved.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+update_doc_from_file(tc-d195-create-doc.md) on DOC_ID: docId matched, web_link present, no error. get_doc_structure matches TC-DOC44's output (HEADING_1, bold/italic, ☑/☐ items, Col A/Col B table). get_file_metadata before/after: same name/parents/webViewLink.
+
 ### TC-DOC169: `update_doc_from_file` with a local .html file ⚠️ destructive
 **Prompt**
 > "Update Google Doc {DOC_ID} from the file <repo-root>/docs/qa/fixtures/tc-d196-create-doc.html"
@@ -3123,6 +3138,9 @@ update_doc_from_file(tc-d195-create-doc.md) on DOC_ID: returned docId matching D
 **Result (2026-09-04) ✅ PASS**
 update_doc_from_file(tc-d196-create-doc.html): docId matched, no error. get_doc_structure: HEADING_2 "From HTML file", paragraph "Content paragraph." — matches TC-DOC45.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+update_doc_from_file(tc-d196-create-doc.html): docId matched, no error. get_doc_structure: HEADING_2 "From HTML file", paragraph "Content paragraph."
+
 ### TC-DOC170: `update_doc_from_file` file not found
 **Prompt**
 > "Update Google Doc {DOC_ID} from the file ~/does-not-exist.md"
@@ -3137,6 +3155,9 @@ update_doc_from_file(tc-d196-create-doc.html): docId matched, no error. get_doc_
 **Result (2026-09-04) ✅ PASS**
 update_doc_from_file('~/does-not-exist.md') returned {"error":"File not found: ~/does-not-exist.md"}, no exception. get_doc_content confirmed doc unchanged (still HEADING_2/paragraph from DOC169).
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+update_doc_from_file('~/does-not-exist.md') returned {"error": "File not found: ~/does-not-exist.md"}, no exception. get_doc_content unchanged.
+
 ### TC-DOC171: `update_doc_from_file` unsupported extension with no override returns an error, doc untouched
 **Setup:** create a local file `qa-update.txt` with arbitrary plain text
 
@@ -3155,6 +3176,9 @@ update_doc_from_file('~/does-not-exist.md') returned {"error":"File not found: ~
 **Result (2026-09-04) ✅ PASS**
 update_doc_from_file(qa-update.txt, no override) returned {"error":"Unsupported file extension '.txt'. Use .md or .html/.htm, or pass content_format explicitly."}. get_doc_content confirmed doc untouched — no Docs API call made.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+update_doc_from_file(qa-update.txt) returned {"error": "Unsupported file extension '.txt'. Use .md or .html/.htm, or pass content_format explicitly."}. get_doc_content unchanged.
+
 ### TC-DOC172: `update_doc_from_file` `content_format` explicitly overrides an unrecognized extension ⚠️ destructive
 **Setup:** create a local file `qa-update-override.txt` containing `# Overridden Heading\n\nParagraph text.\n`
 
@@ -3171,6 +3195,9 @@ update_doc_from_file(qa-update.txt, no override) returned {"error":"Unsupported
 **Result (2026-09-04) ✅ PASS**
 update_doc_from_file(qa-update-override.txt, content_format='markdown') succeeded, no error. get_doc_structure: HEADING_1 "Overridden Heading", paragraph "Paragraph text." Fixture restored after.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+update_doc_from_file(qa-update-override.txt, content_format='markdown'): no error. get_doc_structure: HEADING_1 "Overridden Heading", paragraph "Paragraph text." Fixture restored to setup.md's seed HTML via write_doc_content afterward.
+
 ---
 
 ## `get_doc_as_markdown`
@@ -3747,12 +3774,15 @@ Tool call: `insert_local_images(doc_id={DOC_ID}, images=[{"marker": "IMGMARKERBO
 **Checks**
 - `results[0]` has no `fileId` and an `error` containing "14000x13000 (182.0 megapixels)" and "25 megapixels"
 - No `qa-bomb.png` appears in `{FOLDER_ID}`, and the marker text is unchanged
-- Re-run with `auto_downscale=True`: `results[0]` still has no `fileId`, and its `error` ends with "Could not auto-downscale it (unreadable or corrupt image, animated, or too large to decode safely)."
+- Re-run with `auto_downscale=True`: `results[0]` still has no `fileId`, and its `error` ends with "Could not auto-downscale it (unreadable or corrupt image, animated, too large to decode safely, or still over the file-size limit after shrinking)." (the last reason was added by #894/#581)
 
 **Cleanup:** trash the doc; `rm /tmp/qa-bomb.png`
 
 **Result (2026-09-24) ✅ PASS — Kit, PR #801 round 2 (fix `4d5f842`, issue #560).** Both checks matched exactly, and nothing was uploaded. (Round 1 reproduced the pre-fix behavior locally: `check_image_file` returned `None` for this file.) Doc trashed.
 
+**Result (2026-10-10) ✅ PASS — PR #961 (Sky)**
+insert_local_images with the 14000x13000 PNG: results[0] no fileId, error names "14000x13000 (182.0 megapixels)" and "25 megapixels". With auto_downscale=True: error ends with "Could not auto-downscale it (unreadable or corrupt image, animated, too large to decode safely, or still over the file-size limit after shrinking)." No qa-bomb.png in FOLDER_ID; marker text unchanged. Doc trashed.
+
 ---
 
 ### TC-DOC198: `insert_local_images` — an unreadable local file fails with "failed to read local file", not a raw upload error (PR #801)
@@ -3935,3 +3965,28 @@ Two extra probes ran from a scratch copy of the script (not committed):
 All files from both probes and the three steps, and the doc, were trashed.
 
 **Result (2026-10-04) ✅ PASS — Kit, PR #903 round 2 (`4e392c3`).** All six steps ran from the kit worktree with its OAuth token, on a fresh scratch doc in `{FOLDER_ID}`. Each step printed `cancelled at '<point>'; the tool returned nothing` and the WARNING `Doc edit for {DOC_ID} failed or was cancelled after its images were resolved; files created by this call: <one file ID>; pre-existing files: none; still link-shared by this call: ...`. That last field listed `{KEPT_FILE_ID}` for step 4 and was `none` for every other step. Steps 2 (`share-fail`, the orphan) and 6 (`revoke`), which logged nothing in round 1's probe, now log. `list_permissions` showed no `anyone` grant on `{SHARE_FILE_ID}`, `{ORPHAN_FILE_ID}`, `{EDIT_FILE_ID}`, `{INFLIGHT_FILE_ID}`, or `{REVOKE_FILE_ID}`, and showed `anyoneWithLink`/`reader` on `{KEPT_FILE_ID}`. After `refresh_cache`, `get_doc_as_markdown` read `Before`, `IMGMARKER883`, an image, an image, `After`. So steps 1–4 left `IMGMARKER883` untouched, step 6's edit landed before its cancel, and step 5's in-flight edit also landed (an image replaced `INFLIGHT883`). All six files and the doc were trashed.
+
+## Unreadable source file returns an error — `create_doc_from_file` / `update_doc_from_file` (PR #961)
+
+Both tools read the local file through the shared `_read_doc_source_file` helper. Before PR #961's round 2, a path that existed but wasn't a readable UTF-8 regular file raised out of the tool (`[Errno 21] Is a directory`, `'utf-8' codec can't decode byte 0xe9 ...`) instead of returning `{"error": ...}`.
+
+### TC-DOC208: A directory or non-UTF-8 source file returns `{"error": ...}`, and nothing is created or edited
+**Setup:**
+- `mkdir -p /tmp/tc-doc208/dir.md`
+- `python3 -c "open('/tmp/tc-doc208/latin1.html','wb').write('<p>caf\xe9</p>'.encode('latin-1'))"`
+- `get_doc_content(file_id={DOC_ID})`, note the content for comparison afterward
+
+**Steps**
+1. `create_doc_from_file(local_path="/tmp/tc-doc208/dir.md", folder_id={FOLDER_ID})`
+2. `create_doc_from_file(local_path="/tmp/tc-doc208/latin1.html", folder_id={FOLDER_ID})`
+3. `update_doc_from_file(doc_id={DOC_ID}, local_path="/tmp/tc-doc208/dir.md")`
+4. `update_doc_from_file(doc_id={DOC_ID}, local_path="/tmp/tc-doc208/latin1.html")`
+
+**Checks**
+- Each call returns a dict with an `error` key naming the path (any wording). None comes back as `Error executing tool ...`
+- `list_files(folder_id={FOLDER_ID})` shows no new Doc named `dir` or `latin1` (the filename stem `create_doc_from_file` uses as the default title; steps 1–2 fail before the Drive `create`)
+- `get_doc_content(file_id={DOC_ID})` matches the Setup snapshot (steps 3–4 fail before any Docs API call)
+
+**Cleanup:** `rm -rf /tmp/tc-doc208`
+
+**Result (2026-10-10) ✅ PASS — Sky, PR #961 round 2 (`849f0bb`).** Ran with the fixtures under this job's scratch dir instead of `/tmp/tc-doc208`. Steps 1 and 3 returned `{"error": "Not a regular file: <path>/dir.md"}`; steps 2 and 4 returned `{"error": "File is not valid UTF-8: <path>/latin1.html (invalid continuation byte at byte 6)"}`. No call surfaced as `Error executing tool`. `list_files({FOLDER_ID})` showed only the three standing fixtures. After `refresh_cache`, `get_doc_content({DOC_ID})` matched the Setup snapshot. Round 1 reproduced both raises on the pre-fix code (`075ce99`).

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev286}/docs/roadmap.md

@@ -351,7 +351,7 @@ Requires `gmail/v1` client and `https://www.googleapis.com/auth/gmail.modify` sc
 - [ ] Define the correctness rubric and own execution for the composite-vs-primitive efficiency benchmark — Aziz ([#584](https://github.com/khuisman/mcp-gee-sweet/issues/584))
 - [ ] QA `.env` has no single source of truth — `setup_team.sh` only copies `.env` into a worktree when absent, so fixture-ID changes never propagate (had to hand-sync 9 copies for #305); also `run.md` vs `setup.md` disagree on `docs/qa/.env` vs repo-root `.env`. Surfaced by PR #677, relates to [#648](https://github.com/khuisman/mcp-gee-sweet/issues/648) ([#679](https://github.com/khuisman/mcp-gee-sweet/issues/679))
 - [x] `list_files`/`get_file_metadata` docstrings cite a stale `upload_local_file` `modifiedTime` caveat (fixed at the root by PR #472) and carry a broken self-referential contrast — from Bob's `docs/tools.md` docstring sweep; Dev/QA track, batches with #682/#683 ([#681](https://github.com/khuisman/mcp-gee-sweet/issues/681)) (PR 898)
-- [ ] `create_doc` family docstrings name only the ~25MP inline-image limit; the ~50MB byte-size limit (#562) is equally enforced, and 3 deferring docstrings inherit the gap — from Bob's `docs/tools.md` docstring sweep. Routed to Amy (`documentation`); closed community PR #932 has a diff ([#682](https://github.com/khuisman/mcp-gee-sweet/issues/682))
+- [x] `create_doc` family docstrings name only the ~25MP inline-image limit; the ~50MB byte-size limit (#562) is equally enforced, and 3 deferring docstrings inherit the gap — from Bob's `docs/tools.md` docstring sweep. Routed to Amy (`documentation`); closed community PR #932 has a diff ([#682](https://github.com/khuisman/mcp-gee-sweet/issues/682)) (PR 970)
 - [ ] `qa(docs)`: no comprehensive fixture exercising every Docs formatting construct in one pass — Aziz, triaged out of `backlog` 2026-09-11 ([#477](https://github.com/khuisman/mcp-gee-sweet/issues/477))
 - [ ] Fact-check and word competitive/benchmark claims once real benchmark numbers exist — routed to Amy, triaged out of `backlog` 2026-09-11 ([#585](https://github.com/khuisman/mcp-gee-sweet/issues/585))
 - [x] QA test-doc cross-reference cleanup after the `drive.md`/`docs.md` split (PR #582) — triaged out of `backlog` 2026-09-11 ([#590](https://github.com/khuisman/mcp-gee-sweet/issues/590)) (PR #851)

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev286}/src/mcp_gee_sweet/tools/docs/content.py

@@ -13,7 +13,7 @@ from markdown.inlinepatterns import InlineProcessor
 from mcp.server.mcpserver import Context
 from mcp.types import ToolAnnotations
 
-from ...auth import execute_in_thread
+from ...auth import SpreadsheetContext, execute_in_thread
 from ...cache import CACHE_VALIDATE_MODIFIED_TIME
 from ..drive import _SA_QUOTA_ERROR
 from ..drive.transfer import _GOOGLE_DOC_MIME
@@ -266,14 +266,45 @@ async def _resolve_image_source(
         )
 
 
+_SOURCE_FILE_FORMATS = {".md": "markdown", ".html": "html", ".htm": "html"}
+
+
+def _read_doc_source_file(
+    local_path: str, content_format: str | None, *, format_overridable: bool
+) -> tuple[str, str] | dict[str, Any]:
+    """Shared file reading for create_doc_from_file / update_doc_from_file (#567):
+    returns (content, content_format), or {"error": ...} for a missing file, a path
+    that isn't a regular file, an unreadable or non-UTF-8 file, or an extension with
+    no inferable format. content_format=None infers it from the extension.
+    format_overridable says whether the calling tool takes a content_format
+    parameter, so the error only suggests one when it exists."""
+    path = Path(local_path)
+    if not path.exists():
+        return {"error": f"File not found: {local_path}"}
+    if not path.is_file():
+        return {"error": f"Not a regular file: {local_path}"}
+    if content_format is None:
+        ext = path.suffix.lower()
+        inferred = _SOURCE_FILE_FORMATS.get(ext)
+        if inferred is None:
+            hint = ", or pass content_format explicitly." if format_overridable else ""
+            return {"error": f"Unsupported file extension '{ext}'. Use .md or .html/.htm{hint}"}
+        content_format = inferred
+    try:
+        content = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as e:
+        return {"error": f"File is not valid UTF-8: {local_path} ({e.reason} at byte {e.start})"}
+    except OSError as e:
+        return {"error": f"Could not read file {local_path}: {e.strerror or e}"}
+    return content, content_format
+
+
 async def _replace_doc_content(
-    docs_service,
-    drive_service,
-    doc_cache,
-    folder_id: str | None,
+    lc: SpreadsheetContext,
     doc_id: str,
     content: str,
     content_format: str,
+    *,
     autolink_urls: bool,
     revoke_sharing: bool,
     auto_downscale: bool,
@@ -283,7 +314,14 @@ async def _replace_doc_content(
     the clear-then-insert mechanism (including the same-batch insertText
     style-inheritance quirk below) has exactly one implementation instead of two
     copies that could drift out of sync.
+
+    The three flags are keyword-only (#567), here and in _apply_doc_content: as
+    positional bools, swapping two at a call site would type-check and silently do
+    the wrong thing.
     """
+    docs_service = lc.docs_service
+    drive_service = lc.drive_service
+    doc_cache = lc.doc_cache
     doc = await execute_in_thread(
         docs_service.documents().get(documentId=doc_id).execute,
         docs_service,
@@ -330,10 +368,10 @@ async def _replace_doc_content(
             doc_id,
             content,
             content_format,
-            autolink_urls,
-            folder_id,
-            revoke_sharing,
-            auto_downscale,
+            autolink_urls=autolink_urls,
+            target_folder_id=lc.folder_id,
+            revoke_sharing=revoke_sharing,
+            auto_downscale=auto_downscale,
         )
     except DocEditError as e:
         # The clear above already committed, so the doc changed either way.
@@ -382,6 +420,7 @@ async def _apply_doc_content(
     doc_id: str,
     content: str,
     content_format: str,
+    *,
     autolink_urls: bool,
     target_folder_id: str | None,
     revoke_sharing: bool,
@@ -932,10 +971,10 @@ def register(tool):
                     doc_id,
                     content,
                     content_format,
-                    autolink_urls,
-                    target_folder_id,
-                    revoke_sharing,
-                    auto_downscale,
+                    autolink_urls=autolink_urls,
+                    target_folder_id=target_folder_id,
+                    revoke_sharing=revoke_sharing,
+                    auto_downscale=auto_downscale,
                 )
             except DocEditError as e:
                 if target_folder_id:
@@ -1010,20 +1049,11 @@ def register(tool):
             Requires OAuth or ADC auth. Service accounts cannot create files in personal
             Drive (no storage quota). Check server://auth-status for your current auth method.
         """
-        path = Path(local_path)
-        if not path.exists():
-            return {"error": f"File not found: {local_path}"}
-
-        ext = path.suffix.lower()
-        if ext == ".md":
-            content_format = "markdown"
-        elif ext in (".html", ".htm"):
-            content_format = "html"
-        else:
-            return {"error": f"Unsupported file extension '{ext}'. Use .md or .html/.htm"}
-
-        content = path.read_text(encoding="utf-8")
-        doc_title = title or path.stem
+        source = _read_doc_source_file(local_path, None, format_overridable=False)
+        if isinstance(source, dict):
+            return source
+        content, content_format = source
+        doc_title = title or Path(local_path).stem
 
         lc = ctx.request_context.lifespan_context
         drive_service = lc.drive_service
@@ -1066,10 +1096,10 @@ def register(tool):
                     doc_id,
                     content,
                     content_format,
-                    autolink_urls,
-                    target_folder_id,
-                    revoke_sharing,
-                    auto_downscale,
+                    autolink_urls=autolink_urls,
+                    target_folder_id=target_folder_id,
+                    revoke_sharing=revoke_sharing,
+                    auto_downscale=auto_downscale,
                 )
             except DocEditError as e:
                 if target_folder_id:
@@ -1222,16 +1252,13 @@ def register(tool):
         """
         lc = ctx.request_context.lifespan_context
         return await _replace_doc_content(
-            lc.docs_service,
-            lc.drive_service,
-            lc.doc_cache,
-            lc.folder_id,
+            lc,
             doc_id,
             content,
             content_format,
-            autolink_urls,
-            revoke_sharing,
-            auto_downscale,
+            autolink_urls=autolink_urls,
+            revoke_sharing=revoke_sharing,
+            auto_downscale=auto_downscale,
         )
 
     @tool(annotations=ToolAnnotations(title="Update Document from File", destructiveHint=True))
@@ -1284,38 +1311,20 @@ def register(tool):
             instead, with any temporary image share already revoked. The old content
             was cleared first, so the doc may be empty or partly written.
         """
-        path = Path(local_path)
-        if not path.exists():
-            return {"error": f"File not found: {local_path}"}
-
-        if content_format is None:
-            ext = path.suffix.lower()
-            if ext == ".md":
-                content_format = "markdown"
-            elif ext in (".html", ".htm"):
-                content_format = "html"
-            else:
-                return {
-                    "error": (
-                        f"Unsupported file extension '{ext}'. Use .md or .html/.htm, "
-                        "or pass content_format explicitly."
-                    )
-                }
-
-        content = path.read_text(encoding="utf-8")
+        source = _read_doc_source_file(local_path, content_format, format_overridable=True)
+        if isinstance(source, dict):
+            return source
+        content, content_format = source
 
         lc = ctx.request_context.lifespan_context
         return await _replace_doc_content(
-            lc.docs_service,
-            lc.drive_service,
-            lc.doc_cache,
-            lc.folder_id,
+            lc,
             doc_id,
             content,
             content_format,
-            autolink_urls,
-            revoke_sharing,
-            auto_downscale,
+            autolink_urls=autolink_urls,
+            revoke_sharing=revoke_sharing,
+            auto_downscale=auto_downscale,
         )
 
     @tool(annotations=ToolAnnotations(title="Get Document Structure", readOnlyHint=True))

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev286}/src/mcp_gee_sweet/tools/docs/emitter.py

@@ -910,12 +910,16 @@ async def _fill_children_recursive(
                     table_inserts.append((t, r, c, occurrence, child))
                 new_cursor = cursor + 1
             else:
+                # Consume every non-Table child up to the next Table. An Image is
+                # skipped, as _build_fill_requests does for a cell with no nested
+                # table: table-cell images aren't supported (#509). Stopping only at
+                # a Table guarantees j > cursor, so the cell can't stay pending forever.
                 j = cursor
                 run_group: list[Run] = []
-                while j < len(children) and isinstance(children[j], Run):
-                    next_run = children[j]
-                    assert isinstance(next_run, Run)
-                    run_group.append(next_run)
+                while j < len(children) and not isinstance(children[j], Table):
+                    next_child = children[j]
+                    if isinstance(next_child, Run):
+                        run_group.append(next_child)
                     j += 1
                 reqs = _run_group_fill_requests(run_group, para_start)
                 if reqs:

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev286}/src/mcp_gee_sweet/tools/docs/html_parser.py

@@ -917,9 +917,12 @@ class _AstParser(HTMLParser):
                 self._code_depth = max(0, self._code_depth - 1)
 
     def handle_data(self, data):
-        if (
-            self._table_depth >= 1 and self._table_stack and self._table_stack[-1].in_cell
-        ) or self._block_tag:
+        # Table-cell text and open-block text are independent triggers that happen
+        # to be buffered the same way today; kept as separate branches so either
+        # can diverge without first untangling a merged condition (#638).
+        if self._table_depth >= 1 and self._table_stack and self._table_stack[-1].in_cell:  # noqa: SIM114
+            self._run_buf.append(data)
+        elif self._block_tag:
             self._run_buf.append(data)
         elif self._table_depth == 0 and self._tag_depth == 0 and data.strip():
             # Genuinely bare text — no wrapping block tag, no enclosing tag of

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev286}/src/mcp_gee_sweet/tools/docs/images.py

@@ -70,8 +70,12 @@ _FORMAT_MIME = {"PNG": "image/png", "JPEG": "image/jpeg", "GIF": "image/gif"}
 
 # Every reason downscale_image_bytes can decline for an image already known to be
 # oversized. "Too large to decode safely": Pillow's decompression-bomb guard refuses a
-# full decode above ~179 megapixels, and downscaling needs one.
-_CANNOT_DOWNSCALE_REASONS = "unreadable or corrupt image, animated, or too large to decode safely"
+# full decode above ~179 megapixels, and downscaling needs one. "Still over the size
+# limit": the bounded shrink loop ran out of attempts (#581).
+_CANNOT_DOWNSCALE_REASONS = (
+    "unreadable or corrupt image, animated, too large to decode safely, "
+    "or still over the file-size limit after shrinking"
+)
 
 
 def _decode(data: bytes) -> Image.Image | None:
@@ -187,9 +191,11 @@ def downscale_image_bytes(data: bytes) -> tuple[bytes, str] | None:
     """Resize image `data` to fit both the megapixel and file-size limits, preserving
     aspect ratio and format. Returns (resized_bytes, mime_type), or None if: the image
     can't be decoded; it's already within both limits (nothing to do — caller should
-    keep using the original bytes/upload path); or it's animated (Pillow's resize only
+    keep using the original bytes/upload path); it's animated (Pillow's resize only
     touches the current frame, which would silently drop every other frame of an
-    animated GIF — declining is safer than corrupting it).
+    animated GIF — declining is safer than corrupting it); or the bounded shrink loop
+    below still can't get it under the file-size limit (#581), so a caller never
+    embeds still-oversized bytes as if the resize had worked.
 
     The byte-size limit can't be hit exactly on the first resize the way the
     megapixel one can: encoded size depends on compression, not just pixel count, so a
@@ -236,6 +242,8 @@ def downscale_image_bytes(data: bytes) -> tuple[bytes, str] | None:
         encoded = _encode(resized)
         attempts += 1
 
+    if len(encoded) > MAX_INLINE_IMAGE_BYTES:
+        return None
     return encoded, _FORMAT_MIME.get(fmt, "application/octet-stream")
 
 
@@ -249,17 +257,26 @@ def check_drive_image_metadata(metadata: dict[str, Any]) -> dict[str, Any] | Non
     _resolve_image_source). Dimensions are checked first, matching
     downscale_image_bytes's own resize-by-pixels-first behavior. Returns the first
     violation found, or None if within both limits or the metadata doesn't report
-    enough to check (e.g. a non-image binary with no imageMediaMetadata)."""
+    enough to check (e.g. a non-image binary with no imageMediaMetadata, or a
+    width/height/`size` that isn't a number). Never raises: both call sites call it
+    outside their try/except (#581)."""
     img_meta = metadata.get("imageMediaMetadata") or {}
-    width, height = img_meta.get("width"), img_meta.get("height")
-    if width and height:
+    try:
+        width, height = int(img_meta["width"]), int(img_meta["height"])
+    except (KeyError, TypeError, ValueError):
+        # Missing or malformed dimensions mean unknown; fall through to the size check.
+        width = height = 0
+    if width > 0 and height > 0:
         error = check_dimensions(width, height)
         if error is not None:
             return error
-    size = metadata.get("size")
-    if size is not None:
-        return check_file_size(int(size))
-    return None
+    try:
+        size_bytes = int(metadata["size"])
+    except (KeyError, TypeError, ValueError):
+        # Drive sends `size` as a decimal string. Missing or malformed means unknown,
+        # the same as missing dimensions: let the embed call be the judge.
+        return None
+    return check_file_size(size_bytes)
 
 
 def rewrite_too_large_error(message: str) -> str:

{mcp_gee_sweet-0.9.2.dev283 → mcp_gee_sweet-0.9.2.dev286}/tests/test_docs_content.py

@@ -1,5 +1,6 @@
 """Tests for docs content tools and HTML/Markdown pipeline."""
 
+import inspect
 import io
 import json
 import os
@@ -2400,6 +2401,25 @@ class TestCreateDocFromFile:
         result = await _docs_tools["create_doc_from_file"](local_path=str(txt_file), ctx=ctx)
         assert "error" in result
         assert ".txt" in result["error"]
+        # create_doc_from_file has no content_format parameter to suggest (#567).
+        assert "content_format" not in result["error"]
+
+    @pytest.mark.parametrize("kind", ["directory", "latin1"])
+    async def test_unreadable_source_returns_error(self, tmp_path, kind):
+        # PR #961 QA round 1: a path that exists but isn't a readable UTF-8 file
+        # returns {"error": ...} instead of raising, and creates nothing.
+        if kind == "directory":
+            src = tmp_path / "dir.md"
+            src.mkdir()
+        else:
+            src = tmp_path / "latin1.html"
+            src.write_bytes("<p>caf\xe9</p>".encode("latin-1"))
+        drive_svc, docs_svc = self._make_services()
+        ctx = self._ctx(drive_svc, docs_svc)
+        result = await _docs_tools["create_doc_from_file"](local_path=str(src), ctx=ctx)
+        assert "error" in result
+        assert str(src) in result["error"]
+        drive_svc.files.return_value.create.assert_not_called()
 
 
 class TestUpdateDocFromFile:
@@ -2510,8 +2530,68 @@ class TestUpdateDocFromFile:
         )
         assert "error" in result
         assert ".txt" in result["error"]
+        assert "pass content_format explicitly" in result["error"]
+        docs_svc.documents.return_value.get.assert_not_called()
+
+    @pytest.mark.parametrize("kind", ["directory", "latin1"])
+    async def test_unreadable_source_returns_error(self, tmp_path, kind):
+        # PR #961 QA round 1: same as create_doc_from_file; the doc is never touched.
+        if kind == "directory":
+            src = tmp_path / "dir.md"
+            src.mkdir()
+        else:
+            src = tmp_path / "latin1.html"
+            src.write_bytes("<p>caf\xe9</p>".encode("latin-1"))
+        drive_svc, docs_svc = self._make_services()
+        ctx = self._ctx(drive_svc, docs_svc)
+        result = await _docs_tools["update_doc_from_file"](
+            doc_id="doc1", local_path=str(src), ctx=ctx
+        )
+        assert "error" in result
+        assert str(src) in result["error"]
         docs_svc.documents.return_value.get.assert_not_called()
 
+    def test_doc_content_flags_are_keyword_only(self):
+        # #567 / PR #961 QA round 1: positional bools could be swapped at a call site
+        # and still type-check, in both shared helpers.
+        for fn, names in (
+            (
+                content_module._replace_doc_content,
+                ("autolink_urls", "revoke_sharing", "auto_downscale"),
+            ),
+            (
+                content_module._apply_doc_content,
+                ("autolink_urls", "target_folder_id", "revoke_sharing", "auto_downscale"),
+            ),
+        ):
+            params = inspect.signature(fn).parameters
+            for name in names:
+                assert params[name].kind is inspect.Parameter.KEYWORD_ONLY, (fn.__name__, name)
+
+    @pytest.mark.parametrize(
+        "flags",
+        [
+            {"autolink_urls": False, "revoke_sharing": True, "auto_downscale": True},
+            {"autolink_urls": True, "revoke_sharing": False, "auto_downscale": False},
+        ],
+    )
+    async def test_flags_reach_apply_doc_content_unswapped(self, tmp_path, flags):
+        # #567: _replace_doc_content's three bools are keyword-only, so each tool
+        # flag must land in its own _apply_doc_content slot.
+        md_file = tmp_path / "notes.md"
+        md_file.write_text("text\n")
+        drive_svc, docs_svc = self._make_services(end_index=2)
+        ctx = self._ctx(drive_svc, docs_svc)
+        real_apply = content_module._apply_doc_content
+        with patch.object(content_module, "_apply_doc_content", return_value=None) as apply:
+            await _docs_tools["update_doc_from_file"](
+                doc_id="doc1", local_path=str(md_file), ctx=ctx, **flags
+            )
+        # Bind against the real signature so the assertion holds however the call
+        # site passes them, and fails if the call wouldn't bind at all.
+        bound = inspect.signature(real_apply).bind(*apply.call_args.args, **apply.call_args.kwargs)
+        assert {k: bound.arguments[k] for k in flags} == flags
+
     async def test_clears_trailing_mark_style_before_deleting_in_its_own_batch(self, tmp_path):
         # Same clear-then-insert mechanism as write_doc_content (#255) — verified here
         # too since it's now shared via _replace_doc_content.