@digestseo/mcp-gsc 0.3.1 → 0.4.0

package/SETUP.md

@@ -1,201 +1,219 @@
-# Setup — self-hosting mcp-gsc
-
-This guide walks you through deploying your own instance of `mcp-gsc` on Cloudflare Workers with your own Google OAuth credentials ("bring your own OAuth"). Budget about 30–40 minutes the first time.
-
-By the end you'll have a Worker at `https://<your-worker>.workers.dev/mcp` that you can connect as a custom MCP connector in Claude.ai, Cursor, or ChatGPT.
-
-> **Read [Step 7](#step-7--important-google-verification) before you start.** While your Google OAuth app is unverified, refresh tokens expire after **7 days** and you're capped at **100 users**. This is the single biggest reason self-hosting a Google Search Console MCP is heavier than a key-based MCP — it's how Google's OAuth works for the sensitive `webmasters` and `indexing` scopes, not a limitation of this project.
-
-## Prerequisites
-
-- A [Cloudflare account](https://dash.cloudflare.com/sign-up) (the free Workers plan is enough to start).
-- A [Google account](https://accounts.google.com/) with access to the Search Console properties you want to query.
-- Node.js 20+ and npm.
-- The Wrangler CLI — installed for you by `npm install`; invoke it with `npx wrangler …`.
-
-Clone and install:
-
-```bash
-git clone https://github.com/<you>/mcp-gsc.git
-cd mcp-gsc
-npm install
-```
-
-Authenticate Wrangler with Cloudflare (opens a browser):
-
-```bash
-npx wrangler login
-```
-
----
-
-## Step 1 — Create a Google Cloud project and enable the Search Console API
-
-1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
-2. Create a new project (top bar → project dropdown → **New Project**). Name it anything, e.g. `mcp-gsc`.
-3. With that project selected, enable the **Google Search Console API**:
-   - Go to **APIs & Services → Library**.
-   - Search for **"Google Search Console API"**.
-   - Open it and click **Enable**.
-
-   Direct link: <https://console.cloud.google.com/apis/library/searchconsole.googleapis.com>
-
----
-
-## Step 2 — Configure the OAuth consent screen
-
-1. Go to **APIs & Services → OAuth consent screen**.
-2. Choose **User type: External**, then **Create**.
-3. Fill in the required app info (app name, user support email, developer contact email). The app name is what users see on the Google sign-in screen.
-4. On the **Scopes** step, click **Add or remove scopes** and add these scopes:
-
-   ```
-   https://www.googleapis.com/auth/webmasters
-   https://www.googleapis.com/auth/indexing
-   ```
-
-   These are **sensitive** scopes. They grant read-write access to Search Console data and the Google Indexing API (required to manage sites, sitemaps, and request URL crawling).
-5. On the **Test users** step, click **Add users** and add your own Google email address (and any teammates who need access while the app is in Testing).
-6. Save. Leave the **Publishing status** as **Testing** for now — see [Step 7](#step-7--important-google-verification).
-
----
-
-## Step 3 — Create an OAuth client (Web application)
-
-1. Go to **APIs & Services → Credentials → Create credentials → OAuth client ID**.
-2. **Application type: Web application.**
-3. Under **Authorized redirect URIs**, add both of these:
-
-   ```
-   https://<your-worker>.workers.dev/google/callback
-   http://localhost:8787/google/callback
-   ```
-
-   - Replace `<your-worker>` with your Worker's name + subdomain. If you don't know it yet, deploy once (Step 6) to see the assigned `*.workers.dev` URL, then come back and add it here. The default Worker name is `mcp-gsc` (set in `wrangler.jsonc`).
-   - The `http://localhost:8787/google/callback` entry is for local development with `npm run dev`.
+# Setup — self-hosting mcp-gsc
+
+This guide walks you through deploying your own instance of `mcp-gsc` on Cloudflare Workers with your own Google OAuth credentials ("bring your own OAuth"). Budget about 30–40 minutes the first time.
+
+By the end you'll have a Worker at `https://<your-worker>.workers.dev/mcp` that you can connect as a remote MCP integration in Claude, Cursor, or ChatGPT.
+
+> **Read [Step 7](#step-7--important-google-verification) before you start.** While your Google OAuth app is unverified, refresh tokens expire after **7 days** and you're capped at **100 users**. This is the single biggest reason self-hosting a Google Search Console MCP is heavier than a key-based MCP — it's how Google's OAuth works for the sensitive `webmasters` and `indexing` scopes, not a limitation of this project.
+
+## Prerequisites
+
+- A [Cloudflare account](https://dash.cloudflare.com/sign-up) (the free Workers plan is enough to start).
+- A [Google account](https://accounts.google.com/) with access to the Search Console properties you want to query.
+- Node.js 20+ and npm.
+- The Wrangler CLI — installed for you by `npm install`; invoke it with `npx wrangler …`.
+
+Clone and install:
+
+```bash
+git clone https://github.com/<you>/mcp-gsc.git
+cd mcp-gsc
+npm install
+```
+
+Authenticate Wrangler with Cloudflare (opens a browser):
+
+```bash
+npx wrangler login
+```
+
+---
+
+## Step 1 — Create a Google Cloud project and enable the Search Console API
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
+2. Create a new project (top bar → project dropdown → **New Project**). Name it anything, e.g. `mcp-gsc`.
+3. With that project selected, enable the **Google Search Console API**:
+   - Go to **APIs & Services → Library**.
+   - Search for **"Google Search Console API"**.
+   - Open it and click **Enable**.
+
+   Direct link: <https://console.cloud.google.com/apis/library/searchconsole.googleapis.com>
+
+---
+
+## Step 2 — Configure Google Auth Platform
+
+1. In the Google Cloud console, go to **Google Auth platform → Branding**.
+2. If Google says the Auth platform is not configured yet, click **Get Started** and complete the setup wizard:
+   - **App Information:** enter the app name and user support email.
+   - **Audience:** choose **External**.
+   - **Contact Information:** enter the developer contact email.
+   - **Finish:** review the Google API Services User Data Policy, agree if appropriate, then click **Continue → Create**.
+   If the Auth platform is already configured, review the existing **Branding** and **Audience** settings instead of starting over.
+3. Go to **Google Auth platform → Audience**. Under **Test users**, click **Add users** and add your own Google email address (and any teammates who need access while the app is in Testing).
+4. Go to **Google Auth platform → Data Access → Add or remove scopes**. Choose the access mode for this deployment and add the matching scope set:
+
+   | `GSC_ACCESS_MODE` | Scopes to add |
+   |---|---|
+   | `readwrite` (default) | `https://www.googleapis.com/auth/webmasters` and `https://www.googleapis.com/auth/indexing` |
+   | `readonly` | `https://www.googleapis.com/auth/webmasters.readonly` |
+
+   `readwrite` preserves the full tool surface: it grants Search Console read-write access and the Indexing API scope required to manage sites, sitemaps, and request URL crawling. `readonly` requests only the Search Console read-only scope and omits the mutation tools.
+
+   Note that the Indexing API itself is narrow: Google currently restricts it to pages containing `JobPosting` structured data or livestream pages containing `BroadcastEvent` inside `VideoObject`. It is not available for general webpage submission — the `indexing.request` tool checks a page's structured data before submitting and returns an error for ineligible URLs.
+5. Save the Data Access changes. In **Google Auth platform → Audience**, leave **Publishing status** as **Testing** for now — see [Step 7](#step-7--important-google-verification).
+
+---
+
+## Step 3 — Create an OAuth client (Web application)
+
+1. Go to **Google Auth platform → Clients → Create Client**.
+2. **Application type: Web application.**
+3. Under **Authorized redirect URIs**, add the entries for the ways you will run mcp-gsc:
+
+   ```
+   https://<your-worker>.workers.dev/google/callback
+   http://localhost:8787/google/callback
+   http://127.0.0.1:8080/google/callback
+   ```
+
+   - Replace `<your-worker>` with your Worker's name + subdomain. If you don't know it yet, deploy once (Step 6) to see the assigned `*.workers.dev` URL, then come back and add it here. The default Worker name is `mcp-gsc` (set in `wrangler.jsonc`).
+   - The `http://localhost:8787/google/callback` entry is for local development with `npm run dev`.
+   - The `http://127.0.0.1:8080/google/callback` entry is for the published `npx -y @digestseo/mcp-gsc` launcher, whose Registry transport is `http://127.0.0.1:8080/mcp` by default. If you set `PORT`, replace `8080` with that exact port.
+   - The Worker derives Google's redirect URI from the MCP request URL. Google requires an exact authorized-URI match, so keep the same scheme, host, port, and `/google/callback` path. `localhost` and `127.0.0.1` are different hosts for this check.
    - The path must be exactly `/google/callback` — that's the route this server handles.
    - The DigestSEO-hosted instance also requires this exact callback URI in the OAuth client configured on its Worker: `https://mcp-gsc.digestseo.com/google/callback`.
-4. Click **Create**. Copy the **Client ID** and **Client secret** — you'll set them as secrets in the next step.
-
----
-
-## Step 4 — Set the Worker secrets
-
-This server reads three secrets. **Never commit these to git** — set them with `wrangler secret put`, which stores them encrypted in Cloudflare:
-
-```bash
-npx wrangler secret put GOOGLE_CLIENT_ID
-# paste the Client ID from Step 3
-
-npx wrangler secret put GOOGLE_CLIENT_SECRET
-# paste the Client secret from Step 3
-
-npx wrangler secret put TOKEN_ENCRYPTION_KEY
-# paste the key generated below
-```
-
-`TOKEN_ENCRYPTION_KEY` is the **AES-256 key** used by `src/crypto.ts` to encrypt each user's Google refresh token before it's stored in KV. Generate a fresh 32-byte key, base64-encoded:
-
-```bash
-openssl rand -base64 32
-```
-
-Paste that value when prompted. Keep it safe — if you lose it, the refresh tokens already in KV become undecryptable and every user has to reconnect.
-
-For **local development**, put the same three values in `.dev.vars` instead — copy `.dev.vars.example` to `.dev.vars` (it's gitignored):
-
-```
-GOOGLE_CLIENT_ID=...
-GOOGLE_CLIENT_SECRET=...
-TOKEN_ENCRYPTION_KEY=...
-```
-
----
-
-## Step 5 — Create the KV namespaces
-
-The server uses two Workers KV namespaces: `OAUTH_KV` (pending OAuth state and issued tokens) and `USER_KV` (encrypted refresh tokens, keyed per user).
-
-```bash
-npx wrangler kv namespace create OAUTH_KV
-npx wrangler kv namespace create USER_KV
-```
-
-Each command prints an `id`. Copy the template to your real config and paste the two ids in:
-
-```bash
-cp wrangler.example.jsonc wrangler.jsonc
-```
-
-Then edit `wrangler.jsonc` and replace the placeholders:
-
-```jsonc
-"kv_namespaces": [
-  { "binding": "OAUTH_KV", "id": "YOUR_OAUTH_KV_ID" },   // ← paste OAUTH_KV id
-  { "binding": "USER_KV",  "id": "YOUR_USER_KV_ID" }      // ← paste USER_KV id
-]
-```
-
-`wrangler.jsonc` is gitignored because it contains your account's namespace ids. The `wrangler.example.jsonc` template stays in git.
-
----
-
-## Step 6 — Apply migrations, deploy, and verify
-
-The Durable Object migration declared in `wrangler.jsonc` (`migrations` → tag `v1`, `new_sqlite_classes: ["GscMcpAgent"]`) is applied automatically the first time you deploy. Deploy:
-
-```bash
-npm run deploy
-```
-
-Wrangler prints your Worker URL, e.g. `https://mcp-gsc.<your-subdomain>.workers.dev`. If you didn't know that host in Step 3, add `https://<that-host>/google/callback` to the Authorized redirect URIs now, then deploy again.
-
-Smoke-check the deployment:
-
-```bash
-curl https://<your-worker>.workers.dev/healthz
-# → ok
-```
-
-Opening the root URL in a browser also prints the `/mcp` connect URL.
-
-Now connect it in **Claude.ai**:
-
-1. Settings → **Connectors** → **Add custom connector**.
-2. Paste `https://<your-worker>.workers.dev/mcp`.
-3. Leave **Client ID** and **Client Secret** blank.
-4. Click through; Claude opens a Google sign-in flow. Sign in with a Google account you added as a **test user** in Step 2, and grant read access to your Search Console properties.
-5. The connector turns green. Ask: *"What sites do I have in Search Console?"*
-
-The same `/mcp` URL works in Cursor and ChatGPT.
-
----
-
-## Step 7 — Important: Google verification
-
-**Read this carefully — it determines whether your self-hosted instance keeps working past a week.**
-
-While your OAuth app's **Publishing status** is **Testing** (where it starts, and where Step 2 leaves it), three limits apply:
-
-- **Unverified-app screen.** Users see Google's *"Google hasn't verified this app"* warning during sign-in and must click **Advanced → Go to \<app\> (unsafe)** to continue. That's expected for an unverified app — it isn't a problem with this server.
-- **100-user cap.** At most 100 Google accounts can ever authorize the app.
-- **Refresh tokens expire after 7 days.** This is the big one. In Testing mode, Google expires every refresh token **7 days** after it's issued. When that happens the tools start returning *"Google access revoked. Please reconnect this connector in Claude.ai"*, and the user has to reconnect to get a fresh token. **Any automation or scheduled job you build on top will break every 7 days** until you fix this.
-
-To remove all three limits you must move the app to **Publishing status: In production**:
-
-- In **APIs & Services → OAuth consent screen**, click **Publish app**.
-- Because `webmasters` and `indexing` are **sensitive scopes**, Google requires **OAuth verification**: you submit the app for review, justify the scopes, and (for sensitive/restricted scopes) may need to verify domain ownership and complete a security assessment. **This review can take days to several weeks.**
-- Once the app is **In production and verified**, the unverified-app screen goes away, the 100-user cap is lifted, and refresh tokens stop expiring on the 7-day clock.
-
-**Bottom line:** for personal use with one or two Google accounts, Testing mode is fine as long as you don't mind reconnecting roughly every 7 days. For anything shared or automated, you'll want to complete Google's verification — and that, not the code, is the heaviest part of self-hosting a Google Search Console MCP.
-
-> Don't want to deal with verification at all? The hosted version at **[digestseo.com](https://digestseo.com)** has already been through it (and adds automatic weekly email digests on top).
-
----
-
-## Troubleshooting
-
-- **`redirect_uri_mismatch`** — the redirect URI in Step 3 must match your Worker host exactly, including `https://` and the `/google/callback` path. Check for typos and trailing slashes.
-- **`Google did not return a refresh_token`** — you need a fresh consent. This server requests `access_type=offline` with `prompt=consent`, but if you've authorized before, remove the app from your [Google Account permissions](https://myaccount.google.com/permissions) and reconnect to force a new refresh token.
-- **"Google access revoked" after about a week** — that's the 7-day Testing-mode expiry from Step 7. Reconnect, or move the app to production.
-- **401 on `/mcp`** — expected when unauthenticated. Connect through your MCP client's OAuth flow rather than calling `/mcp` directly in a browser.
+4. Click **Create**. Copy the **Client ID** and **Client secret** — you'll set them as secrets in the next step.
+
+---
+
+## Step 4 — Set the Worker secrets
+
+This server reads three secrets. **Never commit these to git** — set them with `wrangler secret put`, which stores them encrypted in Cloudflare:
+
+```bash
+npx wrangler secret put GOOGLE_CLIENT_ID
+# paste the Client ID from Step 3
+
+npx wrangler secret put GOOGLE_CLIENT_SECRET
+# paste the Client secret from Step 3
+
+npx wrangler secret put TOKEN_ENCRYPTION_KEY
+# paste the key generated below
+```
+
+`TOKEN_ENCRYPTION_KEY` is the **AES-256 key** used by `src/crypto.ts` to encrypt each user's Google refresh token before it's stored in KV. Generate a fresh 32-byte key, base64-encoded:
+
+```bash
+openssl rand -base64 32
+```
+
+Paste that value when prompted. Keep it safe — if you lose it, the refresh tokens already in KV become undecryptable and every user has to reconnect.
+
+For **local development**, put the same three values in `.dev.vars` instead — copy `.dev.vars.example` to `.dev.vars` (it's gitignored):
+
+```
+GOOGLE_CLIENT_ID=...
+GOOGLE_CLIENT_SECRET=...
+TOKEN_ENCRYPTION_KEY=...
+GSC_ACCESS_MODE=readwrite
+```
+
+---
+
+## Step 5 — Create the KV namespaces
+
+The server uses two Workers KV namespaces: `OAUTH_KV` (data required by the OAuth provider) and `USER_KV` (encrypted refresh tokens, keyed per user). Pending OAuth state is stored separately in a Durable Object so each nonce can be consumed exactly once.
+
+```bash
+npx wrangler kv namespace create OAUTH_KV
+npx wrangler kv namespace create USER_KV
+```
+
+Each command prints an `id`. Copy the template to your real config and paste the two ids in:
+
+```bash
+cp wrangler.example.jsonc wrangler.jsonc
+```
+
+Then edit `wrangler.jsonc` and replace the placeholders:
+
+```jsonc
+"kv_namespaces": [
+  { "binding": "OAUTH_KV", "id": "YOUR_OAUTH_KV_ID" },   // ← paste OAUTH_KV id
+  { "binding": "USER_KV",  "id": "YOUR_USER_KV_ID" }      // ← paste USER_KV id
+]
+```
+
+The template also sets `GSC_ACCESS_MODE` to `readwrite`, preserving the historical behavior. To deploy least-privilege read-only access, set it to `readonly` before deploying:
+
+```jsonc
+"vars": {
+  "GSC_ACCESS_MODE": "readonly"
+}
+```
+
+Read-only deployments request `webmasters.readonly`, omit the Indexing API scope, and do not register `sites.add`, `sites.delete`, `sitemaps.submit`, `sitemaps.delete`, or `indexing.request`. Changing modes affects OAuth grants for future connections; reconnect users after changing the mode so Google grants the matching scope set.
+
+`wrangler.jsonc` is gitignored because it contains your account's namespace ids. The `wrangler.example.jsonc` template stays in git.
+
+---
+
+## Step 6 — Apply migrations, deploy, and verify
+
+The Durable Object migrations declared in `wrangler.jsonc` are applied automatically when you deploy: `v1` creates the historical `GscMcpAgent` class, `v2` adds `PendingAuthState` for atomic OAuth-state consumption, and `v3` adds `ToolRateLimiter` for server-side per-user tool limits. The MCP endpoint now uses Cloudflare's stateless MCP handler; `GscMcpAgent` remains as an unused compatibility shell so existing deployments can upgrade without a destructive Durable Object deletion migration. Do not remove or rename the existing binding/migration history. Deploy:
+
+```bash
+npm run deploy
+```
+
+Wrangler prints your Worker URL, e.g. `https://mcp-gsc.<your-subdomain>.workers.dev`. If you didn't know that host in Step 3, add `https://<that-host>/google/callback` to the Authorized redirect URIs now, then deploy again.
+
+Smoke-check the deployment:
+
+```bash
+curl https://<your-worker>.workers.dev/healthz
+# → ok
+```
+
+Opening the root URL in a browser also prints the `/mcp` connect URL.
+
+Now connect it in your client:
+
+- **Claude.ai / Claude Desktop** — go to **Customize → Connectors**, click **+ → Add custom connector**, enter a name, and paste `https://<your-worker>.workers.dev/mcp`. Leave the optional advanced OAuth Client ID/Secret fields blank. On Team/Enterprise, an Owner or Primary Owner must first add the custom Web connector from **Organization settings → Connectors**; members then connect it from Customize → Connectors. On first connection, Claude opens the Google sign-in flow.
+- **Cursor** — add a remote **Streamable HTTP** MCP server with the same `/mcp` URL. Cursor supports OAuth for remote HTTP servers.
+- **ChatGPT** — enable **Developer mode**, then create a custom MCP **app** from **Settings → Apps → Create** (admins/owners can also use **Workspace settings → Apps → Create**). Provide the `/mcp` endpoint, select the applicable authentication option, click **Scan Tools**, complete OAuth, then create the app. Full MCP including write/modify tools is currently available to Business and Enterprise/Edu; Pro custom MCP access is read/fetch-only, so use `GSC_ACCESS_MODE=readonly` for that path.
+
+After the client starts OAuth, sign in with a Google account you added as a **test user** in Step 2 and grant the access requested by your selected deployment mode. Then ask: *"What sites do I have in Search Console?"*
+
+---
+
+## Step 7 — Important: Google verification
+
+**Read this carefully — it determines whether your self-hosted instance keeps working past a week.**
+
+While your OAuth app's **Publishing status** is **Testing** (where it starts, and where Step 2 leaves it), three limits apply:
+
+- **Unverified-app screen.** Users see Google's *"Google hasn't verified this app"* warning during sign-in and must click **Advanced → Go to \<app\> (unsafe)** to continue. That's expected for an unverified app — it isn't a problem with this server.
+- **100-user cap.** At most 100 Google accounts can ever authorize the app.
+- **Refresh tokens expire after 7 days.** This is the big one. In Testing mode, Google expires every refresh token **7 days** after it's issued. When that happens the tools start returning *"Google access revoked. Please reconnect this connector in Claude.ai"*, and the user has to reconnect to get a fresh token. **Any automation or scheduled job you build on top will break every 7 days** until you fix this.
+
+To remove all three limits you must move the app to **Publishing status: In production** and complete any verification Google requires for the scopes you use:
+
+- In **Google Auth platform → Audience**, click **Publish app** and confirm the move to production.
+- Google requires public production apps that use **sensitive or restricted scopes** to complete OAuth verification. Follow **Google Auth platform → Verification Center** for the requirements that apply to your selected scopes. Google's additional security assessment applies to **restricted** scopes; do not assume every sensitive scope requires one. Review time varies by the checks your app requires.
+- Once the app is **In production and verified**, the unverified-app screen goes away, the 100-user cap is lifted, and refresh tokens stop expiring on the 7-day clock.
+
+**Bottom line:** for personal use with one or two Google accounts, Testing mode is fine as long as you don't mind reconnecting roughly every 7 days. For anything shared or automated, you'll want to complete Google's verification — and that, not the code, is the heaviest part of self-hosting a Google Search Console MCP.
+
+> Don't want to deal with verification at all? The hosted version at **[digestseo.com](https://digestseo.com)** has already been through it (and adds automatic weekly email digests on top).
+
+---
+
+## Troubleshooting
+
+- **`redirect_uri_mismatch`** — the redirect URI in Step 3 must match your Worker host exactly, including `https://` and the `/google/callback` path. Check for typos and trailing slashes.
+- **`Google did not return a refresh_token`** — you need a fresh consent. This server requests `access_type=offline` with `prompt=consent`, but if you've authorized before, remove the app from your [Google Account permissions](https://myaccount.google.com/permissions) and reconnect to force a new refresh token.
+- **"Google access revoked" after about a week** — that's the 7-day Testing-mode expiry from Step 7. Reconnect, or move the app to production.
+- **401 on `/mcp`** — expected when unauthenticated. Connect through your MCP client's OAuth flow rather than calling `/mcp` directly in a browser.

package/package.json

@@ -1,6 +1,6 @@
-{
+{
   "name": "@digestseo/mcp-gsc",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "private": false,
   "main": "scripts/glama-start.mjs",
   "bin": {
@@ -9,10 +9,10 @@
   "license": "MIT",
   "description": "Self-hostable Google Search Console MCP server for analytics, URL inspection, sitemaps, indexing, and SEO reporting on Cloudflare Workers.",
   "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/AKzar1el/mcp-gsc.git"
-  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AKzar1el/mcp-gsc.git"
+  },
   "homepage": "https://digestseo.com/gsc-mcp/",
   "author": {
     "name": "DigestSEO",
@@ -50,7 +50,19 @@
     "build": "npm run typecheck",
     "start": "node scripts/glama-start.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck && npm run test:unit",
+    "test:oauth-state": "tsx --test tests/pending-auth-state.test.ts",
+    "test:comparison": "tsx --test tests/performance-comparison.test.ts",
+    "test:annotations": "tsx --test tests/write-tool-annotations.test.ts",
+    "test:worker": "vitest run --config vitest.worker.config.ts",
+    "test:access-mode": "tsx --test tests/access-mode.test.ts",
+    "test:access-token-lifecycle": "tsx --test tests/access-token-lifecycle.test.ts",
+    "test:analytics-response-metadata": "tsx --test tests/analytics-response-metadata.test.ts",
+    "test:indexing-authorization": "tsx --test tests/indexing-property-authorization.test.ts",
+    "test:indexing-eligibility": "tsx --test tests/indexing-eligibility.test.ts",
+    "test:insight-pagination": "tsx --test tests/insight-pagination.test.ts",
+    "test:tool-rate-limits": "tsx --test tests/tool-rate-limit.test.ts",
+    "test": "npm run typecheck && npm run test:metadata && npm run test:oauth-state && npm run test:comparison && npm run test:annotations && npm run test:worker && npm run test:access-mode && npm run test:access-token-lifecycle && npm run test:analytics-response-metadata && npm run test:indexing-authorization && npm run test:indexing-eligibility && npm run test:insight-pagination && npm run test:tool-rate-limits && npm run test:unit",
+    "test:metadata": "tsx --test tests/metadata.test.ts",
     "test:unit": "tsx --test tests/unit.test.ts",
     "test:smoke": "node --test tests/smoke.test.mjs",
     "prepublishOnly": "npm test"
@@ -61,16 +73,18 @@
   },
   "mcpName": "io.github.AKzar1el/mcp-gsc",
   "dependencies": {
-    "@cloudflare/workers-oauth-provider": "^0.8.1",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "agents": "^0.13.1",
-    "wrangler": "^4.93.0",
+    "@cloudflare/workers-oauth-provider": "^0.10.3",
+    "@modelcontextprotocol/server": "2.0.0",
+    "agents": "^0.24.0",
+    "wrangler": "^4.135.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20260520.1",
+    "@cloudflare/vitest-plugin": "^1.1.13",
+    "@cloudflare/workers-types": "^5.20260919.1",
     "tsx": "^4.20.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=20.0.0"

package/scripts/glama-start.mjs

@@ -2,14 +2,22 @@ import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 
 const port = process.env.PORT || '8080';
-const forwardedVariables = ['GOOGLE_CLIENT_ID', 'GOOGLE_CLIENT_SECRET', 'TOKEN_ENCRYPTION_KEY'];
+const localBaseUrl = `http://127.0.0.1:${port}`;
+const mcpUrl = `${localBaseUrl}/mcp`;
+const googleRedirectUri = `${localBaseUrl}/google/callback`;
+const forwardedVariables = [
+  'GOOGLE_CLIENT_ID',
+  'GOOGLE_CLIENT_SECRET',
+  'TOKEN_ENCRYPTION_KEY',
+  'GLAMA_INSPECTION_MODE',
+];
 const args = [
   'dev',
   '--config',
   'wrangler.example.jsonc',
   '--local',
   '--ip',
-  '0.0.0.0',
+  '127.0.0.1',
   '--port',
   port,
 ];
@@ -20,7 +28,10 @@ for (const name of forwardedVariables) {
   }
 }
 
-const wranglerCli = createRequire(import.meta.url).resolve('wrangler/bin/wrangler.js');
+console.error(`[mcp-gsc] Local MCP endpoint: ${mcpUrl}`);
+console.error(`[mcp-gsc] Google OAuth redirect URI: ${googleRedirectUri}`);
+
+const wranglerCli = createRequire(import.meta.url).resolve('wrangler');
 const child = spawn(process.execPath, [wranglerCli, ...args], { stdio: 'inherit' });
 
 const forwardSignal = (signal) => child.kill(signal);

package/src/access-mode.ts

@@ -0,0 +1,59 @@
+export const GSC_ACCESS_MODES = ['readonly', 'readwrite'] as const;
+
+export type GscAccessMode = (typeof GSC_ACCESS_MODES)[number];
+
+export const DEFAULT_GSC_ACCESS_MODE: GscAccessMode = 'readwrite';
+
+const BASE_OAUTH_SCOPES = ['openid', 'email'] as const;
+
+const READONLY_GOOGLE_OAUTH_SCOPES = [
+  ...BASE_OAUTH_SCOPES,
+  'https://www.googleapis.com/auth/webmasters.readonly',
+] as const;
+
+const READWRITE_GOOGLE_OAUTH_SCOPES = [
+  ...BASE_OAUTH_SCOPES,
+  'https://www.googleapis.com/auth/webmasters',
+  'https://www.googleapis.com/auth/indexing',
+] as const;
+
+export const WRITE_TOOL_NAMES = [
+  'sites.add',
+  'sites.delete',
+  'sitemaps.submit',
+  'sitemaps.delete',
+  'indexing.request',
+] as const;
+
+export function resolveGscAccessMode(value: string | undefined): GscAccessMode {
+  if (value === undefined || value === '') {
+    return DEFAULT_GSC_ACCESS_MODE;
+  }
+
+  if ((GSC_ACCESS_MODES as readonly string[]).includes(value)) {
+    return value as GscAccessMode;
+  }
+
+  throw new Error(
+    'Invalid GSC_ACCESS_MODE configuration. Expected "readonly" or "readwrite".',
+  );
+}
+
+export function getGoogleOAuthScopes(mode: GscAccessMode): readonly string[] {
+  return mode === 'readonly'
+    ? READONLY_GOOGLE_OAUTH_SCOPES
+    : READWRITE_GOOGLE_OAUTH_SCOPES;
+}
+
+export function getToolCatalogForAccessMode<T extends { name: string }>(
+  tools: readonly T[],
+  mode: GscAccessMode,
+): T[] {
+  if (mode === 'readwrite') {
+    return [...tools];
+  }
+
+  return tools.filter(
+    (tool) => !(WRITE_TOOL_NAMES as readonly string[]).includes(tool.name),
+  );
+}