mcp-gee-sweet 0.7.0.dev76__tar.gz → 0.7.0.dev82__tar.gz

mcp_gee_sweet-0.7.0.dev82/.claude/commands/orchestrator.md

@@ -0,0 +1,20 @@
+Establish this session as the **orchestrator** — the one session responsible for ticket triage, roadmap grooming, live testing, and reviewing/merging PRs, as opposed to a worker session doing ticket implementation in a worktree.
+
+Why this role split exists: any locally-configured MCP server that runs this project via `uv run --directory <path>` (check your global MCP config for one pointing at this repo), plus the `mcp-gee-sweet` docker-compose service (bind-mounts `./src`), always serve whatever is checked out at that fixed path — the main checkout, not whichever worktree a session's shell happens to be in. A worktree's code is invisible to every live MCP tool call until it's checked out in the main checkout or merged to the default branch. So only one place can ever do meaningful live testing — the main checkout — and only one session should treat it as home base at a time.
+
+1. Confirm this session is running from the main checkout, not a `.claude/worktrees/*` path. If it's in a worktree, tell the user the orchestrator role requires the main checkout and ask whether to `ExitWorktree` (`keep`) first.
+2. Check `git branch --show-current` and `git status --short` on the main checkout:
+   - On `develop` and clean: ready.
+   - On a feature branch, or dirty: flag it. Ticket implementation shouldn't live in the main checkout under this model — it blocks freely checking out other branches to live-test them. Ask the user whether to move that work into its own worktree (`start-worktree`) or continue as-is for now.
+3. Report current state so the user can steer:
+   - `git worktree list` — active worker worktrees
+   - `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). 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`
+   - Worktree cleanup after merge (`cleanup-worktrees`)
+
+   Do NOT pick up ticket implementation directly in this session — hand it to a worker session via `start-worktree` (or `next-issue`, which does this automatically).

{mcp_gee_sweet-0.7.0.dev76 → mcp_gee_sweet-0.7.0.dev82}/.claude/commands/prep-for-pr.md

@@ -7,9 +7,9 @@ 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 tests run** — have those test cases been executed live against the fixture doc?
-- [ ] **QA results recorded** — does each test case have a `**Result (date) ✅/❌**` entry with actual observed output?
+- [ ] **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.
 
 ## 2. QA test case tags
 

mcp_gee_sweet-0.7.0.dev82/.claude/commands/verify-pr.md

@@ -0,0 +1,33 @@
+Verify an open worker PR before merging: code review plus live QA testing against real Google APIs. This only works from the orchestrator session in the main checkout — see `/orchestrator` for why (live MCP tools always serve the main checkout's code, never a worktree's).
+
+CI (the "Lint and test" check `/merge-pr` already gates on) covers unit tests. It cannot cover code review judgment or live calls against real Google APIs, since those need credentials and fixtures CI doesn't have. That's what this skill does instead — it's the step between a worker's PR going up and `/merge-pr`.
+
+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,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).
+
+4. **Reconnect the MCP server.** The server hot-reloads on file change, but this Claude session's MCP connection stays on the old process. Tell the user to run:
+   ```
+   /mcp reconnect
+   ```
+   on its own line, standalone (not embedded in other text). Wait for confirmation before continuing — live tests run against stale code otherwise.
+
+5. **Code review.** Run `/code-review` at `high` effort against the diff (`<baseRefName>...<headRefName>`, typically `develop...HEAD`). Report findings before moving on to live testing — if it surfaces a correctness bug, ask the user whether to still proceed with live QA or send the PR back to the worker first.
+
+6. **Scope the live QA run.** Don't run the full suite. Find what this PR actually touches:
+   - `git diff origin/<baseRefName>...HEAD --name-only -- docs/qa/tests/` — new or modified test case files.
+   - Within those, identify test cases that are new or whose `Prompt`/`Setup`/`Checks` changed (not ones only touched by unrelated reflow). These are mandatory.
+   - Cross-check against `git diff origin/<baseRefName>...HEAD --name-only -- src/mcp_gee_sweet/tools/` — for each changed tool, confirm there's at least one QA test case covering it in scope; if a changed tool has no corresponding test case at all, flag that as a gap rather than silently skipping it.
+   - Existing passing test cases for the same tool (regression) are optional spot-checks, not mandatory re-runs — full regression is `docs/qa/run.md`'s job, run periodically, not per-PR.
+
+7. **Run the scoped test cases live.** Follow each test case's `Prompt`/`Setup` against the fixtures in `docs/qa/.env` (see `docs/qa/setup.md` if fixtures aren't configured), using the now-reconnected MCP tools. For `**Playwright: required**` cases, use the connected Playwright MCP if available; if not connected, tell the user and ask whether to proceed without visual verification or connect it first.
+
+8. **Record results honestly.** For each test case actually executed, add `**Result (<date>) ✅ PASS**` or `**Result (<date>) ❌ FAIL — <what happened>**` directly below its `Checks` block. Never write a Result for a case you didn't actually invoke — if something blocks a case (fixture missing, tool errors before completing), write `**Result (<date>)** pending — <reason>` and say so plainly rather than guessing the outcome.
+
+9. **Commit and push the results.** If any Result entries were added, commit just those QA doc changes onto the PR branch (`qa: record live verification for PR #<number>`) and push, so the evidence lands in history before merge. Ask before pushing, per this repo's normal commit/push confirmation rule.
+
+10. **Report.** Summarize: code review findings (if any), which test cases passed/failed/pending, any coverage gaps found in step 6, and whether the branch looks ready to merge. If everything passed, say the next step is `/merge-pr`. If something failed, say the PR needs to go back to its worker session — don't attempt the fix yourself here; this session's job is verification, not implementation.
+
+Leave the branch checked out either way — `/merge-pr` operates on the current branch's PR, and if it needs rework, the worker's own worktree still has the branch open there too.

