mcp-gee-sweet 0.8.2.dev71__tar.gz → 0.8.2.dev73__tar.gz

{mcp_gee_sweet-0.8.2.dev71 → mcp_gee_sweet-0.8.2.dev73}/CLAUDE.md

@@ -39,7 +39,7 @@ Logic is split across `src/mcp_gee_sweet/`: `server.py` (MCP setup, tool decorat
 - `tools/drive/transfer.py` — upload/download/sync/export/revisions
 - `tools/drive/activity.py` — `list_file_activity` (Drive Activity API v2; requires `drive.activity.readonly` scope)
 - `tools/docs/` — Google Docs package; `__init__.py` is a thin dispatcher that delegates to four submodules:
-  - `docs/content.py` — helpers (`_html_to_text`, `_md_to_html`, `_to_doc_requests`, `_html_to_doc_requests`) and tools (`create_doc`, `get_doc_content`, `write_doc_content`, `create_doc_from_file`, `insert_doc_text`, `delete_doc_range`, `get_doc_structure`, `insert_inline_image`, `insert_page_break`, `create_named_range`, `create_bookmark`). The Docs API has no bookmark-creation endpoint — `create_bookmark` is a thin wrapper over `createNamedRange` spanning a single character; neither tool's output is a link target (only UI-created bookmarks/headings are)
+  - `docs/content.py` — helpers (`_html_to_text`, `_md_to_html`, `_to_doc_requests`, `_html_to_doc_requests`, `_collect_doc_paragraphs`) and tools (`create_doc`, `get_doc_content`, `write_doc_content`, `create_doc_from_file`, `insert_doc_text`, `delete_doc_range`, `get_doc_structure`, `find_in_doc`, `insert_inline_image`, `insert_page_break`, `create_named_range`, `create_bookmark`). The Docs API has no bookmark-creation endpoint — `create_bookmark` is a thin wrapper over `createNamedRange` spanning a single character; neither tool's output is a link target (only UI-created bookmarks/headings are). `find_in_doc` searches paragraph text (including table cells) and returns `start_index`/`end_index` offsets in UTF-16 code units usable directly with `style_doc_range` — `_collect_doc_paragraphs` is a generator (so a caller can stop early once `max_results` is hit) that walks the Docs API body, trusting each `ParagraphElement`'s own `startIndex` when present and otherwise carrying the running offset forward rather than dropping that element, since the API doesn't always populate it (seen on a document's first element)
   - `docs/tables.py` — tools (`insert_doc_table`, `insert_table_row`, `delete_table_row`, `insert_table_column`, `delete_table_column`, `merge_table_cells`)
   - `docs/style.py` — helpers (`_NAMED_STYLE_TYPES`, `_read_body_styles`, `_read_named_styles`, `_build_named_style_requests`) and tools (`style_doc_range`, `style_doc_table_cells`, `get_doc_theme`, `get_doc_named_styles`, `apply_theme`)
   - `docs/layout.py` — tools (`create_header`, `create_footer`)

{mcp_gee_sweet-0.8.2.dev71 → mcp_gee_sweet-0.8.2.dev73}/PKG-INFO

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

@@ -70,7 +70,7 @@ Access logs are emitted at `INFO` level — they appear when `DEBUG_LEVEL` is `D
 
 <!-- Auto-generated by `scripts/gen_tool_docs.py` — do not edit by hand, your changes will be overwritten on the next commit. -->
 
-By default all 108 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 109 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
@@ -96,7 +96,7 @@ get_sheet_data,get_sheet_formulas,get_multiple_sheet_data,get_multiple_spreadshe
 
 **Docs only:**
 ```
