mcp-gee-sweet 0.7.0.dev49__tar.gz → 0.7.0.dev53__tar.gz

mcp_gee_sweet-0.7.0.dev53/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: gen-tool-docs
+        name: Regenerate tool docs
+        entry: uv run python scripts/gen_tool_docs.py
+        language: system
+        pass_filenames: false
+        files: ^(src/mcp_gee_sweet/tools/.*\.py|docs/tools\.md|docs/configuration\.md)$

{mcp_gee_sweet-0.7.0.dev49 → mcp_gee_sweet-0.7.0.dev53}/CLAUDE.md

@@ -81,3 +81,5 @@ Set `AUTH_METHOD` to pin a specific method with no fallback — removes ambiguit
 
 **MCP restart**: After `docker compose restart mcp-gee-sweet`, Claude Code does not automatically reconnect to the SSE server — you must restart Claude Code too to re-establish the connection.
 
+**Generated tool docs**: `docs/tools.md` and the "Tool filtering" section of `docs/configuration.md` are generated by `scripts/gen_tool_docs.py` from the tool source (names, signatures, docstrings) — do not hand-edit the tool tables in either file. The script is wired into `.pre-commit-config.yaml` and runs whenever a file under `src/mcp_gee_sweet/tools/` or either generated doc changes; it fails the commit if a tool has no docstring, if a tool doesn't match any section in the script's `SECTIONS` config, or if a `SUBSETS` entry references a renamed/removed tool name. Run it manually with `uv run python scripts/gen_tool_docs.py`.
+

{mcp_gee_sweet-0.7.0.dev49 → mcp_gee_sweet-0.7.0.dev53}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-gee-sweet
-Version: 0.7.0.dev49
+Version: 0.7.0.dev53
 Summary: MCP server for Google Workspace — Sheets, Drive, Docs, 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
