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

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

@@ -42,7 +42,7 @@ Logic is split across `src/mcp_gee_sweet/`: `server.py` (MCP setup, tool decorat
   - `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.
   - `docs/anchors.py` — `resolve_heading_anchor`, the pure slug-matching logic behind the anchor-resolution pass above. Tries GitHub's non-collapsing hyphen convention (hand-rolled — no known Python package reproduces it) and GitLab's collapsing convention (delegated to `python-markdown`'s own `toc` extension `slugify`, already a project dependency, confirmed live to collapse hyphens the same way) against the document's full heading list, with GitHub/GitLab-style numeric `-1`/`-2` duplicate-heading disambiguation applied before matching; falls back to normalized word-token comparison for a slug that doesn't exactly match either scheme. Deliberately does not try to detect which generator produced a given anchor up front — see the design doc for why. Has an inline `TODO(#409 follow-up)` flagging the cascading try-each-scheme approach as a first pass, not the most precise/efficient possible mechanism. The same QA round (PR #453) found the fuzzy fallback could silently resolve to the *wrong* heading: it unconditionally stripped a trailing `-<digits>` from the anchor before comparing, even when those digits were genuine heading wording rather than a dedup suffix, and its match loop returned the *first* heading with matching normalized tokens with no regard for which duplicate a stripped suffix actually pointed at — directly contradicting the feature's own "a wrong link is worse than no link" design goal. Fixed via `_fuzzy_match`/`_match_tokens_at_occurrence`: the anchor's literal tokens (with any trailing digits intact) are tried first at occurrence 0 — safe, since GitHub/GitLab give a duplicate heading's *first* occurrence the bare/unsuffixed slug, so a suffix-free anchor naming a duplicated heading still resolves correctly without ever needing to strip anything — and only if that fails, and the anchor ends in `-<digits>`, is the suffix stripped and its number used as the required occurrence index among headings sharing the same normalized tokens; a requested occurrence that doesn't exist (e.g. a claimed 3rd duplicate when only one heading matches) returns `None` rather than guessing the nearest candidate.
   - `docs/tables.py` — tools (`insert_doc_table`, `insert_table_row`, `delete_table_row`, `insert_table_column`, `delete_table_column`, `merge_table_cells`)
-  - `docs/style.py` — helpers (`_NAMED_STYLE_TYPES`, `_read_body_styles`, `_read_named_styles`, `_build_named_style_requests`, `_text_style_and_fields`) and tools (`style_doc_range`, `style_doc_table_cells`, `get_doc_theme`, `get_doc_named_styles`, `apply_theme`). `_text_style_and_fields` (shared by `style_doc_range` and `content.py`'s `insert_softbreak_paragraph`) used to clear a hyperlink by setting `textStyle.link = {}` — the Docs API rejects an empty `Link` object outright ("must include at least one type"), confirmed live, so `link_url: null` always failed instead of clearing (#408). Fixed by omitting the `link` key from `textStyle` entirely while still naming `"link"` in the field mask, the correct way to reset a nested message field to its default (no link) per Docs API `fields`-mask semantics — confirmed live this actually clears an existing link. Both call sites' own `if text_style: requests.append(...)` guard had to change to `if fields:` too: a link-clear-only call now legitimately produces an empty `text_style` dict with a non-empty `fields` list (`["link"]`), and the old guard would have silently skipped sending the request at all.
+  - `docs/style.py` — helpers (`_NAMED_STYLE_TYPES`, `_read_body_styles`, `_read_named_styles`, `_build_named_style_requests`, `_text_style_and_fields`) and tools (`style_doc_range`, `style_doc_table_cells`, `create_paragraph_bullets`, `delete_paragraph_bullets`, `get_doc_theme`, `get_doc_named_styles`, `apply_theme`). `create_paragraph_bullets`/`delete_paragraph_bullets` (#334) wrap the Docs API's `createParagraphBullets`/`deleteParagraphBullets` requests, previously only used internally by `emitter.py`'s markdown-to-Doc conversion, as caller-facing tools for fixing list membership/nesting on paragraphs already in a doc — `get_doc_structure` had no way to even detect a flattened nested list (the AST emitter's own conversion bug from the same issue), and there was no way to fix one afterward short of delete-and-retype as plain text. `createParagraphBullets` has no `nestingLevel` field of its own — same constraint the emitter already works around (see that file's own long comment) — the API infers a paragraph's depth purely from its own leading tab characters at call time, consuming them once applied; `create_paragraph_bullets` reproduces that mechanism per range (`insertText`-ing `nesting_level` tab characters before the range, then extending the range's `endIndex` to cover them) rather than exposing a fake `nestingLevel` parameter that doesn't correspond to any real request field. `get_doc_structure` (`content.py`) now also surfaces each paragraph's `bullet` field (`{listId, nestingLevel}` or `null`), normalizing a top-level item's absent `nestingLevel` to `0` so every list paragraph reports a level — this is what makes the flattened-list defect (#334's original report) detectable at all, and is the read half `create_paragraph_bullets`/`delete_paragraph_bullets` fix on the write side. PR #524's QA round found `create_paragraph_bullets`'s first version didn't work at all on its own flagship use case (nesting paragraphs already in an existing list, #334's original repro): live-verified two compounding causes — `createParagraphBullets` is a no-op on a paragraph that's already part of a list (doesn't change its level, doesn't consume the signaling tab, which is left behind as literal text), and even after a `deleteParagraphBullets`+recreate, the API infers a paragraph's depth only relative to whatever else is included in that *same* call — a paragraph adjacent to an untouched, already-listed neighbor gets silently pulled back to that neighbor's level regardless of its own tabs (the same class of bug PR #432 fixed in `emitter.py`, confirmed live to also apply here). Fixed by always `deleteParagraphBullets`-ing a target paragraph first (harmless even if it wasn't previously listed), and — for a paragraph that's already part of a list — expanding the affected span to include its full contiguous run of same-`listId` neighbors (preserving each neighbor's own current `nestingLevel` unchanged) before issuing one `createParagraphBullets` call per contiguous same-preset run, mirroring `emitter.py`'s own established grouping pattern. Confirmed live against the real API for both the multi-paragraph-range case (TC-DOC156) and an isolated single-paragraph target whose only same-list neighbor sits outside the requested range. A second QA round on the same PR caught a follow-on regression from that fix, also live-verified (Playwright): merging context/neighbor paragraphs into the run and applying one `bulletPreset` to the whole call meant an already-numbered list, repaired without the caller re-passing `bullet_preset="NUMBERED_DECIMAL_ALPHA_ROMAN"` explicitly, silently converted its untouched siblings to plain bullets — the tool's own hardcoded default (`BULLET_DISC_CIRCLE_SQUARE`) always won. Fixed by reading the document's own `lists` map (`document["lists"][listId]["listProperties"]["nestingLevels"][level]`) to detect an already-listed paragraph's real style before choosing a run's preset — `glyphType` present means numbered, `glyphSymbol` present means bulleted, confirmed live for both — and preferring that inferred style over the hardcoded default whenever the caller didn't pass `bullet_preset` explicitly on any paragraph in the run; an explicit caller-supplied preset still always wins. Since context paragraphs no longer carry a fixed preset up front (it's resolved once per formed run, after grouping), a preset mismatch only forces a run split when it's between two paragraphs the caller *explicitly* gave conflicting presets to and they're immediately adjacent with no non-explicit paragraph bridging them; a conflict bridged by a shared context paragraph (both explicit ends expand into the same run via a same-`listId` neighbor between them) is instead reported as an `{"error": ...}` rather than silently picking one side. `_text_style_and_fields` (shared by `style_doc_range` and `content.py`'s `insert_softbreak_paragraph`) used to clear a hyperlink by setting `textStyle.link = {}` — the Docs API rejects an empty `Link` object outright ("must include at least one type"), confirmed live, so `link_url: null` always failed instead of clearing (#408). Fixed by omitting the `link` key from `textStyle` entirely while still naming `"link"` in the field mask, the correct way to reset a nested message field to its default (no link) per Docs API `fields`-mask semantics — confirmed live this actually clears an existing link. Both call sites' own `if text_style: requests.append(...)` guard had to change to `if fields:` too: a link-clear-only call now legitimately produces an empty `text_style` dict with a non-empty `fields` list (`["link"]`), and the old guard would have silently skipped sending the request at all.
   - `docs/layout.py` — tools (`create_header`, `create_footer`)
   - `docs/comments.py` — tools (`list_doc_comments`, `add_doc_comment`, `resolve_doc_comment`) via the Drive `comments`/`replies` resource, not the Docs API
   - `docs/ast.py` — dataclass schema

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-gee-sweet
-Version: 0.8.2.dev259
+Version: 0.8.2.dev263
 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.dev259 → mcp_gee_sweet-0.8.2.dev263}/docs/configuration.md

@@ -70,7 +70,7 @@ Access logs are emitted at `INFO` level — they appear when `DEBUG_LEVEL` is `D
 
 <!-- Auto-generated by `scripts/gen_tool_docs.py` — do not edit by hand, your changes will be overwritten on the next commit. -->
 
-By default all 123 tools are registered. Use `ENABLED_TOOLS` (or `--include-tools` on the CLI) to restrict the server to exactly the tools you need. This reduces the AI's context window cost — each registered tool is a name the model must reason about on every call.
+By default all 125 tools are registered. Use `ENABLED_TOOLS` (or `--include-tools` on the CLI) to restrict the server to exactly the tools you need. This reduces the AI's context window cost — each registered tool is a name the model must reason about on every call.
 
 ```bash
 # Environment variable

{mcp_gee_sweet-0.8.2.dev259 → mcp_gee_sweet-0.8.2.dev263}/docs/qa/tests/docs.md

@@ -2794,3 +2794,79 @@ Tool call: `insert_local_images(doc_id=DOC_ID, images=[{"marker": "IMGMARKERONE"
 **Result (2026-08-04) ❌ FAIL — run live against PR #515 (issue #443).** Primary check and companion regression guard both PASS: `<pre>code<table>...</table>   </pre>` produces exactly "code" paragraph → 1×1 table ("cell") → the mandatory structural trailing paragraph every Doc requires, with no spurious visible-space paragraph; a standalone `<pre>   </pre>` (no interruption) still keeps its literal whitespace unconditionally. However, `/code-review high` on the same PR live-verified (via `html_to_ast` against the worktree's own code) and this session independently reproduced via the real Docs API a related, not-yet-fixed case the test prompt above doesn't cover: a resumed `<pre>` whose trailing whitespace-only flush follows genuinely *dropped* unsupported content (e.g. `<pre>code<table>...</table> <hr></pre>`) produces a doc structurally identical to the no-drop case — no boundary node at all, silently losing the paragraph break that `_emit_block_node`'s `preserve_if_empty` guarantees every other block type (`<p>`/`<li>`/headings) in an analogous situation. Sent back to Dev (PR #515 comment) rather than approved; not filed as a separate ticket since it's blocking on this same PR.
 
 **Result (2026-08-05) ✅ PASS — re-verified live against fix commit `a465ea3`.** Round 1's finding is fixed: `<pre>code<table>...</table> <hr></pre>` (space survives after dropped `<hr>`) now renders a boundary paragraph `" \n"` immediately after the table; the zero-whitespace variant `<pre>code<table>...</table><hr></pre>` renders an empty boundary paragraph, matching the fix's own two new unit tests. Both of round 1's original checks (primary + companion regression guard) re-confirmed unaffected by the rewritten condition. `TestPreBlock` (10/10) passes. Note for future rounds: the first live-verification attempt this round produced a false FAIL — the `/mcp reconnect` had been run *before* this worktree was reset to the fix commit, so the tool call exercised stale pre-fix code (same class of gotcha as the PR #385 retro entry in `.claude/team-roles/qa.md`); caught by cross-checking against a direct script invocation of the same code path, not by the tool output itself. `qa-approved` applied.
+
+---
+
+## Paragraph bullet inspection and repair — `get_doc_structure`'s `bullet` field, `create_paragraph_bullets`/`delete_paragraph_bullets` (issue #334)
+
+### TC-DOC155: `get_doc_structure` surfaces `bullet.listId`/`bullet.nestingLevel` for list paragraphs ⚠️ destructive
+
+**Setup:** none — list created fresh by the call under test.
+
+**Prompt**
+> "Write this Markdown to doc {DOC_ID}: '- Top level item\n    - Nested item\n', then show me its structure."
+
+Tool calls: `write_doc_content(doc_id={DOC_ID}, content="- Top level item\n    - Nested item\n", content_format="markdown")`, then `get_doc_structure(doc_id={DOC_ID})`.
+
+**Checks**
+- Both list-item elements have a non-null `bullet` field, and both share the SAME `listId`
+- "Top level item"'s `bullet.nestingLevel` is `0`
+- "Nested item"'s `bullet.nestingLevel` is `1`
+
+**Cleanup:** write fixture content back
+
+**Result (2026-08-06) ❌ FAIL as originally written, ✅ PASS after test-case fix — run live against PR #524 (issue #334).** The prompt originally used a 2-space indent (`"- Top level item\n  - Nested item\n"`), which this codebase's `_md_to_html` (`sane_lists` extension, same as plain `python-markdown`) does not recognize as nested — both items render as a single flat `<ul>` with no nesting, so "Nested item" correctly reported `nestingLevel: 0` given that input; not a product bug, a test-case bug (`sane_lists`/`markdown` requires 4-space indent to nest a list). Fixed the prompt above to 4-space indent and re-ran: both items share one `listId`, "Top level item" is `nestingLevel: 0`, "Nested item" is `nestingLevel: 1` — PASS.
+
+---
+
+### TC-DOC156: `create_paragraph_bullets` fixes a markdown-flattened nested list by promoting specific paragraphs to a deeper nesting level (#334's original repro) ⚠️ destructive
+
+**Background:** issue #334 — `create_doc`'s markdown-to-Doc conversion flattens an indented sub-list under a numbered item into the SAME single-level list (the six settings in the issue's own repro became items 3-8 of one flat list instead of a nested sub-list under item 2), and until now there was no way to fix this after the fact short of delete-and-retype as plain text. This test exercises the fix: `get_doc_structure`'s new `bullet` field to detect the flattening, then `create_paragraph_bullets` to repair it.
+
+**Prompt**
+> "Write this Markdown to doc {DOC_ID}: '1. Select the snapshot\n2. Configure the instance:\n   - Instance identifier\n   - Instance class\n   - Storage encryption\n3. Click Restore\n', then show me its structure."
+
+Tool calls: `write_doc_content(doc_id={DOC_ID}, content="1. Select the snapshot\n2. Configure the instance:\n   - Instance identifier\n   - Instance class\n   - Storage encryption\n3. Click Restore\n", content_format="markdown")`, then `get_doc_structure(doc_id={DOC_ID})` — note the `start_index`/`end_index` of the "Instance identifier" and "Storage encryption" paragraphs from this call's output.
+
+Then: "Now nest the three settings paragraphs (Instance identifier through Storage encryption) one level deeper under item 2, and show me the structure again."
+
+Tool calls: `create_paragraph_bullets(doc_id={DOC_ID}, ranges=[{"start_index": <Instance identifier para start_index>, "end_index": <Storage encryption para end_index>, "nesting_level": 1}])` (one range spanning all three contiguous settings paragraphs), then `get_doc_structure(doc_id={DOC_ID})` again.
+
+**Checks**
+- First `get_doc_structure` call: all 6 items ("Select the snapshot" through "Click Restore") share one `listId`, all at `nestingLevel: 0` — confirms the flattening described in #334 (the three settings paragraphs are not visually distinguished from their numbered siblings)
+- `create_paragraph_bullets` call succeeds with no API error
+- Second `get_doc_structure` call: "Select the snapshot", "Configure the instance", and "Click Restore" are still `nestingLevel: 0`; "Instance identifier", "Instance class", "Storage encryption" are now `nestingLevel: 1`, still sharing the same `listId` as their siblings
+- The three promoted paragraphs' own text is unchanged — no visible tab character leaked into `text` (confirms the Docs API fully consumes the leading tab characters used to signal nesting depth)
+- 🔍 Visual check: the three settings render as a visually indented sub-list under "Configure the instance", and "Click Restore" still numbers as item 3 (not item 6)
+
+**Cleanup:** write fixture content back
+
+**Result (2026-08-06) ❌ FAIL — run live against PR #524 (issue #334).** First `get_doc_structure` call matches expectations (all 6 items share one `listId` at `nestingLevel: 0`, confirming the flattening). The repair step fails: after `create_paragraph_bullets(ranges=[{"start_index": 45, "end_index": 114, "nesting_level": 1}])` (single range spanning all three contiguous settings paragraphs — the tool's own documented "safe" pattern), a second `get_doc_structure` shows **all three settings paragraphs still at `nestingLevel: 0`** — the promotion had no effect. Worse, the leading tab character the tool inserts to signal depth was never consumed by the Docs API: "Instance identifier"'s own `text` field literally reads `"\t   - Instance identifier\n"`, tab included — contradicting this test's own third check ("no visible tab character leaked into text") and the tool's docstring claim that the API "consumes (removing)" the tab once applied. This is the PR's own flagship, headline use case (#334's original repro) and it does not work at all as implemented. Sent back to Dev (PR #524 comment) rather than approved.
+
+**Result (2026-08-06, round 2) ❌ FAIL — re-verified live against fix commit `a36f1c7`.** The `nestingLevel`/tab-leak failure from round 1 is fixed: the second `get_doc_structure` call now shows "Instance identifier"/"Instance class"/"Storage encryption" correctly at `nestingLevel: 1` sharing the sibling `listId`, with no leaked tab in `text`. However, this test's own 🔍 visual check now fails for a new reason: a Playwright screenshot of the result shows the **entire list rendered as unordered bullets (●/○) instead of numbers** — "Click Restore" is a bullet, not "3.". Confirmed via a control doc (identical markdown, no `create_paragraph_bullets` call) that the pre-repair list renders correctly numbered 1–6, so the repair call itself is what strips the numbering. Root cause: the fix's fixed algorithm applies one `bullet_preset` to the entire merged run (the requested paragraphs plus every already-listed neighbor it sweeps in as context) — since this test's own documented tool call doesn't pass `bullet_preset` (defaults to `BULLET_DISC_CIRCLE_SQUARE`), it silently overwrites the numbering of "Select the snapshot"/"Configure the instance"/"Click Restore" even though the caller never asked to touch those paragraphs' preset. The round 1 code-review's two non-blocking findings (uncaught `KeyError` on a malformed range, unvalidated negative `nesting_level`) are both fixed and confirmed live; the original multi-range-fragmentation finding is also fixed and confirmed live (3 single-paragraph ranges at depths 0/1/0 now correctly share one `listId`). Sent back to Dev (PR #524 comment) rather than approved.
+
+**Result (2026-08-06, round 3) ✅ PASS — re-verified live against fix commit `9ae16ee`.** Round 2's numbering regression is fixed: `create_paragraph_bullets` now reads the existing list's own glyph info from the document's `lists` map (`infer_preset`) when the caller doesn't pass `bullet_preset` explicitly, instead of defaulting to unordered bullets. Re-ran this test's exact documented call (no `bullet_preset`) — a Playwright screenshot confirms the list renders correctly: "1./2./3." for the top-level items, "a./b./c." for the promoted settings paragraphs, "Click Restore" still "3." All of this test's own checks pass. Also spot-checked the fix's new conflicting-preset validation: two directly-adjacent ranges with different explicit `bullet_preset`s split cleanly into two separate lists (no error, reasonable default); a mediated 3-paragraph case (two explicit, conflicting presets bridged by an already-listed paragraph with no explicit preset) correctly returns `{"error": "conflicting bullet_preset values among contiguous paragraphs..."}` as the docstring describes — the docstring's phrasing ("two explicitly-requested contiguous paragraphs") is a little imprecise about requiring same-run membership rather than literal adjacency in the caller's `ranges` list, but the behavior itself is correct and safe; noted as a non-blocking documentation nit, not filed as a ticket. Re-confirmed no regression on the original multi-range-fragmentation repro (3 single-paragraph ranges at depths 0/1/0 still land in one shared `listId` with correct depths). `qa-approved` applied.
+
+---
+
+### TC-DOC157: `delete_paragraph_bullets` removes list membership from a range, leaving paragraph text untouched ⚠️ destructive
+
+**Setup:** none — list created fresh by the call under test.
+
+**Prompt**
+> "Write this Markdown to doc {DOC_ID}: '- First item\n- Second item\n- Third item\n', then show me its structure."
+
+Tool calls: `write_doc_content(doc_id={DOC_ID}, content="- First item\n- Second item\n- Third item\n", content_format="markdown")`, then `get_doc_structure(doc_id={DOC_ID})` — note "Second item"'s `start_index`/`end_index`.
+
+Then: "Remove the bullet from just the second item, and show me the structure again."
+
+Tool calls: `delete_paragraph_bullets(doc_id={DOC_ID}, ranges=[{"start_index": <Second item start_index>, "end_index": <Second item end_index>}])`, then `get_doc_structure(doc_id={DOC_ID})` again.
+
+**Checks**
+- After the call: "First item" and "Third item" still have non-null `bullet` fields (unaffected)
+- "Second item"'s `bullet` field is now `null`
+- "Second item"'s `text` is still exactly "Second item\n" (unchanged)
+
+**Cleanup:** write fixture content back
+
+**Result (2026-08-06) ✅ PASS — run live against PR #524 (issue #334).** All three checks confirmed exactly as specified: "First item"/"Third item" kept their `bullet` field and shared `listId`, "Second item"'s `bullet` became `null`, and its `text` was unchanged.

{mcp_gee_sweet-0.8.2.dev259 → mcp_gee_sweet-0.8.2.dev263}/docs/roadmap.md

@@ -150,7 +150,7 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 - [x] `find_in_doc` — search doc text and return match locations, parallel to `find_in_spreadsheet`; removes the manual index math currently needed to retrofit links (or any style) onto text already in a doc, raised while fixing #248 (PR #353) ([#262](https://github.com/khuisman/mcp-gee-sweet/issues/262))
 - [x] Markdown-to-Doc image support — `![alt](path)` silently dropped today; local file path, `drive:<id>`, or HTTPS URL should all resolve to an inline image at the right position — deprioritized behind formatting fixes (#401/#402/#399, #403/#404) per user request; no lane assignment yet (PR #502) ([#333](https://github.com/khuisman/mcp-gee-sweet/issues/333))
 - [ ] `insert_inline_image` fails with the raw Google Docs API error ("The provided image is too large") for images over ~25 megapixels — no upfront size check, no mention of the actual limit or the image's own megapixel count; diagnosing required external tooling (`sips`) and prior knowledge of Google's ceiling. Same image codepath as #333 — deprioritized alongside it, no lane assignment yet ([#400](https://github.com/khuisman/mcp-gee-sweet/issues/400))
-- [ ] Expose paragraph list/nesting info in `get_doc_structure`, plus a tool to set/change bullet membership and nesting level on an existing range (`createParagraphBullets`/`deleteParagraphBullets` equivalent) — markdown converter currently flattens indented sub-lists into the parent list with no way to detect or fix it after the fact ([#334](https://github.com/khuisman/mcp-gee-sweet/issues/334))
+- [x] Expose paragraph list/nesting info in `get_doc_structure`, plus a tool to set/change bullet membership and nesting level on an existing range (`createParagraphBullets`/`deleteParagraphBullets` equivalent) — markdown converter currently flattens indented sub-lists into the parent list with no way to detect or fix it after the fact ([#334](https://github.com/khuisman/mcp-gee-sweet/issues/334)) (PR #524)
 - [x] Soft-break paragraph helper (single paragraph, multiple lines joined by soft breaks, explicit named style) + document `delete_doc_range`'s paragraph-merge-inherits-neighbor-style behavior ([#332](https://github.com/khuisman/mcp-gee-sweet/issues/332)) (PR #362)
 - [ ] `update_doc_from_file` — update an existing Doc in place from a local `.md`/`.html` file, reading server-side like `create_doc_from_file` instead of round-tripping full content through the caller's context; real friction confirmed live — reporter had to fake this via delete-then-recreate. Wants #401/#402 landed first so the same paragraph-collapse defects don't just resurface via the update path ([#341](https://github.com/khuisman/mcp-gee-sweet/issues/341))
 - [x] `style_doc_table_cells` applies `border_color`/`border_width`/`border_dash_style` uniformly to all four cell edges — no per-edge control (top/bottom/left/right independently), even though the Docs API's own `TableCellBorder` supports it; blocks the classic "signature line" (bottom-border-only) cell pattern. Queued for lane-b behind #409/#382's remaining defect chain (defect-before-enhancement precedent) ([#403](https://github.com/khuisman/mcp-gee-sweet/issues/403)) (PR #462)
@@ -169,7 +169,7 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 - [x] Expose `md5Checksum` in `list_files`/`get_file_metadata` for real content-diffing, and let `sync_folder` diff by checksum instead of/in addition to `modifiedTime` — mtime is unreliable across in-place overwrites, `upload_local_file`'s "now" stamp, and content-preserving regenerations; related to #239 (PR #472) ([#274](https://github.com/khuisman/mcp-gee-sweet/issues/274))
 - [x] Drive Activity API — file change history ([#72](https://github.com/khuisman/mcp-gee-sweet/issues/72))
 - [x] `upload_local_folder` doesn't route through `_upload_local_file`, so the `convert` capability (#188) is unreachable from bulk folder uploads — no way to bulk-import a folder of CSV/DOCX/PPTX into native Workspace formats. Same domain as #274, candidate for lane-a once #274 ships (PR #505) ([#411](https://github.com/khuisman/mcp-gee-sweet/issues/411))
-- [ ] Reconcile the two independent Drive-conversion mechanisms — `_upload_local_file`'s `_CONVERT_MIME` map and `upload_file`'s `convert_to_doc` param do the same thing (source mimetype upload + destination-metadata mimeType override) with no cross-reference; risk of drift as more conversion paths get added. Related to #411 ([#412](https://github.com/khuisman/mcp-gee-sweet/issues/412))
+- [x] Reconcile the two independent Drive-conversion mechanisms — `_upload_local_file`'s `_CONVERT_MIME` map and `upload_file`'s `convert_to_doc` param do the same thing (source mimetype upload + destination-metadata mimeType override) with no cross-reference; risk of drift as more conversion paths get added. Related to #411 ([#412](https://github.com/khuisman/mcp-gee-sweet/issues/412), PR #543)
 
 **Infrastructure**
 - [x] Harden concurrent-session access — fail-open on cache read/write errors, `busy_timeout` (PR #280) ([#234](https://github.com/khuisman/mcp-gee-sweet/issues/234))

{mcp_gee_sweet-0.8.2.dev259 → mcp_gee_sweet-0.8.2.dev263}/docs/tools.md

@@ -2,7 +2,7 @@
 
 <!-- Auto-generated by `scripts/gen_tool_docs.py` — do not edit by hand, your changes will be overwritten on the next commit. -->
 
-123 tools. All tool names are lowercase with underscores — use these exact strings with `ENABLED_TOOLS` or `--include-tools`.
+125 tools. All tool names are lowercase with underscores — use these exact strings with `ENABLED_TOOLS` or `--include-tools`.
 
 ## Sheets — data
 
@@ -150,6 +150,8 @@ Requires the `drive.activity.readonly` scope; uses the Drive Activity API v2.
 | `delete_table_column` | Delete a column from an existing table in a Google Doc. | `doc_id`, `table_start_index`, `column_index` |
 | `style_doc_range` | Apply paragraph and/or text styles to one or more index ranges in a Google Doc. | `doc_id`, `ranges` |
 | `style_doc_table_cells` | Apply border, padding, and background styles to table cells in a Google Doc. | `doc_id`, `table_start_index`, `cells` |
+| `create_paragraph_bullets` | Turn one or more paragraph ranges into a bulleted or numbered list, with explicit nesting depth (#334). | `doc_id`, `ranges` |
+| `delete_paragraph_bullets` | Remove list membership (bullets/numbering) from one or more paragraph ranges, leaving each paragraph's text and other styling untouched (#334). | `doc_id`, `ranges` |
 | `get_doc_theme` | Derive a theme dict from a Google Doc's actual paragraph styles. | `doc_id` |
 | `get_doc_named_styles` | Read a Google Doc's named style defaults and return them as a theme dict. | `doc_id` |
 | `apply_theme` | Apply a theme dict to a Google Doc by updating its named style definitions. | `doc_id`, `theme`, `overwrite?` |

{mcp_gee_sweet-0.8.2.dev259 → mcp_gee_sweet-0.8.2.dev263}/src/mcp_gee_sweet/tools/docs/content.py

@@ -1122,8 +1122,15 @@ def register(tool):
             - startIndex, endIndex
             Paragraphs also include namedStyleType, text, headingId (Google's internal
             ID for this heading, present only when namedStyleType is HEADING_1..6 —
-            e.g. "h.abc123"; null otherwise), and a runs list (each run has text,
-            bold, italic, underline, strikethrough, font_size, link_url).
+            e.g. "h.abc123"; null otherwise), a runs list (each run has text,
+            bold, italic, underline, strikethrough, font_size, link_url), and
+            bullet (null for a non-list paragraph; otherwise {listId,
+            nestingLevel} — nestingLevel is 0 for a top-level list item, absent
+            from the raw API response in that case, normalized to 0 here so
+            every list paragraph reports a level). Use this to detect a
+            markdown-to-Doc conversion that flattened an intended nested list
+            (#334) — sibling paragraphs that should differ in depth but share
+            the same nestingLevel — then fix it with create_paragraph_bullets.
             Tables include rows, columns, and a cells list (each cell has row, col,
             startIndex, endIndex, paragraphStartIndex, text).
 
@@ -1153,6 +1160,15 @@ def register(tool):
                 # would offer as a "Headings & bookmarks" link target (HEADING_1..6,
                 # and TITLE/SUBTITLE) — no client-side filtering needed here.
                 heading_id = pstyle.get("headingId")
+                bullet = para.get("bullet")
+                bullet_info = (
+                    {
+                        "listId": bullet.get("listId"),
+                        "nestingLevel": bullet.get("nestingLevel", 0),
+                    }
+                    if bullet
+                    else None
+                )
                 runs = []
                 for pe in para.get("elements", []):
                     tr = pe.get("textRun")
@@ -1179,6 +1195,7 @@ def register(tool):
                         "endIndex": elem.get("endIndex", 0),
                         "namedStyleType": named_style,
                         "headingId": heading_id,
+                        "bullet": bullet_info,
                         "text": "".join(r["text"] for r in runs),
                         "runs": runs,
                     }

{mcp_gee_sweet-0.8.2.dev259 → mcp_gee_sweet-0.8.2.dev263}/src/mcp_gee_sweet/tools/docs/style.py

@@ -460,6 +460,320 @@ def register(tool):
         logger.debug("style_doc_table_cells: %d requests in doc %s", len(requests), doc_id)
         return {"docId": doc_id, "requests": len(requests)}
 
+    @tool(annotations=ToolAnnotations(title="Create Paragraph Bullets", destructiveHint=True))
+    async def create_paragraph_bullets(
+        doc_id: str,
+        ranges: list[dict],
+        ctx: Context = None,
+    ) -> dict[str, Any]:
+        """
+        Turn one or more paragraph ranges into a bulleted or numbered list, with
+        explicit nesting depth (#334).
+
+        Wraps the Docs API's createParagraphBullets/deleteParagraphBullets
+        requests, working around two confirmed-live API quirks:
+
+        - createParagraphBullets is a no-op on a paragraph that's already
+          part of a list — it neither changes the existing nesting level nor
+          consumes any leading tab characters meant to signal a new one
+          (they're left behind as literal text). Every paragraph this tool
+          touches is deleteParagraphBullets'd first (harmless even if it
+          wasn't previously a list item) so createParagraphBullets always
+          applies to a clean, non-list paragraph.
+        - createParagraphBullets has no nestingLevel field of its own — the
+          API infers each paragraph's depth from its own leading tab
+          characters, but only relative to whatever ELSE is included in that
+          *same* call. A paragraph immediately adjacent to an existing list
+          item that call doesn't also cover gets pulled back to that
+          neighbor's level regardless of its own tabs (the same class of bug
+          PR #432 fixed in this project's own markdown-to-Doc converter).
+          To keep every requested paragraph's relative depth correct, this
+          tool fetches the document, resolves each requested range to the
+          paragraph(s) it covers, and — for any that are already part of a
+          list — expands the affected span to include their full contiguous
+          run of same-list neighbors (preserving each neighbor's own current
+          nesting level unchanged). Contiguous spans sharing one bullet
+          preset are then submitted as a single createParagraphBullets call
+          each, applied in descending document-position order so no
+          not-yet-processed span's indices are invalidated by an earlier
+          span's tab insertions.
+
+        Use get_doc_structure to obtain start_index/end_index for each target
+        range — typically one paragraph's own startIndex/endIndex, or a
+        contiguous span covering several (all promoted to the same
+        nesting_level/bullet_preset). For independent depths per paragraph,
+        pass one range per paragraph.
+
+        Args:
+            doc_id: The Google Doc file ID.
+            ranges: List of range dicts, each with:
+                start_index (int), end_index (int): from get_doc_structure —
+                    must overlap at least one existing paragraph.
+                bullet_preset (str, optional): "BULLET_DISC_CIRCLE_SQUARE"
+                    (unordered) or "NUMBERED_DECIMAL_ALPHA_ROMAN" (ordered) —
+                    the only two presets this codebase has confirmed live
+                    (see emitter.py). The Docs API defines additional
+                    glyph/numbering presets not exercised here; pass the
+                    literal API enum string to use one anyway. If omitted,
+                    an already-listed target paragraph keeps its existing
+                    list's own style (read from the document's own `lists`
+                    map) rather than silently being converted to a
+                    different one; a paragraph with no existing list falls
+                    back to "BULLET_DISC_CIRCLE_SQUARE".
+                nesting_level (int, optional): 0 = top-level (default), 1 =
+                    one level indented, etc. Must be >= 0.
+
+        Returns:
+            Confirmation with docId and count of batchUpdate requests sent.
+            {"error": ...} if ranges is empty, a nesting_level is negative, a
+            range doesn't overlap any paragraph, two explicitly-requested
+            contiguous paragraphs specify conflicting presets, or the Docs
+            API call fails.
+        """
+        lc = ctx.request_context.lifespan_context
+        if not ranges:
+            return {"error": "ranges list is empty"}
+        for r in ranges:
+            if r.get("nesting_level", 0) < 0:
+                return {"error": f"nesting_level must be >= 0, got {r['nesting_level']}"}
+
+        try:
+            doc = await execute_in_thread(
+                lc.docs_service.documents().get(documentId=doc_id).execute,
+                lc.docs_service,
+            )
+
+            doc_lists = doc.get("lists", {})
+
+            def infer_preset(bullet: dict | None) -> str | None:
+                # Reads the existing list's own glyph info (not just its
+                # listId/nestingLevel) so an already-listed paragraph's
+                # style is preserved rather than silently overridden by
+                # this tool's own default preset (#334 round 2).
+                if not bullet:
+                    return None
+                levels = (
+                    doc_lists.get(bullet.get("listId"), {})
+                    .get("listProperties", {})
+                    .get("nestingLevels", [])
+                )
+                level = bullet.get("nestingLevel", 0)
+                if level >= len(levels):
+                    return None
+                info = levels[level]
+                if "glyphType" in info:
+                    return "NUMBERED_DECIMAL_ALPHA_ROMAN"
+                if "glyphSymbol" in info:
+                    return "BULLET_DISC_CIRCLE_SQUARE"
+                return None
+
+            body_paragraphs = [
+                (
+                    elem.get("startIndex", 0),
+                    elem.get("endIndex", 0),
+                    elem["paragraph"].get("bullet"),
+                )
+                for elem in doc.get("body", {}).get("content", [])
+                if "paragraph" in elem
+            ]
+            by_start = {ps: (pe, b) for ps, pe, b in body_paragraphs}
+            by_end = {pe: (ps, b) for ps, pe, b in body_paragraphs}
+
+            requested: dict[tuple[int, int], dict] = {}
+            for r in ranges:
+                r_start, r_end = r["start_index"], r["end_index"]
+                preset_explicit = "bullet_preset" in r
+                nesting_level = r.get("nesting_level", 0)
+                covered = [
+                    (ps, pe, b) for ps, pe, b in body_paragraphs if ps < r_end and pe > r_start
+                ]
+                if not covered:
+                    return {"error": f"no paragraph overlaps range {r_start}-{r_end}"}
+                for ps, pe, bullet in covered:
+                    requested[(ps, pe)] = {
+                        "start": ps,
+                        "end": pe,
+                        "nesting_level": nesting_level,
+                        "preset": r.get("bullet_preset"),
+                        "preset_explicit": preset_explicit,
+                        "existing_bullet": bullet,
+                    }
+
+            # Expand each already-listed requested paragraph to include its
+            # full contiguous same-listId neighbor run (see docstring) —
+            # context paragraphs keep their own current nesting level and
+            # carry no explicit preset of their own (resolved per-run below).
+            expanded: dict[tuple[int, int], dict] = dict(requested)
+            for ps, pe, bullet in body_paragraphs:
+                key = (ps, pe)
+                if key not in requested or not bullet:
+                    continue
+                list_id = bullet.get("listId")
+
+                cursor = ps
+                while cursor in by_end:
+                    prev_start, prev_bullet = by_end[cursor]
+                    if not prev_bullet or prev_bullet.get("listId") != list_id:
+                        break
+                    pkey = (prev_start, cursor)
+                    if pkey not in expanded:
+                        expanded[pkey] = {
+                            "start": prev_start,
+                            "end": cursor,
+                            "nesting_level": prev_bullet.get("nestingLevel", 0),
+                            "preset": None,
+                            "preset_explicit": False,
+                            "existing_bullet": prev_bullet,
+                        }
+                    cursor = prev_start
+
+                cursor = pe
+                while cursor in by_start:
+                    next_end, next_bullet = by_start[cursor]
+                    if not next_bullet or next_bullet.get("listId") != list_id:
+                        break
+                    nkey = (cursor, next_end)
+                    if nkey not in expanded:
+                        expanded[nkey] = {
+                            "start": cursor,
+                            "end": next_end,
+                            "nesting_level": next_bullet.get("nestingLevel", 0),
+                            "preset": None,
+                            "preset_explicit": False,
+                            "existing_bullet": next_bullet,
+                        }
+                    cursor = next_end
+
+            units = sorted(expanded.values(), key=lambda u: u["start"])
+
+            # Group touching paragraphs into runs — each run gets exactly one
+            # createParagraphBullets call, since the API infers nesting level
+            # relative to siblings within that one call. Only an explicit,
+            # conflicting caller-specified preset breaks an otherwise-
+            # touching run; an unspecified (context or defaulted) preset
+            # never does, since it's resolved per-run below.
+            runs: list[list[dict]] = [[units[0]]]
+            for u in units[1:]:
+                last = runs[-1][-1]
+                conflicts = (
+                    u["preset_explicit"]
+                    and last["preset_explicit"]
+                    and u["preset"] != last["preset"]
+                )
+                if u["start"] == last["end"] and not conflicts:
+                    runs[-1].append(u)
+                else:
+                    runs.append([u])
+
+            requests: list[dict] = []
+            # Runs applied in descending document-position order so one
+            # run's tab insertions never invalidate a not-yet-processed
+            # run's own indices — same convention as insert_doc_text.
+            for run in sorted(runs, key=lambda run: run[0]["start"], reverse=True):
+                explicit_presets = {u["preset"] for u in run if u["preset_explicit"]}
+                if len(explicit_presets) > 1:
+                    return {
+                        "error": "conflicting bullet_preset values among contiguous "
+                        f"paragraphs at index {run[0]['start']}"
+                    }
+                if explicit_presets:
+                    resolved_preset = next(iter(explicit_presets))
+                else:
+                    resolved_preset = next(
+                        (p for u in run if (p := infer_preset(u["existing_bullet"])) is not None),
+                        "BULLET_DISC_CIRCLE_SQUARE",
+                    )
+
+                run_start = run[0]["start"]
+                run_end = run[-1]["end"]
+                requests.append(
+                    {
+                        "deleteParagraphBullets": {
+                            "range": {"startIndex": run_start, "endIndex": run_end}
+                        }
+                    }
+                )
+                for unit in sorted(run, key=lambda u: u["start"], reverse=True):
+                    if unit["nesting_level"]:
+                        requests.append(
+                            {
+                                "insertText": {
+                                    "location": {"index": unit["start"]},
+                                    "text": "\t" * unit["nesting_level"],
+                                }
+                            }
+                        )
+                total_tabs = sum(u["nesting_level"] for u in run)
+                requests.append(
+                    {
+                        "createParagraphBullets": {
+                            "range": {
+                                "startIndex": run_start,
+                                "endIndex": run_end + total_tabs,
+                            },
+                            "bulletPreset": resolved_preset,
+                        }
+                    }
+                )
+
+            await execute_in_thread(
+                lc.docs_service.documents()
+                .batchUpdate(documentId=doc_id, body={"requests": requests})
+                .execute,
+                lc.docs_service,
+            )
+        except Exception as e:
+            return {"error": str(e)}
+
+        lc.doc_cache.mark_dirty(doc_id)
+        logger.debug("create_paragraph_bullets: %d requests in doc %s", len(requests), doc_id)
+        return {"docId": doc_id, "requests": len(requests)}
+
+    @tool(annotations=ToolAnnotations(title="Delete Paragraph Bullets", destructiveHint=True))
+    async def delete_paragraph_bullets(
+        doc_id: str,
+        ranges: list[dict],
+        ctx: Context = None,
+    ) -> dict[str, Any]:
+        """
+        Remove list membership (bullets/numbering) from one or more paragraph
+        ranges, leaving each paragraph's text and other styling untouched (#334).
+
+        Args:
+            doc_id: The Google Doc file ID.
+            ranges: List of range dicts, each with start_index and end_index
+                (from get_doc_structure).
+
+        Returns:
+            Confirmation with docId and count of batchUpdate requests sent.
+        """
+        lc = ctx.request_context.lifespan_context
+        if not ranges:
+            return {"error": "ranges list is empty"}
+
+        requests = [
+            {
+                "deleteParagraphBullets": {
+                    "range": {"startIndex": r["start_index"], "endIndex": r["end_index"]}
+                }
+            }
+            for r in ranges
+        ]
+
+        try:
+            await execute_in_thread(
+                lc.docs_service.documents()
+                .batchUpdate(documentId=doc_id, body={"requests": requests})
+                .execute,
+                lc.docs_service,
+            )
+        except Exception as e:
+            return {"error": str(e)}
+
+        lc.doc_cache.mark_dirty(doc_id)
+        logger.debug("delete_paragraph_bullets: %d requests in doc %s", len(requests), doc_id)
+        return {"docId": doc_id, "requests": len(requests)}
+
     @tool(annotations=ToolAnnotations(title="Get Document Theme"))
     async def get_doc_theme(
         doc_id: str,

{mcp_gee_sweet-0.8.2.dev259 → mcp_gee_sweet-0.8.2.dev263}/tests/drive/test_transfer.py

@@ -746,6 +746,11 @@ class TestUploadLocalFolder:
         assert result["uploaded"] == []
         ctx.request_context.lifespan_context.drive_folder_cache.mark_dirty.assert_not_called()
 
+    async def test_missing_local_directory_raises(self, tmp_path):
+        drive_svc = MagicMock()
+        with pytest.raises(ValueError, match="No directory found"):
+            await self._tool()(str(tmp_path / "missing"), "folder1", ctx=self._ctx(drive_svc))
+
 
 class TestXlsxRangeValues:
     async def test_no_range_returns_all_rows(self):

{mcp_gee_sweet-0.8.2.dev259 → mcp_gee_sweet-0.8.2.dev263}/tests/test_docs_content.py

@@ -1433,6 +1433,51 @@ class TestGetDocStructureHeadingId:
         assert result["elements"][0]["headingId"] is None
 
 
+class TestGetDocStructureBullet:
+    """#334: get_doc_structure surfaces each paragraph's list membership/nesting."""
+
+    def _ctx(self, docs_svc):
+        return _make_ctx(docs_service=docs_svc)
+
+    def _doc(self, bullet=None):
+        para = {
+            "paragraphStyle": {"namedStyleType": "NORMAL_TEXT"},
+            "elements": [{"textRun": {"content": "Item\n", "textStyle": {}}}],
+        }
+        if bullet is not None:
+            para["bullet"] = bullet
+        return {
+            "documentId": "doc1",
+            "title": "Doc",
+            "body": {"content": [{"startIndex": 1, "endIndex": 10, "paragraph": para}]},
+        }
+
+    async def test_non_list_paragraph_has_null_bullet(self):
+        docs_svc = MagicMock()
+        docs_svc.documents.return_value.get.return_value.execute.return_value = self._doc()
+        result = await _docs_tools["get_doc_structure"](doc_id="doc1", ctx=self._ctx(docs_svc))
+        assert result["elements"][0]["bullet"] is None
+
+    async def test_list_paragraph_reports_bullet_and_nesting_level(self):
+        docs_svc = MagicMock()
+        docs_svc.documents.return_value.get.return_value.execute.return_value = self._doc(
+            bullet={"listId": "list1", "nestingLevel": 2}
+        )
+        result = await _docs_tools["get_doc_structure"](doc_id="doc1", ctx=self._ctx(docs_svc))
+        assert result["elements"][0]["bullet"] == {"listId": "list1", "nestingLevel": 2}
+
+    async def test_top_level_bullet_normalizes_missing_nesting_level_to_zero(self):
+        # The Docs API omits nestingLevel entirely for a top-level (depth 0)
+        # list item rather than sending an explicit 0 — get_doc_structure
+        # normalizes so every list paragraph reports a level.
+        docs_svc = MagicMock()
+        docs_svc.documents.return_value.get.return_value.execute.return_value = self._doc(
+            bullet={"listId": "list1"}
+        )
+        result = await _docs_tools["get_doc_structure"](doc_id="doc1", ctx=self._ctx(docs_svc))
+        assert result["elements"][0]["bullet"] == {"listId": "list1", "nestingLevel": 0}
+
+
 # ---------------------------------------------------------------------------
 # Heading-anchor resolution (#409): _has_pending_anchor_links,
 # _resolve_heading_anchors, and end-to-end via create_doc_from_file.