gsclaw 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton Tuyakhov and GSClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,177 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/logo.svg" width="88" height="88" alt="">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">GSClaw</h1>
+
+<p align="center"><strong>Sink your claws into your Search Console data.</strong></p>
+
+<p align="center">
+  An open-source MCP server that gives Claude, ChatGPT, Cursor and other AI assistants first-party
+  access to Google Search Console. Deploy it in one click, connect it from claude.ai, and ask your
+  SEO questions in plain language.
+</p>
+
+<p align="center">
+  <a href="https://github.com/tuyakhov/gsclaw/actions/workflows/ci.yml"><img src="https://github.com/tuyakhov/gsclaw/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0d9488" alt="MIT license"></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-remote%20%2B%20stdio-7c3aed" alt="MCP: remote and stdio"></a>
+</p>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/images/overview-dark.png">
+    <img src="docs/images/overview.png" width="860" alt="The GSClaw dashboard: clicks, impressions, CTR and position with a daily trend chart and top queries">
+  </picture>
+</p>
+
+## Ask your AI things like
+
+- _"Which queries are stuck on page two with lots of impressions, and what should I change on each
+  page?"_
+- _"Compare the last 28 days with the same period last year. What drove the difference?"_
+- _"Where do two of my pages compete for the same query?"_
+- _"Which blog posts have been losing clicks for three months straight?"_
+- _"Is /pricing indexed? Which canonical did Google choose, and when was it last crawled?"_
+- _"Run a full SEO health check on my site."_
+
+## Why GSClaw
+
+- **Works where you already chat.** A remote MCP endpoint over HTTPS for claude.ai (web, desktop
+  and mobile), ChatGPT, Claude Code, Cursor and VS Code, plus local stdio.
+- **Answers, not raw rows.** Analysis tools find striking-distance keywords, CTR gaps,
+  cannibalization and decaying content, and compare periods, returning compact results that fit
+  in your AI's context.
+- **Your data stays yours.** GSClaw runs on your own account and talks straight to Google's API.
+  There is no third-party service and no database; it stores nothing.
+- **One-click deploys.** Vercel, Netlify, Cloudflare Workers, Render, Railway, DigitalOcean, or
+  any Docker host.
+- **A dashboard included.** See the same numbers your AI sees, find opportunities, and copy
+  connection snippets.
+- **Secure by default.** Refuses to start without authentication, signs clients in with OAuth
+  2.1, and stays read-only unless you enable writes.
+
+## Get started
+
+1. **Create a Google service account** and add its email to your Search Console properties
+   ([setup guide](docs/setup.md), about 10 minutes).
+2. **Deploy** with a button and paste two values: `GOOGLE_SERVICE_ACCOUNT_JSON` (the key) and
+   `GSCLAW_ACCESS_TOKEN` (a long random secret; Render and Railway generate it for you).
+
+   [![Deploy with Vercel](https://vercel.com/button)](<https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Ftuyakhov%2Fgsclaw&env=GOOGLE_SERVICE_ACCOUNT_JSON,GSCLAW_ACCESS_TOKEN&envDescription=Service-account%20key%20JSON%20and%20a%20long%20random%20access%20token%20(openssl%20rand%20-hex%2032)&envLink=https%3A%2F%2Fgithub.com%2Ftuyakhov%2Fgsclaw%2Fblob%2Fmain%2Fdocs%2Fsetup.md&project-name=gsclaw&repository-name=gsclaw>)
+   [![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/tuyakhov/gsclaw)
+   [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/tuyakhov/gsclaw)
+   [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/tuyakhov/gsclaw)
+   [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/gsclaw?utm_medium=integration&utm_source=button&utm_campaign=gsclaw)
+   [![Deploy to DigitalOcean](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/tuyakhov/gsclaw/tree/main)
+
+   Or run the Docker image anywhere:
+
+   ```bash
+   docker run -p 3000:3000 \
+     -e GOOGLE_SERVICE_ACCOUNT_JSON="$(cat service-account.json)" \
+     -e GSCLAW_ACCESS_TOKEN="$(openssl rand -hex 32)" \
+     ghcr.io/tuyakhov/gsclaw
+   ```
+
+   Platform notes (free tiers, timeouts, updates): [deploy guide](docs/deploy/README.md).
+
+3. **Connect your AI.** Open your deployment, sign in with the access token, and copy a snippet
+   from the **Connect** page. For claude.ai: Settings → Connectors → Add custom connector → paste
+   `https://<your-deployment>/mcp` → Connect, then approve with your access token.
+
+Several people with different Search Console access? Use [Google OAuth mode](docs/oauth.md)
+instead: everyone signs in with their own Google account and only sees their own properties.
+
+## Connect any client
+
+| Client                             | How                                                                                                             |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| claude.ai, Claude Desktop & mobile | Settings → Connectors → Add custom connector → `https://<your-deployment>/mcp`                                  |
+| Claude Code                        | `claude mcp add --transport http gsclaw https://<your-deployment>/mcp`, then `/mcp` to sign in                  |
+| Cursor                             | `{ "mcpServers": { "gsclaw": { "url": "https://<your-deployment>/mcp" } } }` in `~/.cursor/mcp.json`            |
+| VS Code                            | `{ "servers": { "gsclaw": { "type": "http", "url": "https://<your-deployment>/mcp" } } }` in `.vscode/mcp.json` |
+| ChatGPT                            | Add a custom connector (developer mode) with the same URL and OAuth                                             |
+| Local (stdio)                      | `claude mcp add gsclaw -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json -- npx -y gsclaw`                    |
+
+Each remote client opens a GSClaw sign-in page the first time: enter your access token, or sign
+in with Google in OAuth mode. Clients that prefer headers can send
+`Authorization: Bearer <token>` instead; the dashboard's Connect page has every variant.
+
+## Tools
+
+| Tool                                 | What it does                                                                                |
+| ------------------------------------ | ------------------------------------------------------------------------------------------- |
+| `list_sites`                         | Properties the server can access, with permission levels                                    |
+| `search_analytics`                   | Raw performance query: any dimensions, filters (incl. regex), search types, auto-pagination |
+| `compare_periods`                    | Current vs previous period or year over year, with top gainers and losers                   |
+| `striking_distance_keywords`         | Queries at positions ~8–20 with meaningful impressions, plus potential clicks               |
+| `ctr_opportunities`                  | High-impression rows with CTR well below the expected CTR for their position                |
+| `keyword_cannibalization`            | Queries where several of your pages split impressions                                       |
+| `content_decay`                      | Pages with sustained click decline across consecutive windows                               |
+| `page_report`                        | One page: totals vs previous period, trend, top queries and index status                    |
+| `inspect_url` / `batch_inspect_urls` | URL Inspection: index status, canonicals, last crawl, rich results                          |
+| `list_sitemaps` / `get_sitemap`      | Sitemap status, errors, warnings and submitted counts                                       |
+| `submit_sitemap` / `delete_sitemap`  | Write tools, only when `GSCLAW_ALLOW_WRITES=true`                                           |
+
+Prompt: `seo_health_check` runs a full property review with these tools. Every tool returns
+readable text plus structured data, and carries MCP annotations that tell clients which tools only
+read.
+
+## Dashboard
+
+Every deployment serves a small dashboard at `/` (turn it off with `GSCLAW_DASHBOARD=false`). It
+calls the exact same tool functions as the MCP server, so its numbers always match what your AI
+sees, and every table exports to CSV.
+
+<table>
+  <tr>
+    <td width="50%"><img src="docs/images/opportunities.png" alt="Opportunities: striking-distance keywords with potential clicks and Ask AI buttons"></td>
+    <td width="50%"><img src="docs/images/connect.png" alt="Connect: copy-paste snippets for claude.ai, Claude Code, Cursor and more"></td>
+  </tr>
+  <tr>
+    <td><strong>Opportunities.</strong> Striking distance, CTR gaps, cannibalization and content decay. "Ask AI" copies a ready-made prompt.</td>
+    <td><strong>Connect.</strong> Snippets for every client, with secrets hidden until you reveal them.</td>
+  </tr>
+  <tr>
+    <td><img src="docs/images/setup.png" alt="Setup and health: live Google connection check and visible properties"></td>
+    <td><img src="docs/images/overview-dark.png" alt="The Overview page in dark mode"></td>
+  </tr>
+  <tr>
+    <td><strong>Setup & health.</strong> A live Google check, which properties are visible, and what to fix.</td>
+    <td><strong>Light and dark, desktop and phone.</strong> Plus Indexing (sitemaps, URL Inspection) and Activity (recent tool calls).</td>
+  </tr>
+</table>
+
+## Authentication modes
+
+GSClaw never runs open: it refuses to start until one of these is configured.
+
+|                      | Service account (default)                                            | Google OAuth                                                                                       |
+| -------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Who sees what        | Everyone you give the token to sees the service account's properties | Each person sees the properties their own Google account can access                                |
+| Clients sign in with | The access token (OAuth sign-in page, bearer header or secret URL)   | Their Google account                                                                               |
+| Best for             | You, or a team sharing the same properties                           | Agencies and teams where people have different access                                              |
+| Required variables   | `GOOGLE_SERVICE_ACCOUNT_JSON`, `GSCLAW_ACCESS_TOKEN`                 | `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`, `GSCLAW_ENCRYPTION_KEY`, `PUBLIC_BASE_URL` |
+| Guide                | [Setup guide](docs/setup.md)                                         | [Google OAuth mode](docs/oauth.md)                                                                 |
+
+Every setting is documented in [.env.example](.env.example).
+
+## Documentation
+
+- [Setup guide](docs/setup.md): Google Cloud, service account, first deploy
+- [Google OAuth mode](docs/oauth.md): multi-user sign-in with Google
+- [Deploy guide](docs/deploy/README.md): per-platform notes and updating
+- [Troubleshooting](docs/troubleshooting.md): common errors and fixes
+- [Architecture](docs/ARCHITECTURE.md): how it's built and why
+- [Security](SECURITY.md): security model and how to report a vulnerability
+
+## Contributing
+
+Issues and pull requests are welcome. `pnpm build && pnpm demo` runs the server and dashboard on
+synthetic data with no Google account. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE). GSClaw is an independent project, not affiliated with or endorsed by Google or
+OpenClaw. Google Search Console is a trademark of Google LLC.

package/dist/adapters/netlify.js

@@ -0,0 +1,15 @@
+import { t as createApp } from "../app-DdGjQNXR.js";
+//#region src/adapters/netlify.ts
+let app;
+function readEnv() {
+	return globalThis.Netlify?.env?.toObject?.() ?? process.env;
+}
+/** Netlify Functions (v2) handler; `netlify/functions/gsclaw.mjs` re-exports it with its route config. */
+function netlifyFetch(request) {
+	app ??= createApp(readEnv(), { name: "netlify" });
+	return app.fetch(request);
+}
+//#endregion
+export { netlifyFetch };
+
+//# sourceMappingURL=netlify.js.map

package/dist/adapters/netlify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"netlify.js","names":[],"sources":["../../src/adapters/netlify.ts"],"sourcesContent":["import { createApp, type App } from '../core/app.js';\nimport type { Env } from '../core/config.js';\n\ninterface NetlifyGlobal {\n  env?: { toObject?: () => Record<string, string> };\n}\n\nlet app: App | undefined;\n\nfunction readEnv(): Env {\n  const netlify = (globalThis as { Netlify?: NetlifyGlobal }).Netlify;\n  return netlify?.env?.toObject?.() ?? process.env;\n}\n\n/** Netlify Functions (v2) handler; `netlify/functions/gsclaw.mjs` re-exports it with its route config. */\nexport function netlifyFetch(request: Request): Promise<Response> {\n  app ??= createApp(readEnv(), { name: 'netlify' });\n  return app.fetch(request);\n}\n"],"mappings":";;AAOA,IAAI;AAEJ,SAAS,UAAe;CAEtB,OADiB,WAA2C,SAC5C,KAAK,WAAW,KAAK,QAAQ;AAC/C;;AAGA,SAAgB,aAAa,SAAqC;CAChE,QAAQ,UAAU,QAAQ,GAAG,EAAE,MAAM,UAAU,CAAC;CAChD,OAAO,IAAI,MAAM,OAAO;AAC1B"}

package/dist/adapters/node-http.js

@@ -0,0 +1,2 @@
+import { n as startNodeServer, t as SetupError } from "../node-http-DW9OenCi.js";
+export { SetupError, startNodeServer };

package/dist/adapters/stdio.js

@@ -0,0 +1,37 @@
+import { c as stderrWriter, n as createRuntime, o as formatConfigErrors, r as buildMcpServer, s as loadConfig } from "../app-DdGjQNXR.js";
+import { t as SetupError } from "../node-http-DW9OenCi.js";
+import { readFileSync } from "node:fs";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+//#region src/adapters/stdio.ts
+/**
+* Local stdio server for Claude Code, Cursor, Claude Desktop, etc. No access token is needed: the
+* client launches this process itself. The key can also come from a file via
+* GOOGLE_APPLICATION_CREDENTIALS.
+*/
+async function runStdio(opts = {}) {
+	const env = { ...opts.env ?? process.env };
+	if (!env.GOOGLE_SERVICE_ACCOUNT_JSON && env.GOOGLE_APPLICATION_CREDENTIALS) try {
+		env.GOOGLE_SERVICE_ACCOUNT_JSON = readFileSync(env.GOOGLE_APPLICATION_CREDENTIALS, "utf8");
+	} catch (error) {
+		throw new SetupError(`Could not read GOOGLE_APPLICATION_CREDENTIALS (${env.GOOGLE_APPLICATION_CREDENTIALS}): ${error.message}`);
+	}
+	const loaded = loadConfig(env, { transport: "stdio" });
+	if (!loaded.ok) throw new SetupError(formatConfigErrors(loaded.errors));
+	const runtime = createRuntime(loaded.config, {
+		fetch: opts.fetch,
+		logWriter: stderrWriter,
+		logFields: { transport: "stdio" }
+	});
+	for (const warning of loaded.warnings) runtime.logger.warn(warning);
+	serveStdio(() => buildMcpServer({
+		tools: runtime.owner.tools,
+		ctx: runtime.owner.ctx,
+		logger: runtime.logger,
+		activity: runtime.activity,
+		client: "stdio"
+	}));
+}
+//#endregion
+export { runStdio };
+
+//# sourceMappingURL=stdio.js.map

package/dist/adapters/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","names":[],"sources":["../../src/adapters/stdio.ts"],"sourcesContent":["import { readFileSync } from 'node:fs';\nimport { serveStdio } from '@modelcontextprotocol/server/stdio';\nimport { formatConfigErrors, loadConfig, type Env } from '../core/config.js';\nimport { stderrWriter } from '../core/log.js';\nimport { buildMcpServer } from '../core/mcp.js';\nimport { createRuntime } from '../core/runtime.js';\nimport { SetupError } from './node-http.js';\n\n/**\n * Local stdio server for Claude Code, Cursor, Claude Desktop, etc. No access token is needed: the\n * client launches this process itself. The key can also come from a file via\n * GOOGLE_APPLICATION_CREDENTIALS.\n */\nexport async function runStdio(opts: { env?: Env; fetch?: typeof fetch } = {}): Promise<void> {\n  const env = { ...(opts.env ?? process.env) };\n  if (!env.GOOGLE_SERVICE_ACCOUNT_JSON && env.GOOGLE_APPLICATION_CREDENTIALS) {\n    try {\n      env.GOOGLE_SERVICE_ACCOUNT_JSON = readFileSync(env.GOOGLE_APPLICATION_CREDENTIALS, 'utf8');\n    } catch (error) {\n      throw new SetupError(\n        `Could not read GOOGLE_APPLICATION_CREDENTIALS (${env.GOOGLE_APPLICATION_CREDENTIALS}): ${(error as Error).message}`,\n      );\n    }\n  }\n\n  const loaded = loadConfig(env, { transport: 'stdio' });\n  if (!loaded.ok) throw new SetupError(formatConfigErrors(loaded.errors));\n\n  // stdout carries the protocol; logs must go to stderr.\n  const runtime = createRuntime(loaded.config, {\n    fetch: opts.fetch,\n    logWriter: stderrWriter,\n    logFields: { transport: 'stdio' },\n  });\n  for (const warning of loaded.warnings) runtime.logger.warn(warning);\n\n  serveStdio(() =>\n    buildMcpServer({\n      tools: runtime.owner!.tools,\n      ctx: runtime.owner!.ctx,\n      logger: runtime.logger,\n      activity: runtime.activity,\n      client: 'stdio',\n    }),\n  );\n}\n"],"mappings":";;;;;;;;;;AAaA,eAAsB,SAAS,OAA4C,CAAC,GAAkB;CAC5F,MAAM,MAAM,EAAE,GAAI,KAAK,OAAO,QAAQ,IAAK;CAC3C,IAAI,CAAC,IAAI,+BAA+B,IAAI,gCAC1C,IAAI;EACF,IAAI,8BAA8B,aAAa,IAAI,gCAAgC,MAAM;CAC3F,SAAS,OAAO;EACd,MAAM,IAAI,WACR,kDAAkD,IAAI,+BAA+B,KAAM,MAAgB,SAC7G;CACF;CAGF,MAAM,SAAS,WAAW,KAAK,EAAE,WAAW,QAAQ,CAAC;CACrD,IAAI,CAAC,OAAO,IAAI,MAAM,IAAI,WAAW,mBAAmB,OAAO,MAAM,CAAC;CAGtE,MAAM,UAAU,cAAc,OAAO,QAAQ;EAC3C,OAAO,KAAK;EACZ,WAAW;EACX,WAAW,EAAE,WAAW,QAAQ;CAClC,CAAC;CACD,KAAK,MAAM,WAAW,OAAO,UAAU,QAAQ,OAAO,KAAK,OAAO;CAElE,iBACE,eAAe;EACb,OAAO,QAAQ,MAAO;EACtB,KAAK,QAAQ,MAAO;EACpB,QAAQ,QAAQ;EAChB,UAAU,QAAQ;EAClB,QAAQ;CACV,CAAC,CACH;AACF"}

package/dist/adapters/vercel.js

@@ -0,0 +1,15 @@
+import { t as createApp } from "../app-DdGjQNXR.js";
+//#region src/adapters/vercel.ts
+let app;
+/**
+* Vercel Function (Node.js runtime, Fluid Compute) using the web-standard `fetch` export.
+* `api/index.js` re-exports this, and vercel.json rewrites every path to it.
+*/
+var vercel_default = { fetch(request) {
+	app ??= createApp(process.env, { name: "vercel" });
+	return app.fetch(request);
+} };
+//#endregion
+export { vercel_default as default };
+
+//# sourceMappingURL=vercel.js.map

package/dist/adapters/vercel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel.js","names":[],"sources":["../../src/adapters/vercel.ts"],"sourcesContent":["import { createApp, type App } from '../core/app.js';\n\nlet app: App | undefined;\n\n/**\n * Vercel Function (Node.js runtime, Fluid Compute) using the web-standard `fetch` export.\n * `api/index.js` re-exports this, and vercel.json rewrites every path to it.\n */\nexport default {\n  fetch(request: Request): Promise<Response> {\n    app ??= createApp(process.env, { name: 'vercel' });\n    return app.fetch(request);\n  },\n};\n"],"mappings":";;AAEA,IAAI;;;;;AAMJ,IAAA,iBAAe,EACb,MAAM,SAAqC;CACzC,QAAQ,UAAU,QAAQ,KAAK,EAAE,MAAM,SAAS,CAAC;CACjD,OAAO,IAAI,MAAM,OAAO;AAC1B,EACF"}