-create_doc,get_doc_content,get_doc_structure,write_doc_content,insert_doc_text,insert_doc_table,delete_doc_range,style_doc_range,style_doc_table_cells
+create_doc,get_doc_content,get_doc_structure,find_in_doc,write_doc_content,insert_doc_text,insert_doc_table,delete_doc_range,style_doc_range,style_doc_table_cells
 ```
 
 **Calendar only:**

{mcp_gee_sweet-0.8.2.dev71 → mcp_gee_sweet-0.8.2.dev73}/docs/qa/tests/docs.md

@@ -1932,3 +1932,88 @@ Returned `{"error": "<HttpError 400 ... Index 99998 must be less than the end in
 
 **Result (2026-07-17) ✅ PASS**
 Returned `{"error": "<HttpError 400 ... Index 99999 must be less than the end index of the referenced segment, 65.>"}` — clean error dict, no exception, references index out of bounds.
+
+---
+
+### TC-DOC111: `find_in_doc` literal case-insensitive search returns correct offsets
+**Setup:** create a doc via `write_doc_content` with content `<p>Hello World</p><p>another hello here</p>`
+
+**Prompt**
+> "Find all instances of 'hello' in doc {DOC_ID}"
+
+**Checks**
+- Returns a list of 2 matches
+- First match: `matched_text` is `"Hello"`, `context` is `"Hello World"`
+- Second match: `matched_text` is `"hello"`, `context` is `"another hello here"`
+- Each match's `start_index`/`end_index` span exactly the matched text — confirm by calling `get_doc_structure` and slicing the paragraph text at those offsets
+
+**Cleanup:** delete the created doc
+
+**Result (2026-07-18) ✅ PASS**
+2 matches returned. `start_index`/`end_index` (1-6, 21-26) confirmed exact against `get_doc_structure` paragraph offsets (paragraphs start at 1 and 13).
+
+---
+
+### TC-DOC112: `find_in_doc` regex search feeds directly into `style_doc_range` to hyperlink matches ⚠️ destructive
+**Setup:** create a doc via `write_doc_content` with content `<p>Contact test@example.com or admin@example.com for help</p>`
+
+**Prompt**
+> "Find every email address in doc {DOC_ID} using a regex, then turn each one into a mailto: link"
+
+**Checks**
+- `find_in_doc(doc_id, query=r"[\w.]+@[\w.]+", regex=True)` returns 2 matches with the correct `matched_text` values and offsets
+- Calling `style_doc_range` with `link_url="mailto:" + matched_text` at each returned `start_index`/`end_index` succeeds
+- `get_doc_structure` afterward shows both runs with `link_url` set to the corresponding `mailto:` address, confirming the offsets from `find_in_doc` landed on the exact right characters
+
+**Cleanup:** delete the created doc
+
+**Result (2026-07-18) ✅ PASS**
+2 email matches found; `style_doc_range` applied `mailto:` links at the returned offsets; `get_doc_structure` afterward showed both runs split exactly at the email boundaries with the correct `link_url`.
+
+---
+
+### TC-DOC113: `find_in_doc` case_sensitive=True excludes different-case matches
+**Setup:** create a doc via `write_doc_content` with content `<p>Hello World, another hello here</p>`
+
+**Prompt**
+> "Find case-sensitive matches of 'hello' in doc {DOC_ID}"
+
+**Checks**
+- Returns exactly 1 match (`matched_text: "hello"`) — the capitalized "Hello" in the same doc is excluded
+
+**Cleanup:** delete the created doc
+
+**Result (2026-07-18) ✅ PASS**
+Exactly 1 match returned (`"hello"`); capitalized "Hello" correctly excluded.
+
+---
+
+### TC-DOC114: `find_in_doc` invalid regex returned gracefully
+**Setup:** create a doc via `write_doc_content` with any content
+
+**Prompt**
+> "Search doc {DOC_ID} using the regex '(unclosed'"
+
+**Checks**
+- Returns `{"error": "..."}` referencing the invalid regex — does not raise an exception
+
+**Cleanup:** delete the created doc
+
+**Result (2026-07-18) ✅ PASS**
+Returned `{"error": "Invalid regex: missing ), unterminated subpattern at position 0"}}` — clean error dict, no exception. Also spot-checked live: an invalid `doc_id` now returns `{"error": "<HttpError 404 ...>"}` instead of raising (regression test for the fix to the missing-try/except finding from code review).
+
+---
+
+### TC-DOC115: `find_in_doc` searches table cell text
+**Setup:** create a doc, insert a 1x1 table via `insert_doc_table`, then write "needle" into the cell via `insert_doc_text` at the cell's `paragraphStartIndex` (from `get_doc_structure`)
+
+**Prompt**
+> "Find 'needle' in doc {DOC_ID}"
+
+**Checks**
+- Returns 1 match with `matched_text: "needle"` and `start_index` equal to the cell's `paragraphStartIndex`
+
+**Cleanup:** delete the created doc
+
+**Result (2026-07-18) ✅ PASS**
+1 match returned, `start_index` (11) equal to the cell's `paragraphStartIndex` (11).

{mcp_gee_sweet-0.8.2.dev71 → mcp_gee_sweet-0.8.2.dev73}/docs/roadmap.md

@@ -98,7 +98,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)_
 - [x] Dev prereleases become unreachable once the base version's stable release ships — `format-jinja` never bumps past the last tag, so `X.Y.Z.devN` is a PEP 440 pre-release of the already-published `X.Y.Z` and always loses precedence to it; fix is `bump = true` in `[tool.uv-dynamic-versioning]` (PR #318) ([#317](https://github.com/khuisman/mcp-gee-sweet/issues/317))
 - [x] `sync_folder` doesn't recurse into subfolders — one-level-only Drive query silently reports a clean "in sync" result while ignoring every nested file (confirmed live: 225 files across 22 subfolders ignored, only the root-level file seen) (PR #328) ([#315](https://github.com/khuisman/mcp-gee-sweet/issues/315))
