feat(mcp): native Gmail adapter — §6.5 profile over GA REST as stdio MCP server

[chaodu-agent]

0. Discord Discussion URL

Follow-up to #1448 (facade MVP) per the maintainer discussion recorded there: Gmail live validation report — hosted Gmail MCP is Developer-Preview-gated and unshippable pre-GA; the ADR's Capability Plugin path (#1446 §5.3/§6.1, rollout step 5) is re-sequenced to ship first.

1. What problem does this solve?

Implements the native Gmail adapter (Capability Plugin): the ADR §6.5 six-capability Gmail profile served from Gmail's generally-available REST API instead of the preview-gated hosted MCP server. Live validation on #1448 established that (a) the hosted server denies every tools/call without Workspace Developer Preview enrollment (per account and per GCP project, manual approval), (b) DPP terms bar shipping preview features in public applications, and (c) the same OAuth token works against Gmail REST — so this is the only Gmail path that can reach OAB users today.

It also fixes the refresh-token gap found in that validation: the rmcp-driven login flow cannot send access_type=offline (embedded authorize_url query params are dropped by the URL builder — verified empirically), so Google never issues a refresh token and headless deployments die after ~1h. The adapter owns its own PKCE login that requests offline access.

2. How it works

mcp.json                                OAB MCP runtime / facade
  "gmail": {                               │  Streamable HTTP client
    "type": "http",                        ▼
    "url": "http://127.0.0.1:8850/mcp" openab-agent gmail-native serve
  }                                        │    --listen 127.0.0.1:8850
                                           │  (loopback-only enforced; env:
                                           │   GMAIL_OAUTH_CLIENT_ID/SECRET)
                                           │  rmcp ServerHandler, 6 tools
                                           │  bearer from auth.json["gmail-native"]
                                           │  single-flight refresh (offline grant)
                                           ▼
                                     gmail.googleapis.com/gmail/v1 (GA REST)

• Packaging = loopback Streamable HTTP MCP server — the same transport and trust model as the OAB MCP Facade (require_loopback reused; non-loopback binds refused at startup; no auth layer, the host/pod boundary is the trust boundary). It registers in mcp.json like any other "type": "http" server, so tool_filter, JSON-Schema argument validation, timeouts, the circuit breaker, and secret redaction apply unchanged (ADR §4: "an implementation path behind the same facade, not a new agent-facing contract"). Any MCP client can also use it directly.
• Tool surface mirrors the hosted server — search_threads, get_thread, get_message, list_labels, list_drafts, create_draft with matching argument shapes — so the GA cut-over back to gmailmcp.googleapis.com is an mcp.json edit with no agent-facing change.
• Drafts-only writes (§6.5): create_draft never sends; no send/delete/label-mutation tool exists. Draft results state explicitly that nothing was sent. Reply threading resolves the original Message-ID and sets In-Reply-To/References.
• Hardening: Gmail ids validated ([A-Za-z0-9_-], bounded) before path use; MIME header values refuse CR/LF (header injection); RFC 2047 encoding for non-ASCII subjects; 76-col base64 body; page sizes clamped to 1–100.
• Credentials: openab-agent gmail-native login runs PKCE S256 paste-back with access_type=offline + prompt=consent, stores rmcp-shaped StoredCredentials under the gmail-native key in the shared auth.json (0600, same store/locking as the runtime). Refresh is single-flight, re-checks under the lock, and keeps the previous refresh token when Google omits a rotated one (RFC 6749 §6). Missing refresh token at login prints a loud warning with the revoke-and-retry remediation.

3. Scope

crates/openab-mcp (new native::gmail module + lib.rs export; facade::require_loopback made crate-visible) and openab-agent (two subcommands: gmail-native serve --listen|login). No changes to runtime, meta_tool, config schema, or broker.

4. Validation

On macOS arm64 (macmini):

• openab-mcp: 208 tests pass (10 new: MIME shape/UTF-8 subject/injection/reply headers, id validation, six-tool catalog + forbidden-capability guard, credential roundtrips, query clamping, bare-string tolerance)
• openab-agent: 62 tests pass; both workspaces build release; cargo clippy --workspace --all-features -- -D warnings = 0 findings; cargo fmt --check clean
• Live e2e against real Gmail through the facade (mcp-facade on loopback, adapter as stdio child):
  • mcp doctor green; search_capabilities returns exactly the 6 tools, all ready
  • list_labels, search_threads (query + pageSize), get_thread (metadata), list_drafts — all isError:false with real mailbox data
  • create_draft with a Chinese subject (RFC 2047 path) → draft created, verified, then deleted (cleanup via REST, HTTP 204 — the adapter itself has no delete)
  • Headless refresh proven: forced token_received_at staleness → next tool call auto-refreshed (new token persisted, refresh token retained)
  • HTTP transport re-validated after the stdio→Streamable-HTTP change: adapter on 127.0.0.1:8850/mcp, facade type:"http" entry — discovery (6 ready), search_threads, create_draft (created then deleted, HTTP 204) all green; --listen 0.0.0.0:9999 refused at startup

