Multi-Google MCP Server Implementation Plan

[MrBenJ]

Summary

• Adds a local stdio MCP server (multi-google-mcp) that lets an MCP client operate across multiple Google accounts with read+write Gmail, Calendar, and Drive scopes, routing each tool call by an explicit account label.
• Ships a standalone OAuth CLI (multi-google-mcp-auth add|list|remove) that runs Google's InstalledAppFlow outside the server, persisting per-label tokens at ~/.config/multi-google-mcp/accounts/<label>.json (chmod 600) with refresh-write-back semantics.
• Exposes 17 tools (1 discovery + 4 Gmail + 6 Calendar + 6 Drive) wired through a single TOOL_REGISTRY so list/call stay in sync; pure shaping helpers keep tool layers thin and unit-testable.
• README walks a new user from zero-GCP through Claude Desktop wiring; opt-in scripts/e2e_smoke.py boots the real server over MCP stdio and round-trips every domain against a live test account.

Test plan

• uv run pytest — 55 unit tests pass (config/exceptions/accounts/auth_cli/shaping{gmail,calendar,drive}/tools{gmail,calendar,drive}/server)
• uv run ruff check . — clean
• uv run mypy — clean under `strict = true`
• uv run multi-google-mcp-auth --help — argparse help renders, all three subcommands listed
• Manual (requires GCP setup): MCP_E2E_ACCOUNT=<test-label> uv run python scripts/e2e_smoke.py — drives every tool surface against a real Google test account over stdio

🤖 Generated with Claude Code

[aria-teknal-studio]

Findings:

1. [High] Account labels are used as filesystem paths without validation.
   In src/multi_google_mcp/accounts.py:33, _path() builds ACCOUNTS_DIR / f"{label}.json" directly from a caller-controlled label. That label comes from both the auth CLI and every MCP tool's account argument. Labels such as ../client_secret or ../../some/path can escape accounts/; save() can overwrite JSON files outside the account store, remove() can unlink them, and credentials()/refresh paths can read/write unexpected files. Because this is an MCP surface exposed to an LLM client, account labels should be treated as untrusted input. Please constrain labels to a safe slug format, reject separators/dots, and/or resolve the path and assert it remains inside ACCOUNTS_DIR. Add tests for traversal attempts on save, remove, and credentials.

2. [Medium] Drive reads can return unbounded file contents through stdio.
   src/multi_google_mcp/tools/drive.py:44 reads the entire Drive object/export into memory, and src/multi_google_mcp/tools/drive.py:59 base64-encodes arbitrary binary content into the MCP JSON response. There is no size check against Drive metadata, no byte cap, and no pagination/streaming strategy. A large Drive file can hang or crash the local MCP server/client and flood the model context. The same pattern exists for uploads/updates accepting arbitrary content in src/multi_google_mcp/tools/drive.py:85 and src/multi_google_mcp/tools/drive.py:106. Please add explicit maximum payload sizes, reject or summarize oversized files before download, and test the limit behavior.

3. [Medium] Token refresh writes are not atomic or protected against concurrent writers.
   src/multi_google_mcp/accounts.py:132 reads the token JSON, mutates it, and rewrites it with path.write_text(). If the auth CLI and server, or two server instances, refresh/write the same account at the same time, the account file can be truncated or corrupted. For a long-running local server this is a lifecycle bug: one bad interleaving can break all future calls for that account. Please use an atomic temp-file + replace flow and a per-account lock, and add a regression test around concurrent refresh/write behavior.

4. [Medium] Most tool failures escape the MCP error handling path.
   src/multi_google_mcp/server.py:316 only catches MultiGoogleMcpError. Google API HttpError, invalid base64 in Drive upload/update, malformed account JSON, missing keys, and unexpected extra arguments all bubble out of call_tool. That leaves clients with transport-level/internal errors instead of a stable tool result, and it may make one bad model/tool call look like a server failure. Please catch and normalize expected operational errors at the MCP boundary while preserving enough detail for local debugging. Tests should cover at least a Google API failure and invalid Drive upload content.

5. [Low] The risky surface has no GitHub CI coverage.
   GitHub reports no checks on this PR, and I do not see a workflow under .github/. Local verification passes for me: uv run pytest (55 passed), uv run ruff check ., and uv run mypy. Given this PR introduces Gmail/Calendar/Drive write tools and token handling, CI should run the unit gates at minimum on PRs before this lands. The live E2E can remain opt-in, but the pure unit/lint/typecheck coverage should be enforced.

[MrBenJ]

Addressed all 5 findings (commits 2bf026e..8194698, 85 unit tests all green).

1. [High] Label path traversal — Fixed in 2bf026e. Added InvalidAccountLabel exception and _validate_label enforcing [A-Za-z0-9_-]{1,64} slug at the _path() chokepoint, so save/credentials/remove all reject ../escape, subdir/leak, .hidden, etc. Parametrised tests in tests/test_accounts.py.

2. [Medium] Drive unbounded payloads — Fixed in 9375f1d. Added config.MAX_DRIVE_BYTES = 10 MiB + DriveFileTooLarge exception. Binary reads check metadata size before downloading; Google-native exports check after fetch but before encoding (size=0 in metadata is unavoidable for native files); uploads/updates check the decoded payload before handing to MediaIoBaseUpload.

3. [Medium] Non-atomic token writes — Fixed in 1ce064e. _atomic_write_json writes to <path>.tmp.<random>, fsyncs, then os.replace(). _file_lock acquires an exclusive fcntl.flock on a sidecar .lock around the RMW in save() and _on_refresh(). Tests cover no-leftovers and original-token preservation when os.replace fails.

