@aiguru/google-web-operations 0.6.4

package/apps/mcp-server/src/index.js

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+/**
+ * Google Web Operations MCP server.
+ *
+ * Thin layer over packages/core. The same process serves Claude Code and
+ * Codex; host differences are packaging only (see hosts/).
+ *
+ * stdout is the MCP protocol channel. Anything diagnostic goes to stderr.
+ *
+ * Tool names use underscores only: some clients reject dots.
+ */
+import { McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import * as z from 'zod/v4';
+import { operations } from "../../../packages/core/src/index.js";
+import * as admin from "../../../packages/core/src/admin.js";
+import { renderDoctor } from "../../../packages/core/src/doctor.js";
+import { ga4, gsc, pagespeed, tokenProvider, makeOauthProvider, discover } from "../../../packages/connectors/google/src/index.js";
+import { getSite } from "../../../packages/core/src/registry.js";
+import { openPullRequest } from "../../../packages/connectors/github/src/index.js";
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { ROOT } from "../../../packages/core/src/paths.js";
+/** The package version, so the server never reports a stale number after a release. */
+const PKG_VERSION = JSON.parse(readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version;
+const text = (value) => ({
+    content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }],
+});
+const fail = (e) => ({
+    isError: true,
+    content: [{ type: 'text', text: `error: ${e.message ?? String(e)}` }],
+});
+async function guard(fn) {
+    try {
+        return text(await fn());
+    }
+    catch (e) {
+        return fail(e);
+    }
+}
+/** Resolve the Search Console property for a site, or explain what is missing. */
+function gscProperty(siteId) {
+    const p = getSite(siteId).google.search_console?.property;
+    if (!p)
+        throw new Error(`Site ${siteId} has no google.search_console.property configured.`);
+    return p;
+}
+function ga4Property(siteId) {
+    const p = getSite(siteId).google.ga4?.property_id;
+    if (!p)
+        throw new Error(`Site ${siteId} has no google.ga4.property_id configured. The measurement id (G-...) is not enough; the numeric property id is needed.`);
+    return p;
+}
+function createServer() {
+    const server = new McpServer({ name: 'google-web-operations', version: PKG_VERSION }, {
+        instructions: 'Google Web Operations runs SEO and GEO operations for registered client sites. ' +
+            'Observe before changing. Classify every write with ops_classify_action; protected actions are never performed; ' +
+            'approval_required actions need the token the operator gives you in this session. ' +
+            'Google tools need credentials (see docs/SECURITY.md); web_* tools work without them. ' +
+            'If nothing is configured yet, start with ops_setup_status and the gwo-setup skill.',
+    });
+    // ------------------------------------------------------------ registry
+    server.registerTool('ops_list_sites', {
+        description: 'List registered sites: id, host, platform, tier, and which Google properties are configured.',
+        inputSchema: z.object({ includeDisabled: z.boolean().default(false) }),
+    }, async ({ includeDisabled }) => guard(() => operations.listSites({ includeDisabled }).map((s) => ({
+        id: s.site_id, name: s.name, enabled: s.enabled, host: s.production_url, platform: s.platform, tier: s.tier,
+        gsc: s.google.search_console?.property ?? null, ga4: s.google.ga4?.measurement_id ?? null, gtm: s.google.tag_manager?.public_id ?? null,
+    }))));
+    server.registerTool('ops_get_site', {
+        description: 'Full registry record for one site (no secrets), last scan summary, snapshot count.',
+        inputSchema: z.object({ site: z.string().min(1).describe('site id or host') }),
+    }, async ({ site }) => guard(() => operations.siteState(site)));
+    server.registerTool('ops_classify_action', {
+        description: 'Ask policy what class an action is for a site: auto, approval_required (returns the token needed), or protected. ' +
+            'Call before proposing any write. Action ids are dotted, e.g. "content.title.update", "gtm.publish", "gsc.sitemap.submit".',
+        inputSchema: z.object({ action: z.string().min(1), site: z.string().optional() }),
+    }, async ({ action, site }) => guard(() => operations.classifyAction(action, site)));
+    server.registerTool('ops_audit_log', {
+        description: 'Operational audit log for a site: runs, proposals, writes with before/after and verification.',
+        inputSchema: z.object({ site: z.string().min(1), limit: z.number().int().min(1).max(500).default(50) }),
+    }, async ({ site, limit }) => guard(() => operations.auditLog(site, limit)));
+    // ------------------------------------------------------------ setup and administration (this system's configuration, never a client site)
+    server.registerTool('ops_setup_status', {
+        description: 'Where setup stands, in one read: OAuth client installed, authorised account and scopes, which write scopes are present, which .env settings are set, ' +
+            'and per site what is configured and what is missing. Ends with nextSteps, and carries a rendered checklist you can show the operator as is. Start every setup or onboarding conversation here (gwo-setup skill).',
+        inputSchema: z.object({}),
+    }, async () => guard(() => { const s = admin.setupStatus(); return { ...s, rendered: renderDoctor(s) }; }));
+    server.registerTool('google_setup_oauth_client', {
+        description: 'Install the OAuth client JSON the operator downloaded from Google Cloud ("Desktop app" type) into secrets/. Pass the file path; never ask for the file contents. Validates the shape and returns the client id only.',
+        inputSchema: z.object({ path: z.string().min(1).describe('local path of the downloaded client_secret_*.json') }),
+    }, async ({ path }) => guard(() => admin.installOauthClient(path)));
+    server.registerTool('google_auth_login', {
+        description: 'Run the Google consent flow: opens the browser on this machine for the operations account and stores the refresh token encrypted. Waits about 90 seconds; if consent takes longer it keeps waiting in the background and ops_setup_status shows the result. ' +
+            'scopes: extra short names, "ga4_write" (key events), "gtm_edit" (staging), "gtm_publish" (publishing). Ask for write scopes only when a write is about to be enabled.',
+        inputSchema: z.object({ scopes: z.array(z.enum(['ga4_write', 'gtm_edit', 'gtm_publish'])).default([]) }),
+    }, async ({ scopes }) => guard(() => admin.authLogin(scopes)));
+    server.registerTool('google_discover_apply', {
+        description: 'List the Search Console properties, GA4 properties and Tag Manager containers the operations account can see, match them to registered sites by host, and write the ids of confident matches into the site files. ' +
+            'Matches by name only are returned for confirmation, never written (use ops_update_site after the operator confirms).',
+        inputSchema: z.object({}),
+    }, async () => guard(() => admin.discoverApply()));
+    server.registerTool('ops_add_site', {
+        description: 'Register a new client site: writes sites/<host>.yaml with the standard layout and defaults (Hebrew, full tier, generate_lead, adapter from platform). Ask only for url, name, platform, and for Odoo the ERP url and database. ' +
+            'Google ids are filled later by google_discover_apply. Credentials never go here. Follow with web_scan_site for the baseline.',
+        inputSchema: z.object({
+            url: z.string().url(), name: z.string().min(1),
+            platform: z.enum(['odoo', 'nextjs', 'wordpress', 'custom']).default('custom'),
+            locales: z.array(z.string()).optional(), defaultLocale: z.string().optional(), altHosts: z.array(z.string()).optional(),
+            tier: z.enum(['full', 'advisory']).optional(), adapter: z.enum(['odoo', 'repo', 'none']).optional(),
+            primaryEvent: z.string().optional(), owner: z.string().optional(), notes: z.string().optional(),
+            odoo: z.object({ url: z.string().url(), db: z.string().min(1), websiteId: z.number().int().optional() }).optional(),
+            repo: z.object({ url: z.string().optional(), branch: z.string().optional(), localPath: z.string().optional() }).optional(),
+        }),
+    }, async (input) => guard(() => { const r = admin.addSite(input); return { file: r.file, site: operations.getSite(r.site.site_id) }; }));
+    server.registerTool('ops_update_site', {
+        description: 'Set one field of a site file by dotted path, keeping the file\'s comments: e.g. "google.tag_manager.public_id", "write.repo.local_path", "contacts.report_to", "cadence.weekly", "enabled". ' +
+            'Values that look like JSON are parsed (numbers, booleans, arrays; quote a string of digits to keep it a string). site_id, policy and credentials are refused.',
+        inputSchema: z.object({ site: z.string().min(1), path: z.string().min(1), value: z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(z.string())]) }),
+    }, async ({ site, path, value }) => guard(() => admin.updateSite(site, path, value)));
+    server.registerTool('ops_add_suppression', {
+        description: 'Record a site decision: a finding that is intentional on this site (e.g. content.thin on /contact/, measurement.no-gtm). Needs the rule id, an optional path (exact or prefix ending in *), and the reason in the client\'s words. ' +
+            'Suppressed findings stay counted in every scan header. Use after the client or their developer confirms the finding is deliberate; never to hide a problem.',
+        inputSchema: z.object({ site: z.string().min(1), rule: z.string().min(1), path: z.string().optional(), reason: z.string().min(3) }),
+    }, async ({ site, rule, path, reason }) => guard(() => admin.addSuppression(site, { rule, ...(path ? { path } : {}), reason })));
+    // ------------------------------------------------------------ web (no credentials)
+    server.registerTool('web_scan_site', {
+        description: 'Crawl a site (sitemap or given URLs), run technical SEO and GEO rules, save the scan and a snapshot. ' +
+            'Returns a grouped summary; full data is in .gwo-data/<site>/latest-scan.json. Needs no credentials.',
+        inputSchema: z.object({
+            site: z.string().min(1),
+            maxPages: z.number().int().min(1).max(200).default(50),
+            urls: z.array(z.string().url()).optional().describe('crawl exactly these URLs instead of the sitemap'),
+        }),
+    }, async ({ site, maxPages, urls }) => guard(async () => {
+        const { scan, scanPath } = await operations.scanSite(site, urls ? { maxPages, urls } : { maxPages });
+        return operations.renderScan(scan) + `\n\nsaved: ${scanPath}`;
+    }));
+    server.registerTool('web_inspect_url', {
+        description: 'Fetch one URL: status, redirect chain, all SEO/GEO signals, page-level findings. Use for spot checks and to verify a fix landed.',
+        inputSchema: z.object({ url: z.string().url(), site: z.string().optional().describe('for canonical-host and locale context') }),
+    }, async ({ url, site }) => guard(async () => {
+        const { page, findings } = await operations.inspectUrl(url, site);
+        const s = page.signals;
+        return {
+            url, status: page.status, finalUrl: page.finalUrl, hops: page.chain.length - 1, ms: page.ms, bytes: page.bytes,
+            title: s?.title, description: s?.description, canonical: s?.canonicalAbs, lang: s?.lang, dir: s?.dir,
+            h1: s?.headings.h1, jsonldTypes: s?.jsonldTypes, alternates: s?.alternates, analytics: s?.analytics,
+            wordCount: s?.wordCount, images: s?.images, links: s?.links, findings,
+        };
+    }));
+    server.registerTool('web_inspect_rendered', {
+        description: 'Load one URL in a headless browser and compare what renders with the static HTML: word count ratio, headings, JSON-LD and form fields that only appear after JavaScript. ' +
+            'Verdict server-rendered / partly-js / js-dependent. Use to confirm or dismiss content.thin, and before proposing structured data (JSON-LD injected by JavaScript is invisible to most answer engines). ' +
+            'Needs Playwright on the machine; if missing, the error says exactly what to install.',
+        inputSchema: z.object({ url: z.string().url(), site: z.string().optional() }),
+    }, async ({ url, site }) => guard(async () => (await operations.inspectRendered(url, site)).rendered));
+    server.registerTool('web_diff_scans', {
+        description: 'What changed between the two most recent scans: new and resolved findings, page field changes, added and removed pages.',
+        inputSchema: z.object({ site: z.string().min(1) }),
+    }, async ({ site }) => guard(() => operations.diffLatest(site)));
+    // ------------------------------------------------------------ Google (credentials required)
+    server.registerTool('google_auth_status', {
+        description: 'Which Google credential source is active, which account, which scopes. Never returns a token. If not authorised, tells the operator to run "npm run cli -- auth login".',
+        inputSchema: z.object({}),
+    }, async () => guard(() => ({ active: tokenProvider().describe(), oauth: makeOauthProvider().status() })));
+    server.registerTool('google_discover_properties', {
+        description: 'List the Search Console properties, GA4 properties and Tag Manager containers the operations account can see, matched to registered sites by host. ' +
+            'Read-only: returns a proposal. Writing ids into site files is done by the operator with "npm run cli -- discover --apply".',
+        inputSchema: z.object({}),
+    }, async () => guard(async () => {
+        const r = await discover({ apply: false });
+        return { inventory: { searchConsole: r.inventory.gsc.map((s) => s.siteUrl), ga4: r.inventory.ga4.map((p) => `${p.property} ${p.displayName}`), tagManager: r.inventory.gtm.map((c) => `${c.publicId} ${c.name}`) }, matches: r.matches };
+    }));
+    server.registerTool('gsc_performance', {
+        description: 'Search Console performance summary for a site and window: totals, top queries and pages, striking-distance queries (position 4-15). Bounded output.',
+        inputSchema: z.object({ site: z.string().min(1), startDate: z.string(), endDate: z.string(), top: z.number().int().min(1).max(100).default(20) }),
+    }, async ({ site, startDate, endDate, top }) => guard(() => gsc.summarisePerformance(gscProperty(site), startDate, endDate, top)));
+    server.registerTool('gsc_search_analytics', {
+        description: 'Raw Search Console query. Prefer gsc_performance; use this only for a dimension or filter the summary lacks. rowLimit defaults to 1000.',
+        inputSchema: z.object({ site: z.string().min(1), request: z.record(z.string(), z.unknown()) }),
+    }, async ({ site, request }) => guard(() => gsc.searchAnalytics(gscProperty(site), request)));
+    server.registerTool('gsc_sitemaps', {
+        description: 'Sitemaps Search Console knows for the site, with status and counts.',
+        inputSchema: z.object({ site: z.string().min(1) }),
+    }, async ({ site }) => guard(() => gsc.listSitemaps(gscProperty(site))));
+    server.registerTool('gsc_submit_sitemap', {
+        description: 'Submit (or resubmit) the site\'s declared sitemap to Search Console. Policy class auto. ' +
+            'Runs the full write loop: reads the sitemap list before, submits, reads after, verifies lastSubmitted advanced, records before/after/verified in the audit log.',
+        inputSchema: z.object({ site: z.string().min(1), approval: z.string().optional().describe('only needed if a site override raised the class') }),
+    }, async ({ site, approval }) => guard(async () => {
+        const r = await operations.submitSitemap(site, approval ? { approval } : {});
+        return { status: r.status, verified: r.verified, reason: r.reason, audit: r.audit };
+    }));
+    server.registerTool('gsc_inspect_url', {
+        description: 'Google index status for one URL: verdict, coverage state, canonical Google chose, last crawl, rich results.',
+        inputSchema: z.object({ site: z.string().min(1), url: z.string().url() }),
+    }, async ({ site, url }) => guard(() => gsc.inspectUrl(gscProperty(site), url)));
+    server.registerTool('ga4_traffic', {
+        description: 'GA4 sessions, users, key events and engagement by channel for a window.',
+        inputSchema: z.object({ site: z.string().min(1), startDate: z.string(), endDate: z.string() }),
+    }, async ({ site, startDate, endDate }) => guard(() => ga4.summariseTraffic(ga4Property(site), startDate, endDate)));
+    server.registerTool('ga4_run_report', {
+        description: 'Raw GA4 Data API runReport. Prefer ga4_traffic. limit defaults to 100.',
+        inputSchema: z.object({ site: z.string().min(1), request: z.record(z.string(), z.unknown()) }),
+    }, async ({ site, request }) => guard(() => ga4.runReport(ga4Property(site), request)));
+    server.registerTool('ga4_realtime', {
+        description: 'GA4 realtime report. Use to confirm events are still arriving.',
+        inputSchema: z.object({ site: z.string().min(1), request: z.record(z.string(), z.unknown()) }),
+    }, async ({ site, request }) => guard(() => ga4.runRealtime(ga4Property(site), request)));
+    server.registerTool('ga4_key_events', {
+        description: 'Key events (conversions) configured on the GA4 property.',
+        inputSchema: z.object({ site: z.string().min(1) }),
+    }, async ({ site }) => guard(() => ga4.listKeyEvents(ga4Property(site))));
+    // ------------------------------------------------------------ site write adapter (read side)
+    server.registerTool('site_adapter_ping', {
+        description: 'Check the site\'s write adapter (Odoo JSON-RPC or repository manifest): reachable, authenticated, what it can address. Run during onboarding before declaring a site full tier.',
+        inputSchema: z.object({ site: z.string().min(1) }),
+    }, async ({ site }) => guard(() => operations.adapterPing(site)));
+    server.registerTool('site_pages', {
+        description: 'Pages the write adapter can change, with their paths and publish state.',
+        inputSchema: z.object({ site: z.string().min(1) }),
+    }, async ({ site }) => guard(() => operations.adapterPages(site)));
+    server.registerTool('site_page_seo', {
+        description: 'SEO fields of one page as the site stores them (title, description, keywords, og image, indexed, published) next to what the live page renders. Use before proposing any content change.',
+        inputSchema: z.object({ site: z.string().min(1), path: z.string().min(1).describe('site path, e.g. "/he/services"') }),
+    }, async ({ site, path }) => guard(() => operations.adapterPageSeo(site, path)));
+    // ------------------------------------------------------------ content writes
+    server.registerTool('content_set_meta_description', {
+        description: 'Set a page\'s meta description through the site adapter. Write the text yourself per the gwo-content-brief skill; the tool validates it ' +
+            '(Hebrew 120-150 chars, Latin 70-160, no stuffing, no HTML), then runs the write loop. Empty field: policy auto. Existing text: approval_required, ' +
+            'pass the token from ops_classify_action for "content.meta_description.update". Verified by reading the stored value back; confirm the live page separately with web_inspect_url.',
+        inputSchema: z.object({ site: z.string().min(1), path: z.string().min(1), text: z.string().min(1), approval: z.string().optional() }),
+    }, async ({ site, path, text, approval }) => guard(async () => {
+        const r = await operations.setMetaDescription(site, path, text, approval ? { approval } : {});
+        if (r.status === 'invalid')
+            return { status: 'invalid', problems: r.problems };
+        return { status: r.status, verified: r.verified, reason: r.reason, audit: r.audit };
+    }));
+    server.registerTool('content_set_title', {
+        description: 'Set a page\'s title through the site adapter. approval_required on every site: pass the token for "content.title.update". ' +
+            'Write it per gwo-content-brief (aim 50-60 characters, primary term first, brand last); the tool rejects under 15 or over 65, HTML, line breaks, repeated terms. ' +
+            'Never change a title on a page that ranks without a Search Console reason. Verified by reading the stored value back.',
+        inputSchema: z.object({ site: z.string().min(1), path: z.string().min(1), text: z.string().min(1), approval: z.string().optional() }),
+    }, async ({ site, path, text, approval }) => guard(async () => {
+        const r = await operations.setTitle(site, path, text, approval ? { approval } : {});
+        if (r.status === 'invalid')
+            return { status: 'invalid', problems: r.problems };
+        return { status: r.status, verified: r.verified, reason: r.reason, audit: r.audit };
+    }));
+    server.registerTool('site_page_schema', {
+        description: 'Structured data of one page: the JSON-LD blocks this system manages (as the site stores them) next to every JSON-LD block the live page emits, ' +
+            'including ones the theme adds on its own. Use before proposing schema so you never duplicate a type the page already has.',
+        inputSchema: z.object({ site: z.string().min(1), path: z.string().min(1) }),
+    }, async ({ site, path }) => guard(() => operations.adapterPageSchema(site, path)));
+    server.registerTool('content_set_schema', {
+        description: 'Replace the managed JSON-LD blocks on a page through the site adapter (Odoo: the page view\'s arch; repo: the manifest entry\'s schema array). ' +
+            'approval_required on every site: pass the token for "content.schema.update". Blocks are validated (schema.org @context, @type, FAQPage shape, size). ' +
+            'An empty list removes the managed blocks. Verified by reading back; confirm the live page with web_inspect_url after deploy.',
+        inputSchema: z.object({ site: z.string().min(1), path: z.string().min(1), blocks: z.array(z.record(z.string(), z.unknown())), approval: z.string().optional() }),
+    }, async ({ site, path, blocks, approval }) => guard(async () => {
+        const r = await operations.setSchema(site, path, blocks, approval ? { approval } : {});
+        if (r.status === 'invalid')
+            return { status: 'invalid', problems: r.problems };
+        return { status: r.status, verified: r.verified, reason: r.reason, audit: r.audit };
+    }));
+    server.registerTool('ga4_create_key_event', {
+        description: 'Mark a GA4 event as a key event (conversion). approval_required: pass the token for "ga4.key_event.create". Idempotent. ' +
+            'Needs the analytics.edit scope; the error tells the operator how to add it.',
+        inputSchema: z.object({ site: z.string().min(1), eventName: z.string().min(1), approval: z.string().optional() }),
+    }, async ({ site, eventName, approval }) => guard(async () => {
+        const r = await operations.createKeyEvent(site, eventName, approval ? { approval } : {});
+        return { status: r.status, verified: r.verified, reason: r.reason, audit: r.audit };
+    }));
+    // ------------------------------------------------------------ repository pull requests
+    server.registerTool('repo_open_pr', {
+        description: 'Commit the checkout\'s pending manifest changes for a repository-backed site, push a branch and open a pull request (idempotent per day). ' +
+            'approval_required: pass the token for "github.pr.create". Needs GITHUB_TOKEN. Pass the list of changes made so the PR body explains them.',
+        inputSchema: z.object({ site: z.string().min(1), changes: z.array(z.string()).default([]), approval: z.string().optional() }),
+    }, async ({ site, changes, approval }) => guard(async () => {
+        const r = await openPullRequest(site, { changes, ...(approval ? { approval } : {}) });
+        return { status: r.status, verified: r.verified, reason: r.reason, pr: r.after, audit: r.audit };
+    }));
+    // ------------------------------------------------------------ reports
+    server.registerTool('report_client_monthly', {
+        description: 'Write the monthly client report as a Word document (.docx, inside the company template when GWO_DOCX_TEMPLATE is set) plus a Markdown twin, under .gwo-data/<site>/reports/. ' +
+            'Gathers the numbers itself: Search Console and GA4 totals for the month and the month before, scan health now and a month ago, and what the audit log says was done or is waiting. ' +
+            'You write the narrative per gwo-client-report-template in the client\'s language: headline (how the site is doing), did (business terms, no rule ids or tool names), need (what the client must do), next. ' +
+            'Any field you omit is derived from the data. month defaults to last month. Returns the Markdown so you can review it before sending.',
+        inputSchema: z.object({
+            site: z.string().min(1),
+            month: z.string().regex(/^\d{4}-\d{2}$/).optional(),
+            headline: z.string().optional(), did: z.array(z.string()).optional(), need: z.array(z.string()).optional(), next: z.string().optional(),
+            lang: z.enum(['he', 'en']).optional().describe('defaults to the site\'s default locale'),
+        }),
+    }, async ({ site, month, headline, did, need, next, lang }) => guard(async () => {
+        const r = await operations.renderClientReport(site, { ...(month ? { month } : {}), ...(lang ? { lang } : {}),
+            narrative: { ...(headline ? { headline } : {}), ...(did ? { did } : {}), ...(need ? { need } : {}), ...(next ? { next } : {}) } });
+        return `${r.markdown}\n\n---\ndocx: ${r.docx}\nmd: ${r.md}\ntemplate: ${r.template ?? 'none (set GWO_DOCX_TEMPLATE)'}${r.notes.length ? `\nnotes: ${r.notes.join('; ')}` : ''}`;
+    }));
+    // ------------------------------------------------------------ Tag Manager (read)
+    server.registerTool('gtm_containers', {
+        description: 'Every Tag Manager container the operations account can see, across accounts. Use to find a client\'s container id after they grant access.',
+        inputSchema: z.object({}),
+    }, async () => guard(() => operations.gtmContainers()));
+    server.registerTool('gtm_versions', {
+        description: 'Version history of a site\'s container. A new version you did not create is a change to verify. Daily playbook step.',
+        inputSchema: z.object({ site: z.string().min(1) }),
+    }, async ({ site }) => guard(() => operations.gtmVersions(site)));
+    server.registerTool('gtm_snapshot', {
+        description: 'Snapshot the live container: tags with their firing triggers, paused tags, triggers, variables. Saved for diffing. Returns a readable summary.',
+        inputSchema: z.object({ site: z.string().min(1) }),
+    }, async ({ site }) => guard(async () => (await operations.gtmSnapshot(site)).rendered));
+    server.registerTool('gtm_diff', {
+        description: 'What changed between the two most recent GTM snapshots: version, tags added/removed/changed (including paused), triggers, variables.',
+        inputSchema: z.object({ site: z.string().min(1) }),
+    }, async ({ site }) => guard(() => operations.gtmDiff(site)));
+    // ------------------------------------------------------------ Tag Manager (staged writes)
+    server.registerTool('gtm_workspaces', {
+        description: 'Workspaces of the site\'s container with pending change counts and merge conflicts. Shows what is staged (ours start with the policy prefix, gwo-) and whether the client left work of their own.',
+        inputSchema: z.object({ site: z.string().min(1) }),
+    }, async ({ site }) => guard(() => operations.gtmWorkspaces(site)));
+    server.registerTool('gtm_stage', {
+        description: 'Stage tags, triggers or variables into the site\'s gwo- workspace (created if missing). Nothing goes live. approval_required: pass the token for "gtm.stage". ' +
+            'Each entity is a GTM API resource body without ids (name, type, parameter[], firingTriggerId[] ...); a name that already exists in the workspace is updated by merge, a new name is created. ' +
+            'Tags may list trigger NAMES in firingTriggerId; they resolve against the workspace and the built-ins ("All Pages"). Triggers are staged before tags. ' +
+            'Every entity is a verified write with its own audit record. Returns the workspace diff against the live version and the review token gtm_publish needs. See the gwo-measurement skill for standard bodies.',
+        inputSchema: z.object({
+            site: z.string().min(1),
+            entities: z.array(z.object({ kind: z.enum(['tag', 'trigger', 'variable']), body: z.record(z.string(), z.unknown()) })).min(1),
+            reason: z.string().optional().describe('one line for the workspace description and audit log'),
+            workspaceId: z.string().optional().describe('stage into this gwo- workspace instead of the default one'),
+            approval: z.string().optional(),
+        }),
+    }, async ({ site, entities, reason, workspaceId, approval }) => guard(async () => {
+        const r = await operations.gtmStage(site, entities, { ...(approval ? { approval } : {}), ...(reason ? { reason } : {}), ...(workspaceId ? { workspaceId } : {}) });
+        return r.rendered + '\n\n' + JSON.stringify({ workspace: r.workspace, results: r.results, reviewToken: r.reviewToken }, null, 2);
+    }));
+    server.registerTool('gtm_workspace_diff', {
+        description: 'What the gwo- workspace would change in the live container: added, updated (with the fields), deleted entities, merge conflicts, and the review token. Read-only. Present this to the operator before asking for the publish token.',
+        inputSchema: z.object({ site: z.string().min(1), workspaceId: z.string().optional() }),
+    }, async ({ site, workspaceId }) => guard(async () => {
+        const r = await operations.gtmWorkspaceDiff(site, workspaceId);
+        return 'error' in r ? r : r.rendered + '\n\n' + JSON.stringify({ workspace: r.workspace, reviewToken: r.reviewToken, counts: r.diff.counts }, null, 2);
+    }));
+    server.registerTool('gtm_publish', {
+        description: 'Create a container version from the gwo- workspace and publish it. Two gates, both enforced in code: the approval token for "gtm.publish" and the review token from gtm_workspace_diff, ' +
+            'which only matches if the workspace and the live version are exactly what was reviewed. Syncs first; merge conflicts or compiler errors abort. Verified by reading the live version after; a snapshot is saved.',
+        inputSchema: z.object({ site: z.string().min(1), review: z.string().min(1), workspaceId: z.string().optional(), versionName: z.string().optional(), notes: z.string().optional(), approval: z.string().optional() }),
+    }, async ({ site, review, workspaceId, versionName, notes, approval }) => guard(() => operations.gtmPublish(site, {
+        review, ...(workspaceId ? { workspaceId } : {}), ...(versionName ? { versionName } : {}), ...(notes ? { notes } : {}), ...(approval ? { approval } : {}),
+    })));
+    server.registerTool('pagespeed_check', {
+        description: 'PageSpeed Insights summary: category scores, lab metrics, and real-user Core Web Vitals when available.',
+        inputSchema: z.object({ url: z.string().url(), strategy: z.enum(['mobile', 'desktop']).default('mobile') }),
+    }, async ({ url, strategy }) => guard(() => pagespeed.summarisePageSpeed(url, strategy)));
+    return server;
+}
+void serveStdio(createServer);
+console.error('google-web-operations MCP server ready on stdio');

