mcp-gee-sweet 0.7.0.dev80__tar.gz → 0.7.0.dev84__tar.gz

{mcp_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/.claude/commands/merge-pr.md

@@ -10,4 +10,5 @@ Merge the current branch's PR and clean up its worktree. Uses `--admin` only to
 5. Clean up the local worktree:
    - If this session created the current worktree (i.e. it got here via `/start-worktree` or `/next-issue` earlier in this same session), use `ExitWorktree` with `action: "remove"`.
    - Otherwise (worktree predates this session), fall back to manual cleanup from the main checkout: `git worktree remove <path>`, then `git branch -d <branch>`, then `git worktree prune`.
-6. Report a summary: the merge commit, the now-merged PR URL, and confirmation the worktree was removed.
+6. Update the roadmap: from the main checkout on `develop`, `git pull` then check `docs/roadmap.md` for a checkbox line referencing the issue(s) this PR closes (search by issue number). If found, check it off (`- [ ]` → `- [x]`) and append `(PR <number>)` in the existing style (e.g. `(PR #280)`) — see recent `- [x]` entries for the exact convention. If the roadmap has no line item for this issue (not every ticket is roadmap-tracked — chores, follow-up defects, etc.), skip this step silently. Commit directly to `develop` (`docs(roadmap): check off #<issue> (PR <number>)`) and push — `develop`'s branch protection has `enforce_admins: false`, so a direct push by the repo owner is allowed for this kind of small, reversible, docs-only change; don't open a separate PR for it.
+7. Report a summary: the merge commit, the now-merged PR URL, confirmation the worktree was removed, and whether the roadmap was updated.

{mcp_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/.claude/commands/orchestrator.md

@@ -11,7 +11,7 @@ Why this role split exists: any locally-configured MCP server that runs this pro
    - `gh pr list --state open` — PRs awaiting live-test/review/merge (run from inside the repo so `gh` infers it from the git remote — don't hardcode a repo slug, forks won't match)
    - `gh issue list --label ready-for-development --state open` — queued ticket(s)
 4. State the orchestrator's responsibilities plainly:
-   - Ticket triage and labeling (`ready-for-development`, version labels)
+   - Ticket triage and labeling (`ready-for-development`, version labels). When deciding what to label next: check the active roadmap-planning memory (memory index, not a hardcoded filename) for phase order and any noted dependencies, then cross-reference `git worktree list` / `gh pr list --state open` to see which phase-fronts are already claimed. Label only the single next unclaimed ticket per active phase — not a whole phase or the backlog. Before labeling a ticket to run *in parallel* with other in-flight work, check whether the roadmap memory flags it as cross-cutting or conflict-risk (e.g. a rewrite touching most/all tool files); if so, hold it for a solo slot once only one session is active instead of parallelizing it.
    - Roadmap grooming (`docs/roadmap.md` + whichever roadmap-planning memory is currently active — check the memory index rather than assuming a specific version-numbered file)
    - Live/manual tool testing — only possible here
    - Reviewing worker PRs: `verify-pr` (code review + scoped live QA against real Google APIs) before `merge-pr`

{mcp_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/.claude/commands/prep-for-pr.md

@@ -7,7 +7,7 @@ Review the current branch against this checklist and report the status of each i
 - [ ] **Unit tests written** — are there new tests in `tests/` covering the changed code?
 - [ ] **Unit tests passing** — has `uv run python -m pytest tests/` been run and passed?
 - [ ] **Regression coverage** — were tests that touch the modified files (not just new tests) also run?
-- [ ] **QA test cases written** — are there AI-driven test cases in `docs/qa/tests/` for the new/changed tools?
+- [ ] **QA test cases written** — are there AI-driven test cases in `docs/qa/tests/` covering the changed behavior? This applies beyond new tools: a change to shared internal code under `src/mcp_gee_sweet/tools/` (e.g. `docs/emitter.py`, `sheets/helpers.py`) that alters what a live tool call produces needs a test case too — a unit test alone confirms the function's internal contract, not the real API output. If this is a bug fix, the test case should reproduce the regression scenario itself, not just spot-check the tool's happy path.
 
 **Live QA execution is out of scope for this checklist.** If this session is a worker in a `.claude/worktrees/*` checkout, running live QA tools here would exercise the main checkout's code, not this branch's changes — the result would look real but prove nothing. Do not run live tests and do not write `**Result**` entries from a worktree. That happens in the orchestrator's `/verify-pr` pass after the PR is open, in the main checkout, where the branch's actual code is reachable by the live MCP tools. Leave the `**Result**` line off new/changed test cases entirely — don't stub it as "pending," just omit it so `/verify-pr` adds the first real one.
 

{mcp_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/.claude/commands/verify-pr.md

@@ -4,7 +4,7 @@ CI (the "Lint and test" check `/merge-pr` already gates on) covers unit tests. I
 
 1. **Preconditions.** Confirm this session is in the main checkout, not a worktree (same check as `/orchestrator` step 1). If the main checkout has uncommitted changes, stop and ask the user how to proceed — don't stash or discard anything.
 
-2. **Identify the PR.** Take a PR number as an argument if given, otherwise use `gh pr list --state open` and ask the user which one if there's more than one. Get its details: `gh pr view <number> --json number,title,url,headRefName,baseRefName,statusCheckRollup`.
+2. **Identify the PR.** Take a PR number as an argument if given, otherwise use `gh pr list --state open` and ask the user which one if there's more than one. Get its details: `gh pr view <number> --json number,title,url,headRefName,baseRefName,statusCheckRollup,mergeable,mergeStateStatus`. If `mergeable` is `CONFLICTING`, stop here — report it and say the branch needs a rebase onto `<baseRefName>` before verification is worth doing. Don't spend code-review or live-QA effort on a branch that can't merge as-is; that cost is only worth paying once it's rebased.
 
 3. **Check out the branch.** `gh pr checkout <number>`. This fetches and switches the main checkout to the PR's branch directly (no worktree needed — the orchestrator owns the main checkout).
 

{mcp_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/CLAUDE.md

@@ -46,7 +46,7 @@ Logic is split across `src/mcp_gee_sweet/`: `server.py` (MCP setup, tool decorat
   - `docs/ast.py` — dataclass schema
   - `docs/html_parser.py` — HTML→AST
   - `docs/emitter.py` — AST→Docs API requests + multi-phase table fill including nested table and cell styling support
-- `tools/cache.py` — `refresh_cache`
+- `tools/cache.py` — `refresh_cache`, `set_cache_ttl`/`get_cache_ttl` (runtime TTL change, no restart needed)
 - `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`
 

{mcp_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/PKG-INFO

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

@@ -13,7 +13,8 @@
 | `CREDENTIALS_CONFIG` | Base64-encoded credentials JSON (for containers) | — |
 | `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) |
+| `CACHE_TTL` | Cache time-to-live in seconds. Also adjustable at runtime via the `set_cache_ttl` tool, no restart needed | `1800` (30 min) |
+| `CACHE_VALIDATE_MODIFIED_TIME` | Validate sheet/doc cache hits against Drive's `modifiedTime` before serving them, catching edits from other sessions without waiting out the TTL. Costs one extra Drive API call per cache lookup | `true` |
 | `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` (or `FASTMCP_HOST`) | Bind address for SSE transport. `FASTMCP_HOST` is a fallback if `HOST` isn't set | `0.0.0.0` |
 | `PORT` (or `FASTMCP_PORT`) | Port for SSE transport. `FASTMCP_PORT` is a fallback if `PORT` isn't set | `8000` |
@@ -69,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 90 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 92 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
@@ -109,8 +110,9 @@ See [Tools](tools.md) for the full list of tool names.
 
 The server caches responses in a local SQLite database to reduce API calls and latency. Five namespaces are cached: sheet structure, sheet data, Drive folder listings, doc content, and calendar metadata.
 
-- TTL-based expiry: controlled by `CACHE_TTL` (default 30 minutes)
+- TTL-based expiry: controlled by `CACHE_TTL` (default 30 minutes); change it at runtime with the `set_cache_ttl` tool instead of restarting the server
 - Dirty invalidation: write operations mark the relevant cache entries stale immediately
+- Change-based invalidation: for sheet structure/data and doc content (the namespaces keyed by a single Drive file), a cache hit is checked against that file's live `modifiedTime` before being served — an edit from another session or tab invalidates the entry immediately instead of waiting out the TTL. Controlled by `CACHE_VALIDATE_MODIFIED_TIME` (default `true`); disable it if the extra Drive API call per lookup isn't worth the freshness guarantee for your usage pattern. Not applied to Drive folder listings (a folder's own `modifiedTime` doesn't change when its children do) or calendar metadata (no comparable field via the Calendar API)
 - Scoped flush: `refresh_cache` accepts a `spreadsheet_id`, `doc_id`, `folder_id`, or `calendar_id` to invalidate only that resource; omit all params to flush everything
 
 The DB path defaults to `/tmp/mcp_gee_sweet.db`. Set `CACHE_DB_PATH` to a persistent location if you want the cache to survive container restarts.

mcp_gee_sweet-0.7.0.dev84/docs/decisions/decision-cache-invalidation.md

@@ -0,0 +1,51 @@
+# Decision: Runtime Cache TTL and modifiedTime-Based Invalidation (issue #99)
+
+**Date:** 2026-07-07
+**Snapshot commit:** branch `feat/issue-99` — see `src/mcp_gee_sweet/cache.py`
+
+## Background
+
+The cache's only staleness defenses were a fixed `CACHE_TTL` (set at process start, unchangeable without a restart) and `mark_dirty` calls from this server's own write tools. Neither catches an edit that happens outside this MCP session — another Claude session, or a person editing the spreadsheet/doc directly — until the TTL window closes. Issue #99 asked for two independent improvements: a way to change the TTL without restarting, and a way to detect out-of-band edits sooner.
+
+## Decisions
+
+### 1. `set_cache_ttl` tool, not a per-call TTL parameter
+
+The issue suggested either a `set_cache_ttl` tool or a per-resource TTL parameter added to every read tool. Chose the tool: it's one new surface instead of a parameter threaded through a dozen existing signatures, and TTL is a deployment-wide tuning knob in practice (this codebase already treats `CACHE_TTL` as global, not per-call). The tool updates `_ttl` on all five in-memory cache instances immediately; it doesn't touch the `CACHE_TTL` env var, so it only affects the running process, not the startup default.
+
+### 2. `modified_time` stored inside the cached JSON value, not a new DB column
+
+Considered adding a `source_modified_time` column to the `cache` table. Rejected — it would need a migration path for every already-deployed SQLite file (`ALTER TABLE ... ADD COLUMN` guarded against pre-existing installs), for a value that's only ever read back by the same process that wrote it. Storing `modified_time` as a key inside the existing JSON `value` blob avoids the migration entirely and, for `DocContentCache`, turned out to already be present — `get_doc_content` was already fetching and storing `modifiedTime` as part of the cached doc dict, so that cache needed no `store()` signature change at all, only a comparison added to `_get_valid`.
+
+### 3. Applied to sheet structure/data and doc content only — not Drive folder listings or calendar metadata
+
+The issue's own framing ("a spreadsheet or doc is being edited by others") pointed at file-keyed caches. Checked whether the other two namespaces could reuse the same mechanism and concluded no for structural reasons, not just scope-trimming:
+
+- **`DriveFolderCache`**: a folder's own `modifiedTime` does not change when a child file is added, removed, or renamed — Drive doesn't propagate child mutations to the parent's metadata. The signal this feature depends on doesn't exist for folder listings.
+- **`CalendarCache`**: calendars aren't Drive files and the Calendar API doesn't expose a directly comparable field via the endpoints already in use (`calendarList().list()` / `calendars().get()`). Out of scope without a separate investigation into what Calendar API field, if any, would serve the same purpose.
+
+Both classes still got `set_ttl` (decision 1 applies uniformly); only the modifiedTime check is scoped down.
+
+### 4. Validation is opt-out (`CACHE_VALIDATE_MODIFIED_TIME`, default `true`), not opt-in
+
+The issue's own "Notes" section flagged the cost explicitly: one extra Drive `files.get(fields=modifiedTime)` call per cache lookup, and asked whether that overhead is worth it relative to the cost of a stale read. Without a production benchmark available, defaulted to correctness (matching the problem the issue opened with — staleness that fails silently) and exposed the env var as the escape hatch for deployments where the extra round-trip matters more than immediate freshness.
+
+### 5. `drive_service` threaded through every `fetch_sheets()` call site, including `_get_sheet_id`
+
+**Reversed from the original PR.** The first version deliberately left `_get_sheet_id()` (`tools/sheets/helpers.py`) — the internal sheet-name→ID resolver used by ~11 write-path tools in `structure.py` (`add_rows`, `format_cells`, etc.) — calling `fetch_sheets()` without `drive_service`, reasoning that write-path correctness was a separate concern from read-path freshness (decision 3's cost/scope framing).
+
+Code review caught that this was a correctness bug, not a scoping choice: `SheetStructureCache` rows are keyed only by `spreadsheet_id` and shared across every call path. `_get_sheet_id`'s 3-arg `fetch_sheets()` call computed `current_mtime=None` (no `drive_service`), and on a cache miss `store()` only writes the `modified_time` key when it's not `None` — so the row got re-stored *without* a `modified_time` key at all. The next reader's `_check_modified_time` sees `cached_mtime is None` and skips the comparison entirely (there's nothing to compare against), silently disabling staleness detection for that spreadsheet for every subsequent caller — including the correctly-updated `list_sheets`/`find_in_spreadsheet`/`get_multiple_spreadsheet_summary` paths. Since almost every mutating sheet tool routes through `_get_sheet_id`, this defeated a large fraction of the feature in practice. Fixed by threading `drive_service` through `_get_sheet_id` and all 11 call sites; regression-tested in `tests/test_cache.py::TestGetSheetIdModifiedTimePropagation`.
+
+### 6. `get_cache_ttl` tool added alongside `set_cache_ttl`
+
+`set_cache_ttl` mutates 5 process-wide singleton cache instances shared by every concurrent SSE client session, with no prior way to inspect the current value before overwriting it — one session calling `set_cache_ttl(0)` silently changed behavior for everyone else with no way to know what to restore. Added a read-only `get_cache_ttl` tool (backed by a new `_BaseCache.get_ttl()`) and a docstring/log line on `set_cache_ttl` making the process-wide, multi-session blast radius explicit. The underlying single-process-wide-cache design itself is unchanged (decision 1 still applies) — this only closes the "can't see or restore the previous value" gap.
+
+### 7. Shared `_BaseCache` for the TTL/modifiedTime-check plumbing
+
+The modifiedTime-comparison-and-mark-dirty block was duplicated near-verbatim across three cache classes, and `set_ttl`/`close`/`mark_all_dirty` were duplicated across all five, with no single source of truth — exactly the shape of bug that produced decision 5's regression (one call site missed a signature update, and nothing forced the other four to be checked). Extracted a `_BaseCache` with `_check_modified_time`/`_check_ttl` helpers and the shared connection/TTL/dirty-marking methods; each cache class now only owns its own key shape and payload shape. `_get_valid` methods also now parse the cached JSON value once and return it directly instead of returning the raw `sqlite3.Row` for callers to re-parse.
+
+## When to Re-evaluate
+
+- If Calendar API staleness turns out to matter in practice, investigate what field (if any) the Calendar API exposes that's comparable to Drive's `modifiedTime` before assuming this pattern extends there directly.
+- No live benchmark of the extra `files.get` call's latency impact has been run (decision 4) — if `CACHE_VALIDATE_MODIFIED_TIME` overhead is reported as a real problem, that's the first thing to measure. `get_multiple_spreadsheet_summary` now makes one such call per sheet (not per spreadsheet) to keep each sheet's cached `modified_time` tag accurate against its own, separately-timed fetch — if that tool's Drive-call volume becomes a problem for spreadsheets with many sheets, this is the place to revisit first.
+- `get_cache_ttl`/`set_cache_ttl` still have no per-session scoping (decision 6) — if that becomes a real operational problem in multi-session SSE deployments, the fix is per-session cache instances, not another env var.

{mcp_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/docs/decisions/index.md

@@ -11,3 +11,4 @@ Point-in-time records of specific decisions — context, alternatives, and reaso
 | [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 |
+| [Cache Invalidation](decision-cache-invalidation.md) | 2026-07-07 | decided | `set_cache_ttl` tool for runtime TTL; `modifiedTime`-based validation for sheet/doc caches only (not folders/calendar); opt-out via `CACHE_VALIDATE_MODIFIED_TIME` |

{mcp_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/docs/design/docs-ast-pipeline.md

@@ -338,3 +338,17 @@ Cells with no `Table` in `children` are still filled in one bulk batch by `_buil
 - Text before, between, and after any number of nested tables in one cell renders in true source order, at any nesting depth.
 - The "one level of nesting only" and "no colspan/rowspan/col_widths inside nested tables" limitations from the original #92 design are otherwise unchanged — this rewrite only touches content ordering, not those structural features.
 - Tested with `tests/test_docs_tables.py`'s `TestFillNestedCellContent`, which drives the real algorithm against a small in-memory Docs-API simulator (`FakeDoc`/`Para`/`TableNode` in that file) that actually applies `insertText`/`insertTable` mutations and re-derives indices — chosen over hand-computed index fixtures because this much re-fetch/recursion logic is easy to get subtly wrong in a way a fixture can't catch (and did, twice, during development).
+
+---
+
+## Nested table colspan/rowspan (#109)
+
+**Date:** 2026-07-08
+
+Nested tables produced a correctly-sized shell but never merged cells with `colspan`/`rowspan` > 1 — `_fill_table_fully` (the per-nested-table fill helper introduced in the rewrite above) only ran the plain-cell bulk fill, with no equivalent of the outer-table merge phase (`fill_tables` phase 2).
+
+Fix: `_fill_table_fully` now checks the nested `ast_table` for any cell with `colspan > 1 or rowspan > 1` and, if found, builds and executes `mergeTableCells` requests via the existing `_build_merge_requests` (unchanged — it already operated generically on any `doc_table`/`ast_table` pair, nested or not) before re-fetching and running the bulk fill. This exactly mirrors `fill_tables`'s own phase 1→2→3 order, just scoped to one nested table.
+
+`col_widths` on nested tables remains unsupported — out of scope for #109, not addressed here.
+
+Tested in `tests/test_docs_tables.py`'s `TestNestedTableMerges`, extending the same `FakeDoc` simulator with a no-op `mergeTableCells` handler (the real Docs API doesn't shift indices or delete content on merge — covered cells stay physical, just skipped by the existing phantom-cell mapping — so the simulator has nothing to mutate; the tests instead assert the merge request's shape and its position in batch order relative to the fill).

{mcp_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/docs/qa/tests/docs.md

@@ -1038,6 +1038,25 @@ These test the HTML→AST→Docs API pipeline introduced in Phase 2 (#87). All u
 
 ---
 
+### TC-DOC90: `colspan`/`rowspan` inside a nested table now merges correctly (issue #109) ⚠️ destructive
+
+**Background:** Nested tables produced a correctly-sized shell but silently ignored `colspan`/`rowspan` on their own cells — no `mergeTableCells` request was ever emitted for them, unlike outer-table cells (TC-DOC34/36/37). Fixed by having `_fill_table_fully` run the same merge phase for a nested table's own cells that `fill_tables` already runs for the outer table.
+
+**Prompt**
+> "Write this HTML to doc {DOC_ID}: `<table><tr><td><table><tr><td colspan=\"2\">Header</td></tr><tr><td>A</td><td>B</td></tr></table></td></tr></table>`"
+
+**Checks**
+- Call succeeds with no API error
+- `get_doc_structure` shows the outer table (1 row × 1 col) with cell [0,0] text empty (holds the nested table, not text)
+- 🔍 Visual check: nested table renders with "Header" spanning both columns of the top row, and "A"/"B" as two separate cells in the second row — not four ungrouped cells
+
+**Cleanup:** write fixture content back
+
+**Result (2026-07-09) ✅ PASS**
+`write_doc_content` succeeded. `get_doc_structure` showed the outer table (1 row × 1 col) with cell [0,0] text empty. Playwright screenshot confirmed the nested table rendered with "Header" spanning both columns of the top row and "A"/"B" as two separate cells below — the merge applied correctly. (Unrelated observation: the fixture doc had leftover header/footer text visible in the render and in `get_doc_content`'s plain-text export but not in `get_doc_structure` — headers/footers aren't part of the body map that tool returns; pre-existing fixture-doc state from an earlier header/footer test, untouched by `write_doc_content`, not a regression from this PR.) Fixture content restored per cleanup step.
+
+---
+
 ### TC-DOC52: `get_doc_theme` scans body paragraph styles
 **Note:** `get_doc_theme` reads explicit per-paragraph and per-run styles from the document body. It returns data for AI-generated docs (where styles are set explicitly on runs); for standard docs whose styles are fully inherited from named style defaults it returns an empty dict.
 

{mcp_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/docs/qa/tests/infra.md

@@ -21,6 +21,8 @@ Most infrastructure behaviours are verified by unit tests rather than live QA pr
 | 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 |
 | TC-I21 (strict tool arg validation, issue #239) | ✅ Unit-tested in `tests/test_server.py::TestToolStrictArgs` (dummy tool + real `list_sheets`) and live-tested — see Result entry below |
+| TC-I22 (`set_cache_ttl`/`get_cache_ttl`, issue #99) | Unit-tested in `tests/test_cache.py` (`set_ttl`/`get_ttl` on all 5 cache classes) — TTL change takes effect on the next lookup without a restart, and is readable back |
+| TC-I23 (`CACHE_VALIDATE_MODIFIED_TIME`, issue #99) | Unit-tested in `tests/test_cache.py` (modified-time comparison in `_get_valid`, `get_modified_time` helper, `fetch_sheets` wiring). Live verification needs an edit path outside the MCP tools' own `mark_dirty` calls (which already invalidate immediately) — see TC-I23 below for the Playwright-based approach |
 
 ---
 
@@ -87,6 +89,64 @@ Restart the MCP server (`docker compose restart mcp-gee-sweet` or stop/start `uv
 
 ---
 
+### TC-I22: `set_cache_ttl`/`get_cache_ttl` — runtime TTL change takes effect without restart (issue #99)
+
+**Prompt** (step 0 — record the starting TTL, to restore later)
+> "What's the current cache TTL?"
+
+**Prompt** (step 1 — warm the cache, default TTL)
+> "List the sheets in {SPREADSHEET_ID}"
+
+**Prompt** (step 2 — lower the TTL at runtime)
+> "Set the cache TTL to 3 seconds"
+
+**Prompt** (step 3 — confirm the new TTL is readable back)
+> "What's the current cache TTL now?"
+
+**Prompt** (step 4 — confirm the new TTL is honored)
+> "Wait 5 seconds, then list the sheets in {SPREADSHEET_ID} again"
+
+**Checks**
+- Step 0 returns `{"ttl_seconds": 1800}` (the default, assuming no prior test left it changed)
+- Step 2 returns `{"ttl_seconds": 3}`
+- Step 3 returns `{"ttl_seconds": 3}` — `get_cache_ttl` reflects the change immediately
+- Step 1's call is a cache miss (cold or expired from a prior test) — API fetch, result cached
+- Step 4's call is a cache miss too, despite no server restart between steps — confirms the lowered TTL applied to the already-cached entry once evaluated, not just newly stored ones
+- Restore the TTL after this test: `"Set the cache TTL to 1800"`
+
+**Result (2026-07-08) ✅ PASS**
+Ran all 5 steps live against `TEST_SPREADSHEET_ID`. Step 0: `get_cache_ttl` → `{"ttl_seconds": 1800}`. Step 1: `list_sheets` cache miss, warmed. Step 2: `set_cache_ttl(3)` → `{"ttl_seconds": 3}`; log emitted `WARNING mcp_gee_sweet.tools.cache Cache TTL changed process-wide 1800s -> 3s (affects all concurrent sessions)`. Step 3: `get_cache_ttl` → `{"ttl_seconds": 3}`, immediate readback confirmed. Step 4: after a 5s wait, `list_sheets` again — log showed `Cache TTL expired for <id>, marking dirty` followed by a fresh `Cached 4 sheets`, confirming the lowered TTL applied retroactively to the already-cached entry. Restored TTL to 1800 (`get_cache_ttl` confirmed).
+
+---
+
+### TC-I23: `CACHE_VALIDATE_MODIFIED_TIME` — external edit invalidates cache before TTL expires (issue #99)
+
+**Background:** by default, a sheet-structure/data or doc-content cache hit is checked against the source file's live Drive `modifiedTime` before being served. This matters specifically for edits that don't go through this MCP session's own write tools (which already call `mark_dirty` immediately) — e.g. another Claude session, or a person editing the file directly in the Sheets/Docs UI.
+
+**Setup**
+1. Warm the cache: "List the sheets in {SPREADSHEET_ID}"
+2. Using the browser (Playwright), open {SPREADSHEET_ID} in the Sheets UI and rename one sheet tab directly (not through any MCP tool) — this changes Drive's `modifiedTime` without calling `mark_dirty`.
+
+**Prompt**
+> "List the sheets in {SPREADSHEET_ID}"
+
+**Checks**
+- The renamed sheet's new title is reflected in the result, even though `CACHE_TTL` has not elapsed since step 1 — the `modifiedTime` mismatch invalidated the cache entry immediately
+- Logs show a lightweight `files.get` call (`fields=modifiedTime`) preceding the decision, distinct from the fuller `spreadsheets.get` fetch that follows on the resulting miss
+
+Note: Playwright is used here only as the mechanism to make an edit outside the MCP tool surface (step 2 of Setup) — the actual pass/fail check is a plain API-response comparison, not a visual confirmation. Doesn't fit the existing `Playwright: required` tag definition (visual mutation the API can't confirm), so left untagged; flagging in case this is a second, distinct case the tag convention should eventually cover.
+
+**Cleanup:** rename the sheet back to its original name.
+
+**Result (2026-07-08) ✅ PASS**
+Warmed the structure cache via `list_sheets("BrandNew"...)`, then used Playwright to rename the "BrandNew" tab to "BrandNewRenamedQA" directly in the Sheets UI. Immediate `list_sheets` call (no wait, `CACHE_TTL` at default 1800s) returned the new name. Log showed `DEBUG mcp_gee_sweet.cache Source modified since cache for <id>, marking dirty` — the modifiedTime-mismatch path, distinct from the `Cache TTL expired` path — immediately followed by a fresh `Cached 4 sheets`. Renamed back via Playwright; confirmed reverted.
+
+**Supplementary live check (2026-07-08) — cache-poisoning regression from code review, not a scripted TC:** the code review on this PR's first pass (before the `6d4a59b` fix) found that `_get_sheet_id` (backing ~11 write-path tools: `add_rows`, `rename_sheet`, `format_cells`, etc.) called `fetch_sheets()` without `drive_service`, storing the shared structure-cache row with `modified_time=None` — silently disabling staleness detection for *all* subsequent readers of that spreadsheet, including `list_sheets`. Verified the fix closes this end-to-end: `refresh_cache` (cold) → `freeze(sheet="EmptyRenamedQA")` (write-path call, cache MISS/STORE) → renamed "EmptyRenamedQA" back to "Empty" via Playwright → `list_sheets` (read-path, no explicit refresh) immediately returned `"Empty"`, with the log showing `Source modified since cache... marking dirty` right after the write-path's own store. Confirms the write-path cache entry now carries a valid `modified_time`, so it no longer poisons reads by other tools.
+
+TC-I22/TC-I23 (issue #99) are the only mandatory live QA cases for this PR (see `git diff origin/develop...HEAD -- docs/qa/tests/`). No existing test case directly exercises the `_get_sheet_id`/write-path fix or `get_multiple_spreadsheet_summary`'s per-sheet `modified_time` fix — the supplementary check above covers the more severe of the two live; the `get_multiple_spreadsheet_summary` gap is lower-risk (confirmed correct by code trace + unit tests, not independently live-verified here).
+
+---
+
 ## Tool filtering (`ENABLED_TOOLS`)
 
 ### TC-I05: CLI flag — only specified tools registered

{mcp_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/docs/roadmap.md

@@ -95,8 +95,8 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 ### Tier 2 — Useful for structured work, plus defects surfaced since v0.8.1 _(target: [v0.9.0](https://github.com/khuisman/mcp-gee-sweet/issues?q=is%3Aissue+label%3Av0.9))_
 
 **Defects** _(found after v0.8.1 shipped; too late for that release, don't warrant a standalone patch)_
-- [ ] Bare URLs in markdown content aren't autolinked — Python-Markdown's built-in autolink only fires on `<https://...>` or `[text](url)`, not a bare URL ([#248](https://github.com/khuisman/mcp-gee-sweet/issues/248))
-- [ ] `zip(doc_tables, ast_tables)` in `emitter.py` silently cross-pairs tables when one is skipped (zero-row/zero-col table), misapplying fill/merge/style requests to the wrong table — surfaced during #276's review ([#277](https://github.com/khuisman/mcp-gee-sweet/issues/277))
+- [x] Bare URLs in markdown content aren't autolinked — Python-Markdown's built-in autolink only fires on `<https://...>` or `[text](url)`, not a bare URL (PR #265) ([#248](https://github.com/khuisman/mcp-gee-sweet/issues/248))
+- [x] `zip(doc_tables, ast_tables)` in `emitter.py` silently cross-pairs tables when one is skipped (zero-row/zero-col table), misapplying fill/merge/style requests to the wrong table — surfaced during #276's review (PR #282) ([#277](https://github.com/khuisman/mcp-gee-sweet/issues/277))
 
 **Sheets**
 - [ ] `update_borders` — border style, width, color on a range ([#122](https://github.com/khuisman/mcp-gee-sweet/issues/122)) _(freema/mcp-gsheets)_
@@ -106,11 +106,11 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 - [ ] `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))
+- [x] `import_csv_to_sheet` — populate a spreadsheet from a local CSV file (PR #272) ([#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))
+- [x] `create_calendar` / `update_calendar` / `delete_calendar` — calendar lifecycle (PR #266) ([#156](https://github.com/khuisman/mcp-gee-sweet/issues/156))
+- [x] `add_calendar_to_list` / `remove_calendar_from_list` — subscribe/unsubscribe (PR #269) ([#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))
 
@@ -120,7 +120,7 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 - [ ] 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 ([#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))
+- [x] Warn/error on mixed text + nested table in same cell — shipped as the fuller `Cell.children: list[Run | Table]` ordered model, also fixing trailing-text-after-nested-table ordering ([#275](https://github.com/khuisman/mcp-gee-sweet/issues/275)) in the same PR (PR #276) ([#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))
 - [ ] `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 ([#262](https://github.com/khuisman/mcp-gee-sweet/issues/262))
 
@@ -135,7 +135,8 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 - [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))
+- [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))
+- [x] Cache reliability & configurability — runtime-configurable TTL, smarter invalidation for shared files (PR #284) ([#99](https://github.com/khuisman/mcp-gee-sweet/issues/99))
 - [ ] Async tool execution — `asyncio.gather()` for parallel Google API calls; establishes the project's parallel-call pattern, which [#194](https://github.com/khuisman/mcp-gee-sweet/issues/194) should reuse rather than introducing its own `ThreadPoolExecutor` ([#183](https://github.com/khuisman/mcp-gee-sweet/issues/183))
 
 **Documentation**

{mcp_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/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. -->
 
-90 tools. All tool names are lowercase with underscores — use these exact strings with `ENABLED_TOOLS` or `--include-tools`.
+92 tools. All tool names are lowercase with underscores — use these exact strings with `ENABLED_TOOLS` or `--include-tools`.
 
 ## Sheets — data
 
@@ -160,6 +160,8 @@ Requires the `drive.activity.readonly` scope; uses the Drive Activity API v2.
 
 | Tool | Description | Key parameters |
 |---|---|---|
+| `get_cache_ttl` | Read the cache TTL currently in effect for this running process. | — |
+| `set_cache_ttl` | Change the cache time-to-live at runtime, without restarting the server. | `ttl_seconds` |
 | `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_gee_sweet-0.7.0.dev80 → mcp_gee_sweet-0.7.0.dev84}/src/mcp_gee_sweet/.env.template

@@ -26,8 +26,12 @@ ACCESS_LOG_FILE=/tmp/mcp-gee-sweet-access.log
 # PORT=8000
 
 # Cache
-# CACHE_TTL=1800
+# CACHE_TTL=1800   # also adjustable at runtime via the set_cache_ttl tool, no restart needed
 # CACHE_DB_PATH=/tmp/mcp_gee_sweet.db
+# Validate sheet/doc cache hits against Drive's modifiedTime before serving them
+# (one extra Drive API call per lookup). Disable if that overhead isn't worth it
+# for your usage pattern.
+# CACHE_VALIDATE_MODIFIED_TIME=true
 
 # 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,