pal-e-docs

Review: gmail-mcp: SSH-compatible gmail_reauth tool

review-361-2026-03-25 Review

review ready
Project

Verdict: READY

Template Completeness

  • [x] Lineage — present: pal-e-platform#162 (parent confirmed open)
  • [x] Repo — present: forgejo_admin/gmail-mcp
  • [x] User Story — present, well-formed
  • [x] Context — present, thorough explanation of SSH limitation and SDK building blocks
  • [x] File Targets — present with create/modify/don't-touch sections
  • [x] Acceptance Criteria — 5 checkable items
  • [x] Test Expectations — 3 items + run command
  • [x] Constraints — 4 items covering architecture, cache, redirect URI, naming
  • [x] Checklist — present
  • [x] Related — 3 links
  • [x] Type — bonus section (not required)

File Targets

  • [x] src/gmail_mcp/tools/reauth.py — to create: directory exists at ~/gmail-mcp/src/gmail_mcp/tools/, no naming conflict
  • [x] src/gmail_mcp/tools/__init__.py — to modify: exists, registration pattern confirmed (register_all_tools() imports all tool modules)
  • [x] src/gmail_mcp/auth.py — NOT to touch: confirmed, only contains SECRETS_DIR path
  • [x] ~/gmail-sdk/ — NOT to touch: confirmed, all 4 AuthMixin methods exist: get_auth_url(), exchange_code(), _save_token(), _load_credentials()

Repo Placement

OK. Issue filed on forgejo_admin/gmail-mcp. All file targets are within that repo. SDK changes explicitly excluded. Single-repo scope is correct.

Dependencies

  • Board item #359 (pal-e-platform#162 "Automate Gmail OAuth re-auth lifecycle") is in todo column — this is the parent lifecycle issue. Item #361 is a child deliverable. No blocking dependency.
  • gmail-sdk already has all required primitives — no SDK changes needed.
  • _clients cache in server.py is importable from tool modules (all 8 existing tools use from ..server import pattern). No new import pattern required.

Acceptance Criteria

All 5 criteria are testable by an agent:
  • gmail_reauth_start returns URL — unit-testable by checking URL format and scopes
  • gmail_reauth_complete exchanges + saves — unit-testable with mocked exchange_code
  • Post-reauth cache clear — verifiable by checking _clients dict state
  • Scopes list — verified: matches SCOPES constant in gmail-sdk/src/gmail_sdk/auth.py lines 22-28
  • No webbrowser/HTTP server — verifiable by code inspection (grep for webbrowser)
Note: exchange_code() takes a raw code string, but the tool spec says it accepts "full redirect URL (or bare code)". The tool must parse the auth code from the callback URL using urllib.parse. This is well-documented in the constraints and the SDK already imports those modules.

Blast Radius

Low. pal-e-mail also uses gmail-sdk but runs in k8s (not MCP), so it does not need this re-auth tool. No other MCP servers use Gmail OAuth. No downstream consumers affected.

Recommendation

No action needed. Scope is solid, all file targets verified, SDK primitives confirmed, import patterns established. Ready for agent execution.