Review Contract

Goal

Ship the ADR §6.5 Gmail profile as a native Capability Plugin (stdio MCP server over Gmail GA REST) with offline-access OAuth, so Gmail capabilities are usable by OAB deployments today, without DPP enrollment, with no agent-facing contract change relative to the hosted server.

Non-goals

• Sending mail, deleting anything, or label mutation (drafts-only by design).
• Attachments (hosted server doesn't support them in create_draft either).
• Retiring the hosted-MCP path — it remains the intended default at GA (rollout step 5 decision recorded on feat(mcp): OAB MCP Facade MVP — shared openab-mcp crate + broker loopback HTTP server #1448); this adapter is the pre-GA ship vehicle.
• A generic extra_authorize_params mechanism in the shared OAuth flow (tracked as a follow-up; this adapter self-contains its offline-access need).
• Native adapters for other providers (Calendar etc.) — same pattern, separate PRs.

Accepted Residual Risks

• The adapter trusts Gmail REST response shapes (no schema validation of Google's responses); malformed responses surface as JSON passthrough to the agent.
• GMAIL_OAUTH_CLIENT_SECRET is read from the serve process's environment (delivered by the operator/task definition). Secret-less Desktop-type OAuth clients avoid it entirely.
• The loopback endpoint is unauthenticated (facade trust model): any process on the host can use the authorized mailbox capabilities while the adapter runs. Same accepted risk and mitigations as the facade MVP (feat(mcp): OAB MCP Facade MVP — shared openab-mcp crate + broker loopback HTTP server #1448).
• Refresh-token revocation (user revokes at Google) surfaces as an actionable re-login error on the next call, not proactively.

Acceptance Criteria

• Both workspaces: fmt/clippy/test green per §4 with zero introduced clippy findings.
• gmail_tools() exposes exactly the six §6.5 tools; no send/delete/modify/label-mutation names (regression test in place).
• Header-injection attempts (CR/LF in address or subject) are refused, not sanitized (tests).
• Login stores a refresh token when Google issues one and warns loudly when it doesn't; forced-staleness refresh works end-to-end (validated live per §4).
• A tool_filter-excluded tool is invisible/blocked exactly as for any other server (inherited from the runtime — no adapter-specific policy code to review).

Follow-ups

• Trash capability (deliberately deferred, discussed with maintainer): trash_message/trash_thread/untrash_message require the gmail.modify scope and a policy expansion beyond the §6.5 drafts-only profile — separate PR with its own contract, reversible-trash-only (never permanent delete / full-mailbox scope).
• Generalize offline-access params: an oauth.extra_authorize_params map in the shared OAuth flow so provider quirks (Google's access_type=offline) don't require adapter-owned login code.
• Calendar native adapter: same Capability Plugin pattern for the Calendar profile (hosted Calendar MCP is gated behind the same Workspace-only Developer Preview Program).
• Hosted-MCP cut-over evaluation at GA: when gmailmcp.googleapis.com reaches GA (and if it opens to consumer accounts), re-evaluate swapping the mcp.json entry back per rollout step 5; tool names/shapes are already aligned.
• User-facing OAuth authorization flow: today's login is operator-CLI paste-back. For chat-product UX, add (a) in-chat paste-back — the bot posts the authorize URL and accepts the pasted redirect in the conversation (no infra), then (b) gateway-callback — register https://gw.openab.dev/oauth/callback as the redirect URI and route the code back to the requesting bot by state (zero-paste, OpenWork-style "Connect Gmail"). Google device flow is not an option (gmail.* scopes unsupported). Note: gmail.* are restricted scopes — public distribution beyond 100 test users requires Google's restricted-scope verification.
• Fleet deployment hardening: the b2 validation ran the adapter as a manually started process; production-izing means baking the binary into the image, starting serve from boot config, and moving the OAuth client secret to Secrets Manager.