package/apps/worker/src/index.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * Scheduled operations worker: the sensing half of a playbook, without an agent.
+ *
+ *   node apps/worker/src/index.ts [daily|weekly|monthly] [site-id] [--deliver]
+ *
+ * For every enabled site (or one): scan, diff against the previous snapshot,
+ * apply the escalation rules, and write a report. With --deliver and Resend
+ * configured, the report is emailed; otherwise it is printed. Exit code 1 if
+ * any site failed to scan, 2 if any site escalated, so a scheduler can alert.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { listSites } from "../../../packages/core/src/registry.js";
+import { scanSite } from "../../../packages/core/src/operations.js";
+import { escalations } from "../../../packages/core/src/escalate.js";
+import { DATA_DIR } from "../../../packages/core/src/paths.js";
+import * as storage from "../../../packages/storage/src/index.js";
+import * as resend from "../../../packages/connectors/resend/src/index.js";
+const PAGES = { daily: 25, weekly: 200, monthly: 200 };
+const args = process.argv.slice(2);
+const deliver = args.includes('--deliver');
+const positional = args.filter((a) => !a.startsWith('--'));
+const cadence = ['daily', 'weekly', 'monthly'].find((c) => c === positional[0]) ?? 'daily';
+const only = positional[1];
+const lines = [];
+const sites = listSites().filter((s) => s.cadence[cadence] && (!only || s.site_id === only));
+for (const site of sites) {
+    const t0 = Date.now();
+    try {
+        const { scan } = await scanSite(site.site_id, { maxPages: PAGES[cadence] });
+        const snaps = storage.listSnapshots(site.site_id);
+        let esc = [];
+        let changed = 0;
+        if (snaps.length >= 2) {
+            const b = storage.loadSnapshot(site.site_id, snaps.at(-2));
+            const a = storage.loadSnapshot(site.site_id, snaps.at(-1));
+            if (b && a) {
+                const diff = storage.diffSnapshots(b, a);
+                changed = diff.newFindings.length + diff.pageChanges.length + diff.removedPages.length;
+                esc = escalations(b, a, diff);
+            }
+        }
+        const s = scan.summary;
+        const summary = `${scan.pagesCrawled} pages, ${s.blocker}/${s.high}/${s.medium} blocker/high/medium, ${changed} change${changed === 1 ? '' : 's'} since last scan`;
+        storage.appendAudit({ siteId: site.site_id, operation: `worker.${cadence}`, status: 'observed', risk: 'auto',
+            summary: `${cadence} run: ${summary}${esc.length ? `; ${esc.length} escalation(s)` : ''}`, data: { summary: s, changed, escalations: esc, ms: Date.now() - t0 } });
+        lines.push({ siteId: site.site_id, ok: true, summary, escalations: esc });
+    }
+    catch (e) {
+        const error = e.message;
+        storage.appendAudit({ siteId: site.site_id, operation: `worker.${cadence}`, status: 'failure', risk: 'auto', summary: error });
+        lines.push({ siteId: site.site_id, ok: false, escalations: [], error });
+    }
+}
+// ---------------------------------------------------------------- report
+const failures = lines.filter((l) => !l.ok).length;
+const escalated = lines.filter((l) => l.escalations.length).length;
+const stamp = new Date().toISOString();
+const title = `GWeb Ops ${cadence} run, ${stamp.slice(0, 16).replace('T', ' ')} UTC: ${sites.length} site${sites.length === 1 ? '' : 's'}, ${escalated} escalated, ${failures} failed`;
+const report = [title, ''];
+for (const l of lines) {
+    if (!l.ok) {
+        report.push(`${l.siteId}: FAILED. ${l.error}`);
+        continue;
+    }
+    if (!l.escalations.length) {
+        report.push(`${l.siteId}: healthy. ${l.summary}.`);
+        continue;
+    }
+    report.push(`${l.siteId}: ESCALATE. ${l.summary}.`);
+    for (const e of l.escalations)
+        report.push(`  - ${e.kind}${e.url ? ` ${e.url}` : ''}: ${e.detail}`);
+}
+report.push('', `Full scans and audit logs: ${DATA_DIR}`);
+const text = report.join('\n');
+const runsDir = path.join(DATA_DIR, '_runs');
+mkdirSync(runsDir, { recursive: true });
+const file = path.join(runsDir, `${cadence}-${stamp.replace(/[:.]/g, '-')}.txt`);
+writeFileSync(file, text + '\n');
+console.log(text);
+if (deliver) {
+    if (resend.isConfigured()) {
+        try {
+            const r = await resend.send({ subject: title, text });
+            console.error(`delivered: ${r.id}`);
+        }
+        catch (e) {
+            console.error(`delivery failed: ${e.message}`);
+        }
+    }
+    else {
+        console.error(`delivery skipped: ${resend.describe()}`);
+    }
+}
+process.exitCode = failures ? 1 : escalated ? 2 : 0;