@@ -27,7 +27,7 @@ Description-Content-Type: text/markdown
 ![GitHub License](https://img.shields.io/github/license/khuisman/mcp-gee-sweet)
 </div>
 
-An MCP server that gives AI clients reliable, direct access to Google Workspace — Sheets, Drive, Docs, and Calendar. 75 tools across four domains. Forked from [xing5/mcp-google-sheets](https://github.com/xing5/mcp-google-sheets) and expanded substantially.
+An MCP server that gives AI clients reliable, direct access to Google Workspace — Sheets, Drive, Docs, and Calendar. 84 tools across four domains. Forked from [xing5/mcp-google-sheets](https://github.com/xing5/mcp-google-sheets) and expanded substantially.
 
 **Install (stable):**
 ```bash

{mcp_gee_sweet-0.7.0.dev49 → mcp_gee_sweet-0.7.0.dev53}/README.md

@@ -5,7 +5,7 @@
 ![GitHub License](https://img.shields.io/github/license/khuisman/mcp-gee-sweet)
 </div>
 
-An MCP server that gives AI clients reliable, direct access to Google Workspace — Sheets, Drive, Docs, and Calendar. 75 tools across four domains. Forked from [xing5/mcp-google-sheets](https://github.com/xing5/mcp-google-sheets) and expanded substantially.
+An MCP server that gives AI clients reliable, direct access to Google Workspace — Sheets, Drive, Docs, and Calendar. 84 tools across four domains. Forked from [xing5/mcp-google-sheets](https://github.com/xing5/mcp-google-sheets) and expanded substantially.
 
 **Install (stable):**
 ```bash

{mcp_gee_sweet-0.7.0.dev49 → mcp_gee_sweet-0.7.0.dev53}/docs/configuration.md

@@ -14,6 +14,7 @@
 | `ENABLED_TOOLS` | Comma-separated list of tool names to register | all tools |
 | `CACHE_DB_PATH` | Path to the SQLite cache database | `/tmp/mcp_gee_sweet.db` |
 | `CACHE_TTL` | Cache time-to-live in seconds | `1800` (30 min) |
+| `MAX_GRID_DATA_RESPONSE_CHARS` | Safety cap on `get_sheet_data(include_grid_data=True)` response size, in characters. Raise to match a raised `MAX_MCP_OUTPUT_TOKENS` in your MCP client (roughly 2 characters per token observed for this densely-formatted JSON) | `40000` |
 | `HOST` | Bind address for SSE transport | `0.0.0.0` |
 | `PORT` | Port for SSE transport | `8000` |
 | `DEBUG_LEVEL` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` — controls package and access logs | — |
@@ -66,7 +67,9 @@ Access logs are emitted at `INFO` level — they appear when `DEBUG_LEVEL` is `D
 
 ## Tool filtering
 
-By default all 60 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.
+<!-- 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 84 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.7.0.dev53/docs/decisions/decision-grid-data-size-cap.md

@@ -0,0 +1,63 @@
+# Decision: Response-Size Safety Net for get_sheet_data(include_grid_data=True)
+
+**Date:** 2026-07-03
+**Snapshot commit:** branch `feat/issue-235-grid-data-range` — see `src/mcp_gee_sweet/tools/sheets/data.py`
+
+## Background
+
+Issue #235: `get_sheet_data(include_grid_data=True)` without a `range` fetches the sheet's full padded grid (often 1000x26 by default, regardless of actual content). In the reported case, the server-side Sheets API call succeeded (`200` in under a second), but the MCP client reported "Connection closed" — the failure was downstream of this server, in the client/transport layer, with no exception for the server to catch.
+
+## Options Considered
+
+### Option A: Require an explicit range
+
+Raise a `ValueError` if `include_grid_data=True` and `range` is omitted, forcing the caller to supply a bounded range up front.
+
+**Pros:** simplest possible fix; turns a silent transport failure into an immediate, actionable error.
+
+**Cons:** pushes the burden onto the caller (typically an LLM) to already know the sheet's used extent before it can safely ask for formatting — usually means an extra round-trip (a values-only call first) just to learn the range, spending tokens on something the server can trivially compute itself. Rejected as poor UX once raised in review.
+
+### Option B: Auto-detect used range + pre-fetch cell-count cap
+
+Auto-detect the used range from a values-only probe when `range` is omitted (removes the guesswork), and reject the request before fetching if the resolved range's cell count exceeds a fixed threshold (initially 2000 cells), estimated from the issue's own numbers (150 cells ≈ 107KB, ~713 bytes/cell).
+
+**Cons — falsified by live testing:** a live test against a real spreadsheet found cell count doesn't predict response size at all. A 26,000-cell **blank** range (a fresh sheet's default padding) returned almost nothing — Sheets omits `rowData` entirely for cells with no explicit formatting. A 1,300-cell range with real formatting applied (bold, background, number format) returned 983,982 characters and broke the session's own client. A pre-fetch estimate based on range shape can't distinguish these two cases; cutting the cap at any fixed cell count either blocks working requests (blank/lightly-formatted large ranges) or lets truly dangerous ones (small but densely-formatted ranges) through.
+
+### Option C: Auto-detect used range + post-fetch response-size check (chosen)
+
+Keep auto-detection (still correct and valuable — it prevents ever requesting formatting for irrelevant padding). Replace the pre-fetch cell-count estimate with a check on the **actual serialized response**, made after the Sheets API call completes (which is fast either way, per the issue's own account) but before returning it through the MCP tool response.
+
+A second live-testing round, this time applying real formatting and binary-searching range size against the session's own MCP client, found the actual failure point much lower than the cell-count-based guess would have suggested:
+
+| Cells | Characters | Result |
+|---|---|---|
+| 60 | (not captured — succeeded) | ✅ |
+| 65 | 51,208 | ❌ |
+| 75 | 58,784 | ❌ |
+| 100 | 77,694 | ❌ |
+| 500 | 380,494 | ❌ |
+| 1,300 | 983,982 | ❌ |
+
+This placed the real limit around 48,000–51,000 characters for that session — which matches Claude Code's documented default of 25,000 tokens per MCP tool response (`MAX_MCP_OUTPUT_TOKENS`), given this densely-nested, repeated-key JSON (`userEnteredFormat`, `backgroundColorStyle`, `rgbColor` on every cell) tokenizes at roughly 2 characters/token rather than the ~4 chars/token typical of prose.
+
+Two consequences follow directly from this finding:
+
+1. **The cap has to be measured, not estimated.** There's no way to know from range shape alone how formatted a range's cells are, so the check runs on `len(json.dumps(result))` after the fetch.
+2. **The cap has to be configurable, not fixed.** `MAX_MCP_OUTPUT_TOKENS` is a client-side setting the server has no visibility into — a different MCP client, or the same client with a raised limit, has a different real threshold. `MAX_GRID_DATA_RESPONSE_CHARS` (default `40000`, chosen with margin below the ~48-51K observed here) lets an operator match their own client's actual configuration.
+
+`local_path` (optional file/directory path) was added as an escape hatch that bypasses the cap entirely by writing the result to disk instead of returning it inline — this avoids the client output-token limit altogether, at the cost of the same server-filesystem-locality caveat `download_file`/`download_folder` already carry (meaningful for stdio and shared-volume SSE deployments; not useful for a remote SSE client with no shared filesystem).
+
+## Decision
+
+**Use Option C.** Auto-detect the used range when omitted; check the actual serialized response size after fetching, not an estimate beforehand; make the cap configurable via `MAX_GRID_DATA_RESPONSE_CHARS`; offer `local_path` as an unconditional bypass.
+
+The chosen default (`40000` characters) is explicitly documented in code as *one environment's observed limit, not a universal constant* — it should not be read as an authoritative number for all MCP clients.
+
+## Follow-up
+
+Issue #242 tracks generalizing this pattern (post-fetch size check + configurable cap + `local_path` bypass) to other tools that can return large responses (`export_file`, `get_doc_content`, `get_multiple_sheet_data`, etc.) — out of scope for #235's fix, which is deliberately scoped to the one tool named in the bug report. That follow-up also needs to address that `MAX_GRID_DATA_RESPONSE_CHARS` was named for its one-tool scope and won't generalize as-is.
+
+## When to Re-evaluate
+
+- If #242 generalizes this pattern, this decision's env var naming and per-tool scoping should be revisited together, not left as a precedent copied ad hoc.
+- If Claude Code's `MAX_MCP_OUTPUT_TOKENS` default changes, or another MCP client with a materially different limit becomes a primary consumer of this server, the default cap value should be re-measured rather than assumed to still be well-calibrated.

{mcp_gee_sweet-0.7.0.dev49 → mcp_gee_sweet-0.7.0.dev53}/docs/decisions/index.md

@@ -10,3 +10,4 @@ Point-in-time records of specific decisions — context, alternatives, and reaso
 | [Publishing Strategy](decision-publishing.md) | 2026-05-23 | draft | Two-track PyPI release (stable + edge); version injection open |
 | [Docs Formatting Architecture](decision-docs-formatting.md) | 2026-06-17 | decided | Two-layer approach (direct API tools + HTML abstraction via AST); phase plan for #41, #65–#70, #79–#82 |
 | [Chart Theming and Phase 3 Integration](decision-chart-theming.md) | 2026-06-17 | decided | No parsing layer for charts; no Vega-Lite adoption; unified brand config (docs + charts sections) for Phase 3 theme system |
+| [Grid Data Size Cap](decision-grid-data-size-cap.md) | 2026-07-03 | decided | Post-fetch response-size check (not pre-fetch cell-count estimate) for `get_sheet_data(include_grid_data=True)`; configurable cap + `local_path` bypass; empirically falsified two earlier approaches |

{mcp_gee_sweet-0.7.0.dev49 → mcp_gee_sweet-0.7.0.dev53}/docs/qa/tests/infra.md

@@ -19,6 +19,7 @@ Most infrastructure behaviours are verified by unit tests rather than live QA pr
 | TC-I15 (hot reload) | Manual / live QA only — known uvicorn + SSE limitation, observe and note |
 | TC-I16–I20 (logging) | ✅ Already live-tested and passed — see Result entries below |
 | DB recovery (issue #212) | Unit-tested in `tests/test_cache.py` `TestOpenFallback` — read-only file, read-only dir, and `:memory:` fallback all covered |
+| Tool doc generation (issue #94) | `scripts/gen_tool_docs.py` is a build-time/pre-commit script, not an MCP tool — no live prompt applies. Unit-tested in `tests/test_gen_tool_docs.py`: every registered tool is covered by a section and has a docstring, subset validation catches unknown tool names, and `main()` is idempotent on a second run |
 
 ---
 

{mcp_gee_sweet-0.7.0.dev49 → mcp_gee_sweet-0.7.0.dev53}/docs/qa/tests/sheets_read.md

@@ -34,14 +34,78 @@ Fixtures: see [`docs/qa/setup.md`](../setup.md). Substitute your `{SPREADSHEET_I
 
 ---
 
-### TC-R03: Grid data with formatting
+### TC-R03: Grid data with an explicit range
 
 **Prompt**
-> "Get the Sales sheet from {SPREADSHEET_ID} with full grid data including formatting"
+> "Get A1:D6 from the Sales sheet of {SPREADSHEET_ID} with full grid data including formatting"
 
 **Checks**
 - Response includes `rowData` field
 - `include_grid_data=True` was passed to the API (visible in raw response structure)
+- Call includes `range="A1:D6"` — no auto-detection probe request happens when a range is given
+
+---
+
+### TC-R03b: Grid data without a range auto-detects the used range (issue #235)
+
+**Setup**
+Call `get_sheet_data(spreadsheet_id={SPREADSHEET_ID}, sheet="Sales", include_grid_data=True)` — no `range` argument. The Sales sheet has 6 rows x 4 columns of actual content but Sheets' default padded grid is 1000x26.
+
+**Checks**
+- No error — the call succeeds
+- Server makes a values-only probe request first, then a grid-data request scoped to `A1:D6` — not the full padded grid
+- Response includes `rowData` only for the 6x4 used range, not ~26,000 padded cells
+- No "Connection closed" / oversized-response symptom (the original failure mode)
+
+**Result (2026-07-02) ✅ PASS**
+Called live against the actual Sales fixture (`gridProperties: rowCount=3016, columnCount=33`). Response's `rowData` covered exactly the 6x4 used range (header row + Widget/Gadget/Donut/Gizmo + Totals row, matching TC-R01's known fixture content) — confirmed scoped down from the sheet's real 3016x33 padding, not just the smaller 1000x26 default. No error, no truncation.
+
+---
+
+### TC-R03c: Densely formatted range over the safety cap raises a clear error (issue #235)
+
+**Setup**
+Apply formatting across a range with `format_cells(spreadsheet_id={SPREADSHEET_ID}, sheet="Sales", range="A1:Z200", bold=True, background_color={"red": 0.9, "green": 0.95, "blue": 1}, number_format_type="NUMBER")`, then call `get_sheet_data(spreadsheet_id={SPREADSHEET_ID}, sheet="Sales", range="A1:Z200", include_grid_data=True)`.
+
+Note: cell *count* alone doesn't predict this — a live test found a 26,000-cell blank range costs almost nothing (Sheets omits `rowData` for untouched cells), while densely-formatted ranges cost ~700-780 bytes/cell. The cap check runs on the actual serialized response, after the fetch, not an estimate from range size. A live binary search against Claude Code's default MCP client found the real failure point around 48,000-51,000 characters — consistent with Claude Code's documented 25,000-token default per-tool-response cap (`MAX_MCP_OUTPUT_TOKENS`) at ~2 chars/token for this kind of repeated-key JSON. The server-side default (`MAX_GRID_DATA_RESPONSE_CHARS=40000`) sits below that with margin.
+
+**Checks**
+- The Sheets API fetch itself succeeds (it's fast either way) — the error comes from the size check on the result, not a failed API call
+- Error message states the actual response size in characters, the cap, and mentions narrowing the range, `local_path`, or `MAX_GRID_DATA_RESPONSE_CHARS` as options
+- Clean up: remove the formatting from A1:Z200 afterward so it doesn't affect other test cases
+
+**Result (2026-07-02) ✅ PASS**
+Tested against a scratch sheet (temp tab, deleted after) rather than formatting the shared Sales fixture directly, to avoid leaving unwanted formatting on it — same effective setup (`format_cells(range="A1:Z1000", bold=True, background_color=..., number_format_type="NUMBER")`, then `get_sheet_data(range="A1:Z200", include_grid_data=True)`). Raised:
+`get_sheet_data(include_grid_data=True): the response is 4325100 characters, over the 40000-character safety cap. ... Narrow the range; pass local_path to write the result to disk instead of returning it inline (bypasses this cap); or set MAX_GRID_DATA_RESPONSE_CHARS if your MCP client can handle larger responses (e.g. a raised MAX_MCP_OUTPUT_TOKENS).`
+Exact size (4,325,100 chars) confirms the fetch completed before the check ran, as designed.
+
+---
+
+### TC-R03d: Grid data with local_path writes to disk instead of returning inline (issue #235)
+
+**Setup**
+Same formatted range as TC-R03c, but call `get_sheet_data(spreadsheet_id={SPREADSHEET_ID}, sheet="Sales", range="A1:Z200", include_grid_data=True, local_path="/tmp/qa_grid_data.json")`.
+
+**Checks**
+- Call succeeds (no cap error) despite the response exceeding the cap
+- Response is a small dict — `local_path`, `spreadsheet_id`, `sheet`, `range`, `bytes_written` — not the grid data itself
+- `/tmp/qa_grid_data.json` exists and contains the full grid-data JSON (`rowData` present, formatting visible)
+
+**Result (2026-07-02) ✅ PASS**
+Same scratch-sheet setup as TC-R03c. Call returned `{"local_path": "/tmp/qa_grid_data_235.json", "spreadsheet_id": "...", "sheet": "SizeTest235d", "range": "SizeTest235d!A1:Z200", "bytes_written": 4325100}` — no error despite exceeding the cap. Verified on disk: file exists, `wc -c` matches `bytes_written` exactly (4,325,100), and contains real `rowData` with formatting. Scratch sheet and temp file both cleaned up afterward.
+
+---
+
+### TC-R03e: MAX_GRID_DATA_RESPONSE_CHARS raises the cap (issue #235)
+
+**Setup**
+Set `MAX_GRID_DATA_RESPONSE_CHARS=200000` in server config and restart the server (e.g. to match a `MAX_MCP_OUTPUT_TOKENS` raised in your MCP client config). Repeat the same call as TC-R03c: a formatted range whose response is over the *default* 40,000-character cap but under 200,000.
+
+**Checks**
+- Call now succeeds instead of raising — confirms the cap is actually read from the env var, not hardcoded
+- Restore `MAX_GRID_DATA_RESPONSE_CHARS` (unset it) after this test
+
+**Result:** ⏳ Pending — not yet live-tested. Unlike TC-R03b-d, this requires a server restart with a changed env var (not just an MCP reconnect), which wasn't done this pass. Covered by unit tests (`test_cap_is_configurable`, `test_env_var_sets_cap_at_import_time` in `tests/sheets/test_data.py`) in the meantime.
 
 ---
 

{mcp_gee_sweet-0.7.0.dev49 → mcp_gee_sweet-0.7.0.dev53}/docs/roadmap.md

@@ -32,8 +32,9 @@ Features are ordered by practical priority within each tier, cross-domain. Items
 | Version | Scope | Signal |
 |---------|-------|--------|
 | **v0.7.0** | ✅ First stable PyPI release — 63 tools across Sheets, Drive, Docs, Calendar | Published 2026-06-21 |
-| **v0.8.0** | Tier 1 complete — all "frequently needed" items across all domains (~14 tools) | "Complete for everyday use" |
-| **v0.9.0** | Tier 2 complete — power-user and structured-work layer (~20 tools) | Covers most real workflows |
+| **v0.8.0** | ✅ Tier 1 complete — all "frequently needed" items across all domains (84 tools) | Published 2026-06-29 |
+| **v0.8.1** | Defect & documentation cleanup — no new tools, ships the QA/refactor work already on `develop` plus fixes for #235, #213, #239, #236 | Stabilizes before Tier 2 feature work begins |
+| **v0.9.0** | Tier 2 complete — power-user and structured-work layer, features only (~20 tools) | Covers most real workflows |
 | **v1.0.0** | API stability declaration — Tier 3 items that make the cut + any breaking cleanups from v0.8–0.9 | Backwards-compatibility commitment |
 | **v1.1.0+** | Future domains — Tasks, Gmail (separate minor releases, each needs a new API client) | Expanded scope |
 
@@ -70,7 +71,26 @@ Tier 4 items remain backlog with no assigned version.
 - [x] `list_recent_files` — files recently accessed or modified ([#136](https://github.com/khuisman/mcp-gee-sweet/issues/136))
 - [x] `get_storage_quota` — Drive storage usage and limits ([#137](https://github.com/khuisman/mcp-gee-sweet/issues/137))
 
-### Tier 2 — Useful for structured work _(target: v0.9.0)_
+### v0.8.1 — Defect & documentation cleanup _(target: v0.8.1, before Tier 2 begins)_
+
+No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature work.
+
+**Already on `develop`, awaiting release**
+- [x] Playwright per-test tagging policy, conductor prompt improvements (PR #228)
+- [x] QA test case fixes — `share_file` fixtures, TC-D148 setup, Playwright tags (PR #229)
+- [x] SQLite cache defensive recovery from read-only/corrupted DB files at connect time (PR #230)
+- [x] `tools/docs/__init__.py` split into `content.py`/`tables.py`/`style.py`/`layout.py` (PR #232)
+
+**Remaining defects to fix before cutting the release**
+- [ ] `get_sheet_data(include_grid_data=True)` without a range fetches the full padded grid instead of the used range ([#235](https://github.com/khuisman/mcp-gee-sweet/issues/235))
+- [ ] `create_doc_from_file` markdown `$` escape renders as literal backslash+dollar in the doc ([#213](https://github.com/khuisman/mcp-gee-sweet/issues/213))
+- [ ] Unknown tool parameters are silently dropped instead of raising a validation error — FastMCP's generated pydantic arg models default to ignoring extra fields, so a typo'd kwarg (e.g. `parent_id` instead of `parent_folder_id`) silently falls back to default behavior instead of erroring ([#239](https://github.com/khuisman/mcp-gee-sweet/issues/239))
+- [x] Auto-generate `docs/tools.md` from tool source as a pre-commit hook — makes the manual tools.md backfill in #236 unnecessary (PR #240) ([#94](https://github.com/khuisman/mcp-gee-sweet/issues/94))
+- [ ] Correct `docs/roadmap.md`'s own tool catalog counts, `known-limitations.md`'s `list_all_events` entry, and rework README's/`docs/client-setup.md`'s Configuration examples to lead with OAuth (not service account) for local/dev quick-start — currently mismatches the project's own auth priority order and PyPI's page inherits it verbatim ([#236](https://github.com/khuisman/mcp-gee-sweet/issues/236))
+- [ ] Rewrite `CONTRIBUTING.md` — fix broken links to removed README anchors, fix stale "Available Tool Names" and `bug`-label references, add better local-dev setup examples including observability (`DEBUG_LEVEL`/`LOG_FILE`/`ACCESS_LOG_FILE`) ([#95](https://github.com/khuisman/mcp-gee-sweet/issues/95))
+- [ ] Define and document community PR expectations — template, testing bar for non-tool PRs, scope/size convention, CLA/DCO/code-of-conduct decision, review turnaround ([#237](https://github.com/khuisman/mcp-gee-sweet/issues/237))
+
+### Tier 2 — Useful for structured work, features only _(target: v0.9.0)_
 
 **Sheets**
 - [ ] `update_borders` — border style, width, color on a range ([#122](https://github.com/khuisman/mcp-gee-sweet/issues/122)) _(freema/mcp-gsheets)_
@@ -79,18 +99,21 @@ Tier 4 items remain backlog with no assigned version.
 - [ ] `add_data_validation` / `get_data_validation` — dropdowns, checkboxes, value constraints ([#125](https://github.com/khuisman/mcp-gee-sweet/issues/125)) _(freema/mcp-gsheets)_
 - [ ] `update_sheet_properties` — tab color, hide/show gridlines ([#126](https://github.com/khuisman/mcp-gee-sweet/issues/126)) _(freema/mcp-gsheets)_
 - [ ] `duplicate_sheet` — copy a sheet within the same spreadsheet ([#127](https://github.com/khuisman/mcp-gee-sweet/issues/127))
+- [ ] Partial (rich-text) hyperlinks in `update_cells` ([#89](https://github.com/khuisman/mcp-gee-sweet/issues/89))
+- [ ] `import_csv_to_sheet` — populate a spreadsheet from a local CSV file ([#187](https://github.com/khuisman/mcp-gee-sweet/issues/187))
 
 **Calendar**
 - [ ] `create_calendar` / `update_calendar` / `delete_calendar` — calendar lifecycle ([#156](https://github.com/khuisman/mcp-gee-sweet/issues/156))
 - [ ] `add_calendar_to_list` / `remove_calendar_from_list` — subscribe/unsubscribe ([#157](https://github.com/khuisman/mcp-gee-sweet/issues/157))
 - [ ] Calendar ACL — share a calendar with users or groups ([#158](https://github.com/khuisman/mcp-gee-sweet/issues/158))
+- [ ] `list_all_events` — query all subscribed calendars in parallel _(decision needed — also tracked in Decisions Needed)_ ([#194](https://github.com/khuisman/mcp-gee-sweet/issues/194))
 
 **Docs**
 - [ ] `insert_page_break` — explicit page break at an index ([#148](https://github.com/khuisman/mcp-gee-sweet/issues/148))
 - [ ] `merge_table_cells` — merge cells in an existing table (distinct from write-time colspan) ([#150](https://github.com/khuisman/mcp-gee-sweet/issues/150))
 - [ ] Comments API — list, add, resolve doc comments ([#151](https://github.com/khuisman/mcp-gee-sweet/issues/151))
 - [ ] `create_named_range` / `create_bookmark` — anchor points for internal links ([#152](https://github.com/khuisman/mcp-gee-sweet/issues/152))
-- [ ] Rowspan emitter — AST `Cell.rowspan` field exists but emitter does not yet merge rows
+- [ ] Rowspan emitter — AST `Cell.rowspan` field exists but emitter does not yet merge rows ([#195](https://github.com/khuisman/mcp-gee-sweet/issues/195))
 - [ ] Warn/error on mixed text + nested table in same cell ([#108](https://github.com/khuisman/mcp-gee-sweet/issues/108))
 - [ ] colspan/rowspan inside nested tables ([#109](https://github.com/khuisman/mcp-gee-sweet/issues/109))
 
@@ -99,8 +122,13 @@ Tier 4 items remain backlog with no assigned version.
 - [ ] `star_file` / `unstar_file` — mark files with a star for easy retrieval ([#139](https://github.com/khuisman/mcp-gee-sweet/issues/139))
 - [ ] `transfer_ownership` — transfer a file to another user ([#140](https://github.com/khuisman/mcp-gee-sweet/issues/140))
 - [ ] `create_shortcut` — create a Drive shortcut to a file ([#141](https://github.com/khuisman/mcp-gee-sweet/issues/141))
+- [ ] `sync_folder` — option to convert markdown files to Google Docs on upload ([#211](https://github.com/khuisman/mcp-gee-sweet/issues/211))
+- [ ] `upload_local_file` with Drive format conversion (CSV→Sheets, MD→Docs) ([#188](https://github.com/khuisman/mcp-gee-sweet/issues/188))
 - [x] Drive Activity API — file change history ([#72](https://github.com/khuisman/mcp-gee-sweet/issues/72))
 
+**Infrastructure**
+- [ ] Cache reliability & configurability — runtime-configurable TTL, smarter invalidation for shared files ([#99](https://github.com/khuisman/mcp-gee-sweet/issues/99)); harden concurrent-session access — fail-open on cache read/write errors, `busy_timeout` ([#234](https://github.com/khuisman/mcp-gee-sweet/issues/234))
+
 ### Tier 3 — Advanced / occasionally needed _(target: v1.0.0)_
 
 **Sheets**
@@ -138,6 +166,23 @@ Tier 4 items remain backlog with no assigned version.
 - [ ] Working location / OOO / Focus time events ([#164](https://github.com/khuisman/mcp-gee-sweet/issues/164))
 - [ ] Watch notifications — webhook push on calendar or event changes ([#165](https://github.com/khuisman/mcp-gee-sweet/issues/165))
 
+### Decisions Needed — blocking backlog _(no assigned version)_
+
+Design questions raised during Phase 1 QA that need a deliberate product/API decision rather than just code. Each blocks whichever tool it names until resolved — pick these up opportunistically alongside the tool they affect, or dedicate a pass to clear the backlog.
+
+- [ ] `get_sheet_data` on an unknown sheet — exception vs structured error ([#31](https://github.com/khuisman/mcp-gee-sweet/issues/31))
+- [ ] `batch_update_cells` empty input — validation error vs silent no-op ([#32](https://github.com/khuisman/mcp-gee-sweet/issues/32))
+- [ ] `add_rows` count cap — accept unlimited or enforce a maximum ([#33](https://github.com/khuisman/mcp-gee-sweet/issues/33))
+- [ ] `rename_sheet` same-name — skip the API call or always round-trip ([#34](https://github.com/khuisman/mcp-gee-sweet/issues/34))
+- [ ] `create_sheet` duplicate title — API error or auto-suffix ([#35](https://github.com/khuisman/mcp-gee-sweet/issues/35))
+- [ ] Hide Drive-create tools from the toolset when service account auth is detected ([#36](https://github.com/khuisman/mcp-gee-sweet/issues/36))
+- [ ] `list_spreadsheets` with no folder — all accessible or Drive root ([#37](https://github.com/khuisman/mcp-gee-sweet/issues/37))
+- [ ] Validate ownership before `share_spreadsheet` / `share_file` ([#38](https://github.com/khuisman/mcp-gee-sweet/issues/38))
+- [ ] `search_spreadsheets` empty query — return all or require non-empty input ([#39](https://github.com/khuisman/mcp-gee-sweet/issues/39))
+- [ ] `get_file_metadata` size field for Workspace files — normalize or document ([#40](https://github.com/khuisman/mcp-gee-sweet/issues/40))
+- [ ] `rows_to_fetch=0` — clamp to 1 or return all rows ([#78](https://github.com/khuisman/mcp-gee-sweet/issues/78))
+- [ ] `list_all_events` — how to handle per-calendar failures when querying in parallel (partial results vs fail-fast) ([#194](https://github.com/khuisman/mcp-gee-sweet/issues/194))
+
 ---
 
 ## Bugs found in Phase 1 QA run (2026-06-02)
@@ -183,6 +228,7 @@ The test expected the API to silently truncate a 2D array that's wider than the
 - [x] Google Docs tools (all 13) — `docs.md`
 - [x] Calendar tools — `calendar.md`
 - [x] Infrastructure — `infra.md`
+- [ ] QA gaps targeted for v0.9 — second Drive folder fixture ([#44](https://github.com/khuisman/mcp-gee-sweet/issues/44)), shared drive coverage ([#48](https://github.com/khuisman/mcp-gee-sweet/issues/48)), domain/public sharing coverage ([#49](https://github.com/khuisman/mcp-gee-sweet/issues/49)), local-filesystem coverage ([#50](https://github.com/khuisman/mcp-gee-sweet/issues/50)), environment-constraint coverage ([#53](https://github.com/khuisman/mcp-gee-sweet/issues/53)), image fixtures for `insert_inline_image` ([#224](https://github.com/khuisman/mcp-gee-sweet/issues/224)), dedicated QA Google account ([#225](https://github.com/khuisman/mcp-gee-sweet/issues/225)), OAuth all-scopes token for faster setup ([#226](https://github.com/khuisman/mcp-gee-sweet/issues/226)), disposition of v0.8.0 SKIP entries ([#227](https://github.com/khuisman/mcp-gee-sweet/issues/227))
 - See [GitHub Issues (label: qa)](https://github.com/khuisman/mcp-gee-sweet/issues?q=label%3Aqa) for open QA gaps and fixture issues
 
 ---

mcp_gee_sweet-0.7.0.dev53/docs/tools.md

@@ -0,0 +1,168 @@
+# Tool Reference
+
+<!-- Auto-generated by `scripts/gen_tool_docs.py` — do not edit by hand, your changes will be overwritten on the next commit. -->
+
+84 tools. All tool names are lowercase with underscores — use these exact strings with `ENABLED_TOOLS` or `--include-tools`.
+
+## Sheets — data
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `get_sheet_data` | Get data from a specific sheet in a Google Spreadsheet. | `spreadsheet_id`, `sheet`, `range?`, `include_grid_data?`, `local_path?` |
+| `get_sheet_formulas` | Get formulas from a specific sheet in a Google Spreadsheet. | `spreadsheet_id`, `sheet`, `range?` |
+| `get_multiple_sheet_data` | Get data from multiple specific ranges in Google Spreadsheets. | `queries` |
+| `get_multiple_spreadsheet_summary` | Get a summary of multiple Google Spreadsheets, including sheet names, headers, and the first few rows of data for each sheet. | `spreadsheet_ids`, `rows_to_fetch?` |
+| `find_in_spreadsheet` | Find cells containing a specific value in a Google Spreadsheet. | `spreadsheet_id`, `query`, `sheet?`, `case_sensitive?`, `max_results?` |
+| `clear_values` | Clear cell content in a range without touching formatting. | `spreadsheet_id`, `sheet`, `range?` |
+| `update_cells` | Update cells in a Google Spreadsheet. | `spreadsheet_id`, `sheet`, `range`, `data` |
+| `batch_update_cells` | Batch update multiple ranges in a Google Spreadsheet. | `spreadsheet_id`, `sheet`, `ranges` |
+| `batch_update` | Execute a batch update on a Google Spreadsheet using the full batchUpdate endpoint. This provides access to all batchUpdate operations including adding sheets, updating properties, inserting/deleting dimensions, formatting, and more. | `spreadsheet_id`, `requests` |
+
+`batch_update` is the escape hatch for anything not covered by a named tool (formatting, conditional formatting, dimension properties, etc.).
+
+## Sheets — structure
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `list_sheets` | List all sheets in a Google Spreadsheet. | `spreadsheet_id` |
+| `copy_sheet` | Copy a sheet from one spreadsheet to another. | `src_spreadsheet`, `src_sheet`, `dst_spreadsheet`, `dst_sheet` |
+| `rename_sheet` | Rename a sheet in a Google Spreadsheet. | `spreadsheet`, `sheet`, `new_name` |
+| `create_sheet` | Create a new sheet tab in an existing Google Spreadsheet. | `spreadsheet_id`, `title` |
+| `add_rows` | Add rows to a sheet in a Google Spreadsheet. | `spreadsheet_id`, `sheet`, `count`, `start_row?` |
+| `add_columns` | Add columns to a sheet in a Google Spreadsheet. | `spreadsheet_id`, `sheet`, `count`, `start_column?` |
+| `delete_sheet` | Delete a sheet tab from a Google Spreadsheet. | `spreadsheet_id`, `sheet` |
+| `delete_rows` | Delete rows from a sheet. | `spreadsheet_id`, `sheet`, `start_row`, `end_row?` |
+| `delete_columns` | Delete columns from a sheet. | `spreadsheet_id`, `sheet`, `start_column`, `end_column?` |
+| `format_cells` | Apply formatting to a cell range (background color, font, alignment, number format). | `spreadsheet_id`, `sheet`, `range`, `bold?`, `italic?`, `strikethrough?`, `font_size?`, `font_color?`, `background_color?`, `horizontal_alignment?`, `vertical_alignment?`, `number_format_type?`, `number_format_pattern?` |
+| `merge_cells` | Merge a range of cells into one cell. | `spreadsheet_id`, `sheet`, `range`, `merge_type?` |
+| `unmerge_cells` | Unmerge all merged cells in a range. | `spreadsheet_id`, `sheet`, `range` |
+| `freeze` | Freeze rows and/or columns in a sheet. | `spreadsheet_id`, `sheet`, `rows?`, `columns?` |
+| `sort_range` | Sort a range by one or more columns. | `spreadsheet_id`, `sheet`, `range`, `sort_order?` |
+| `add_chart` | Add a chart to a Google Spreadsheet. | `spreadsheet_id`, `sheet`, `chart_type`, `data_range`, `title?`, `x_axis_label?`, `y_axis_label?`, `position_x?`, `position_y?`, `width?`, `height?` |
+
+`add_chart` supports types: `COLUMN`, `BAR`, `LINE`, `AREA`, `PIE`, `SCATTER`, `COMBO`, `HISTOGRAM`.
+
+## Spreadsheets (Drive-level)
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `create_spreadsheet` | Create a new Google Spreadsheet. | `title`, `folder_id?` |
+| `list_spreadsheets` | List all spreadsheets in the specified Google Drive folder. If no folder is specified, uses the configured default folder or lists from 'My Drive'. | `folder_id?` |
+| `search_spreadsheets` | Search for spreadsheets in Google Drive by name or content. | `query`, `max_results?` |
+
+`create_spreadsheet` cannot create files in a personal Drive when using service account auth — use OAuth or a Shared Drive.
+
+## Drive — files
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `list_folders` | List all folders in the specified Google Drive folder. If no parent folder is specified, lists folders from 'My Drive' root. | `parent_folder_id?` |
+| `list_drives` | List shared (Team) Drives accessible to the authenticated account. | `query?`, `max_results?` |
+| `list_files` | List files in a Google Drive folder, optionally filtered by MIME type. | `folder_id`, `mime_type?`, `max_results?` |
+| `search_files` | Search for files in Google Drive by name or content. | `query`, `mime_type?`, `folder_id?`, `max_results?` |
+| `get_file_metadata` | Get metadata for any file or folder in Google Drive. | `file_id` |
+| `create_folder` | Create a new folder in Google Drive. | `name`, `parent_folder_id?` |
+| `copy_file` | Copy a file in Google Drive. | `file_id`, `new_name?`, `folder_id?` |
+| `move_file` | Move a file or folder to a different folder in Google Drive. | `file_id`, `destination_folder_id` |
+| `rename_file` | Rename a file or folder in Google Drive. | `file_id`, `new_name` |
+| `list_shared_with_me` | List files explicitly shared with the authenticated user. | `mime_type?`, `max_results?` |
+| `list_recent_files` | List recently modified files in Drive, newest first. | `max_results?`, `days?`, `mime_type?` |
+| `get_storage_quota` | Get Drive storage usage and limits for the authenticated account. | — |
+| `delete_file` | Move a file to the trash or permanently delete it. | `file_id`, `permanent?` |
+
+## Drive — transfer
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `export_file` | Export or download a file from Google Drive. | `file_id`, `export_format` |
+| `list_revisions` | List available revisions for a Google Drive file (Sheets, Docs, or any file). | `file_id` |
+| `export_revision` | Export a historical revision of a Google Sheets file and return its cell data. | `file_id`, `revision_id`, `range?`, `sheet?` |
+| `upload_file` | Upload a text file to Google Drive, optionally converting it to a Google Doc. | `name`, `content`, `source_format?`, `folder_id?`, `convert_to_doc?` |
+| `upload_local_file` | Upload a file from the local filesystem to a Google Drive folder. Handles binary and text files (images, PDFs, DOCX, XLSX, scripts, etc.). | `local_path`, `parent_folder_id`, `name?`, `skip_if_exists?` |
+| `upload_local_folder` | Upload all files in a local directory (non-recursive) to a Google Drive folder. | `local_path`, `parent_folder_id`, `skip_if_exists?`, `skip_system_files?` |
+| `download_file` | Download a file from Google Drive to the local filesystem. | `file_id`, `local_path`, `export_format?` |
+| `download_folder` | Download all files in a Google Drive folder (non-recursive) to a local directory. | `folder_id`, `local_path`, `export_format?`, `mime_type_filter?`, `skip_if_exists?` |
+| `sync_folder` | Sync files between a Google Drive folder and a local directory. | `folder_id`, `local_path`, `direction?`, `export_format?`, `skip_system_files?`, `dry_run?` |
+
+## Drive — sharing
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `share_spreadsheet` | Share a Google Spreadsheet with multiple users via email, assigning specific roles. | `spreadsheet_id`, `recipients`, `send_notification?` |
+| `list_permissions` | List all permissions on a file or folder in Google Drive. | `file_id` |
+| `update_permission` | Change the role on an existing permission for a file or folder. | `file_id`, `permission_id`, `role` |
+| `remove_permission` | Revoke a permission on a file or folder. | `file_id`, `permission_id` |
+| `share_file` | Share any file or folder with one or more principals. | `file_id`, `permissions`, `send_notification?` |
+
+`share_spreadsheet`'s `recipients` is a list of `{email_address, role}` objects. Valid roles: `reader`, `commenter`, `writer`, `owner`.
+
+`share_file`'s `permissions` is a list of `{type, role, ...}` objects — `type` is `user`, `group`, `domain`, or `anyone`; `user`/`group` also need `email_address`, `domain` needs `domain`. Valid roles: `reader`, `commenter`, `writer`.
+
+## Drive — activity
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `list_file_activity` | Return the activity timeline for a Google Drive file. | `file_id`, `page_size?`, `page_token?` |
+
+Requires the `drive.activity.readonly` scope; uses the Drive Activity API v2.
+
+## Docs
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `create_doc` | Create a new Google Doc, optionally with initial content. | `title`, `content?`, `folder_id?`, `content_format?` |
+| `create_doc_from_file` | Create a Google Doc from a local .md or .html file. | `local_path`, `title?`, `folder_id?` |
+| `get_doc_content` | Get the plain text content of a Google Doc. | `file_id` |
+| `write_doc_content` | Replace the full content of an existing Google Doc. | `doc_id`, `content`, `content_format?` |
+| `get_doc_structure` | Return the full structural map of a Google Doc body with element indices. | `doc_id` |
+| `insert_doc_text` | Insert text at one or more positions in a Google Doc. | `doc_id`, `insertions` |
+| `delete_doc_range` | Delete one or more content ranges from a Google Doc. | `doc_id`, `deletions` |
+| `insert_inline_image` | Insert an inline image at a specific index in a Google Doc. | `doc_id`, `index`, `uri?`, `drive_file_id?`, `width?`, `height?` |
+| `insert_doc_table` | Insert an empty table at a specific position in a Google Doc. | `doc_id`, `index`, `rows`, `columns` |
+| `insert_table_row` | Insert a row into an existing table in a Google Doc. | `doc_id`, `table_start_index`, `row_index`, `insert_below?` |
+| `delete_table_row` | Delete a row from an existing table in a Google Doc. | `doc_id`, `table_start_index`, `row_index` |
+| `insert_table_column` | Insert a column into an existing table in a Google Doc. | `doc_id`, `table_start_index`, `column_index`, `insert_right?` |
+| `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` |
+| `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?` |
+| `create_header` | Add a page header to a Google Doc. | `doc_id`, `header_type?`, `content?` |
+| `create_footer` | Add a page footer to a Google Doc. | `doc_id`, `footer_type?`, `content?` |
+
+`write_doc_content` accepts HTML and converts it to Docs API requests via the HTML→AST→emitter pipeline. See [Docs AST Pipeline](design/docs-ast-pipeline.md) for the design.
+
+`create_doc` cannot create files in a personal Drive when using service account auth — see [Authentication](auth.md#method-a-service-account-recommended-for-servers).
+
+## Calendar
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `list_calendars` | List all calendars accessible to the authenticated user. | — |
+| `get_calendar` | Fetch metadata for a single calendar. | `calendar_id` |
+| `list_events` | List events in a calendar. | `calendar_id`, `time_min?`, `time_max?`, `query?`, `max_results?`, `expand_recurring?` |
+| `get_event` | Fetch a single event by calendar ID and event ID. | `calendar_id`, `event_id` |
+| `create_event` | Create a new event in a calendar. | `calendar_id`, `summary`, `start`, `end`, `description?`, `location?`, `attendees?`, `timezone?`, `recurrence?` |
+| `update_event` | Update fields on an existing event using a partial update (patch semantics). Only the fields you provide are changed; omitted fields are left as-is. | `calendar_id`, `event_id`, `summary?`, `start?`, `end?`, `description?`, `location?`, `attendees?`, `timezone?`, `recurrence?` |
+| `delete_event` | Delete or cancel an event. | `calendar_id`, `event_id` |
+| `find_free_slots` | Query busy times for a list of calendars and return free slots within the window. | `calendar_ids`, `time_min`, `time_max`, `timezone?` |
+
+**Note:** when using service account auth, calendars must be explicitly shared with the service account. The service account must also subscribe to shared calendars via `calendarList().insert()` before they appear in `list_calendars`.
+
+## Cache
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `refresh_cache` | Invalidate caches, forcing a fresh fetch on next use. | `spreadsheet_id?`, `doc_id?`, `folder_id?`, `calendar_id?` |
+
+Omit all parameters to flush the entire cache. See [Configuration](configuration.md#caching) for TTL and path settings.
+
+## MCP resources
+
+Two resources are available (read-only, not tools):
+
+| Resource | Description |
+|---|---|
+| `server://auth-status` | Active auth method and Drive capability limits |
+| `spreadsheet://{spreadsheet_id}/info` | Sheet list and grid properties for a spreadsheet |