4. [Medium] MCP error handling too narrow — Fixed in 20a20ba. Extracted _invoke_tool as a module-level function; catches MultiGoogleMcpError, googleapiclient.errors.HttpError, (ValueError, TypeError, KeyError), and a fallthrough for unexpected exceptions. Each returns "error: ..." text so the transport never sees a raw Python exception. Tests cover HttpError, ValueError, TypeError-for-unexpected-kwarg.

5. [Low] No CI — Fixed in 8194698. .github/workflows/ci.yml runs uv run ruff check ., uv run mypy, uv run pytest on every push to main and every PR. Python 3.11 (the pyproject floor); uv for install. The opt-in E2E smoke stays opt-in (no live Google creds in CI).

Ready for re-review.

[aria-teknal-studio]

Findings:

1. High - OAuth refresh tokens are briefly written to a temp file with default umask permissions before chmod 600.
   File: src/multi_google_mcp/accounts.py:48
   _atomic_write_json() opens the temp token file with plain open(tmp_path, "w"), writes refresh_token/access_token, fsyncs, closes it, and only then chmods it to 0600 at line 52. On a normal umask like 022, the temp file is readable by other local users during the write window, and the accounts directory is created with default directory permissions. Because this file contains Google refresh tokens for Gmail/Calendar/Drive, this is a real secret exposure. Open the temp file with restrictive permissions from creation time, e.g. os.open(..., O_CREAT|O_EXCL|O_WRONLY, 0o600) + fdopen, or set a restrictive umask around creation. Add a regression test that forces a permissive umask and observes the temp file mode before os.replace/chmod.

2. Medium - The Drive native-file size cap still downloads the whole export into memory before enforcing the cap.
   File: src/multi_google_mcp/tools/drive.py:58
   For Google Docs/Sheets/Slides, drive_read_file() calls export(...).execute() and only checks len(raw_bytes) afterward at line 61. A large shared Sheet/Doc can still allocate the full export and block or kill the MCP server before DriveFileTooLarge is raised, so the cap does not actually protect this path from resource exhaustion. Use a chunked MediaIoBaseDownload/export stream and abort once accumulated bytes exceed MAX_DRIVE_BYTES, then test that oversized native exports stop before buffering the whole payload.

3. Medium - Gmail full-message reads have no response-size guard.
   File: src/multi_google_mcp/tools/gmail.py:45
   gmail_get_message() fetches format="full" and shape_message_full() returns body_text without any cap (src/multi_google_mcp/shaping/gmail.py:71). Gmail messages can carry very large plain/html bodies, and this MCP server returns the decoded body directly into the stdio/model context. That creates the same resource-exhaustion/context-flooding risk the PR already mitigates for Drive. Add a max Gmail body/response size policy, use fields/format choices where possible, and cover oversized message bodies in tests.

Verification:

• uv run ruff check . passed.
• uv run mypy passed.
• uv run pytest passed: 85 tests.
• GitHub PR check "pytest + ruff + mypy" is passing.

Summary:
This is a strong first implementation and CI now covers the main local gates, but the remaining issues are on security-sensitive token persistence and unbounded external payload paths. I would not merge until those are addressed.

[MrBenJ]

Iteration 2 fixes — 88 unit tests green, ruff + mypy clean, CI passing.

1. [High] Temp file perms during write window — Fixed in 6f07f40. Swapped _atomic_write_json from open(tmp_path, "w") to os.open(tmp_path, O_CREAT|O_EXCL|O_WRONLY, 0o600) + os.fdopen, so the file is never world-readable even under umask 0o022. Regression test forces umask 0o022, patches os.chmod to a no-op, and asserts the mode captured just before os.replace is still 0o600.

2. [Medium] Native Drive export buffered entire body before cap — Fixed in 033ba31. Added _download_chunked which wraps the export request in MediaIoBaseDownload with 1 MiB chunks and checks buf.tell() between next_chunk() calls. For a 500 MiB Sheet the abort fires after ~11 chunks instead of buffering the whole payload. Test feeds 1 MiB chunks indefinitely (next_chunk never returns done) and asserts the abort lands well below 50 iterations.

3. [Medium] Gmail body unbounded — Fixed in ac16ecf. Added config.MAX_GMAIL_BODY_BYTES = 256 KiB and _truncate_body in gmail_get_message. Oversized bodies are clipped with a marker exposing the original size, so the agent knows the view is partial instead of silently working from truncated content. UTF-8 byte length so multibyte chars don't slip past the cap.

Ready for re-review.

[aria-teknal-studio]

No findings.

The current head addresses the prior review findings:

• src/multi_google_mcp/accounts.py now creates token temp files with os.open(..., 0o600) from creation time, with a permissive-umask regression test.
• src/multi_google_mcp/tools/drive.py now streams native Google exports through MediaIoBaseDownload and aborts once the accumulated buffer exceeds MAX_DRIVE_BYTES, with coverage for the oversized-export path.
• src/multi_google_mcp/tools/gmail.py now truncates full message bodies before returning them through MCP, with tests for both oversized and under-cap bodies.

Verification:

• uv run ruff check . passed.
• uv run mypy passed.
• uv run pytest passed: 88 tests.
• GitHub PR check "pytest + ruff + mypy" is passing.

Residual risk:
The live Google e2e smoke test remains opt-in by design because it requires real credentials and network access. That is reasonable for CI, but it should be run manually before relying on this against production Google accounts.