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

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

@@ -48,6 +48,7 @@ Logic is split across `src/mcp_gee_sweet/`: `server.py` (MCP setup, tool decorat
   - `docs/emitter.py` — AST→Docs API requests + multi-phase table fill including nested table and cell styling support
 - `tools/cache.py` — `refresh_cache`
 - `tools/calendar.py` — Calendar API tools
+- `tools/response_limits.py` — shared response-size safety net (`enforce_response_size_cap`, `write_capped_result_to_disk`); imported cross-package the same way `tools/drive/__init__.py`'s `_SA_QUOTA_ERROR` is. Cap configured via `MAX_TOOL_RESPONSE_CHARS` (default 40000); see `docs/decisions/decision-response-size-cap-generalization.md`
 
 `__init__.py` loads `src/mcp_gee_sweet/.env` via `python-dotenv` before importing `server`, so env vars from that file are in `os.environ` by the time any module-level `os.environ.get()` runs. Priority: real env var > `.env` > default.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-gee-sweet
-Version: 0.7.0.dev53
+Version: 0.7.0.dev55
 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

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

@@ -14,7 +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` |
+| `MAX_TOOL_RESPONSE_CHARS` | Safety cap on response size, in characters, for tools that can return large inline payloads (`get_sheet_data`, `get_multiple_sheet_data`, `find_in_spreadsheet`, `get_doc_content`, `export_file`, `list_file_activity`). Raise to match a raised `MAX_MCP_OUTPUT_TOKENS` in your MCP client (roughly 2 characters per token observed for 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 | — |

{mcp_gee_sweet-0.7.0.dev53 → mcp_gee_sweet-0.7.0.dev55}/docs/decisions/decision-grid-data-size-cap.md

@@ -3,6 +3,8 @@
 **Date:** 2026-07-03
 **Snapshot commit:** branch `feat/issue-235-grid-data-range` — see `src/mcp_gee_sweet/tools/sheets/data.py`
 
+**Update (2026-07-03, issue #242):** `MAX_GRID_DATA_RESPONSE_CHARS` referenced below was renamed to `MAX_TOOL_RESPONSE_CHARS` and generalized to 5 more tools — see `docs/decisions/decision-response-size-cap-generalization.md`. This doc is left as-is below as the historical record of the original decision.
+
 ## 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.

mcp_gee_sweet-0.7.0.dev55/docs/decisions/decision-response-size-cap-generalization.md

@@ -0,0 +1,66 @@
+# Decision: Generalizing the Response-Size Safety Net (issue #242)
+
+**Date:** 2026-07-03
+**Snapshot commit:** branch `feat/issue-242-response-size-safety-net` — see `src/mcp_gee_sweet/tools/response_limits.py`
+
+## Background
+
+Issue #235 (see `docs/decisions/decision-grid-data-size-cap.md`) added a response-size safety net to exactly one tool, `get_sheet_data(include_grid_data=True)`: an MCP client (e.g. Claude Code, via `MAX_MCP_OUTPUT_TOKENS`) enforces a hard cap on tool response size, and exceeding it doesn't degrade gracefully — it silently kills the MCP session, requiring a full server restart to recover. That decision doc explicitly flagged #242 as the follow-up to generalize the pattern to other tools, and warned that `MAX_GRID_DATA_RESPONSE_CHARS` was scoped to one tool and wouldn't generalize as named.
+
+This is a confirmed defect, not a hypothetical hardening gap: the silent-session-death failure mode has been observed live. What was unmapped was *which other tools* can trigger it and at what real thresholds — verifying that requires generating fixtures above the ceiling per tool, which gets most of the way to the fix anyway, so investigation and fix were scoped as one unit (`docs/roadmap.md`, v0.8.1).
+
+## Scope
+
+Five more tools, in priority order by how easily they can produce an oversized response:
+
+1. `export_file` — base64-encodes binary content inline, unbounded, no existing size control
+2. `get_doc_content` — full unbounded plain-text export of a doc
+3. `get_multiple_sheet_data` — unbounded query list, each returning a full value range
+4. `find_in_spreadsheet` — bounds match *count* (`max_results`) but not match *size*
+5. `list_file_activity` — already Drive-API-paginated and lowest risk of the five
+
+## Decisions
+
+### 1. Single global env var, not per-tool
+
+Considered three options: (A) one global `MAX_TOOL_RESPONSE_CHARS` for all 6 capped tools, (B) six separate per-tool vars, (C) a hybrid — global default with a per-tool override reserved for `export_file` (whose base64 encoding inflates raw file size ~33%, making it structurally different from the others).
+
+**Chose (A), confirmed with the user.** One knob is simpler to discover and configure than six, and the marginal precision a per-tool override buys wasn't judged worth the added config surface — an operator who needs a materially higher ceiling for `export_file` specifically can raise the shared var, or use `download_file` instead (see below).
+
+`MAX_GRID_DATA_RESPONSE_CHARS` (from #235) was renamed to `MAX_TOOL_RESPONSE_CHARS` as part of this change — free to do since #235 hadn't shipped in a released package version yet (still pre-release on `develop`). The cap constant and check logic now live in one shared module, `src/mcp_gee_sweet/tools/response_limits.py` (`enforce_response_size_cap`, `write_capped_result_to_disk`), imported cross-package by each tool module the same way `tools/drive/__init__.py`'s `_SA_QUOTA_ERROR` already is.
+
+### 2. `export_file` gets the cap but not `local_path`
+
+`local_path` on the other four tools writes `json.dumps(result)` to disk as an escape hatch. For `export_file`, that would mean writing a JSON file *containing a base64 string* — a worse artifact than what already exists: `download_file` (pre-existing tool) writes the raw file bytes straight to disk with no base64 or JSON wrapping overhead. Adding a redundant, structurally worse bypass just for API symmetry with the other tools wasn't worth it. `export_file`'s cap error message points to `download_file` instead.
+
+### 3. `list_file_activity` gets the cap, no `local_path`, no dedicated live-fixture verification
+
+Already paginated (`page_size` clamped 1–100) and low per-item size — the only realistic exposure is a single activity's `actors` list ballooning on a file with many collaborators. Included the cap for defense-in-depth (cheap — one shared-helper call), but:
+- No `local_path`: the natural remedy for "too much" here is `page_size`/pagination, not writing timeline fragments to disk.
+- No dedicated live-fixture verification (see below): reproducing hundreds of real Drive Activity events cheaply isn't practical, and the risk is real but rare.
+
+### 4. `get_doc_content` cache-ordering bug fixed while touched
+
+The `doc_cache` early-return previously ran *before* any cap logic could — a cached oversized doc would bypass the cap on repeat calls. Fixed so the cap check runs on both the cache-hit and cache-miss paths (see `tests/test_docs_content.py::TestGetDocContent::test_cached_oversized_result_also_raises`).
+
+## Live-tested thresholds
+
+Live-verified against the real QA fixture spreadsheet/docs on 2026-07-03, after reconnecting the MCP session to this branch. Full detail in `docs/qa/tests/sheets_read.md` (TC-R34, TC-R35), `docs/qa/tests/docs.md` (TC-DOC80), `docs/qa/tests/drive.md` (TC-D167, TC-D168).
+
+| Tool | Real fixture | Measured size | Cap tripped? |
+|---|---|---|---|
+| `get_doc_content` | `TEST_LARGE_DOC_ID` grown to ~49,700 chars (seeded via `insert_doc_text`) | 49,700 chars | ✅ (fetch path and cached path both) |
+| `export_file` (xlsx) | Small QA fixture spreadsheet (3 sheets, mostly tiny) | 54,280 chars | ✅ — even a small workbook's base64-encoded xlsx export exceeds the cap |
+| `get_multiple_sheet_data` | 200 queries against a 6x4 range (`Sales` sheet) | 150,106 chars | ✅ — query *count* alone is a real vector, independent of per-query range size |
+| `find_in_spreadsheet` | 10 cells x ~4,785 chars each, all matching (well under `max_results=50`) | 42,491 chars | ✅ — confirms `max_results` bounds count, not size |
+| `list_file_activity` | N/A — no dedicated fixture, per the scoping decision above | N/A | Not live-tested; unit-tested only (defense-in-depth) |
+
+Two findings worth calling out:
+
+1. **`export_file` trips the cap far more readily than the others.** A workbook small enough that its *values* fit trivially under the cap still blows past it once base64-encoded — this validates the concern raised during design (item 2 above) and confirms `download_file` is the practical default, not `export_file`, for anything but the smallest files.
+2. **`get_multiple_sheet_data`'s query-count axis is real and independent of range size** — 200 queries against a *tiny* 6x4 range (not a large one) already produced a 150K-character response. This means the cap protects against "many small things" just as much as "one big thing," which the original #235 cap (single range, single tool) never had to consider.
+
+## When to Re-evaluate
+
+- If a materially different MCP client (different `MAX_MCP_OUTPUT_TOKENS` or equivalent) becomes a primary consumer, the shared `40000`-character default should be re-measured, not assumed to still be well-calibrated — same caveat #235 already carries.
+- If `export_file` usage in practice shows the shared cap is routinely too restrictive for legitimate small-to-medium binary exports, revisit the per-tool-override hybrid (option C) that was considered and set aside here.

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

@@ -1352,3 +1352,19 @@ These test the HTML→AST→Docs API pipeline introduced in Phase 2 (#87). All u
 
 **Result (2026-06-25) ✅ PASS**
 - Tool completed without error. Structure: sectionBreak → HEADING_2 "HIGH\n" (1-6) → blank para "\n" (6-7, `font_size: 1` on its run confirming collapse applied) → table (7-70, cells filled correctly: Finding/Severity/Ticket header, Some finding/HIGH/KINDLY-123 data) → trailing para (70-71). Visual check: no visible gap between heading and table in the rendered doc.
+
+---
+
+### TC-DOC80: get_doc_content trips the response-size cap; cached path re-checks it too (issue #242)
+
+**Background:** #242 generalized #235's response-size safety net to `get_doc_content`. `doc_cache` previously returned a cached result *before* any cap check ran, so a cached oversized doc would bypass the cap on repeat calls — fixed so the check runs on both the cache-hit and cache-miss paths.
+
+**Setup:** `TEST_LARGE_DOC_ID` (`mcp-gee-sweet-qa-large-doc`), grown from its original ~5,300-character seed content to ~49,700 characters by inserting repeated padding text (permanent fixture growth — this doc's whole purpose is being a large-content fixture, and it was never previously large enough to exceed any cap since none existed for this tool before now).
+
+**Checks**
+- First call (fetch path) raises `ValueError` mentioning the actual response size, the cap, and `MAX_TOOL_RESPONSE_CHARS`
+- Second call (cache-hit path, no `refresh_cache` in between) raises the *same* error — proves the cache-hit path re-checks the cap rather than returning the stale oversized cached result
+- Same call with `local_path` set succeeds, returns `{local_path, id, bytes_written}`, and the file on disk contains the full content
+
+**Result (2026-07-03) ✅ PASS**
+Fetch-path call raised: `get_doc_content: the response is 49700 characters, over the 40000-character safety cap. Pass local_path to write the result to disk instead of returning it inline (bypasses this cap), or set MAX_TOOL_RESPONSE_CHARS if your MCP client can handle larger responses (e.g. a raised MAX_MCP_OUTPUT_TOKENS).` Repeat call (served from `doc_cache`, confirmed via no additional Drive API round-trip) raised the identical error — confirms the cache-ordering fix. `local_path` call succeeded: `{"local_path":"/tmp/qa_doc_content_242.json","bytes_written":49700,"id":"{TEST_LARGE_DOC_ID}"}`; file verified then cleaned up.

{mcp_gee_sweet-0.7.0.dev53 → mcp_gee_sweet-0.7.0.dev55}/docs/qa/tests/drive.md

@@ -1992,3 +1992,26 @@ Fixtures: see [`docs/qa/setup.md`](../setup.md). Substitute your `{SPREADSHEET_I
 - When the Drive Activity API returns an HTTP 403 or 404, the tool returns `{"error": "..."}` rather than raising an exception
 
 **Result (2026-06-24) ✅** Unit test `test_http_error_returns_error_dict` confirms HTTP errors are caught and returned as `{"error": str(e)}`.
+
+---
+
+### TC-D167: export_file trips the response-size cap on base64-inflated content (issue #242)
+
+**Background:** #242 generalized #235's response-size safety net to `export_file`. Unlike the other capped tools, `export_file` has no `local_path` param — its base64 output written to a JSON file would be a worse artifact than `download_file` (pre-existing tool) already produces, so the error points there instead.
+
+**Prompt**
+> "Export {SPREADSHEET_ID} as xlsx"
+
+**Checks**
+- Call raises `ValueError` mentioning the actual response size, the 40,000-character cap, base64's ~33% inflation, and `download_file` as the recommended alternative — must NOT mention `local_path` (this tool doesn't have that param)
+
+**Result (2026-07-03) ✅ PASS**
+Exporting even the small QA fixture spreadsheet as `xlsx` immediately exceeded the cap: `export_file: the response is 54280 characters, over the 40000-character safety cap. Base64 encoding inflates raw file size by ~33%. Call download_file instead to write the file straight to disk without this overhead, or set MAX_TOOL_RESPONSE_CHARS if your MCP client can handle larger responses (e.g. a raised MAX_MCP_OUTPUT_TOKENS).` Confirms `export_file`'s cap trips far more readily than the other capped tools given base64 inflation — `download_file` is the practical default for anything but tiny files.
+
+---
+
+### TC-D168: list_file_activity response-size cap — code path only, no dedicated live fixture (issue #242)
+
+**Background:** `list_file_activity` is already Drive-API-paginated (`page_size` clamped 1–100) and low per-item size — the only realistic exposure is a single activity's `actors` list ballooning on a file with many collaborators. Per the #242 decision doc, this tool intentionally did NOT get a dedicated live-fixture verification (reproducing hundreds of real Drive Activity events isn't cheaply reproducible) — the cap was added for defense-in-depth only, verified by unit tests (`tests/drive/test_activity.py::TestListFileActivity::test_oversized_result_raises`, `test_error_points_to_page_size_not_local_path`).
+
+**Result (2026-07-03) ✅ N/A (by design)** — sanity-checked live that the tool still functions normally post-change (`list_file_activity(file_id={SPREADSHEET_ID}, page_size=5)` returned a normal activity list, no regression). Cap-triggering behavior covered by unit tests only, not live-verified — documented scoping decision, not an oversight.

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

