feat: add gmail_reauth MCP tools for SSH-compatible token refresh

forgejo_admin commented

2026-03-26 03:51:51 +00:00

Owner

Summary

Two-step OAuth re-authorization flow that works over SSH without a local browser or HTTP server
gmail_reauth_start generates the Google consent URL with all scopes; gmail_reauth_complete accepts the redirect URL or bare auth code, exchanges for tokens, saves to disk, and clears the client cache
Subsequent tool calls work immediately after reauth -- no MCP restart needed

Changes

src/gmail_mcp/tools/reauth.py: new module with gmail_reauth_start, gmail_reauth_complete, and _extract_code helper
src/gmail_mcp/tools/__init__.py: register reauth module in register_all_tools()
tests/test_reauth.py: 11 tests covering URL generation, code exchange, cache clearing, bare code handling, and error paths

Test Plan

Tests pass locally -- 105 tests (94 existing + 11 new), uv run pytest tests/ -v
Ruff lint and format clean -- uv run ruff check src/ tests/
Manual verification: call gmail_reauth_start, open URL, copy redirect, call gmail_reauth_complete, verify gmail_get_profile works

Review Checklist

Passed automated review-fix loop
No secrets committed
No unnecessary file changes
Commit messages are descriptive

Closes #6
plan-pal-e-mail -- Phase 2c sender registry re-auth flow

## Summary - Two-step OAuth re-authorization flow that works over SSH without a local browser or HTTP server - `gmail_reauth_start` generates the Google consent URL with all scopes; `gmail_reauth_complete` accepts the redirect URL or bare auth code, exchanges for tokens, saves to disk, and clears the client cache - Subsequent tool calls work immediately after reauth -- no MCP restart needed ## Changes - `src/gmail_mcp/tools/reauth.py`: new module with `gmail_reauth_start`, `gmail_reauth_complete`, and `_extract_code` helper - `src/gmail_mcp/tools/__init__.py`: register `reauth` module in `register_all_tools()` - `tests/test_reauth.py`: 11 tests covering URL generation, code exchange, cache clearing, bare code handling, and error paths ## Test Plan - [x] Tests pass locally -- 105 tests (94 existing + 11 new), `uv run pytest tests/ -v` - [x] Ruff lint and format clean -- `uv run ruff check src/ tests/` - [ ] Manual verification: call `gmail_reauth_start`, open URL, copy redirect, call `gmail_reauth_complete`, verify `gmail_get_profile` works ## Review Checklist - [x] Passed automated review-fix loop - [x] No secrets committed - [x] No unnecessary file changes - [x] Commit messages are descriptive ## Related - Closes #6 - `plan-pal-e-mail` -- Phase 2c sender registry re-auth flow

forgejo_admin added 1 commit

2026-03-26 03:51:51 +00:00

feat: add gmail_reauth_start and gmail_reauth_complete MCP tools

ci/woodpecker/push/woodpecker Pipeline failed

Details

ci/woodpecker/pr/woodpecker Pipeline failed

Details

5e9fac0ce0

SSH-compatible two-step OAuth re-authorization flow that generates
the consent URL and exchanges the callback code without needing a
local browser or HTTP server. Clears the client cache after reauth
so subsequent tool calls use fresh credentials immediately.

Closes #6

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

forgejo_admin commented

2026-03-26 03:52:21 +00:00

Author

Owner

Review: LGTM

Files reviewed: 3 (1 modified, 2 new)

Findings

No issues found. The implementation is clean:

Pattern adherence: Follows all 8 existing tool modules exactly -- @mcp.tool() decorator, Annotated[..., Field(...)] parameters, _error_response exception handling, json.dumps returns
SDK integration: Correctly uses AuthMixin.get_auth_url(), exchange_code(), _load_credentials(), _save_token() without modifying the SDK
Cache invalidation: _clients.pop(alias, None) ensures subsequent tool calls get a fresh GmailClient -- no MCP restart needed
URL parsing: _extract_code handles both full callback URLs and bare auth codes, with clear error on missing code parameter
Test coverage: 11 tests across 3 classes cover happy paths, error paths, bare code handling, and cache clearing verification
Registration: Single alphabetically-sorted line in __init__.py

Test results

105/105 tests pass (94 existing + 11 new)
ruff check + format clean
337 additions, 0 deletions -- purely additive, no regression risk