{mcp_gee_sweet-0.7.0.dev76 → mcp_gee_sweet-0.7.0.dev82}/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.dev76 → mcp_gee_sweet-0.7.0.dev82}/PKG-INFO

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

@@ -1020,6 +1020,24 @@ These test the HTML→AST→Docs API pipeline introduced in Phase 2 (#87). All u
 
 ---
 
+### TC-DOC89: Degenerate table (row with no cells) followed by a real table doesn't desync content (issue #277)
+
+**Background:** `ast_to_requests` skips emitting an `insertTable` request for a table with zero rows or zero columns (e.g. a `<tr>` with no `<td>`s), but was still counting that table in the list it hands to `fill_tables()`. Since `fill_tables()` pairs AST tables against live-doc tables positionally, a skipped table shifted every later table's fill/merge/style requests onto the wrong doc table — silently, with no error. Fixed by excluding degenerate tables from that list at the source.
+
+**Prompt**
+> "Write this HTML to doc {DOC_ID}: `<table><tr></tr></table><table><tr><td>A</td><td>B</td></tr></table>`"
+
+**Checks**
+- Call succeeds with no API error
+- `get_doc_structure` shows exactly **one** table in the doc (the empty-row table produces no table element at all)
+- That table is `columns: 2` with cell [0,0] text "A" and cell [0,1] text "B" — not empty, not misapplied, not offset onto the wrong table
+
+**Cleanup:** write fixture content back
+
+**Result (2026-07-09) ✅ PASS**
+
+---
+
 ### 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.dev76 → mcp_gee_sweet-0.7.0.dev82}/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.dev76 → mcp_gee_sweet-0.7.0.dev82}/docs/roadmap.md

@@ -96,6 +96,7 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 
 **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))
 
 **Sheets**
 - [ ] `update_borders` — border style, width, color on a range ([#122](https://github.com/khuisman/mcp-gee-sweet/issues/122)) _(freema/mcp-gsheets)_
@@ -130,6 +131,7 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 - [ ] `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))
+- [ ] Expose `md5Checksum` in `list_files`/`get_file_metadata` for real content-diffing, and let `sync_folder` diff by checksum instead of/in addition to `modifiedTime` — mtime is unreliable across in-place overwrites, `upload_local_file`'s "now" stamp, and content-preserving regenerations; related to #239 ([#274](https://github.com/khuisman/mcp-gee-sweet/issues/274))
 - [x] Drive Activity API — file change history ([#72](https://github.com/khuisman/mcp-gee-sweet/issues/72))
 
 **Infrastructure**

{mcp_gee_sweet-0.7.0.dev76 → mcp_gee_sweet-0.7.0.dev82}/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.dev76 → mcp_gee_sweet-0.7.0.dev82}/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,