@@ -67,11 +67,11 @@ Called live against the actual Sales fixture (`gridProperties: rowCount=3016, co
 **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.
+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_TOOL_RESPONSE_CHARS=40000`, named `MAX_GRID_DATA_RESPONSE_CHARS` at the time this test was first run — renamed and generalized to 5 more tools by issue #242) 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
+- Error message states the actual response size in characters, the cap, and mentions narrowing the range, `local_path`, or `MAX_TOOL_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**
@@ -96,16 +96,16 @@ Same scratch-sheet setup as TC-R03c. Call returned `{"local_path": "/tmp/qa_grid
 
 ---
 
-### TC-R03e: MAX_GRID_DATA_RESPONSE_CHARS raises the cap (issue #235)
+### TC-R03e: MAX_TOOL_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.
+Set `MAX_TOOL_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
+- Restore `MAX_TOOL_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.
+**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` in `tests/sheets/test_data.py`, `test_env_var_sets_cap_at_import_time` in `tests/test_response_limits.py`) in the meantime. Var renamed from `MAX_GRID_DATA_RESPONSE_CHARS` by issue #242 (generalized to 5 more tools).
 
 ---
 
@@ -491,3 +491,38 @@ Clear `userEnteredFormat` from B2.
 
 **Result (2026-06-20) ✅ PASS**
 - `effectiveFormat.numberFormat = {type:"CURRENCY", pattern:"$#,##0.00"}`, `formattedValue = "$100.00"`, `effectiveValue.numberValue = 100`
+
+---
+
+### TC-R34: get_multiple_sheet_data — many small queries trips the response-size cap (issue #242)
+
+**Background:** #242 generalized #235's response-size safety net beyond `get_sheet_data`. For `get_multiple_sheet_data`, the unbounded axis is query *count*, not just per-query range size — many small results can add up.
+
+**Setup**
+No fixture setup needed — repeat the same tiny query (`{spreadsheet_id: {SPREADSHEET_ID}, sheet: "Sales"}`, a 6x4 range) 200 times in one `queries` list.
+
+**Checks**
+- Call raises `ValueError` mentioning the actual response size, the 40,000-character cap, and `MAX_TOOL_RESPONSE_CHARS`
+- Same call with only 2 queries + `local_path` set succeeds, returns `{local_path, query_count, bytes_written}`, and the file on disk contains the full per-query results
+
+**Result (2026-07-03) ✅ PASS**
+200 queries against the small `Sales` range (6 rows x 4 cols) raised: `get_multiple_sheet_data: the response is 150106 characters, over the 40000-character safety cap. Pass local_path to write the result to disk instead of returning it inline (bypasses this cap), or set MAX_TOOL_RESPONSE_CHARS if your MCP client can handle larger responses (e.g. a raised MAX_MCP_OUTPUT_TOKENS).` `local_path` with 2 queries succeeded, returned `{"local_path":"/tmp/qa_multiple_sheet_data_242.json","bytes_written":2048,"query_count":2}`; file verified on disk then cleaned up.
+
+---
+
+### TC-R35: find_in_spreadsheet — max_results bounds count, not size (issue #242)
+
+**Background:** `max_results` (default 50) caps how many matches are returned, not how large each matched cell value is. A handful of large matching cells can exceed the response-size cap even with few matches.
+
+**Setup**
+Write 10 cells (`Empty!A1:A10`) each containing a ~4,785-character string with a shared marker substring (e.g. repeated "PADTEST marker text..." sentence), then search for the marker.
+
+**Checks**
+- Call raises `ValueError` mentioning the actual response size and the cap, even though match count (10) is well under `max_results` (50)
+- Same call with `local_path` set succeeds, returns `{local_path, spreadsheet_id, query, match_count, bytes_written}`, and the file on disk contains all matches
+
+**Teardown**
+`clear_values` on the `Empty` sheet to remove the test data.
+
+**Result (2026-07-03) ✅ PASS**
+10 matches (42,491 chars total) raised: `find_in_spreadsheet: the response is 42491 characters, over the 40000-character safety cap. ...` despite being far under the `max_results=50` default — confirming match-count capping alone doesn't bound response size. `local_path` call succeeded: `{"local_path":"/tmp/qa_find_in_spreadsheet_242.json","bytes_written":42491,"spreadsheet_id":"...","query":"PADTEST","match_count":10}`; file verified then cleaned up. Test data cleared from the `Empty` sheet afterward.

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

@@ -31,12 +31,12 @@ 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 (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 |
+| [**v0.7.0**](https://github.com/khuisman/mcp-gee-sweet/issues?q=is%3Aissue+label%3Av0.7) | ✅ First stable PyPI release — 63 tools across Sheets, Drive, Docs, Calendar | Published 2026-06-21 |
+| [**v0.8.0**](https://github.com/khuisman/mcp-gee-sweet/issues?q=is%3Aissue+label%3Av0.8) | ✅ Tier 1 complete — all "frequently needed" items across all domains (84 tools) | Published 2026-06-29 |
+| [**v0.8.1**](https://github.com/khuisman/mcp-gee-sweet/issues?q=is%3Aissue+label%3Av0.8.1) | Defect & documentation cleanup — no new tools, ships the QA/refactor work already on `develop` plus fixes for #235, #242, #213, #239, #236 | Stabilizes before Tier 2 feature work begins |
+| [**v0.9.0**](https://github.com/khuisman/mcp-gee-sweet/issues?q=is%3Aissue+label%3Av0.9) | Tier 2 complete — power-user and structured-work layer, features only (~20 tools) | Covers most real workflows |
+| [**v1.0.0**](https://github.com/khuisman/mcp-gee-sweet/issues?q=is%3Aissue+label%3Av1.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+**](https://github.com/khuisman/mcp-gee-sweet/issues?q=is%3Aissue+label%3A%22v1.1%2B%22) | Future domains — Tasks, Gmail (separate minor releases, each needs a new API client) | Expanded scope |
 
 Tier 4 items remain backlog with no assigned version.
 
@@ -44,7 +44,7 @@ Tier 4 items remain backlog with no assigned version.
 
 ## Roadmap
 
-### Tier 1 — High value, frequently needed _(target: v0.8.0)_
+### Tier 1 — High value, frequently needed _(target: [v0.8.0](https://github.com/khuisman/mcp-gee-sweet/issues?q=is%3Aissue+label%3Av0.8))_
 
 **Infrastructure**
 - [x] PyPI publish — OIDC trusted publishing ([#55](https://github.com/khuisman/mcp-gee-sweet/issues/55)) — v0.7.0 stable live; `uvx mcp-gee-sweet` works
@@ -71,7 +71,7 @@ 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))
 
-### v0.8.1 — Defect & documentation cleanup _(target: v0.8.1, before Tier 2 begins)_
+### v0.8.1 — Defect & documentation cleanup _(target: [v0.8.1](https://github.com/khuisman/mcp-gee-sweet/issues?q=is%3Aissue+label%3Av0.8.1), before Tier 2 begins)_
 
 No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature work.
 
@@ -83,6 +83,7 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 
 **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))
+- [x] Generalize the #235 response-size safety net (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`, `find_in_spreadsheet`, `list_file_activity`. Oversized responses silently kill the MCP session today (client-side output cap, e.g. Claude Code's `MAX_MCP_OUTPUT_TOKENS`), requiring a server restart to recover — confirmed live, not hypothetical. Renamed `MAX_GRID_DATA_RESPONSE_CHARS` to `MAX_TOOL_RESPONSE_CHARS` (single global cap); live-verified thresholds per tool ([#242](https://github.com/khuisman/mcp-gee-sweet/issues/242))
 - [ ] `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))
@@ -90,7 +91,7 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 - [ ] 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)_
+### Tier 2 — Useful for structured work, features only _(target: [v0.9.0](https://github.com/khuisman/mcp-gee-sweet/issues?q=is%3Aissue+label%3Av0.9))_
 
 **Sheets**
 - [ ] `update_borders` — border style, width, color on a range ([#122](https://github.com/khuisman/mcp-gee-sweet/issues/122)) _(freema/mcp-gsheets)_
@@ -129,7 +130,7 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 **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)_
+### Tier 3 — Advanced / occasionally needed _(target: [v1.0.0](https://github.com/khuisman/mcp-gee-sweet/issues?q=is%3Aissue+label%3Av1.0))_
 
 **Sheets**
 - [ ] `add_conditional_formatting` / `delete_conditional_formatting` ([#129](https://github.com/khuisman/mcp-gee-sweet/issues/129)) _(freema/mcp-gsheets)_

{mcp_gee_sweet-0.7.0.dev53 → mcp_gee_sweet-0.7.0.dev55}/docs/tools.md

@@ -10,9 +10,9 @@
 |---|---|---|
 | `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_sheet_data` | Get data from multiple specific ranges in Google Spreadsheets. | `queries`, `local_path?` |
 | `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?` |
+| `find_in_spreadsheet` | Find cells containing a specific value in a Google Spreadsheet. | `spreadsheet_id`, `query`, `sheet?`, `case_sensitive?`, `max_results?`, `local_path?` |
 | `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` |
@@ -112,7 +112,7 @@ Requires the `drive.activity.readonly` scope; uses the Drive Activity API v2.
 |---|---|---|
 | `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` |
+| `get_doc_content` | Get the plain text content of a Google Doc. | `file_id`, `local_path?` |
 | `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` |

{mcp_gee_sweet-0.7.0.dev53 → mcp_gee_sweet-0.7.0.dev55}/src/mcp_gee_sweet/.env.template

@@ -29,10 +29,12 @@ ACCESS_LOG_FILE=/tmp/mcp-gee-sweet-access.log
 # CACHE_TTL=1800
 # CACHE_DB_PATH=/tmp/mcp_gee_sweet.db
 
-# 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 (~2 chars/token
-# observed for this densely-formatted JSON — see docs/qa/tests/sheets_read.md TC-R03c/d).
-# MAX_GRID_DATA_RESPONSE_CHARS=40000
+# Safety cap on response size, in characters, for tools that can return large inline
+# payloads (get_sheet_data, get_multiple_sheet_data, find_in_spreadsheet,
+# get_doc_content, export_file, list_file_activity). Raise to match a raised
+# MAX_MCP_OUTPUT_TOKENS in your MCP client (~2 chars/token observed for densely
+# formatted JSON — see docs/qa/tests/sheets_read.md TC-R03c/d).
+# MAX_TOOL_RESPONSE_CHARS=40000
 
 # QA OAuth automation (scripts/oauth_setup.py — see docs/qa/playwright_oauth.md)
 # GOOGLE_TEST_EMAIL=

{mcp_gee_sweet-0.7.0.dev53 → mcp_gee_sweet-0.7.0.dev55}/src/mcp_gee_sweet/tools/docs/content.py

@@ -10,6 +10,7 @@ from mcp.server.fastmcp import Context
 from mcp.types import ToolAnnotations
 
 from ..drive import _SA_QUOTA_ERROR
+from ..response_limits import enforce_response_size_cap, write_capped_result_to_disk
 from .ast import Table
 from .emitter import ast_to_requests, fill_tables
 from .html_parser import html_to_ast
@@ -251,44 +252,63 @@ def register(tool):
         }
 
     @tool(annotations=ToolAnnotations(title="Get Document Content", readOnlyHint=True))
-    def get_doc_content(file_id: str, ctx: Context = None) -> dict[str, Any]:
+    def get_doc_content(
+        file_id: str, local_path: str | None = None, ctx: Context = None
+    ) -> dict[str, Any]:
         """
         Get the plain text content of a Google Doc.
 
         Args:
             file_id: The Google Drive file ID of the document.
+            local_path: Optional local filesystem path (file or directory) to write the
+                result to instead of returning it inline. Bypasses the response-size cap.
+                Same caveat as download_file/download_folder: this path is resolved on the
+                *server's* filesystem, not the caller's.
 
         Returns:
             Dictionary with the document's text content and metadata. Results are
             cached; call refresh_cache(doc_id=file_id) to invalidate, or
-            refresh_cache() to clear all caches.
+            refresh_cache() to clear all caches. Raises ValueError if the response
+            exceeds a safety cap (default 40,000 characters, set MAX_TOOL_RESPONSE_CHARS
+            to change it) and local_path is not set. If local_path is set, returns
+            {local_path, id, bytes_written} instead.
         """
         lc = ctx.request_context.lifespan_context
         drive_service = lc.drive_service
         doc_cache = lc.doc_cache
 
-        cached = doc_cache.get(file_id)
-        if cached is not None:
-            return cached
-
-        metadata = (
-            drive_service.files()
-            .get(
-                fileId=file_id, fields="id, name, modifiedTime, webViewLink", supportsAllDrives=True
+        result = doc_cache.get(file_id)
+        if result is None:
+            metadata = (
+                drive_service.files()
+                .get(
+                    fileId=file_id,
+                    fields="id, name, modifiedTime, webViewLink",
+                    supportsAllDrives=True,
+                )
+                .execute()
             )
-            .execute()
-        )
 
-        content = drive_service.files().export(fileId=file_id, mimeType="text/plain").execute()
+            content = drive_service.files().export(fileId=file_id, mimeType="text/plain").execute()
 
-        result = {
-            "id": metadata["id"],
-            "name": metadata["name"],
-            "modified_time": metadata.get("modifiedTime"),
-            "web_link": metadata.get("webViewLink"),
-            "content": content.decode("utf-8") if isinstance(content, bytes) else content,
-        }
-        doc_cache.store(file_id, result)
+            result = {
+                "id": metadata["id"],
+                "name": metadata["name"],
+                "modified_time": metadata.get("modifiedTime"),
+                "web_link": metadata.get("webViewLink"),
+                "content": content.decode("utf-8") if isinstance(content, bytes) else content,
+            }
+            doc_cache.store(file_id, result)
+
+        if local_path:
+            return write_capped_result_to_disk(
+                result,
+                local_path,
+                default_filename=f"{file_id}_content.json",
+                manifest_extra={"id": file_id},
+            )
+
+        enforce_response_size_cap(result, tool_name="get_doc_content")
         return result
 
     @tool(annotations=ToolAnnotations(title="Write Document Content", destructiveHint=True))

{mcp_gee_sweet-0.7.0.dev53 → mcp_gee_sweet-0.7.0.dev55}/src/mcp_gee_sweet/tools/drive/activity.py

@@ -5,6 +5,8 @@ from googleapiclient.errors import HttpError
 from mcp.server.fastmcp import Context
 from mcp.types import ToolAnnotations
 
+from ..response_limits import enforce_response_size_cap
+
 logger = logging.getLogger(__name__)
 
 # Maps Drive Activity API primaryActionDetail keys to human-readable action types.
@@ -83,6 +85,10 @@ def register(tool):
             - file_id: echoed back for reference
             - activities: list of activity entries (timestamp, action, actors)
             - next_page_token: present when more results are available
+            Raises ValueError if the response exceeds a safety cap (default 40,000
+            characters, set MAX_TOOL_RESPONSE_CHARS to change it) — lower page_size and
+            paginate via next_page_token instead of raising the cap; a single activity's
+            actors list can be large on files with many collaborators.
 
         Note:
             The Drive Activity API requires the drive.activity.readonly OAuth scope.
@@ -118,5 +124,12 @@ def register(tool):
         if npt := response.get("nextPageToken"):
             result["next_page_token"] = npt
 
+        enforce_response_size_cap(
+            result,
+            tool_name="list_file_activity",
+            hint="Lower page_size and paginate via next_page_token, or ",
+            local_path_available=False,
+        )
+
         logger.debug("list_file_activity: %d activities for file %s", len(activities), file_id)
         return result

{mcp_gee_sweet-0.7.0.dev53 → mcp_gee_sweet-0.7.0.dev55}/src/mcp_gee_sweet/tools/drive/transfer.py

@@ -12,6 +12,7 @@ from googleapiclient.http import MediaFileUpload, MediaInMemoryUpload, MediaIoBa
 from mcp.server.fastmcp import Context
 from mcp.types import ToolAnnotations
 
+from ..response_limits import enforce_response_size_cap
 from . import _SA_QUOTA_ERROR
 
 logger = logging.getLogger(__name__)
@@ -80,7 +81,12 @@ def register(tool):
         Returns:
             fileId, name, mime_type, format, encoding ('utf-8' or 'base64'), content.
             Text formats (txt, html, csv, rtf) are returned as plain strings; all others
-            are base64-encoded bytes.
+            are base64-encoded bytes. Raises ValueError if the response exceeds a safety
+            cap (default 40,000 characters, set MAX_TOOL_RESPONSE_CHARS to change it) —
+            base64 encoding inflates raw file size by ~33%, so binary exports hit this
+            cap at a much smaller *file* size than text ones. Call download_file instead
+            for anything but small files; it writes raw bytes straight to disk with no
+            base64/JSON overhead.
         """
         _TEXT_MIME_PREFIXES = ("text/",)
 
@@ -102,53 +108,40 @@ def register(tool):
             while not done:
                 _, done = downloader.next_chunk()
             raw_bytes = buf.getvalue()
-            is_text = any(file_mime.startswith(p) for p in _TEXT_MIME_PREFIXES)
-            if is_text:
-                return {
-                    "fileId": file_id,
-                    "name": metadata["name"],
-                    "mime_type": file_mime,
-                    "format": export_format,
-                    "encoding": "utf-8",
-                    "content": raw_bytes.decode("utf-8", errors="replace"),
-                }
-            return {
-                "fileId": file_id,
-                "name": metadata["name"],
-                "mime_type": file_mime,
-                "format": export_format,
-                "encoding": "base64",
-                "content": base64.b64encode(raw_bytes).decode("ascii"),
-            }
-
-        if export_format not in _EXPORT_MIME:
-            raise ValueError(
-                f"Unknown export_format '{export_format}'. "
-                f"Valid options: {', '.join(_EXPORT_MIME)}, raw"
+            target_mime = file_mime
+            content_bytes = raw_bytes
+        else:
+            if export_format not in _EXPORT_MIME:
+                raise ValueError(
+                    f"Unknown export_format '{export_format}'. "
+                    f"Valid options: {', '.join(_EXPORT_MIME)}, raw"
+                )
+            target_mime = _EXPORT_MIME[export_format][0]
+            content_bytes = (
+                drive_service.files().export(fileId=file_id, mimeType=target_mime).execute()
             )
-        target_mime = _EXPORT_MIME[export_format][0]
+            if isinstance(content_bytes, str):
+                content_bytes = content_bytes.encode("utf-8")
 
-        content_bytes = drive_service.files().export(fileId=file_id, mimeType=target_mime).execute()
         is_text = any(target_mime.startswith(p) for p in _TEXT_MIME_PREFIXES)
-        if is_text:
-            return {
-                "fileId": file_id,
-                "name": metadata["name"],
-                "mime_type": target_mime,
-                "format": export_format,
-                "encoding": "utf-8",
-                "content": content_bytes.decode("utf-8")
-                if isinstance(content_bytes, bytes)
-                else content_bytes,
-            }
-        return {
+        result = {
             "fileId": file_id,
             "name": metadata["name"],
             "mime_type": target_mime,
             "format": export_format,
-            "encoding": "base64",
-            "content": base64.b64encode(content_bytes).decode("ascii"),
+            "encoding": "utf-8" if is_text else "base64",
+            "content": content_bytes.decode("utf-8", errors="replace")
+            if is_text
+            else base64.b64encode(content_bytes).decode("ascii"),
         }
+        enforce_response_size_cap(
+            result,
+            tool_name="export_file",
+            hint="Base64 encoding inflates raw file size by ~33%. Call download_file "
+            "instead to write the file straight to disk without this overhead, or ",
+            local_path_available=False,
+        )
+        return result
 
     @tool(annotations=ToolAnnotations(title="List Revisions", readOnlyHint=True))
     def list_revisions(file_id: str, ctx: Context = None) -> list[dict[str, Any]]:

mcp_gee_sweet-0.7.0.dev55/src/mcp_gee_sweet/tools/response_limits.py

@@ -0,0 +1,45 @@
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+# See docs/decisions/decision-grid-data-size-cap.md and
+# docs/decisions/decision-response-size-cap-generalization.md for the live-tested
+# numbers behind this default and cap/local_path design.
+MAX_TOOL_RESPONSE_CHARS = int(os.environ.get("MAX_TOOL_RESPONSE_CHARS", "40000"))
+
+
+def enforce_response_size_cap(
+    result: Any, *, tool_name: str, hint: str = "", local_path_available: bool = True
+) -> None:
+    """Raise ValueError if the serialized result exceeds the configured cap."""
+    size = len(json.dumps(result))
+    if size > MAX_TOOL_RESPONSE_CHARS:
+        local_path_clause = (
+            "Pass local_path to write the result to disk instead of returning it inline "
+            "(bypasses this cap), or set"
+            if local_path_available
+            else "set"
+        )
+        raise ValueError(
+            f"{tool_name}: the response is {size} characters, over the "
+            f"{MAX_TOOL_RESPONSE_CHARS}-character safety cap. {hint}"
+            f"{local_path_clause} MAX_TOOL_RESPONSE_CHARS if your MCP client can "
+            "handle larger responses (e.g. a raised MAX_MCP_OUTPUT_TOKENS)."
+        )
+
+
+def write_capped_result_to_disk(
+    result: Any, local_path: str, *, default_filename: str, manifest_extra: dict[str, Any]
+) -> dict[str, Any]:
+    """Write result (dict or list) to local_path and return a manifest dict.
+
+    Resolves a directory path via default_filename, mirroring get_sheet_data's
+    original local_path handling from issue #235.
+    """
+    dest = Path(local_path)
+    if dest.is_dir():
+        dest = dest / default_filename
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(json.dumps(result))
+    return {"local_path": str(dest), "bytes_written": dest.stat().st_size, **manifest_extra}