mcp-gee-sweet 0.7.0.dev30__tar.gz → 0.7.0.dev32__tar.gz

{mcp_gee_sweet-0.7.0.dev30 → mcp_gee_sweet-0.7.0.dev32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-gee-sweet
-Version: 0.7.0.dev30
+Version: 0.7.0.dev32
 Summary: MCP server for Google Workspace — Sheets, Drive, Docs, and Calendar. 60+ tools for AI clients.
 Project-URL: Homepage, https://github.com/khuisman/mcp-gee-sweet
 Project-URL: Bug Tracker, https://github.com/khuisman/mcp-gee-sweet/issues

mcp_gee_sweet-0.7.0.dev32/docs/qa/playwright_oauth.md

@@ -0,0 +1,130 @@
+# Playwright OAuth Automation
+
+How to acquire or refresh an OAuth token for QA runs without manually clicking through Google's consent screen.
+
+---
+
+## When you need this
+
+- Fresh environment with no `token.json`
+- `token.json` expired and cannot be refreshed (e.g. revoked, scopes changed)
+- Running `⚠️ requires-oauth` test cases in an automated QA session
+
+If `token.json` already exists and is valid, you don't need any of this — the server refreshes the access token automatically.
+
+---
+
+## Approach A — Playwright-assisted browser flow
+
+Use `oauth_setup.py` to start the consent flow without auto-launching a browser, then let the Playwright MCP complete it.
+
+### Prerequisites
+
+Add to `src/mcp_gee_sweet/.env`:
+
+```
+GOOGLE_TEST_EMAIL=your-test-account@gmail.com
+GOOGLE_TEST_PASSWORD=your-test-account-password
+```
+
+> **Security note:** these are used only by the Playwright step below and are never sent to the MCP server. Keep them in `.env` (gitignored).
+
+### Step 1 — Start the OAuth server
+
+In a terminal:
+
+```bash
+uv run python scripts/oauth_setup.py
+```
+
+The script prints an `OAUTH_URL: https://accounts.google.com/o/oauth2/auth?...` line and waits for the callback.
+
+### Step 2 — Conductor prompt (Playwright MCP)
+
+Paste this into a Claude Code session that has the Playwright MCP connected:
+
+```
+I need to complete a Google OAuth consent flow. Do the following:
+
+1. Read GOOGLE_TEST_EMAIL and GOOGLE_TEST_PASSWORD from src/mcp_gee_sweet/.env
+2. Navigate to the OAUTH_URL printed by the oauth_setup.py script (running in a terminal)
+3. On the Google sign-in page, enter the email address and click Next
+4. Enter the password and click Next
+5. On the consent screen, click "Allow" (or "Continue") to grant all requested scopes
+6. Wait for the "Authorization complete" message on the page
+
+Report what you see at each step and flag immediately if Google shows a CAPTCHA or
+"This browser or app may not be secure" warning — those require manual intervention.
+```
+
+### Step 3 — Verify
+
+Once the script exits, confirm `token.json` was updated:
+
+```bash
+python3 -c "import json; d=json.load(open('token.json')); print('refresh_token present:', bool(d.get('refresh_token')))"
+```
+
+### Known limitations
+
+**Page load: ✅ confirmed working.** Google's sign-in page (`accounts.google.com/signin`) renders correctly in Playwright — the "Email or phone" field is present and accessible.
+
+The remaining risk is at the credential-entry step. Google may apply bot detection after password entry:
+
+| Symptom | Cause | Resolution |
+|---|---|---|
+| "This browser or app may not be secure" | Google flagged the automated browser post-login | Switch to Approach B (manual) then save refresh token |
+| CAPTCHA or phone verification prompt | Account triggered fraud detection | Use a test-only Google account with 2FA disabled and a trusted browser profile |
+| Redirect loop or 400 error | `redirect_uri` mismatch | Ensure `credentials.json` has `http://localhost` in authorized redirect URIs |
+
+If Playwright is blocked after email/password entry, fall back to a one-time manual browser flow (paste the URL into Chrome) and then use Approach B for all future runs.
+
+---
+
+## Approach B — Refresh token injection (CI / headless)
+
+Run the browser flow **once** (manually or via Playwright), then store the refresh token as an environment secret. All future runs reconstruct `token.json` without any browser.
+
+### Step 1 — Extract the refresh token (one time)
+
+After a successful OAuth flow:
+
+```bash
+python3 -c "import json; d=json.load(open('token.json')); print(d['refresh_token'])"
+```
+
+Store the output as:
+- `GOOGLE_OAUTH_REFRESH_TOKEN` (secret)
+- `GOOGLE_OAUTH_CLIENT_ID` (from `credentials.json → installed.client_id`)
+- `GOOGLE_OAUTH_CLIENT_SECRET` (from `credentials.json → installed.client_secret`)
+
+### Step 2 — Reconstruct token.json on each run
+
+```bash
+uv run python scripts/oauth_setup.py --from-refresh-token
+```
+
+This writes a minimal `token.json` with the refresh token. The MCP server exchanges it for a fresh access token on first use (same as a normal expired-token refresh — no browser needed).
+
+### In CI (GitHub Actions example)
+
+```yaml
+- name: Restore OAuth token
+  env:
+    GOOGLE_OAUTH_REFRESH_TOKEN: ${{ secrets.GOOGLE_OAUTH_REFRESH_TOKEN }}
+    GOOGLE_OAUTH_CLIENT_ID: ${{ secrets.GOOGLE_OAUTH_CLIENT_ID }}
+    GOOGLE_OAUTH_CLIENT_SECRET: ${{ secrets.GOOGLE_OAUTH_CLIENT_SECRET }}
+  run: uv run python scripts/oauth_setup.py --from-refresh-token
+```
+
+---
+
+## Which approach to use
+
+| Scenario | Approach |
+|---|---|
+| First-ever token acquisition on a new machine | A (Playwright or manual) |
+| QA run after token expiry — Playwright available | A |
+| QA run after token expiry — no browser possible | B (if refresh token stored) |
+| CI pipeline | B |
+| Playwright blocked by Google | Manual browser + B for future |

{mcp_gee_sweet-0.7.0.dev30 → mcp_gee_sweet-0.7.0.dev32}/docs/qa/runs/v0.8.0.md

@@ -27,7 +27,7 @@ Run each suite using the conductor prompt in `docs/qa/run.md`. Check off when th
 - [ ] **Sheets Management** — `tests/sheets_mgmt.md` (TC-S01–TC-S24)
 - [ ] **Sheets Charts** — `tests/sheets_charts.md` (TC-C01–TC-C12)
 - [ ] **Drive + Docs** — `tests/drive.md` (TC-D01–TC-D166)
-- [ ] **Docs Tools** — `tests/docs.md` (TC-D152–TC-D226)
+- [ ] **Docs Tools** — `tests/docs.md` (TC-DOC01–TC-DOC79)
 - [ ] **Calendar** — `tests/calendar.md` (TC-CAL01–TC-CAL43)
 
 ---

{mcp_gee_sweet-0.7.0.dev30 → mcp_gee_sweet-0.7.0.dev32}/docs/qa/setup.md

@@ -118,6 +118,17 @@ Add the returned IDs to `.env` as `TEST_CALENDAR_ID` and `TEST_EVENT_ID`.
 
 ---
 
+## OAuth token setup (for `⚠️ requires-oauth` tests)
+
+Tests tagged `⚠️ requires-oauth` need a valid OAuth token (`token.json`). If you're running with a service account or ADC, these tests will be skipped or will fail — they require personal Drive access.
+
+To acquire or refresh a token without manually clicking through Google's consent screen, see **[`docs/qa/playwright_oauth.md`](playwright_oauth.md)**. Two paths are documented:
+
+- **Playwright-assisted**: run `scripts/oauth_setup.py`, let Claude Code + Playwright MCP complete the browser flow
+- **Refresh token injection**: one-time manual flow, then store the refresh token as an env secret for all future runs (CI-friendly)
+
+---
+
 ## Resetting fixtures
 
 Re-run the Step 3 seed prompt against your existing IDs to restore known state. No need to create new files.