package/apps/worker/src/loop.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * Long-running scheduler for hosts without Task Scheduler or cron: a
+ * container, a small VM, a NAS. Runs the daily worker at GWO_DAILY_AT
+ * (default 07:00) every day and the weekly worker at GWO_WEEKLY_AT (default
+ * Monday 07:30) in the process time zone (set TZ=Asia/Jerusalem). Delivery
+ * is on when RESEND_API_KEY is configured.
+ *
+ *   gwo worker loop
+ *
+ * Each run is a child process, so a crash in one run never stops the loop,
+ * and the exit code of every run is logged.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+const workerEntry = ['index.js', 'index.ts'].map((f) => path.join(import.meta.dirname, f)).find((f) => existsSync(f));
+const at = (s, fallback) => { const m = (s ?? fallback).match(/^(\d{1,2}):(\d{2})$/); return m ? { h: Number(m[1]), m: Number(m[2]) } : { h: 7, m: 0 }; };
+const daily = at(process.env['GWO_DAILY_AT'], '07:00');
+const weekly = at(process.env['GWO_WEEKLY_AT'], '07:30');
+const weeklyDay = Number(process.env['GWO_WEEKLY_DAY'] ?? '1'); // 0 Sunday .. 6 Saturday; default Monday
+const deliver = !!process.env['RESEND_API_KEY'];
+const log = (s) => console.log(`${new Date().toISOString()} ${s}`);
+let lastDaily = '', lastWeekly = '';
+const stamp = (d) => d.toISOString().slice(0, 10);
+function run(cadence) {
+    log(`run ${cadence}${deliver ? ' --deliver' : ''}`);
+    const r = spawnSync(process.execPath, [workerEntry, cadence, ...(deliver ? ['--deliver'] : [])], { stdio: 'inherit' });
+    log(`${cadence} finished with exit code ${r.status ?? 'null'} (0 healthy, 2 escalations, 1 failures)`);
+}
+log(`worker loop: daily ${daily.h}:${String(daily.m).padStart(2, '0')}, weekly day ${weeklyDay} ${weekly.h}:${String(weekly.m).padStart(2, '0')}, TZ ${process.env['TZ'] ?? 'system'}, delivery ${deliver ? 'on' : 'off'}`);
+setInterval(() => {
+    const now = new Date();
+    const today = stamp(now);
+    if (now.getDay() === weeklyDay && now.getHours() === weekly.h && now.getMinutes() >= weekly.m && lastWeekly !== today) {
+        lastWeekly = today;
+        run('weekly');
+        return;
+    }
+    if (now.getHours() === daily.h && now.getMinutes() >= daily.m && lastDaily !== today) {
+        lastDaily = today;
+        run('daily');
+    }
+}, 30_000).unref();
+// Keep the process alive without busy-waiting.
+setInterval(() => { }, 1 << 30);

