From 22d3b6d6084604185621a778c8676abd7b4cd411 Mon Sep 17 00:00:00 2001
From: Ben Junya <teknal@teknal.studio>
Date: Wed, 20 May 2026 21:03:21 -0700
Subject: [PATCH 1/3] docs: spec for openid OAuth scope fix

Add a brainstorm design doc describing the single-line addition of
"openid" to config.SCOPES to unblock multi-google-mcp-auth add against
oauthlib's scope-change-as-Warning behavior.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../2026-05-20-openid-scope-fix-design.md     | 68 +++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-20-openid-scope-fix-design.md

diff --git a/docs/superpowers/specs/2026-05-20-openid-scope-fix-design.md b/docs/superpowers/specs/2026-05-20-openid-scope-fix-design.md
new file mode 100644
index 0000000..df7f392
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-20-openid-scope-fix-design.md
@@ -0,0 +1,68 @@
+# Add `openid` to OAuth SCOPES to unblock auth flow
+
+## Goal
+
+Fix `multi-google-mcp-auth add <label>` aborting when Google returns `openid` in
+the granted scope set. Add `"openid"` to `config.SCOPES` so the requested set
+matches what Google returns, and `oauthlib`'s scope-change check stops firing.
+
+## Background
+
+Google's OAuth implementation implicitly grants `openid` whenever
+`userinfo.email` (or other identity-bearing scopes) is requested. `oauthlib`'s
+`InstalledAppFlow` treats any divergence between requested and granted scopes as
+a `Warning`, which `oauthlib` raises as an exception, aborting the flow before
+the token is persisted. The repro is `multi-google-mcp-auth add personal`
+against a fresh OAuth client — it fails consistently.
+
+## Change
+
+Single-line edit to `src/multi_google_mcp/config.py`: append `"openid"` to the
+`SCOPES` list.
+
+```python
+SCOPES = [
+    "https://www.googleapis.com/auth/gmail.modify",
+    "https://www.googleapis.com/auth/calendar",
+    "https://www.googleapis.com/auth/drive",
+    "https://www.googleapis.com/auth/userinfo.email",
+    "openid",
+]
+```
+
+No code changes elsewhere. `accounts.py` consumes `SCOPES` directly from
+`config`; nothing else cares about the list contents.
+
+## Why not a test
+
+The OAuth flow only runs against live Google APIs — `auth_cli.py` calls
+`google_auth_oauthlib.flow.InstalledAppFlow.from_client_secrets_file(...)` and
+drives a local browser callback. The existing test suite mocks
+`googleapiclient.discovery.build` and never exercises the auth flow. There is no
+seam for a unit test to catch this regression, and the scope-list contents are
+trivially inspectable. Per the `superpowers:test-driven-development` config-only
+exception, no new test is added.
+
+## Verification
+
+1. `uv tool install --reinstall .` — reinstall the console script so the
+   already-installed `multi-google-mcp-auth` picks up the updated `SCOPES`.
+2. `multi-google-mcp-auth add personal` — completes without `oauthlib` raising
+   on scope mismatch, prints success, writes
+   `~/.config/multi-google-mcp/accounts/personal.json`.
+
+## Caveats
+
+- CLAUDE.md notes: changing `SCOPES` requires every existing account to be
+  re-added. The `personal` account is re-added as the verify step. No other
+  accounts exist locally (confirmed by user), so nothing else to handle.
+- This is a one-way fix — `openid` is a stable, standardized OIDC scope and is
+  effectively always granted alongside `userinfo.email`. No regression risk for
+  callers that don't care about identity tokens (we don't use the ID token; the
+  scope is purely there to keep `oauthlib` quiet).
+
+## Non-goals
+
+- No update to CLAUDE.md's scope-list commentary in this change.
+- No revisit of the broader OAuth flow or scope set.
+- No swap to a different OAuth library or relaxed `oauthlib` warning policy.