## Review: LGTM **Files reviewed:** 3 (1 modified, 2 new) ### Findings No issues found. The implementation is clean: - **Pattern adherence**: Follows all 8 existing tool modules exactly -- `@mcp.tool()` decorator, `Annotated[..., Field(...)]` parameters, `_error_response` exception handling, `json.dumps` returns - **SDK integration**: Correctly uses `AuthMixin.get_auth_url()`, `exchange_code()`, `_load_credentials()`, `_save_token()` without modifying the SDK - **Cache invalidation**: `_clients.pop(alias, None)` ensures subsequent tool calls get a fresh `GmailClient` -- no MCP restart needed - **URL parsing**: `_extract_code` handles both full callback URLs and bare auth codes, with clear error on missing code parameter - **Test coverage**: 11 tests across 3 classes cover happy paths, error paths, bare code handling, and cache clearing verification - **Registration**: Single alphabetically-sorted line in `__init__.py` ### Test results - 105/105 tests pass (94 existing + 11 new) - ruff check + format clean - 337 additions, 0 deletions -- purely additive, no regression risk

forgejo_admin commented

2026-03-26 03:55:12 +00:00

Author

Owner

PR #7 Review

DOMAIN REVIEW

Tech stack: Python / MCP server (FastMCP) / gmail-sdk / pytest. Domain checklist: Python/PEP compliance, OWASP awareness, test coverage.

Code quality: The implementation is clean and follows the established patterns in this codebase well. Both tools use the same @mcp.tool() decorator, Annotated[..., Field(...)] parameter style, try/except -> _error_response error handling, and json.dumps(..., indent=2) return pattern seen in messages.py, threads.py, etc. The _extract_code helper is well-factored with clear docstring and handles both full-URL and bare-code inputs.

PEP compliance: Module docstrings (PEP 257), from __future__ import annotations (PEP 604 union syntax), type hints on all functions (PEP 484). Clean.

SDK coupling observation: The code uses AuthMixin._load_credentials() and AuthMixin._save_token() -- both underscore-prefixed "private" methods on the SDK. However, reviewing the SDK source at /home/ldraney/gmail-sdk/src/gmail_sdk/auth.py, these are @staticmethod methods with clear signatures and the SDK's own authorize() method uses them the same way. The get_auth_url() and exchange_code() methods are public. Since this MCP server and the SDK share the same owner/maintainer, this coupling is acceptable -- but worth noting that SDK changes to _load_credentials or _save_token signatures would break this tool without a compile-time guard.

Input validation: The callback_url parameter is validated through _extract_code() which properly raises ValueError when a URL has no code parameter. Bare strings are passed through with .strip(), which is the correct behavior since Google will reject invalid codes at the exchange step. No injection risk -- the code is passed to Google's token endpoint via httpx.post, not interpolated into SQL or shell commands.

Error handling: Both tools catch all exceptions and route through _error_response(), consistent with the rest of the codebase. The _extract_code ValueError is caught by the outer try/except in gmail_reauth_complete.

Cache invalidation: _clients.pop(alias, None) correctly clears the cached client so the next tool call gets a fresh GmailClient with the new token. This is the right approach.

BLOCKERS

None.

Test coverage: 11 new tests covering happy paths, error paths, edge cases (bare code, whitespace, missing code, exchange failure, cache clearing). No zero-coverage gap.
No secrets or credentials committed -- test values are clearly synthetic ("test-client-id", "test-secret").
No unvalidated user input risk -- callback URL is parsed, not executed.
No DRY violation in auth paths -- credential loading delegates to AuthMixin, no duplicated auth logic.

NITS

_extract_code edge case -- URL with scheme but no query: If someone passes http://localhost:8090 (no query string at all), parsed.scheme is truthy but parsed.query is empty string (falsy), so the function falls through to the bare-code branch and returns "http://localhost:8090". This would fail at Google's token endpoint anyway, but a more descriptive error could be raised here. Very minor -- Google's error message will surface through _error_response.
Unused alias in gmail_reauth_start: The alias = resolve_account(account) call validates the account and the alias is used in the response JSON, so this is fine. Just noting it reads slightly like alias might be unused at first glance -- the code is correct.
Test imports inside with blocks: The tests import gmail_reauth_start / gmail_reauth_complete inside the with context manager blocks. This works because the modules are already registered at import time, but it is slightly unusual compared to top-of-file imports. This appears to be a pattern choice to ensure the patches are active during import-time side effects, which is valid for this @mcp.tool() decorator pattern.

SOP COMPLIANCE

Branch named after issue: 6-gmail-reauth-tool matches issue #6
PR body has: Summary, Changes, Test Plan, Related sections
Related section references plan-pal-e-mail plan slug
Tests exist: 11 new tests (208 lines) for 128 lines of implementation
No secrets committed
No unnecessary file changes: exactly 3 files, all directly related to the feature
Commit messages are descriptive

PROCESS OBSERVATIONS

Deployment frequency: Clean, small PR (337 additions, 0 deletions, 3 files). Good change size for rapid deployment.
Change failure risk: Low. The new tools are additive -- no existing tools modified. The only existing file touched is __init__.py to register the new module (1 line). The registration is alphabetically ordered, consistent with the existing pattern.
CI coverage: Woodpecker pipeline runs ruff check, ruff format --check, and pytest on PRs. The 11 new tests will run in CI.
Documentation: The tool docstrings and inline instructions provide clear user-facing guidance for the two-step reauth flow.