package/bin/gwo.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * gwo: the one entry point of the installed package.
+ *
+ *   gwo install [claude|codex|all] [--print]   register the MCP server, skills and commands
+ *   gwo uninstall [claude|codex|all]           remove them (operator state in GWO_HOME stays)
+ *   gwo mcp                                    run the MCP server on stdio (what the hosts launch)
+ *   gwo worker daily|weekly|monthly [--deliver]
+ *   gwo worker loop                            built-in scheduler for containers and VMs (docs/HOSTED-WORKER.md)
+ *   gwo schedule install|status|remove         Windows Task Scheduler for the worker
+ *   gwo update [spec]                          npm i -g the latest published version, then gwo install
+ *   gwo <cli command>                          everything else: sites, scan, setup, auth, gtm, content, report ...
+ *
+ * Plain JavaScript so npm's bin shim can load it on any Node; the rest of the
+ * package is TypeScript that Node 22.18+ runs natively.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 22 || (major === 22 && minor < 18)) {
+  console.error(`Google Web Operations needs Node 22.18 or newer (found ${process.versions.node}).`);
+  process.exit(1);
+}
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const cmd = process.argv[2];
+// A checkout runs the TypeScript sources; the packaged build ships JavaScript.
+const ext = existsSync(path.join(root, 'apps', 'cli', 'src', 'index.js')) ? 'index.js' : 'index.ts';
+// Dynamic imports need file URLs on Windows; a bare drive path is read as a URL scheme.
+const load = (...parts) => import(pathToFileURL(path.join(root, ...parts)).href);
+
+switch (cmd) {
+  case 'install':
+  case 'uninstall':
+    await load('tools', ext === 'index.js' ? 'install.js' : 'install.ts');
+    break;
+  case 'mcp':
+    await load('apps', 'mcp-server', 'src', ext);
+    break;
+  case 'worker':
+    process.argv.splice(2, 1);
+    if (process.argv[2] === 'loop') await load('apps', 'worker', 'src', ext === 'index.js' ? 'loop.js' : 'loop.ts');
+    else await load('apps', 'worker', 'src', ext);
+    break;
+  case 'update': {
+    // Latest published version, then re-register the hosts from the new package location.
+    const spec = process.argv[3] ?? '@aiguru/google-web-operations@latest';
+    const r = spawnSync(`npm install -g ${spec}`, { stdio: 'inherit', shell: true });
+    if (r.status !== 0) process.exit(r.status ?? 1);
+    const g = spawnSync('npm root -g', { encoding: 'utf8', shell: true });
+    const fresh = path.join(g.stdout.trim(), '@aiguru', 'google-web-operations', 'bin', 'gwo.js');
+    const i = spawnSync(process.execPath, [fresh, 'install'], { stdio: 'inherit' });
+    process.exit(i.status ?? 1);
+    break;
+  }
+  case 'schedule': {
+    if (process.platform !== 'win32') { console.error('gwo schedule is Windows only; use cron with "gwo worker daily" elsewhere.'); process.exit(1); }
+    const r = spawnSync('powershell', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', path.join(root, 'tools', 'schedule.ps1'), process.argv[3] ?? 'status'], { stdio: 'inherit' });
+    process.exit(r.status ?? 1);
+    break;
+  }
+  default:
+    await load('apps', 'cli', 'src', ext);
+}

package/docs/BOOTSTRAP-NEXT-PROMPT.md

@@ -0,0 +1,57 @@
+# Bootstrap prompt for the next implementation session
+
+You are continuing the **Google Web Operations** repository (v0.6). This applies whether you are Claude Code or Codex.
+
+## Architecture is decided
+
+Read, in order: `README.md`, `docs/PRODUCT-TECHNICAL-SPEC-v0.6.md`, `docs/adr/*.md`, `docs/SECURITY.md`, `docs/SITE-ADAPTERS.md`. Do not re-litigate them. In particular:
+
+- One core, one MCP server, hosts are generated. Never edit `hosts/`.
+- Playbooks live in `packages/playbooks/` only. Run `npm run build:hosts` after editing.
+- Policy is data in `policies/default.yaml`; enforcement is `packages/policy`. Every write goes through `performWrite()` in `packages/core/src/writes.ts`. Never call a connector's mutating function directly.
+- A Tag Manager publish needs the approval token and the review token (ADR-005). Do not add a way around either.
+- The package installs with `gwo install` and keeps state in `GWO_HOME` (ADR-006). New state must go under `HOME_DIR` from `paths.ts`, never under `ROOT`. Anything the code reads from `ROOT` at runtime (a new asset directory) must also be copied by `tools/build-package.ts`, or the installed package will not find it.
+- Releasing: bump `package.json`, `git tag v<version>`, push the tag; the release workflow publishes to GitHub Packages and attaches the tarball. Installed machines run `gwo update`.
+- TypeScript runs natively on Node. Import with `.ts` extensions, `import type` for types, no constructor parameter properties, no enums.
+- Load the project skills `seo-geo` and `hebrew-content-writer` (under `.claude/skills/`) before writing any client-facing text; the `gwo-content-brief` playbook is their distilled form.
+
+## Before changing anything
+
+```
+npm install
+npm run check          # typecheck, tests, regenerate hosts
+npm run smoke:mcp
+npm run cli -- scan doritgrinberg --pages 30
+node apps/worker/src/index.ts daily
+```
+
+All pass at the time of writing. If one does not, fix that first.
+
+## Operator actions that unlock live paths (not code work)
+
+All of these can now be driven from the chat with the `gwo-setup` skill (`ops_setup_status` first). The CLI forms:
+
+1. `npm run cli -- auth login --scope ga4_write`, then `npm run cli -- ga4 key-event <site> <event> --approval <site>:ga4.key_event.create`.
+2. For each repository-backed site: set `write.repo.local_path` and `write.repo.url`, add `gwo.seo.json` to the site (see `docs/SITE-ADAPTERS.md`), then `npm run cli -- site ping <site>`.
+3. For each site with a container: set `google.tag_manager.public_id` (or run `discover --apply`), then `npm run cli -- auth login --scope gtm_edit --scope gtm_publish` once. `npm run cli -- gtm workspaces <site>` is the first read.
+4. `RESEND_API_KEY`, `GWO_REPORT_FROM`, `GWO_REPORT_TO` in `.env` for delivery; `GITHUB_TOKEN` for pull requests.
+5. `powershell -ExecutionPolicy Bypass -File tools\schedule.ps1 install` registers the daily and weekly tasks; `status` shows them.
+
+## First live use of the v0.4 writes
+
+Before the first real client container, run the whole protocol once on a container the company owns: `gtm stage` the standard stack from `gwo-measurement`, `gtm wdiff`, `gtm publish`, then `gtm versions` and `ga4_realtime`. The staged path is tested against a fake API; one live pass will surface any API field the fake does not model (built-in variables, consent settings, folder ids). Fix the connector, not the playbook.
+
+Run `npm run cli -- report client <site> --month <YYYY-MM>` once with `GWO_DOCX_TEMPLATE` set and open the .docx in Word: the template's header and footer must be there and the body in Hebrew, right to left.
+
+Likewise `content schema` on one Odoo page: confirm the API user can write `ir.ui.view.arch` (Website Designer rights), and that the rendered page shows the block.
+
+## Next milestone: v0.7
+
+1. **First live Tag Manager cycle** on a company-owned container (see above), then the first client container. Fix the connector for whatever the fake API did not model.
+2. **Install feedback.** The package is being installed on a second Claude Code machine and on Codex. Whatever confuses a person there goes into `gwo-setup`, `gwo doctor` or `docs/GETTING-STARTED.he.md`, not into a chat answer.
+3. **Outcome metrics.** The client report says what was done; it should say what it changed: clicks and impressions for the pages touched, before and after, from Search Console. Audit records carry the URL and date of every write, so the data is there.
+4. **Advisory profile.** A second policy profile for advisory-tier clients where nothing is `auto` except reads and reports.
+
+## Definition of done for a session
+
+Report only what was implemented and verified: files changed, commands run and their output, host results, what remains blocked. Update the spec's delivered table when scope moves, and bump the version when a milestone completes.