From ffd9e4793a4e60657ca11aa989767228779ddbaa Mon Sep 17 00:00:00 2001
From: Ben Junya <teknal@teknal.studio>
Date: Wed, 20 May 2026 21:04:31 -0700
Subject: [PATCH 2/3] docs: implementation plan for openid OAuth scope fix

Task-by-task plan for the single-line config edit, reinstall, and
end-to-end auth-flow verification against the personal account.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../plans/2026-05-20-openid-scope-fix.md      | 147 ++++++++++++++++++
 1 file changed, 147 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-20-openid-scope-fix.md

diff --git a/docs/superpowers/plans/2026-05-20-openid-scope-fix.md b/docs/superpowers/plans/2026-05-20-openid-scope-fix.md
new file mode 100644
index 0000000..1dc9c0b
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-20-openid-scope-fix.md
@@ -0,0 +1,147 @@
+# Add `openid` to OAuth SCOPES Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Append `"openid"` to `SCOPES` in `src/multi_google_mcp/config.py` so `oauthlib` stops aborting `multi-google-mcp-auth add` when Google implicitly grants the `openid` scope.
+
+**Architecture:** One-line edit to a config list. No new tests (the OAuth flow is not exercised in the test suite; verification happens against live Google APIs). After editing, the locally installed `multi-google-mcp-auth` console script is reinstalled with `uv tool install --reinstall .` so it picks up the new code, then the auth flow is driven manually against the `personal` account to confirm the fix.
+
+**Tech Stack:** Python 3.11+, `uv`, `google-auth-oauthlib`, `oauthlib`, `mcp` SDK.
+
+---
+
+## File Structure
+
+- Modify: `src/multi_google_mcp/config.py:9-14` — add `"openid"` to the existing `SCOPES` list.
+
+That's all. No new files, no other modifications.
+
+---
+
+### Task 1: Add `openid` to SCOPES and verify static checks
+
+**Files:**
+- Modify: `src/multi_google_mcp/config.py:9-14`
+
+- [ ] **Step 1: Make the edit**
+
+Open `src/multi_google_mcp/config.py` and change the `SCOPES` list from:
+
+```python
+SCOPES = [
+    "https://www.googleapis.com/auth/gmail.modify",
+    "https://www.googleapis.com/auth/calendar",
+    "https://www.googleapis.com/auth/drive",
+    "https://www.googleapis.com/auth/userinfo.email",
+]
+```
+
+to:
+
+```python
+SCOPES = [
+    "https://www.googleapis.com/auth/gmail.modify",
+    "https://www.googleapis.com/auth/calendar",
+    "https://www.googleapis.com/auth/drive",
+    "https://www.googleapis.com/auth/userinfo.email",
+    "openid",
+]
+```
+
+- [ ] **Step 2: Run the existing test suite**
+
+Run: `uv run pytest`
+Expected: PASS — all existing tests still pass. The added scope is consumed only by the auth CLI's `InstalledAppFlow` and is not exercised in tests (`accounts.py` references `config.SCOPES` but the test fixtures stub out the OAuth flow entirely).
+
+- [ ] **Step 3: Run the linter**
+
+Run: `uv run ruff check .`
+Expected: PASS — `All checks passed!`.
+
+- [ ] **Step 4: Run the type-checker**
+
+Run: `uv run mypy`
+Expected: PASS — no new errors.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/multi_google_mcp/config.py
+git commit -m "$(cat <<'EOF'
+fix: add openid to OAuth SCOPES to unblock auth flow
+
+Google implicitly grants the openid scope whenever userinfo.email (or
+any identity-bearing scope) is requested. oauthlib raises the scope
+mismatch as an exception via its Warning-to-error path, aborting
+multi-google-mcp-auth add before any token is written.
+
+Adding "openid" to the requested set keeps the granted set aligned and
+silences oauthlib without changing actual API access.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+### Task 2: Reinstall the console scripts so the installed CLI picks up the new code
+
+**Files:** None modified.
+
+- [ ] **Step 1: Reinstall**
+
+Run: `uv tool install --reinstall .`
+Expected: output ends with something like `Installed 2 executables: multi-google-mcp, multi-google-mcp-auth`. No errors.
+
+- [ ] **Step 2: Sanity-check the installed binary picks up the new scope list**
+
+Run:
+```bash
+which multi-google-mcp-auth
+uv tool run --from . python -c "from multi_google_mcp.config import SCOPES; print('openid' in SCOPES, len(SCOPES))"
+```
+Expected: path is printed; second line prints `True 5`.
+
+- [ ] **Step 3: No commit**
+
+Reinstall produces no repo changes — nothing to commit.
+
+---
+
+### Task 3: Verify the fix end-to-end against the `personal` account
+
+**Files:** None modified.
+
+- [ ] **Step 1: Run the auth flow**
+
+Run: `multi-google-mcp-auth add personal`
+Expected behavior:
+- Prints a `Please visit this URL` line and opens a browser tab to Google's consent screen.
+- User completes consent in the browser.
+- Process prints something like `Saved account 'personal' to ~/.config/multi-google-mcp/accounts/personal.json` (or whatever success line `auth_cli.py` emits) and exits 0.
+- The previous failure mode — an `oauthlib` exception about scope mismatch / Warning before the token file is written — does NOT occur.
+
+Note: this step is interactive (browser OAuth consent). If running in a non-interactive context, hand off to the user with a clear "please complete the OAuth consent in your browser" prompt.
+
+- [ ] **Step 2: Confirm the token file was (re)written**
+
+Run: `ls -la ~/.config/multi-google-mcp/accounts/personal.json && stat -f '%Sm' ~/.config/multi-google-mcp/accounts/personal.json`
+Expected: file exists, permissions are `-rw-------` (mode 0o600 per `accounts._atomic_write_json`), modification timestamp is from the last few seconds.
+
+- [ ] **Step 3: Confirm the new scope set is in the saved token**
+
+Run: `python -c "import json; d=json.load(open('${HOME}/.config/multi-google-mcp/accounts/personal.json')); print(sorted(d.get('scopes', [])))"`
+Expected: list includes `"openid"` alongside the other four scopes.
+
+- [ ] **Step 4: No commit**
+
+Verification produces no repo changes — nothing to commit.
+
+---
+
+## Notes on what is *not* in this plan
+
+- No new unit test. The `SCOPES` list is data, not behavior; the OAuth flow it feeds is not under test in this repo (test fixtures mock `googleapiclient.discovery.build` and never construct an `InstalledAppFlow`). Per the test-driven-development skill's config-only exception, no test is added.
+- No update to CLAUDE.md's commentary about the SCOPES list — out of scope for this fix.
+- No revisit of other OAuth-flow ergonomics (token rotation, scope subset upgrades, etc.).