VERDICT: APPROVED

## PR #7 Review ### DOMAIN REVIEW **Tech stack**: Python / MCP server (FastMCP) / gmail-sdk / pytest. Domain checklist: Python/PEP compliance, OWASP awareness, test coverage. **Code quality**: The implementation is clean and follows the established patterns in this codebase well. Both tools use the same `@mcp.tool()` decorator, `Annotated[..., Field(...)]` parameter style, `try/except -> _error_response` error handling, and `json.dumps(..., indent=2)` return pattern seen in `messages.py`, `threads.py`, etc. The `_extract_code` helper is well-factored with clear docstring and handles both full-URL and bare-code inputs. **PEP compliance**: Module docstrings (PEP 257), `from __future__ import annotations` (PEP 604 union syntax), type hints on all functions (PEP 484). Clean. **SDK coupling observation**: The code uses `AuthMixin._load_credentials()` and `AuthMixin._save_token()` -- both underscore-prefixed "private" methods on the SDK. However, reviewing the SDK source at `/home/ldraney/gmail-sdk/src/gmail_sdk/auth.py`, these are `@staticmethod` methods with clear signatures and the SDK's own `authorize()` method uses them the same way. The `get_auth_url()` and `exchange_code()` methods are public. Since this MCP server and the SDK share the same owner/maintainer, this coupling is acceptable -- but worth noting that SDK changes to `_load_credentials` or `_save_token` signatures would break this tool without a compile-time guard. **Input validation**: The `callback_url` parameter is validated through `_extract_code()` which properly raises `ValueError` when a URL has no `code` parameter. Bare strings are passed through with `.strip()`, which is the correct behavior since Google will reject invalid codes at the exchange step. No injection risk -- the code is passed to Google's token endpoint via `httpx.post`, not interpolated into SQL or shell commands. **Error handling**: Both tools catch all exceptions and route through `_error_response()`, consistent with the rest of the codebase. The `_extract_code` ValueError is caught by the outer `try/except` in `gmail_reauth_complete`. **Cache invalidation**: `_clients.pop(alias, None)` correctly clears the cached client so the next tool call gets a fresh `GmailClient` with the new token. This is the right approach. ### BLOCKERS None. - Test coverage: 11 new tests covering happy paths, error paths, edge cases (bare code, whitespace, missing code, exchange failure, cache clearing). No zero-coverage gap. - No secrets or credentials committed -- test values are clearly synthetic (`"test-client-id"`, `"test-secret"`). - No unvalidated user input risk -- callback URL is parsed, not executed. - No DRY violation in auth paths -- credential loading delegates to `AuthMixin`, no duplicated auth logic. ### NITS 1. **`_extract_code` edge case -- URL with scheme but no query**: If someone passes `http://localhost:8090` (no query string at all), `parsed.scheme` is truthy but `parsed.query` is empty string (falsy), so the function falls through to the bare-code branch and returns `"http://localhost:8090"`. This would fail at Google's token endpoint anyway, but a more descriptive error could be raised here. Very minor -- Google's error message will surface through `_error_response`. 2. **Unused `alias` in `gmail_reauth_start`**: The `alias = resolve_account(account)` call validates the account and the alias is used in the response JSON, so this is fine. Just noting it reads slightly like `alias` might be unused at first glance -- the code is correct. 3. **Test imports inside `with` blocks**: The tests import `gmail_reauth_start` / `gmail_reauth_complete` inside the `with` context manager blocks. This works because the modules are already registered at import time, but it is slightly unusual compared to top-of-file imports. This appears to be a pattern choice to ensure the patches are active during import-time side effects, which is valid for this `@mcp.tool()` decorator pattern. ### SOP COMPLIANCE - [x] Branch named after issue: `6-gmail-reauth-tool` matches issue #6 - [x] PR body has: Summary, Changes, Test Plan, Related sections - [x] Related section references `plan-pal-e-mail` plan slug - [x] Tests exist: 11 new tests (208 lines) for 128 lines of implementation - [x] No secrets committed - [x] No unnecessary file changes: exactly 3 files, all directly related to the feature - [x] Commit messages are descriptive ### PROCESS OBSERVATIONS - **Deployment frequency**: Clean, small PR (337 additions, 0 deletions, 3 files). Good change size for rapid deployment. - **Change failure risk**: Low. The new tools are additive -- no existing tools modified. The only existing file touched is `__init__.py` to register the new module (1 line). The registration is alphabetically ordered, consistent with the existing pattern. - **CI coverage**: Woodpecker pipeline runs `ruff check`, `ruff format --check`, and `pytest` on PRs. The 11 new tests will run in CI. - **Documentation**: The tool docstrings and inline instructions provide clear user-facing guidance for the two-step reauth flow. ### VERDICT: APPROVED