-- [ ] `download_folder`'s file loop is genuinely sequential (`for f in ...: await asyncio.to_thread(...)`) — the one multi-file transfer path missed when the `asyncio.gather` pattern was established (#183); `sync_folder`'s own transfer step already uses it correctly ([#316](https://github.com/khuisman/mcp-gee-sweet/issues/316))
+- [x] `download_folder`'s file loop is genuinely sequential (`for f in ...: await asyncio.to_thread(...)`) — the one multi-file transfer path missed when the `asyncio.gather` pattern was established (#183); `sync_folder`'s own transfer step already uses it correctly (PR #351) ([#316](https://github.com/khuisman/mcp-gee-sweet/issues/316))
 - [ ] `sync_folder` re-uploads every file after its first download — download never sets the local file's mtime to match Drive's `modifiedTime`, so any real time gap past the 5s tolerance makes the local copy look "locally newer" on the next sync; confirmed live during #315/#328 QA, reproduces on both new and long-standing files, unrelated to recursion ([#346](https://github.com/khuisman/mcp-gee-sweet/issues/346))
 - [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))
@@ -209,7 +209,7 @@ No new tools. Stabilize on what Tier 1 shipped before starting Tier 2 feature wo
 - [ ] Watch notifications — webhook push on calendar or event changes ([#165](https://github.com/khuisman/mcp-gee-sweet/issues/165))
 
 **Infrastructure**
-- [ ] `notifications/progress` feedback for long-running transfer calls (`download_folder`, `sync_folder`) — no tool uses MCP progress reporting today, would establish a new pattern; split from #316 ([#319](https://github.com/khuisman/mcp-gee-sweet/issues/319))
+- [x] `notifications/progress` feedback for long-running transfer calls (`download_folder`, `sync_folder`) — no tool uses MCP progress reporting today, would establish a new pattern; split from #316 (PR #351) ([#319](https://github.com/khuisman/mcp-gee-sweet/issues/319))
 
 ### Decisions Needed — blocking backlog _(no assigned version)_
 

{mcp_gee_sweet-0.8.2.dev71 → mcp_gee_sweet-0.8.2.dev73}/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. -->
 
-108 tools. All tool names are lowercase with underscores — use these exact strings with `ENABLED_TOOLS` or `--include-tools`.
+109 tools. All tool names are lowercase with underscores — use these exact strings with `ENABLED_TOOLS` or `--include-tools`.
 
 ## Sheets — data
 
@@ -125,6 +125,7 @@ Requires the `drive.activity.readonly` scope; uses the Drive Activity API v2.
 | `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?`, `autolink_urls?` |
 | `get_doc_structure` | Return the full structural map of a Google Doc body with element indices. | `doc_id` |
+| `find_in_doc` | Search a Google Doc's text and return match locations as document character offsets. | `doc_id`, `query`, `regex?`, `case_sensitive?`, `max_results?`, `local_path?` |
 | `insert_doc_text` | Insert text at one or more positions in a Google Doc. | `doc_id`, `insertions` |
 | `delete_doc_range` | Delete one or more content ranges from a Google Doc. | `doc_id`, `deletions` |
 | `create_named_range` | Create a named range over a span of content in a Google Doc. | `doc_id`, `name`, `start_index`, `end_index` |

{mcp_gee_sweet-0.8.2.dev71 → mcp_gee_sweet-0.8.2.dev73}/scripts/gen_tool_docs.py

@@ -215,6 +215,7 @@ SUBSETS = [
             "create_doc",
             "get_doc_content",
             "get_doc_structure",
+            "find_in_doc",
             "write_doc_content",
             "insert_doc_text",
             "insert_doc_table",

{mcp_gee_sweet-0.8.2.dev71 → mcp_gee_sweet-0.8.2.dev73}/src/mcp_gee_sweet/tools/docs/content.py

@@ -1,6 +1,8 @@
 import html as html_module
 import logging
+import re
 import xml.etree.ElementTree as etree
+from collections.abc import Iterator
 from html.parser import HTMLParser
 from pathlib import Path
 from typing import Any
@@ -143,6 +145,62 @@ def _html_to_doc_requests(
     return _to_doc_requests(html_content, "html", start_index)
 
 
+def _utf16_units(ch: str) -> int:
+    """UTF-16 code units a single Python character occupies. Docs API indices
+    (startIndex/endIndex) are UTF-16 code units, not Python code points — an
+    astral-plane character (most emoji, some CJK/math symbols) is one Python
+    str character but 2 UTF-16 units (a surrogate pair), so every offset past
+    one would drift by 1 if counted with plain enumerate()."""
+    return 2 if ord(ch) > 0xFFFF else 1
+
+
+def _collect_doc_paragraphs(content: list[dict[str, Any]]) -> Iterator[tuple[str, list[int]]]:
+    """Walk document body content, recursing into table cells, yielding each
+    paragraph's text paired with a parallel list of document character indices
+    (one per Python character in the text, in UTF-16 code units) — lets a
+    match's in-paragraph span be translated back into document offsets usable
+    with style_doc_range.
+
+    A generator so a caller (e.g. find_in_doc bounding results by max_results)
+    can stop pulling early without walking the rest of a large document.
+
+    Each ParagraphElement carries its own startIndex, but the Docs API doesn't
+    always populate it (observed on a document's very first element). When
+    present it's trusted directly, resyncing the running offset; when absent,
+    the offset just carries forward from the paragraph's own startIndex plus
+    whatever's been consumed so far, so one missing field doesn't silently
+    drop that element's text the way an unconditional skip would."""
+    for elem in content:
+        if "paragraph" in elem:
+            # Google Docs body content is never index 0 — a missing startIndex
+            # here only happens on the document's very first element, which
+            # implicitly starts at 1 (same convention as tables.py/emitter.py).
+            offset = elem.get("startIndex", 1)
+            text_parts: list[str] = []
+            indices: list[int] = []
+            for pe in elem["paragraph"].get("elements", []):
+                start = pe.get("startIndex")
+                if start is not None:
+                    offset = start
+                tr = pe.get("textRun")
+                if tr and tr.get("content"):
+                    run_text = tr["content"]
+                    text_parts.append(run_text)
+                    for ch in run_text:
+                        indices.append(offset)
+                        offset += _utf16_units(ch)
+                else:
+                    end = pe.get("endIndex")
+                    if end is not None:
+                        offset = end
+            if text_parts:
+                yield "".join(text_parts), indices
+        elif "table" in elem:
+            for row in elem["table"].get("tableRows", []):
+                for cell in row.get("tableCells", []):
+                    yield from _collect_doc_paragraphs(cell.get("content", []))
+
+
 async def _create_named_range(
     docs_service, doc_cache, doc_id: str, name: str, start_index: int, end_index: int
 ) -> dict[str, Any]:
@@ -690,6 +748,109 @@ def register(tool):
             "elements": elements,
         }
 
+    @tool(annotations=ToolAnnotations(title="Find in Document", readOnlyHint=True))
+    async def find_in_doc(
+        doc_id: str,
+        query: str,
+        regex: bool = False,
+        case_sensitive: bool = False,
+        max_results: int = 50,
+        local_path: str | None = None,
+        ctx: Context = None,
+    ) -> list[dict[str, Any]] | dict[str, Any]:
+        """
+        Search a Google Doc's text and return match locations as document
+        character offsets.
+
+        Matches feed directly into style_doc_range's ranges — e.g. to link up
+        bare URLs already sitting in a doc: find_in_doc(doc_id,
+        query=r'https?://[^\\s<>"]+(?<![.,;:!?)])', regex=True), then
+        style_doc_range with link_url per match. The trailing negative
+        lookbehind keeps a URL followed by sentence punctuation (or an
+        unmatched closing paren) from swallowing it into the link.
+
+        Args:
+            doc_id: The Google Doc file ID.
+            query: Text to search for. Interpreted literally by default; pass
+                regex=True to treat it as a Python regular expression.
+            regex: Whether query is a regular expression (default False).
+            case_sensitive: Whether the search is case-sensitive (default False).
+            max_results: Maximum number of matches to return (default 50).
+            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:
+            List of matches, each with start_index/end_index (document offsets
+            usable directly as a style_doc_range range), matched_text, and
+            context (the containing paragraph's full text). Searches paragraph
+            text in the document body, including table cells; headers,
+            footers, and footnotes are not searched. A zero-length regex match
+            (e.g. "x*" with no "x" present) is skipped. Returns {"error": ...}
+            if query is an invalid regex, or if the Docs API call itself fails
+            (e.g. doc_id doesn't exist). max_results bounds match count, not
+            response size — matched context can still be large. 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 — lower max_results, or pass local_path. If
+            local_path is set, returns {local_path, doc_id, query, match_count,
+            bytes_written} instead.
+        """
+        lc = ctx.request_context.lifespan_context
+        docs_service = lc.docs_service
+
+        flags = 0 if case_sensitive else re.IGNORECASE
+        try:
+            pattern = re.compile(query, flags) if regex else re.compile(re.escape(query), flags)
+        except re.error as e:
+            return {"error": f"Invalid regex: {e}"}
+
+        try:
+            doc = await execute_in_thread(
+                docs_service.documents().get(documentId=doc_id).execute,
+                docs_service,
+            )
+        except Exception as e:
+            return {"error": str(e)}
+
+        results: list[dict[str, Any]] = []
+        for para_text, para_indices in _collect_doc_paragraphs(
+            doc.get("body", {}).get("content", [])
+        ):
+            if len(results) >= max_results:
+                break
+            for m in pattern.finditer(para_text):
+                if len(results) >= max_results:
+                    break
+                start_char, end_char = m.start(), m.end()
+                if start_char == end_char:
+                    continue
+                results.append(
+                    {
+                        "start_index": para_indices[start_char],
+                        "end_index": para_indices[end_char - 1]
+                        + _utf16_units(para_text[end_char - 1]),
+                        "matched_text": para_text[start_char:end_char],
+                        "context": para_text.rstrip("\n"),
+                    }
+                )
+
+        if local_path:
+            return await write_capped_result_to_disk(
+                results,
+                local_path,
+                default_filename="find_in_doc_results.json",
+                manifest_extra={
+                    "doc_id": doc_id,
+                    "query": query,
+                    "match_count": len(results),
+                },
+            )
+
+        enforce_response_size_cap(results, tool_name="find_in_doc")
+        return results
+
     @tool(annotations=ToolAnnotations(title="Insert Document Text", destructiveHint=True))
     async def insert_doc_text(
         doc_id: str,