From db5cca640b4180e60db7df5d07c480168a75db04 Mon Sep 17 00:00:00 2001
From: Ben Junya <teknal@teknal.studio>
Date: Wed, 20 May 2026 21:06:12 -0700
Subject: [PATCH 3/3] fix: add openid to OAuth SCOPES to unblock auth flow

Google implicitly grants the openid scope whenever userinfo.email (or
any identity-bearing scope) is requested. oauthlib treats the resulting
scope-set divergence as a Warning, which it raises as an exception via
its warnings-as-errors path, aborting multi-google-mcp-auth add before
the token is written to disk.

Adding "openid" to the requested set keeps requested and granted
aligned, silencing oauthlib without changing the API access we actually
hold (we don't consume the OIDC id_token).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/multi_google_mcp/config.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/multi_google_mcp/config.py b/src/multi_google_mcp/config.py
index a756351..ea65585 100644
--- a/src/multi_google_mcp/config.py
+++ b/src/multi_google_mcp/config.py
@@ -11,6 +11,7 @@
     "https://www.googleapis.com/auth/calendar",
     "https://www.googleapis.com/auth/drive",
     "https://www.googleapis.com/auth/userinfo.email",
+    "openid",
 ]
 
 # Cap on Drive payload size (read or upload) so a 1 GB PDF can't hang the MCP