{"_id":"ga4-manager-mcp","_rev":"7-3c6fee1ee7ea074e60f324ab0114aa3b","name":"ga4-manager-mcp","dist-tags":{"latest":"5.1.0"},"versions":{"0.0.0-stage":{"name":"ga4-manager-mcp","version":"0.0.0-stage","_id":"ga4-manager-mcp@0.0.0-stage","stub":true,"maintainers":[{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"}],"dist":{"shasum":"a753451537ffdb9226c7c9b5ede17dd5780f3aaa","tarball":"https://registry.npmjs.org/ga4-manager-mcp/-/ga4-manager-mcp-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-5JnJnywouc1C32RR7mYIdbn1PNhN+saV7+Ejp5JvimJhr/uguVSNxABHqpknhDfygKOqVbMLT6kTivOQBarExw==","signatures":[{"sig":"MEUCIQCO0YttHBPGbUlXegYYZUyEBOrVP01GIVfN78lUN4AA0AIgOR639CTAY67HJ4F3zkb1/e1Dhf9V360Zi9NOX6UaBmY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":337},"_npmUser":{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"4.0.0":{"name":"ga4-manager-mcp","version":"4.0.0","keywords":["mcp","model-context-protocol","google-analytics","ga4","search-console","seo","adsense","dataforseo","claude"],"author":{"name":"Oscar Gallego"},"license":"MIT","_id":"ga4-manager-mcp@4.0.0","maintainers":[{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"}],"homepage":"https://github.com/garbarok/ga4-manager/tree/main/mcp#readme","bugs":{"url":"https://github.com/garbarok/ga4-manager/issues"},"bin":{"ga4-manager-mcp":"dist/index.js"},"dist":{"shasum":"606ff3a92cf86712a64863282838418ed6ec3a3f","tarball":"https://registry.npmjs.org/ga4-manager-mcp/-/ga4-manager-mcp-4.0.0.tgz","fileCount":279,"integrity":"sha512-2UDVZFbcu7yWWYZGM87yw9F388Gc9fvb73RIT2yR/X57C3blD7P9BXz3sczjnvPqjFqwFw7Gm41LpEt0GpkjBw==","signatures":[{"sig":"MEYCIQDY5wAwj9c1P/6iG6y4XrVwxxi6O/h2RQSrAyQbVk2x/QIhAKBTkSvBPoa3959WVYJL00kIhiySQlSs+2hs9RS7I4kU","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCICD19jglQ1eEBGhqKAYwf8iNSycVQwCSddu3iLbW+w4hAiA+KIa98i7VyNSUph5jPUeIYKzxsNtQOiYawz8FB9G91A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1199392},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"316acab14c86d36b2599a9d4908fd5e3202e0bb8","mcpName":"io.github.garbarok/ga4-manager","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/","test":"vitest","build":"tsc","test:run":"vitest run","pack:mcpb":"bash scripts/build-mcpb.sh","test:watch":"vitest watch","prepublishOnly":"pnpm run lint && pnpm exec tsc --noEmit && pnpm run test:run && pnpm run build"},"_npmUser":{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"},"repository":{"url":"git+https://github.com/garbarok/ga4-manager.git","type":"git","directory":"mcp"},"_npmVersion":"11.19.1","description":"MCP server for organic growth: Google Analytics 4, Search Console, AdSense, on-page SEO audits and DataForSEO, built for AI agents","directories":{},"_nodeVersion":"24.22.1","dependencies":{"zod":"^4.6.5","tldts":"^7.4.16","csv-parse":"^6.2.1","bottleneck":"^2.19.5","robots-parser":"^3.0.1","node-html-parser":"^7.1.0","@modelcontextprotocol/sdk":"^1.30.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.15","eslint":"^10.11.0","vitest":"^4.1.11","globals":"^17.12.0","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^25.9.8","@typescript-eslint/parser":"^8.70.1","@typescript-eslint/eslint-plugin":"^8.70.1"},"_npmOperationalInternal":{"tmp":"tmp/ga4-manager-mcp_4.0.0_1793270310867_0.32811010945250807","host":"s3://npm-registry-packages-npm-production"}},"4.1.0":{"name":"ga4-manager-mcp","version":"4.1.0","keywords":["mcp","model-context-protocol","google-analytics","ga4","search-console","seo","adsense","dataforseo","claude"],"author":{"name":"Oscar Gallego"},"license":"MIT","_id":"ga4-manager-mcp@4.1.0","maintainers":[{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"}],"homepage":"https://github.com/garbarok/ga4-manager/tree/main/mcp#readme","bugs":{"url":"https://github.com/garbarok/ga4-manager/issues"},"bin":{"ga4-manager-mcp":"dist/index.js"},"dist":{"shasum":"4dc0a94372d7cfd8f7a8e6b446bd587a8cbf4166","tarball":"https://registry.npmjs.org/ga4-manager-mcp/-/ga4-manager-mcp-4.1.0.tgz","fileCount":283,"integrity":"sha512-z/4Xbl2Nf6VRKglp3XiRit4K1DY1m6v8ZDK+MvSEnaSF5R1SzXdZooPxfvRKv0d3asRYKYmw23iNLoMvQQm15g==","signatures":[{"sig":"MEYCIQCSOsw4NRqS5nUumfO9igi85/ITrzTlKEOLCiJqg+P8hwIhAIA6x+Uol297h/rkBpgsExTWr8LtgBzkH+ZsPCWp5N9Y","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQCHtAg3QOv+AVy08f9xVtAcINdwc04UOSCgXv5j1MjVjwIhAIj1WrRVxDQcAg9XuQu9MQyttoziccwtcXekY3biboOO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1209182},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"18dca50cbec76565844f9b2ca7767ba46dabbb78","mcpName":"io.github.garbarok/ga4-manager","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/","test":"vitest","build":"tsc","test:run":"vitest run","pack:mcpb":"bash scripts/build-mcpb.sh","test:watch":"vitest watch","prepublishOnly":"pnpm run lint && pnpm exec tsc --noEmit && pnpm run test:run && pnpm run build"},"_npmUser":{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"},"repository":{"url":"git+https://github.com/garbarok/ga4-manager.git","type":"git","directory":"mcp"},"_npmVersion":"11.19.1","description":"MCP server for organic growth: Google Analytics 4, Search Console, AdSense, on-page SEO audits and DataForSEO, built for AI agents","directories":{},"_nodeVersion":"24.22.1","dependencies":{"zod":"^4.6.5","tldts":"^7.4.16","csv-parse":"^6.2.1","bottleneck":"^2.19.5","robots-parser":"^3.0.1","node-html-parser":"^7.1.0","@modelcontextprotocol/sdk":"^1.30.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.15","eslint":"^10.11.0","vitest":"^4.1.11","globals":"^17.12.0","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^25.9.8","@typescript-eslint/parser":"^8.70.1","@typescript-eslint/eslint-plugin":"^8.70.1"},"_npmOperationalInternal":{"tmp":"tmp/ga4-manager-mcp_4.1.0_1793272300793_0.5018262923542519","host":"s3://npm-registry-packages-npm-production"}},"4.1.1":{"name":"ga4-manager-mcp","version":"4.1.1","keywords":["mcp","model-context-protocol","google-analytics","ga4","search-console","seo","adsense","dataforseo","claude"],"author":{"name":"Oscar Gallego"},"license":"MIT","_id":"ga4-manager-mcp@4.1.1","maintainers":[{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"}],"homepage":"https://github.com/garbarok/ga4-manager/tree/main/mcp#readme","bugs":{"url":"https://github.com/garbarok/ga4-manager/issues"},"bin":{"ga4-manager-mcp":"dist/index.js"},"dist":{"shasum":"ab47a6551e02ede6c93da4c1103ac240437d39fc","tarball":"https://registry.npmjs.org/ga4-manager-mcp/-/ga4-manager-mcp-4.1.1.tgz","fileCount":283,"integrity":"sha512-syghEHSYVNMfJq3wox8rkYmmoTTylAaTEZ8rPD+jly1fNxZCAHOpo3Zql/jkDPwmKgsewXlWswKfv1QjvqKjGg==","signatures":[{"sig":"MEUCIDbbP+AkZVphIRxbK2yYp88CqbIApxI8TlF8N80FOPc2AiEA3dq5U9gCJ43HuzU0kAmT6Lr3DC+G61Sl1bqT8tx1ybE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIHcRbh3sUDZw2VVMj0eCnC3DFmYutdN+EpPK8Zf1ANgZAiB7Y8duIPeyOMUCNce0pYuyS1zoGUkFeSmd41jHuEfkgQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1210443},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"099e4d6d0430290118bff779ff6787aacca61eeb","mcpName":"io.github.garbarok/ga4-manager","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/","test":"vitest","build":"tsc","test:run":"vitest run","pack:mcpb":"bash scripts/build-mcpb.sh","test:watch":"vitest watch","prepublishOnly":"pnpm run lint && pnpm exec tsc --noEmit && pnpm run test:run && pnpm run build"},"_npmUser":{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"},"repository":{"url":"git+https://github.com/garbarok/ga4-manager.git","type":"git","directory":"mcp"},"_npmVersion":"11.19.1","description":"MCP server for organic growth: Google Analytics 4, Search Console, AdSense, on-page SEO audits and DataForSEO, built for AI agents","directories":{},"_nodeVersion":"24.22.1","dependencies":{"zod":"^4.6.5","tldts":"^7.4.16","csv-parse":"^6.2.1","bottleneck":"^2.19.5","robots-parser":"^3.0.1","node-html-parser":"^7.1.0","@modelcontextprotocol/sdk":"^1.30.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.15","eslint":"^10.11.0","vitest":"^4.1.11","globals":"^17.12.0","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^25.9.8","@typescript-eslint/parser":"^8.70.1","@typescript-eslint/eslint-plugin":"^8.70.1"},"_npmOperationalInternal":{"tmp":"tmp/ga4-manager-mcp_4.1.1_1793273796213_0.06087590577688662","host":"s3://npm-registry-packages-npm-production"}},"4.1.2":{"name":"ga4-manager-mcp","version":"4.1.2","keywords":["mcp","model-context-protocol","google-analytics","ga4","search-console","seo","adsense","dataforseo","claude"],"author":{"name":"Oscar Gallego"},"license":"MIT","_id":"ga4-manager-mcp@4.1.2","maintainers":[{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"}],"homepage":"https://github.com/garbarok/ga4-manager/tree/main/mcp#readme","bugs":{"url":"https://github.com/garbarok/ga4-manager/issues"},"bin":{"ga4-manager-mcp":"dist/index.js"},"dist":{"shasum":"80026c43ccf0bf9626ec61727d2c2b89508e71b4","tarball":"https://registry.npmjs.org/ga4-manager-mcp/-/ga4-manager-mcp-4.1.2.tgz","fileCount":283,"integrity":"sha512-T+/tkFhvCP0lER2cW5Bur/p7EdPiPDbyu8z0nLXgzI6UnWk8MNbpJRDxvdhN27xATzu0a0QvjEz04ACKhikOmg==","signatures":[{"sig":"MEYCIQD2k3P1ESkcq0JdZEQ2FQ9vkvHYNqJ/a1wWKlT6hwrnCgIhAM1TA53n/yEV1LLuCHXpmjDivCYKPKRYvRDoLG0s7ree","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQDZpIi/azG8cjzEq3btQRba7bhgeXkJNV842RuLqIGsuwIgQ8vBVHXHjAOIyaPFD7PdSc538r4cUZ33/MoSf5fQFsY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1210967},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"74f21ce42bbc74160342615a88835ba2bcb0d7e8","mcpName":"io.github.garbarok/ga4-manager","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/","test":"vitest","build":"tsc","test:run":"vitest run","pack:mcpb":"bash scripts/build-mcpb.sh","smoke:pack":"node scripts/pack-smoke.mjs","test:watch":"vitest watch","prepublishOnly":"pnpm run lint && pnpm exec tsc --noEmit && pnpm run test:run --reporter=dot && pnpm run build && pnpm run smoke:pack"},"_npmUser":{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"},"repository":{"url":"git+https://github.com/garbarok/ga4-manager.git","type":"git","directory":"mcp"},"_npmVersion":"11.19.1","description":"MCP server for organic growth: Google Analytics 4, Search Console, AdSense, on-page SEO audits and DataForSEO, built for AI agents","directories":{},"_nodeVersion":"24.22.1","dependencies":{"zod":"^4.6.5","tldts":"^7.4.16","csv-parse":"^6.2.1","bottleneck":"^2.19.5","robots-parser":"^3.0.1","node-html-parser":"^7.1.0","@modelcontextprotocol/sdk":"^1.30.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.15","eslint":"^10.11.0","vitest":"^4.1.11","globals":"^17.12.0","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^25.9.8","@typescript-eslint/parser":"^8.70.1","@typescript-eslint/eslint-plugin":"^8.70.1"},"_npmOperationalInternal":{"tmp":"tmp/ga4-manager-mcp_4.1.2_1793274889749_0.978983435889668","host":"s3://npm-registry-packages-npm-production"}},"5.0.1":{"name":"ga4-manager-mcp","version":"5.0.1","keywords":["mcp","model-context-protocol","google-analytics","ga4","search-console","seo","adsense","dataforseo","claude"],"author":{"name":"Oscar Gallego"},"license":"MIT","_id":"ga4-manager-mcp@5.0.1","maintainers":[{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"}],"homepage":"https://github.com/garbarok/ga4-manager/tree/main/mcp#readme","bugs":{"url":"https://github.com/garbarok/ga4-manager/issues"},"bin":{"ga4m":"dist/cli.js","ga4-manager-mcp":"dist/index.js"},"dist":{"shasum":"d574696d6d1b132b1317eb0d403a0f567f883508","tarball":"https://registry.npmjs.org/ga4-manager-mcp/-/ga4-manager-mcp-5.0.1.tgz","fileCount":467,"integrity":"sha512-wMVcKrYFug5N3o2TFfvEw+1+RJt1emPH5LVN0SjQyKEXkGLU6AzEnSVhC4O17hPGvJGlZsyE/qElg4fHnAjOcw==","signatures":[{"sig":"MEQCIFEfqep/nVFquNCnkfHTk1BVxXH1RROpeHR93BUC8aUCAiAv/wkqpANhqjeiH3jj4ebKKVdgigl1tWSz0F23b+j4JQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIFGqhIEyUiHIVvcRUp284r2nTYnvN7fQ6H4je6x/NCzfAiAb9S8CYNQQ1G0VJkxW9npvFZLLjQnEXC7tBXxgLhvBBQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2432379},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"5ad811da98d98609430b284d0e28c2d09e5fd85c","mcpName":"io.github.garbarok/ga4-manager","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/","test":"vitest","build":"tsc","test:run":"vitest run","pack:mcpb":"bash scripts/build-mcpb.sh","smoke:pack":"node scripts/pack-smoke.mjs","test:watch":"vitest watch","manifest:sync":"tsx scripts/sync-manifest-tools.ts","prepublishOnly":"pnpm run lint && pnpm exec tsc --noEmit && pnpm run test:run --reporter=dot && pnpm run build && pnpm run smoke:pack"},"_npmUser":{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"},"repository":{"url":"git+https://github.com/garbarok/ga4-manager.git","type":"git","directory":"mcp"},"_npmVersion":"11.20.0","description":"MCP server for organic growth: Google Analytics 4, Search Console, AdSense, on-page SEO audits and DataForSEO, built for AI agents","directories":{},"_nodeVersion":"26.13.1","dependencies":{"zod":"^4.6.7","tldts":"^7.4.18","csv-parse":"^7.0.3","bottleneck":"^2.19.5","robots-parser":"^3.0.1","node-html-parser":"^9.0.5","@modelcontextprotocol/sdk":"^1.32.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.15","eslint":"^10.13.0","vitest":"^5.0.5","globals":"^17.13.0","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^26.6.5","@typescript-eslint/parser":"^8.72.0","@typescript-eslint/eslint-plugin":"^8.72.0"},"_npmOperationalInternal":{"tmp":"tmp/ga4-manager-mcp_5.0.1_1795024263544_0.8331079492851236","host":"s3://npm-registry-packages-npm-production"}},"5.1.0":{"_id":"ga4-manager-mcp@5.1.0","bin":{"ga4m":"dist/cli.js","ga4-manager-mcp":"dist/index.js"},"bugs":{"url":"https://github.com/garbarok/ga4-manager/issues"},"dist":{"shasum":"ea5d61ff05e2f081d76e4f480097c38ab2239170","tarball":"https://registry.npmjs.org/ga4-manager-mcp/-/ga4-manager-mcp-5.1.0.tgz","fileCount":471,"integrity":"sha512-8INvFF5zOWuVNM5LVJPBGsPuvW7XMVRQtwtYw/F/uHPet0yZGOYliQ7jQWzNl8obp77MhEsxa7/rO0EH/BtW4Q==","signatures":[{"sig":"MEUCIFGT+6zdx6gn8S5pinphH6Sz5mx2OVeGjucNXQq0tdPpAiEAmuQQ/r9EQ3XtILNarz5tfOPsW0i/nbPnCYxikrY3J5A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC4EDvZ4q1FvaYJoaUl046ncIdiJNIk6dtvbGPUOTlLcgIgSBoC4EdKsKQBe70DFlkT8hx6mzEi5gqCDI086iPkUP4="}],"unpackedSize":2441961},"main":"dist/index.js","name":"ga4-manager-mcp","type":"module","types":"./dist/index.d.ts","author":{"name":"Oscar Gallego"},"engines":{"node":">=18.0.0"},"gitHead":"bc79621325113fdff43f22418d1c5a47a9df5205","license":"MIT","mcpName":"io.github.garbarok/ga4-manager","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/","test":"vitest","build":"tsc","test:run":"vitest run","pack:mcpb":"bash scripts/build-mcpb.sh","smoke:pack":"node scripts/pack-smoke.mjs","test:watch":"vitest watch","manifest:sync":"tsx scripts/sync-manifest-tools.ts","prepublishOnly":"pnpm run lint && pnpm exec tsc --noEmit && pnpm run test:run --reporter=dot && pnpm run build && pnpm run smoke:pack"},"version":"5.1.0","_npmUser":{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"},"homepage":"https://github.com/garbarok/ga4-manager/tree/main/mcp#readme","keywords":["mcp","model-context-protocol","google-analytics","ga4","search-console","seo","adsense","dataforseo","claude"],"repository":{"url":"git+https://github.com/garbarok/ga4-manager.git","type":"git","directory":"mcp"},"_npmVersion":"11.20.0","description":"MCP server for organic growth: Google Analytics 4, Search Console, AdSense, on-page SEO audits and DataForSEO, built for AI agents","directories":{},"maintainers":[{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"}],"_nodeVersion":"26.13.1","dependencies":{"zod":"^4.6.7","tldts":"^7.4.18","csv-parse":"^7.0.3","bottleneck":"^2.19.5","robots-parser":"^3.0.1","node-html-parser":"^9.0.5","@modelcontextprotocol/sdk":"^1.32.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.15","eslint":"^10.13.0","vitest":"^5.0.5","globals":"^17.13.0","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^26.6.5","@typescript-eslint/parser":"^8.72.0","@typescript-eslint/eslint-plugin":"^8.72.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ga4-manager-mcp_5.1.0_1795028441434_0.2958721199797695"}}},"time":{"created":"2026-10-29T10:35:21.027Z","modified":"2026-11-18T19:00:41.885Z","0.0.0-stage":"2026-10-29T10:35:21.027Z","4.0.0":"2026-10-29T10:38:31.022Z","4.1.0":"2026-10-29T11:11:40.917Z","4.1.1":"2026-10-29T11:36:36.366Z","4.1.2":"2026-10-29T11:54:49.866Z","5.0.1":"2026-11-18T17:51:03.652Z","5.1.0":"2026-11-18T19:00:41.586Z"},"bugs":{"url":"https://github.com/garbarok/ga4-manager/issues"},"author":{"name":"Oscar Gallego"},"license":"MIT","homepage":"https://github.com/garbarok/ga4-manager/tree/main/mcp#readme","keywords":["mcp","model-context-protocol","google-analytics","ga4","search-console","seo","adsense","dataforseo","claude"],"repository":{"url":"git+https://github.com/garbarok/ga4-manager.git","type":"git","directory":"mcp"},"description":"MCP server for organic growth: Google Analytics 4, Search Console, AdSense, on-page SEO audits and DataForSEO, built for AI agents","maintainers":[{"name":"garbarok","email":"garbaroknpm@oscargallegoruiz.com"}],"readme":"# GA4 Manager MCP Server\n\n> **AI-powered GA4 and Google Search Console management through Model Context Protocol**\n\nA Model Context Protocol (MCP) server with 44 tools and 3 workflow prompts for AI assistants: Google Analytics 4 setup and reports, Search Console diagnostics, AdSense, on-page SEO audits with Core Web Vitals field data, IndexNow, and DataForSEO keyword, backlink and AI-visibility research. Works with Claude Code, Claude Desktop and other MCP clients.\n\n[![npm](https://img.shields.io/npm/v/ga4-manager-mcp)](https://www.npmjs.com/package/ga4-manager-mcp)\n[![Latest Release](https://img.shields.io/github/v/release/garbarok/ga4-manager)](https://github.com/garbarok/ga4-manager/releases/latest)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n---\n\n## What is This?\n\nThis MCP server bridges AI assistants like **Claude Code** with the GA4 Manager CLI, enabling:\n\n- **Natural language analytics configuration** - \"Set up conversion tracking for purchases\"\n- **Automated Search Console management** - \"Submit my sitemap and check indexing status\"\n- **Data-driven insights** - \"Show me top search queries for the last 30 days\"\n- **Workflow automation** - \"Validate config, preview setup, then apply if it looks good\"\n\n### What is MCP?\n\n**Model Context Protocol (MCP)** is an open protocol that lets AI assistants interact with external tools and data sources. Think of it as an API designed for AI agents.\n\n**How it works:**\n1. AI assistant (Claude Code) receives user request\n2. MCP client calls tool on MCP server (this project)\n3. MCP server executes GA4 CLI command\n4. Structured JSON response returned to AI assistant\n5. AI assistant uses data to help user\n\n---\n\n## Features\n\n- ✅ **13 Production-Ready Tools** - Complete GA4 and GSC operation coverage\n- ✅ **Comprehensive Test Suite** - All tools covered by unit and integration tests\n- ✅ **Structured JSON Output** - All CLI responses parsed to machine-readable format\n- ✅ **Intelligent Parsing** - Auto-detects and handles JSON, tables, CSV, markdown\n- ✅ **Dry-Run Support** - Preview changes before applying (safe operations)\n- ✅ **Quota Tracking** - Monitor Google Search Console API usage\n- ✅ **Error Handling** - Actionable error messages with suggestions\n- ✅ **Multi-Client Support** - Works with Claude Desktop, Claude CLI, VS Code, Cursor, Cline\n\n---\n\n## Quick Start\n\n### Installation\n\n#### From npm\n\n```bash\nclaude mcp add ga4-manager \\\n  --env GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json \\\n  --env GOOGLE_CLOUD_PROJECT=your-gcp-project-id \\\n  -- npx -y ga4-manager-mcp\n```\n\nNative tools (GA4 reports, Search Console comparisons, AdSense, SEO audits, DataForSEO) work with just this. CLI-backed tools (`ga4_setup`, `gsc_health`, `gsc_decay`…) also need the `ga4` binary: download it from [GitHub Releases](https://github.com/garbarok/ga4-manager/releases) and put it on your `PATH` or set `GA4_BINARY_PATH`. Destructive tools stay disabled until you add `--env GA4M_ALLOW_DESTRUCTIVE=1`.\n\n#### From source\n\n```bash\n# 1. Clone repository\ngit clone https://github.com/garbarok/ga4-manager.git\ncd ga4-manager\n\n# 2. Build CLI binary\nmake build\n\n# 3. Build MCP server\ncd mcp\nnpm install\nnpm run build\n```\n\n### Configuration\n\nChoose your client and follow the setup:\n\n#### Claude CLI (Recommended)\n\n```bash\nclaude mcp add \\\n  --name ga4-manager \\\n  --transport stdio \\\n  --command \"node\" \\\n  --args \"/absolute/path/to/ga4-manager/mcp/dist/index.js\" \\\n  --env \"GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json\" \\\n  --env \"GOOGLE_CLOUD_PROJECT=your-gcp-project-id\" \\\n  --env \"GA4_BINARY_PATH=/absolute/path/to/ga4-manager/ga4\" \\\n  --env \"GA4_DEFAULT_PROPERTY_ID=123456789\"\n```\n\n#### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"ga4-manager\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/ga4-manager/mcp/dist/index.js\"],\n      \"env\": {\n        \"GOOGLE_APPLICATION_CREDENTIALS\": \"/path/to/credentials.json\",\n        \"GOOGLE_CLOUD_PROJECT\": \"your-gcp-project-id\",\n        \"GA4_BINARY_PATH\": \"/absolute/path/to/ga4-manager/ga4\",\n        \"GA4_DEFAULT_PROPERTY_ID\": \"123456789\"\n      }\n    }\n  }\n}\n```\n\n#### Other Clients\n\nSee **[CONFIGURATION.md](./CONFIGURATION.md)** for setup guides:\n- VS Code (via MCP extension)\n- Cursor\n- Cline\n- Custom integrations\n\nFor Claude Code cloud sessions (claude.ai/code, `claude --cloud`), see **[CLOUD.md](./CLOUD.md)**.\n\n### Verify Installation\n\n**Claude Desktop:**\n- Restart Claude Desktop\n- Click 🔌 icon in bottom-left\n- Should show \"ga4-manager\" with 29 tools\n\n**Claude CLI:**\n```bash\nclaude mcp list\n# Should show: ga4-manager (29 tools)\n```\n\n**VS Code/Cursor:**\n- Check MCP status indicator in status bar\n\n---\n\n## Available Tools\n\nThe registry is the authoritative list (`ga4m list`, or `server_info` from your assistant). Every tool is also a `ga4m` command with the same input and output.\n\n### Tool Categories\n\n**Start here (3 tools)** - What this install can do, and the shared project memory\n- `server_info` - Version, enabled tool groups and why a group is off (missing `DATAFORSEO_*`, no `ga4` binary, scope not granted), state dir, spending caps, update path\n- `project_context_get` / `project_context_update` - Per-site brand, goal, positioning, writing preferences, competitors, key pages (hub/spoke/money) and the research log of paid lookups already bought\n\n**Search Console × GA4 (2 tools)**\n- `page_opportunities` - Pages ranking 4–20 joined with GA4 organic landing-page outcomes; score = 0.5 demand + 0.3 business value + 0.2 reachability; unmatched pages kept visible; coverage and time-zone warnings\n- `gsc_change_impact` - Before/after verdict (too_early / improved / worse / flat) for changes or GA4 annotations, equal windows, lag-safe\n\n**GA4 organic reports (8 tools)**\n- `ga4_organic_overview`, `ga4_organic_landing_pages`, `ga4_key_events`, `ga4_traffic_acquisition`, `ga4_audience`, `ga4_site_search`, `ga4_ecommerce`, `ga4_measurement_health`\n\n**Site crawl audit (7 tools)** - Background crawler, free\n- `site_audit_run`, `site_audit_status`, `site_audit_issues`, `site_audit_pages`, `site_audit_lighthouse`, `site_audit_list`, `site_audit_delete`\n\n**Keyword workspace and competitors (7 tools)** - DataForSEO where marked\n- `keywords_save`, `keywords_list`, `keywords_remove` - Saved, tagged keyword lists per site\n- `keyword_suggestions` - Search Console queries at positions 4–30 not saved yet (free) + optional paid `keywords_for_site`\n- `serp_competitors` (paid), `domain_overview` (paid), `serp_locations` (free)\n\n**Rank tracking (8 tools)** - Stored runs and history\n- `rank_tracker_create`, `rank_tracker_update`, `rank_tracker_get`, `rank_tracker_history`, `rank_tracker_list`, `rank_tracker_delete`, `rank_tracker_estimate` (free), `rank_tracker_run` (paid)\n\n**AI visibility tracking (11 tools)**\n- `ai_visibility_research`, `ai_visibility_explore`, `ai_visibility_estimate`, `ai_visibility_run` (paid, gated); `ai_visibility_prompts_generate`, `ai_visibility_tracker_save`, `ai_visibility_results`, `ai_visibility_trend`, `ai_visibility_sources`, `ai_visibility_answer`, `ai_visibility_export` (free)\n\n**Saved reports (7 tools)**\n- `report_save`, `report_list`, `report_get`, `report_delete`, `report_template_save`, `report_template_list`, `report_template_delete`\n\n**Growth planning (1 tool)** - Start here for SEO / monetization plans\n- `site_growth_brief` - One compact brief per site: GSC + GA4 traffic + AdSense-in-GA4 revenue KPIs with deltas, top pages by revenue, and the top 10 diagnostic findings ranked by estimated clicks\n\n**GA4 Analytics (8 tools)** - Configuration, management and traffic\n- `ga4_setup` - Create conversions, dimensions, metrics\n- `ga4_report` - View current configuration\n- `ga4_cleanup` - Remove unused resources\n- `ga4_link_list` - List existing external-service links\n- `ga4_link_create` - Create a Search Console/BigQuery/Channels link\n- `ga4_link_remove` - Remove (unlink) a BigQuery/Channels link\n- `ga4_validate` - Configuration validation\n- `ga4_traffic_report` - Sessions, engagement, page views and ad revenue (when AdSense is linked) by page, landing page, channel, source, country, device or date\n\n**Search Console (14 tools)** - SEO and indexing\n- `gsc_sitemaps_list` - List all sitemaps\n- `gsc_sitemaps_submit` - Submit new sitemap\n- `gsc_sitemaps_delete` - Remove sitemap\n- `gsc_sitemaps_get` - Get sitemap details\n- `gsc_inspect_url` - Check URL indexing status\n- `gsc_analytics_run` - Search performance data\n- `gsc_monitor_urls` - Batch URL monitoring\n- `gsc_index_coverage` - Index coverage report\n- `gsc_cannibalization` - Detect keyword cannibalization across URLs\n- `gsc_opportunities` - Surface ranking/CTR improvement opportunities (per query, or per page with `granularity: \"page\"`)\n- `gsc_ctr_anomaly` - Flag pages with anomalous CTR for their position\n- `gsc_decay` - Flag pages that slipped in position and lost clicks vs the prior window\n- `gsc_health` - Search Console health overview\n- `gsc_url_hygiene` - URLs with impressions that should not be indexed (fragments, asset routes, malformed paths, query duplicates)\n- `gsc_hreflang` - hreflang pair integrity and cross-language ranking\n\n**Diagnostics & SEO (4 tools)** - Traffic analysis and page auditing\n- `gsc_traffic_compare` - Diff GSC traffic between two date ranges per URL, or before/after a change date (`around`) with an optional `pages` filter\n- `ga4_consent_health` - Consent banner grant/deny rates and health score\n- `seo_page_audit` - On-page SEO audit with optional Core Web Vitals; `render_js: true` fetches the post-JavaScript DOM via Cloudflare Browser Rendering for JS-rendered/SPA pages\n- `seo_audit_batch` - Batch on-page SEO audit over a sitemap or URL list; supports `render_js`, include/exclude regex filters and SiteOne crawl discovery (`discover.siteone`)\n\n**AdSense (2 tools)** - Publisher earnings reporting\n- `adsense_accounts_list` - List accessible AdSense publisher accounts\n- `adsense_report` - Earnings / page views / impressions / clicks / RPM by date, domain, country, ad unit\n\n**Keyword research (3 tools)** - DataForSEO / ValueSERP, opt-in third-party credentials\n- `keyword_volume` - Search volume, CPC and competition for a list of keywords (DataForSEO)\n- `keyword_serp_snapshot` - Who currently ranks for a keyword, for content-gap/competitive research (DataForSEO)\n- `keyword_rank_check` - A domain's live Google rank for a keyword today, distinct from GSC's historical average position (ValueSERP)\n\n**Competitive & AI-visibility research (9 tools)** - DataForSEO, opt-in; every result reports `cost_usd`\n- `dataforseo_balance` - Remaining DataForSEO balance (free)\n- `llm_mentions` - Whether Google AI answers / ChatGPT mention or cite a domain for given queries, and who they cite instead\n- `keyword_gap` - Keywords a competitor ranks for that you don't, with volume and difficulty\n- `ranked_keywords` - Every keyword and position for any domain, competitors included\n- `keyword_ideas` - Keyword ideas with volume, difficulty (KD) and search intent\n- `google_trends` - Interest over time (0–100) for up to 5 terms: rising/falling, seasonality, peak date\n- `backlinks_overview` - Domain rank, backlinks and referring domains, side by side\n- `link_gap` - Referring domains that link to competitors but not to you (outreach targets)\n- `dataforseo_request` - Gated escape hatch: any DataForSEO v3 endpoint by path; billed per call, off unless `DATAFORSEO_ALLOW_RAW=1`\n\n**Indexing (1 tool)** - IndexNow, no account needed (just a key file on your site)\n- `indexnow_submit` - Notify Bing, Yandex, Seznam, Naver, Yep and others (not Google) about new or changed URLs. `dry_run` defaults to true; the key file is verified before submitting\n\n### Tool Operation Types\n\n**Read-Only (Safe):** every tool whose MCP annotation has `readOnlyHint: true`. The list below predates the OpenSEO-parity tools; for those, the annotations are authoritative. Tools that write only local state (project context, saved keywords, trackers, reports, audit records) are not read-only, so `GA4M_READ_ONLY` refuses them, but they are not destructive.\n- `ga4_report`, `ga4_validate`, `ga4_link_list`, `gsc_sitemaps_list`, `gsc_sitemaps_get`, `gsc_inspect_url`, `gsc_analytics_run`, `gsc_monitor_urls`, `gsc_index_coverage`, `gsc_cannibalization`, `gsc_opportunities`, `gsc_ctr_anomaly`, `gsc_health`, `gsc_traffic_compare`, `ga4_consent_health`, `seo_page_audit`, `seo_audit_batch`, `adsense_accounts_list`, `adsense_report`, `site_growth_brief`, `ga4_traffic_report`, `gsc_url_hygiene`, `gsc_hreflang`, `keyword_volume`, `keyword_serp_snapshot`, `keyword_rank_check`, `dataforseo_balance`, `llm_mentions`, `keyword_gap`, `ranked_keywords`, `keyword_ideas`, `google_trends`, `backlinks_overview`, `link_gap`, `dataforseo_request`\n- `ga4_report`, `ga4_validate`, `ga4_link_list`, `gsc_sitemaps_list`, `gsc_sitemaps_get`, `gsc_inspect_url`, `gsc_analytics_run`, `gsc_monitor_urls`, `gsc_index_coverage`, `gsc_cannibalization`, `gsc_opportunities`, `gsc_ctr_anomaly`, `gsc_decay`, `gsc_health`, `gsc_traffic_compare`, `ga4_consent_health`, `seo_page_audit`, `seo_audit_batch`, `adsense_accounts_list`, `adsense_report`, `site_growth_brief`, `ga4_traffic_report`, `gsc_url_hygiene`, `gsc_hreflang`, `keyword_volume`, `keyword_serp_snapshot`, `keyword_rank_check`, `dataforseo_balance`, `llm_mentions`, `keyword_gap`, `ranked_keywords`, `keyword_ideas`, `google_trends`, `backlinks_overview`, `link_gap`\n\n**Modifying (Use with caution):**\n- `indexnow_submit` (dry-run by default), `ga4_setup`, `ga4_cleanup`, `ga4_link_create`, `ga4_link_remove`, `gsc_sitemaps_submit`, `gsc_sitemaps_delete`\n\n**Always use dry-run first for modifying operations!**\n\n---\n\n## Tool Documentation\n\n### GA4 Tools\n\n#### `ga4_setup` - Setup GA4/GSC Configuration\n\nCreates conversions, dimensions, metrics, and Search Console configuration from YAML file.\n\n**Input Schema:**\n\n```typescript\n{\n  config_path?: string;  // Path to YAML config file\n  project_name?: string; // Project name (alternative to config_path)\n  all?: boolean;         // Setup all configs in configs/ directory\n  dry_run?: boolean;     // Preview without applying (recommended)\n}\n```\n\n**Example Request:**\n\n```typescript\n{\n  \"config_path\": \"configs/example-site.yaml\",\n  \"dry_run\": true\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"operation\": \"setup\",\n  \"dry_run\": true,\n  \"project\": {\n    \"name\": \"Example Site\",\n    \"property_id\": \"123456789\"\n  },\n  \"results\": {\n    \"ga4\": {\n      \"conversions_created\": 5,\n      \"conversions_skipped\": 2,\n      \"dimensions_created\": 8,\n      \"metrics_created\": 3\n    },\n    \"gsc\": {\n      \"sitemaps_submitted\": 2,\n      \"urls_monitored\": 10\n    }\n  },\n  \"execution_time_ms\": 2345,\n  \"message\": \"Dry-run complete. No changes applied.\"\n}\n```\n\n**Use Cases:**\n- Initial GA4 property setup\n- Deploying analytics to new environment\n- Bulk configuration changes\n\n---\n\n#### `ga4_report` - View Configuration\n\nLists existing conversions, dimensions, and metrics for a GA4 property.\n\n**Input Schema:**\n\n```typescript\n{\n  config_path?: string;  // Path to YAML config\n  project_name?: string; // Project name\n  all?: boolean;         // Report on all configs\n}\n```\n\n**Example Request:**\n\n```typescript\n{\n  \"config_path\": \"configs/example-site.yaml\"\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"operation\": \"report\",\n  \"project\": {\n    \"name\": \"Example Site\",\n    \"property_id\": \"123456789\"\n  },\n  \"report\": {\n    \"conversions\": [\n      {\n        \"name\": \"purchase\",\n        \"counting_method\": \"ONCE_PER_EVENT\",\n        \"status\": \"active\"\n      }\n    ],\n    \"dimensions\": [\n      {\n        \"parameter\": \"user_tier\",\n        \"display_name\": \"User Tier\",\n        \"scope\": \"USER\",\n        \"status\": \"active\"\n      }\n    ],\n    \"metrics\": [\n      {\n        \"parameter\": \"cart_value\",\n        \"display_name\": \"Cart Value\",\n        \"unit\": \"CURRENCY\",\n        \"scope\": \"EVENT\"\n      }\n    ]\n  }\n}\n```\n\n**Use Cases:**\n- Audit existing configuration\n- Verify setup completed successfully\n- Document current state\n\n---\n\n#### `ga4_cleanup` - Remove Unused Resources\n\nArchives unused conversions, dimensions, and metrics to free up quota.\n\n**Input Schema:**\n\n```typescript\n{\n  config_path?: string;     // Path to YAML config\n  project_name?: string;    // Project name\n  all?: boolean;            // Cleanup all configs\n  type?: string;            // \"conversions\" | \"dimensions\" | \"metrics\" | \"all\"\n  dry_run?: boolean;        // Preview deletions (recommended)\n  yes?: boolean;            // Auto-confirm (use with caution)\n}\n```\n\n**Example Request:**\n\n```typescript\n{\n  \"config_path\": \"configs/example-site.yaml\",\n  \"type\": \"all\",\n  \"dry_run\": true\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"operation\": \"cleanup\",\n  \"dry_run\": true,\n  \"items_to_remove\": {\n    \"conversions\": [\"old_event_1\", \"deprecated_conversion\"],\n    \"dimensions\": [\"unused_param\"],\n    \"metrics\": []\n  },\n  \"quota_freed\": {\n    \"conversions\": 2,\n    \"dimensions\": 1,\n    \"metrics\": 0\n  },\n  \"warning\": \"Archived parameters cannot be reused. Consider new names (e.g., user_type_v2).\"\n}\n```\n\n**Important:**\n- Archived dimension/metric parameters are **permanently reserved** (GA4 limitation)\n- Always use `dry_run: true` first\n- Consider using new parameter names instead of archiving\n\n**Use Cases:**\n- Free up quota for new items\n- Remove deprecated tracking\n- Clean up test configurations\n\n---\n\n#### External Service Integration (`ga4_link_list` / `ga4_link_create` / `ga4_link_remove`)\n\nLinking is split into three tools so that read, write, and delete operations\nare distinct (this is required for the Claude connector directory — a single\ntool may not mix safe and unsafe operations). All three dispatch to the same\n`ga4 link` CLI command.\n\n##### `ga4_link_list` - List Links (read-only)\n\nLists existing BigQuery export links and custom Channel Groups. (Search Console\nlinks can't be listed via the GA4 Admin API and are reported as\n`manual_check_required`.)\n\n```typescript\n{\n  project_name: string;     // Required: Project name\n}\n```\n\n**Example Request:**\n\n```typescript\n{\n  \"project_name\": \"example-site\"\n}\n```\n\n##### `ga4_link_create` - Create a Link (modifying)\n\nCreates a BigQuery export link, sets up default Channel Groups, or returns a\nSearch Console setup guide.\n\n```typescript\n{\n  project_name: string;     // Required: Project name\n  service: string;          // Required: \"search-console\" | \"bigquery\" | \"channels\"\n  url?: string;             // Site URL (required for search-console)\n  gcp_project?: string;     // GCP project (required for bigquery)\n  dataset?: string;         // BigQuery dataset (required for bigquery)\n}\n```\n\n**Example Request (Link Search Console):**\n\n```typescript\n{\n  \"project_name\": \"example-site\",\n  \"service\": \"search-console\",\n  \"url\": \"https://example.com\"\n}\n```\n\n##### `ga4_link_remove` - Remove a Link (destructive)\n\nUnlinks an existing BigQuery export or Channel Group. (Search Console links\ncannot be removed via the Admin API.)\n\n```typescript\n{\n  project_name: string;     // Required: Project name\n  service: string;          // Required: \"bigquery\" | \"channels\"\n}\n```\n\n**Example Request:**\n\n```typescript\n{\n  \"project_name\": \"example-site\",\n  \"service\": \"bigquery\"\n}\n```\n\n**Use Cases:**\n- Connect GA4 to Search Console\n- Setup BigQuery export\n- Configure custom channel groups\n\n---\n\n#### `ga4_validate` - Configuration Validation\n\nValidates YAML configuration files against GA4 tier limits and naming rules.\n\n**Input Schema:**\n\n```typescript\n{\n  config_file?: string;  // Path to config file\n  all?: boolean;         // Validate all configs in configs/\n  verbose?: boolean;     // Detailed validation output\n}\n```\n\n**Example Request:**\n\n```typescript\n{\n  \"config_file\": \"configs/example-site.yaml\",\n  \"verbose\": true\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"operation\": \"validate\",\n  \"file\": \"configs/example-site.yaml\",\n  \"validation\": {\n    \"valid\": true,\n    \"errors\": [],\n    \"warnings\": [\n      \"Property tier 'standard' allows max 30 conversions (you have 5)\"\n    ],\n    \"details\": {\n      \"conversions\": 5,\n      \"dimensions\": 8,\n      \"metrics\": 3,\n      \"tier\": \"standard\",\n      \"limits\": {\n        \"conversions\": 30,\n        \"dimensions\": 50,\n        \"metrics\": 50\n      }\n    }\n  }\n}\n```\n\n**Use Cases:**\n- Verify config before setup\n- Check quota usage\n- Identify configuration errors\n\n---\n\n### Google Search Console Tools\n\n#### `gsc_sitemaps_list` - List Sitemaps\n\nLists all sitemaps submitted for a Search Console property.\n\n**Input Schema:**\n\n```typescript\n{\n  site: string;  // Required: \"sc-domain:example.com\" or \"https://example.com/\"\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"operation\": \"sitemaps_list\",\n  \"site\": \"sc-domain:example.com\",\n  \"sitemaps\": [\n    {\n      \"path\": \"https://example.com/sitemap.xml\",\n      \"type\": \"sitemapsIndex\",\n      \"submitted\": \"2024-12-01T10:00:00Z\",\n      \"last_downloaded\": \"2024-12-27T15:30:00Z\",\n      \"is_pending\": false,\n      \"is_sitemaps_index\": true,\n      \"contents\": {\n        \"submitted\": 1500,\n        \"indexed\": 1450\n      }\n    }\n  ],\n  \"total\": 1\n}\n```\n\n---\n\n#### `gsc_sitemaps_submit` - Submit Sitemap\n\nSubmits a new sitemap URL to Search Console for crawling.\n\n**Input Schema:**\n\n```typescript\n{\n  site: string;  // Required: Site URL\n  url: string;   // Required: Sitemap URL\n}\n```\n\n**Example Request:**\n\n```typescript\n{\n  \"site\": \"sc-domain:example.com\",\n  \"url\": \"https://example.com/sitemap.xml\"\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"operation\": \"sitemap_submit\",\n  \"site\": \"sc-domain:example.com\",\n  \"sitemap_url\": \"https://example.com/sitemap.xml\",\n  \"message\": \"Sitemap submitted successfully\"\n}\n```\n\n---\n\n#### `gsc_sitemaps_delete` - Delete Sitemap\n\nRemoves a sitemap from Search Console (does not delete the actual file).\n\n**Input Schema:**\n\n```typescript\n{\n  site: string;  // Required: Site URL\n  url: string;   // Required: Sitemap URL to remove\n}\n```\n\n---\n\n#### `gsc_sitemaps_get` - Get Sitemap Details\n\nRetrieves detailed information about a specific sitemap including errors and content breakdown.\n\n**Input Schema:**\n\n```typescript\n{\n  site: string;  // Required: Site URL\n  url: string;   // Required: Sitemap URL\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"operation\": \"sitemap_get\",\n  \"sitemap\": {\n    \"path\": \"https://example.com/sitemap.xml\",\n    \"type\": \"sitemapsIndex\",\n    \"submitted\": \"2024-12-01T10:00:00Z\",\n    \"last_downloaded\": \"2024-12-27T15:30:00Z\",\n    \"errors\": 0,\n    \"warnings\": 2,\n    \"contents\": {\n      \"web_pages\": {\n        \"submitted\": 1000,\n        \"indexed\": 950\n      },\n      \"images\": {\n        \"submitted\": 500,\n        \"indexed\": 500\n      }\n    }\n  }\n}\n```\n\n---\n\n#### `gsc_inspect_url` - URL Indexing Inspection\n\nInspects a URL's indexing status, mobile usability, rich results, and coverage state.\n\n**Input Schema:**\n\n```typescript\n{\n  site: string;  // Required: \"sc-domain:example.com\" (domain property recommended)\n  url: string;   // Required: Full URL to inspect\n}\n```\n\n**Example Request:**\n\n```typescript\n{\n  \"site\": \"sc-domain:example.com\",\n  \"url\": \"https://example.com/products/widget\"\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"operation\": \"inspect_url\",\n  \"url\": \"https://example.com/products/widget\",\n  \"inspection_result\": {\n    \"index_status\": {\n      \"verdict\": \"PASS\",\n      \"coverage_state\": \"Submitted and indexed\",\n      \"crawled_as\": \"DESKTOP\",\n      \"last_crawl_time\": \"2024-12-27T10:30:00Z\",\n      \"page_fetch_state\": \"SUCCESSFUL\",\n      \"robots_txt_state\": \"ALLOWED\",\n      \"indexing_state\": \"INDEXING_ALLOWED\"\n    },\n    \"mobile_usability\": {\n      \"verdict\": \"PASS\",\n      \"issues\": []\n    },\n    \"rich_results\": {\n      \"verdict\": \"PASS\",\n      \"detected_items\": [\n        {\n          \"type\": \"Product\",\n          \"name\": \"Widget\",\n          \"issues\": []\n        }\n      ]\n    },\n    \"amp\": {\n      \"verdict\": \"NOT_APPLICABLE\"\n    }\n  },\n  \"quota\": {\n    \"used\": 1,\n    \"limit\": 2000,\n    \"remaining\": 1999,\n    \"percentage\": 0.05\n  }\n}\n```\n\n**Rate Limits:**\n- 2,000 inspections per day per property\n- 600 inspections per minute per property\n\n**Use Cases:**\n- Check why page isn't indexed\n- Verify mobile usability\n- Validate rich results markup\n- Monitor critical pages\n\n---\n\n#### `gsc_analytics_run` - Search Analytics Report\n\nQueries Search Console for performance data: queries, pages, impressions, clicks, CTR, and position.\n\n**Input Schema:**\n\n```typescript\n{\n  site?: string;            // Site URL (or from config)\n  config?: string;          // Config file path (alternative)\n  days?: number;            // Period: 1-180 days (default: 30)\n  dimensions?: string;      // Comma-separated: \"query,page,country,device\"\n  limit?: number;           // Max rows: 1-25000 (default: 100)\n  format?: string;          // Output: \"json\" | \"csv\" | \"table\" | \"markdown\"\n  dry_run?: boolean;        // Preview query parameters\n}\n```\n\n**Example Request:**\n\n```typescript\n{\n  \"site\": \"sc-domain:example.com\",\n  \"days\": 30,\n  \"dimensions\": \"query,page\",\n  \"limit\": 50,\n  \"format\": \"json\"\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"operation\": \"gsc_analytics\",\n  \"site_url\": \"sc-domain:example.com\",\n  \"period\": \"2024-11-27 to 2024-12-27\",\n  \"total_rows\": 50,\n  \"aggregates\": {\n    \"total_clicks\": 1250,\n    \"total_impressions\": 15000,\n    \"average_ctr\": 0.0833,\n    \"average_position\": 8.5\n  },\n  \"rows\": [\n    {\n      \"keys\": [\"best analytics tool\", \"https://example.com/\"],\n      \"clicks\": 45,\n      \"impressions\": 500,\n      \"ctr\": 0.09,\n      \"position\": 3.2\n    },\n    {\n      \"keys\": [\"ga4 setup guide\", \"https://example.com/blog/ga4-guide\"],\n      \"clicks\": 38,\n      \"impressions\": 420,\n      \"ctr\": 0.09,\n      \"position\": 4.1\n    }\n  ],\n  \"quota\": {\n    \"used\": 1,\n    \"limit\": 2000,\n    \"remaining\": 1999\n  }\n}\n```\n\n**Available Dimensions:**\n- `query` - Search query\n- `page` - Landing page URL\n- `country` - User country (ISO)\n- `device` - DESKTOP, MOBILE, TABLET\n- `searchAppearance` - How result appeared\n- `date` - Individual dates\n\n**Limits:**\n- Max 3 dimensions per query\n- Data typically 2-3 days behind\n- 25,000 rows maximum\n\n**Use Cases:**\n- Identify top-performing content\n- Find ranking opportunities\n- Track keyword performance\n- Analyze traffic patterns\n\n---\n\n#### `gsc_monitor_urls` - Batch URL Monitoring\n\nMonitors multiple priority URLs for indexing issues using configuration file or direct URL array.\n\n**Input Schema (Config-based):**\n\n```typescript\n{\n  config: string;     // Path to YAML config with priority_urls\n  format?: string;    // \"json\" | \"table\" | \"markdown\"\n  dry_run?: boolean;  // Preview URLs without inspecting\n}\n```\n\n**Input Schema (Direct URLs):**\n\n```typescript\n{\n  site: string;       // Site URL\n  urls: string[];     // Array of URLs to inspect (max 50)\n  dry_run?: boolean;  // Preview without API calls\n}\n```\n\n**Example Request (Direct):**\n\n```typescript\n{\n  \"site\": \"sc-domain:example.com\",\n  \"urls\": [\n    \"https://example.com/\",\n    \"https://example.com/products/\",\n    \"https://example.com/blog/\"\n  ]\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"operation\": \"monitor_urls\",\n  \"site\": \"sc-domain:example.com\",\n  \"summary\": {\n    \"total\": 3,\n    \"indexed\": 3,\n    \"not_indexed\": 0,\n    \"with_issues\": 0\n  },\n  \"results\": [\n    {\n      \"url\": \"https://example.com/\",\n      \"label\": \"Homepage\",\n      \"verdict\": \"PASS\",\n      \"coverage_state\": \"Submitted and indexed\",\n      \"mobile_usability\": \"PASS\",\n      \"last_crawl\": \"2024-12-27T10:00:00Z\",\n      \"issues\": []\n    }\n  ],\n  \"quota\": {\n    \"used\": 3,\n    \"limit\": 2000,\n    \"remaining\": 1997\n  }\n}\n```\n\n**Use Cases:**\n- Monitor critical pages daily\n- Detect indexing issues early\n- Track mobile usability\n- Audit site after deployment\n\n---\n\n#### `gsc_index_coverage` - Index Coverage Report\n\nGenerates index coverage analysis showing indexed, excluded, and error pages based on Search Analytics impressions data.\n\n**Input Schema:**\n\n```typescript\n{\n  site?: string;      // Site URL (or from config)\n  config?: string;    // Config file path\n  days?: number;      // Analysis period: 1-180 (default: 90)\n  limit?: number;     // Sample size: 1-1000 (default: 1000)\n  format?: string;    // \"json\" | \"table\" | \"markdown\"\n}\n```\n\n**Example Request:**\n\n```typescript\n{\n  \"site\": \"sc-domain:example.com\",\n  \"days\": 90,\n  \"limit\": 1000,\n  \"format\": \"json\"\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"operation\": \"index_coverage\",\n  \"site\": \"sc-domain:example.com\",\n  \"period\": \"2024-09-28 to 2024-12-27\",\n  \"analysis\": {\n    \"total_pages\": 1000,\n    \"indexed\": 850,\n    \"low_impressions\": 100,\n    \"no_impressions\": 50\n  },\n  \"classification\": {\n    \"healthy\": 850,\n    \"needs_review\": 100,\n    \"excluded\": 50\n  },\n  \"top_pages\": [\n    {\n      \"url\": \"https://example.com/\",\n      \"impressions\": 5000,\n      \"clicks\": 450,\n      \"status\": \"indexed\"\n    }\n  ],\n  \"recommendations\": [\n    \"50 pages with no impressions may need content improvement or removal\",\n    \"100 pages with low impressions could benefit from SEO optimization\"\n  ]\n}\n```\n\n**How It Works:**\n- Queries Search Analytics for page impressions\n- Classifies pages: ≥10 impressions = indexed, 1-9 = low, 0 = none\n- Samples up to 1,000 pages for performance\n- Estimates overall index health\n\n**Use Cases:**\n- Monitor index health trends\n- Identify indexing issues\n- Track coverage after site updates\n- Estimate indexed page count\n\n### Diagnostics & SEO Tools\n\n#### `gsc_traffic_compare` - Compare GSC Traffic Between Date Ranges\n\nDiffs Google Search Console search analytics between two date ranges per URL to surface the biggest drops and gains.\n\n**Before/after mode:** instead of the two periods, pass `around: { date, window_days?, gap_days? }` (`window_days` 7-90, default 28; `gap_days` 0-14, default 0) to compare the window ending the day before `date` with the window starting at `date + gap_days`. Use a GA4 annotation date as `date` for a SEOTesting-style test. If the after window would end within 3 days of today, both windows are shortened equally with a warning. Add `pages: string[]` (exact URL match after `normalize`) to target the changed pages; with `around` or `pages` the response includes a `before_after` block with total clicks, impressions, CTR and position and their deltas. Passing both `around` and `period_a`/`period_b`, or neither, is an error.\n\n**Input Schema:**\n\n```typescript\n{\n  site: string;                     // Required: \"sc-domain:example.com\" or URL-prefix\n  period_a_start: string;           // Required: ISO date \"YYYY-MM-DD\"\n  period_a_end: string;             // Required: ISO date \"YYYY-MM-DD\"\n  period_b_start: string;           // Required: ISO date \"YYYY-MM-DD\"\n  period_b_end: string;             // Required: ISO date \"YYYY-MM-DD\"\n  fetch_limit?: number;             // Max URLs to fetch per period (default 500)\n  output_limit?: number;            // Max rows in output (default 50)\n  sort_by?: \"clicks\" | \"impressions\" | \"delta\"; // Sort mode (default \"clicks\")\n  min_clicks_a?: number;            // Minimum clicks in period A to include URL\n  url_normalization?: \"none\" | \"minimal\" | \"aggressive\";\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"site\": \"sc-domain:example.com\",\n  \"period_a\": { \"start\": \"2024-12-01\", \"end\": \"2024-12-14\" },\n  \"period_b\": { \"start\": \"2024-11-17\", \"end\": \"2024-11-30\" },\n  \"summary\": { \"urls_analyzed\": 120, \"total_click_delta\": -340 },\n  \"rows\": [\n    {\n      \"url\": \"https://example.com/pricing\",\n      \"clicks_a\": 45, \"clicks_b\": 120,\n      \"delta_clicks\": -75, \"delta_pct\": -62.5\n    }\n  ]\n}\n```\n\n---\n\n#### `ga4_consent_health` - Consent Banner Health Report\n\nReports consent banner grant/deny rates and a composite health score from `consent_granted` / `consent_denied` custom events in GA4.\n\n**Input Schema:**\n\n```typescript\n{\n  property_id: string;  // Required: GA4 property ID (e.g. \"123456789\")\n  days?: number;        // Lookback window in days (default 30)\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"property_id\": \"123456789\",\n  \"period_days\": 30,\n  \"consent_rate_pct\": 72.4,\n  \"consent_visibility_pct\": 89.1,\n  \"health_score\": 64.5,\n  \"granted\": 14821,\n  \"denied\": 5641,\n  \"note\": \"Uses consent_granted/consent_denied custom events. Requires Consent Mode v2 event instrumentation.\"\n}\n```\n\n---\n\n#### `seo_page_audit` - On-Page SEO Audit\n\nSingle-URL on-page SEO audit: title/description length and pixel-width checks, canonical severity escalation, JSON-LD extraction, redirect chain tracing, robots.txt respect, and optional Core Web Vitals via PageSpeed Insights.\n\n**Input Schema:**\n\n```typescript\n{\n  url: string;                    // Required: page URL to audit\n  include_cwv?: boolean;          // Include Core Web Vitals via PSI (default false)\n  psi_api_key?: string;           // PageSpeed Insights API key (required for CWV)\n  strategy?: \"mobile\" | \"desktop\"; // PSI strategy (default \"mobile\")\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"url\": \"https://example.com/pricing\",\n  \"issues\": [\n    { \"type\": \"title_too_long\", \"severity\": \"warning\", \"value\": \"62 chars / 498px\" },\n    { \"type\": \"canonical_mismatch\", \"severity\": \"error\", \"canonical\": \"https://example.com/pricing/\" }\n  ],\n  \"meta\": {\n    \"title\": \"Pricing - Example\",\n    \"description\": \"Choose the right plan.\",\n    \"canonical\": \"https://example.com/pricing/\"\n  },\n  \"redirects\": [],\n  \"schema_types\": [\"Product\", \"BreadcrumbList\"]\n}\n```\n\n---\n\n### AdSense Tools\n\nPublisher-side reporting via the [AdSense Management API v2](https://developers.google.com/adsense/management/reference/rest). These tools answer \"how much do the ads **on my own site** earn\" — the opposite of the advertiser-side Google Ads API. They are **read-only** and need **no developer token or Manager account**: just the `adsense.readonly` OAuth scope on the same credentials used for GA4/GSC (see [PERMISSIONS.md](PERMISSIONS.md)).\n\n> **Scope:** Add `https://www.googleapis.com/auth/adsense.readonly` to your credential. For an ADC user credential, re-run `gcloud auth application-default login --scopes=...,https://www.googleapis.com/auth/adsense.readonly`. Note: a personal AdSense account cannot be read with a service-account key — use ADC user credentials.\n\n#### `adsense_accounts_list` - List AdSense Accounts\n\nLists the AdSense publisher accounts the authenticated identity can access. Call this first — the returned `name` (`accounts/pub-XXXXXXXXXXXXXXXX`) is the `account` argument every other AdSense tool needs. No parameters.\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"accounts\": [\n    { \"name\": \"accounts/pub-1234567890123456\", \"displayName\": \"example.com\", \"state\": \"READY\", \"timeZone\": { \"id\": \"America/Los_Angeles\" } }\n  ]\n}\n```\n\n#### `adsense_report` - Generate AdSense Report\n\nGenerates an earnings report for one account, returning each row as a `header → value` map plus totals.\n\n**Input Schema:**\n\n```typescript\n{\n  account: string;        // Required: \"accounts/pub-...\" from adsense_accounts_list\n  date_range?:            // Preset window (default \"LAST_7_DAYS\")\n    | \"CUSTOM\" | \"TODAY\" | \"YESTERDAY\" | \"MONTH_TO_DATE\" | \"YEAR_TO_DATE\"\n    | \"LAST_7_DAYS\" | \"LAST_30_DAYS\";\n                          // Anything longer (e.g. last 3 months): use \"CUSTOM\".\n                          // The AdSense API rejects LAST_MONTH / LAST_3_MONTHS /\n                          // LAST_6_MONTHS / LAST_12_MONTHS / LAST_YEAR.\n  start_date?: string;    // YYYY-MM-DD, required when date_range = \"CUSTOM\"\n  end_date?: string;      // YYYY-MM-DD, required when date_range = \"CUSTOM\"\n  metrics?: string[];     // default ESTIMATED_EARNINGS, PAGE_VIEWS, IMPRESSIONS, CLICKS, IMPRESSIONS_RPM\n  dimensions?: string[];  // default [\"DATE\"]; e.g. DOMAIN_NAME, COUNTRY_NAME, AD_UNIT_NAME\n  order_by?: string[];    // sort before limit; requested metric/dimension, \"-\" = desc,\n                          // e.g. [\"-ESTIMATED_EARNINGS\"] for top earners first\n  currency_code?: string; // ISO-4217, e.g. \"USD\" (defaults to account currency)\n  limit?: number;         // max rows (default 100, max 1000)\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"success\": true,\n  \"account\": \"accounts/pub-1234567890123456\",\n  \"date_range\": \"LAST_7_DAYS\",\n  \"start_date\": \"2026-06-19\",\n  \"end_date\": \"2026-06-25\",\n  \"headers\": [\"DATE\", \"ESTIMATED_EARNINGS\", \"PAGE_VIEWS\", \"IMPRESSIONS\", \"CLICKS\", \"IMPRESSIONS_RPM\"],\n  \"rows\": [\n    { \"DATE\": \"2026-06-19\", \"ESTIMATED_EARNINGS\": \"1.23\", \"PAGE_VIEWS\": \"842\", \"IMPRESSIONS\": \"910\", \"CLICKS\": \"7\", \"IMPRESSIONS_RPM\": \"1.35\" }\n  ],\n  \"totals\": { \"ESTIMATED_EARNINGS\": \"9.81\", \"PAGE_VIEWS\": \"5894\" },\n  \"warnings\": []\n}\n```\n\n### Growth, Traffic & Index-Quality Tools\n\n#### `site_growth_brief` - Per-Site Growth Brief\n\nThe starting point for an SEO or monetization plan. For one config (or every `configs/*.yaml` with `all: true`, examples excluded) it joins Search Console, GA4 traffic and AdSense-in-GA4 revenue into a compact brief (≤ ~4 KB per site):\n\n- `kpis` — GSC clicks, impressions, CTR, position; GA4 sessions, engagement rate; ad revenue and revenue per 1k sessions\n- `deltas` — % change vs the preceding window of the same length\n- `top_pages` — up to 10 pages joined on path (GSC clicks/impressions, sessions, ad revenue), ranked by revenue then clicks\n- `findings` — top 10 from page-level opportunities, CTR anomalies, URL-hygiene warnings and (when `hreflang_pairs` are configured) hreflang warnings, ranked by estimated clicks at stake\n- `data_gaps` — sources that were not configured or failed; the brief still returns the rest\n\n```typescript\n{ config?: string; all?: boolean; days?: number /* 7–240, default 28 */ }\n```\n\nRevenue is GA4-attributed (`totalAdRevenue`), so it needs AdSense linked to the GA4 property; use `adsense_report` for payout figures. The brief never calls URL Inspection or the AdSense API.\n\n#### `ga4_traffic_report` - GA4 Traffic & Ad Revenue\n\nGA4 Data API report by up to two of `pagePath`, `landingPage`, `sessionDefaultChannelGroup`, `sessionSource`, `country`, `deviceCategory`, `date`. Every row carries `sessions`, `engaged_sessions`, `engagement_rate`, `average_session_duration_s`, `page_views`, `ad_revenue`, `ad_impressions`, `ad_clicks` and `revenue_per_1k_sessions`, plus `totals`. The warning `ad_revenue_unavailable` means no AdSense impressions were attributed (not linked, or no ads served).\n\n```typescript\n{\n  property_id?: string;   // \"123456789\" or \"properties/123456789\"\n  config?: string;        // alternative: uses the config's ga4.property_id\n  days?: number;          // 1–365, default 28, ending yesterday\n  dimensions?: string[];  // default [\"pagePath\"]\n  order_by?: \"sessions\" | \"page_views\" | \"ad_revenue\" | \"engagement_rate\"; // desc, default sessions\n  limit?: number;         // 1–1000, default 50\n}\n```\n\n#### `gsc_opportunities` with `granularity: \"page\"`\n\nPage mode ranks whole pages instead of query × page rows. It catches high-impression pages whose traffic is spread over anonymized long-tail queries, where no single query looks like an opportunity. The expected CTR is the higher of the bucket's site median (≥3 peer pages above `min_impressions`) and the industry baseline, so weak neighbours never excuse a page. Each result adds `top_queries` (up to 5) and `anonymized_share` (0–1). Costs 2 Search Analytics calls.\n\n#### `gsc_url_hygiene` - Index-Polluting URLs\n\nClassifies every URL with impressions (default 90 days) into at most one of `malformed_path`, `fragment`, `asset_route`, `query_duplicate`, `utility_page` (info). Each result has a one-line `fix`. Exit 2 / `results` non-empty on any warning.\n\n#### `gsc_hreflang` - hreflang Integrity & Cross-Language Ranking\n\nUses `search_console.hreflang_pairs` from the config, or discovers pairs by fetching the top `max_pages` pages (default 50) and reading their `<link rel=\"alternate\" hreflang>` tags. Reports `missing_return_link`, `missing_self_reference`, `wrong_target`, `missing_x_default` (info), and `cross_language_ranking` (a query in one pair language getting ≥ `min_impressions` on the other language's page). Fetches only the configured site's host, as `ga4-manager/<version>`, max 4 at a time.\n\n```yaml\nsearch_console:\n  site_url: \"sc-domain:example.com\"\n  hreflang_pairs:\n    - en: \"https://www.example.com/calculator\"\n      es: \"https://www.example.com/es/calculadora\"\n```\n\n---\n\n### Paid lookups: estimates, cache and research log\n\nEvery OpenSEO-parity tool that spends DataForSEO credit takes three inputs:\n\n- **`estimate_only`** returns the cost estimate and the balance, and spends nothing. Prices come from DataForSEO's own price list (`appendix/user_data`, free). SERP depth is billed per 10 results.\n- **`max_cost_usd`** makes the tool refuse when the estimate is higher. The tool also refuses when the balance is lower than the estimate.\n- **`refresh_cache`** skips the lookup cache.\n\nTwo more layers apply on top:\n\n- **Lookup cache.** Paid responses are cached per site and parameters under `.ga4-state/cache/`: SERPs for 6 h, AI answers for 7 days, everything else for 24 h. Results say when they came from cache (`cache.hits`). `GA4M_CACHE=off` disables it; `GA4M_CACHE_TTL_HOURS` overrides the TTLs.\n- **Research log.** Every billed request is appended to the site's project context (`research_log`). `project_context_get` returns a de-duplicated `recent_lookups` list for the next agent.\n\nThe per-session caps (`GA4M_MAX_SPEND_USD`, `GA4M_MAX_PAID_CALLS`) still apply.\n\n### Site crawl audit\n\n`site_audit_run` starts a background crawl and returns an `audit_id` at once. Poll `site_audit_status`, then read `site_audit_issues`, `site_audit_pages` and `site_audit_lighthouse`.\n\n- **Scope.** Same-origin from `start_url` (the start redirect's host counts too), seeded from the sitemaps.\n- **Limits.** `max_pages` (default 200), `max_duration_s` (default 900), `exclude_paths` with robots-style patterns (`/tag/`, `/*?sort=`, `/*.pdf$`), and `concurrency` / `delay_ms`.\n- **robots.txt.** It is honoured, Crawl-delay included. Blocked URLs are recorded as `blocked_robots`.\n- **Rate limits.** HTTP 429 backs off (Retry-After) and slows the crawl. URLs still throttled are `rate_limited`, never \"broken\".\n- **JS rendering.** `render_js` uses Cloudflare Browser Rendering.\n- **Issues.** Each issue has a severity and a `how_to_fix`:\n  - broken internal links, unreachable pages, orphan pages, no outgoing links, deep pages;\n  - redirect chains, redirect loops, internal links to redirects;\n  - duplicate titles, descriptions and content, thin content;\n  - heading-order skips, missing or multiple H1, images without alt, slow responses;\n  - canonical conflicts, canonicalised pages, noindex pages, title and description length;\n  - blocked and rate-limited notices, and the crawl page-limit and time-limit notices.\n- **Lighthouse.** `lighthouse: true`, or `site_audit_lighthouse {run: true}` later, runs PageSpeed Insights on up to 10 representative pages, mobile and desktop. It returns scores, lab LCP/CLS/TBT/TTFB, field LCP/CLS/INP/TTFB, and the top savings with resources.\n- **Storage.** Results are stored per audit under `.ga4-state/site-audits/`.\n- **Proxies.** Behind an HTTP proxy, set `NODE_USE_ENV_PROXY=1` (Node's fetch ignores `HTTPS_PROXY` otherwise).\n\n### page_opportunities\n\nJoins Search Console pages in a position band with GA4 Organic Search landing pages over the same calendar window, ending at `data_through`. Each page gets a score:\n\n```\nscore = round(100 × (0.5 demand + 0.3 business_value + 0.2 reachability))\n```\n\n- **demand:** log-scaled impressions relative to the largest candidate.\n- **business_value:** session key-event rate (engagement rate when the property has no key events), smoothed toward the site average with a 10-session prior.\n- **reachability:** 1 at `min_position`, 0 at `max_position`.\n\nPages with no GA4 match stay in the list with `score: null`. `coverage` reports rows considered, matched and unmatched. Warnings cover: no organic landing pages, time zones that differ (with the hour offset), several GSC hosts, and the row limit being hit.\n\n### gsc_change_impact\n\nFor each change ({url | prefix | whole site, changed_on, label}), or each GA4 annotation with `from_annotations: true`, it compares equal windows before and after the change day. The change day is skipped, and the after window ends at `data_through`. It returns clicks, impressions, CTR, impression-weighted position, deltas, `days_per_window`, and a verdict:\n\n- `too_early`: fewer than 7 days after the change, or fewer than 100 impressions.\n- Otherwise, clicks ±10% decide first, then position ±1: `improved`, `worse` or `flat`.\n\nThe thresholds are returned with every result.\n\n### data_through and position filters\n\nEvery Search Console performance tool returns `data_through`: the last date Search Console has final data for. `gsc_analytics_run` accepts `min_position`, `max_position` and `min_impressions`. These are applied over the fetched top rows (GSC cannot filter by position), and `row_filter` reports rows considered vs kept.\n\n### GA4 organic reports\n\nOrganic Search means `sessionDefaultChannelGroup` \"Organic Search\". All eight tools take `property_id` or `config` plus `days` (default 28, ending yesterday). They return an absolute `window`, and `warnings` that explain empty results.\n\n- `ga4_organic_overview`: KPIs vs the previous equal window, organic share of sessions, and a day/week trend.\n- `ga4_organic_landing_pages`: sessions, engagement, key events, key event rate and revenue per landing page.\n- `ga4_key_events`: key events by name (and landing page).\n- `ga4_traffic_acquisition`: all channels, and source/medium.\n- `ga4_audience`: country, device, or new vs returning.\n- `ga4_site_search`: internal search terms.\n- `ga4_ecommerce`: purchases, revenue and the item funnel.\n- `ga4_measurement_health`: pass/warn/fail checks with `how_to_fix` for organic sessions, key events, consent, freshness, \"(not set)\", site search and time zone vs Search Console.\n\n### Keyword workspace and competitors\n\n- `keywords_save` / `keywords_list` / `keywords_remove`: saved, tagged keyword lists per site, with optional stored metrics so bought data is reused.\n- `keyword_suggestions`: Search Console queries at positions 4–30 not saved yet (free), plus optional `keywords_for_site` (paid).\n- `serp_competitors`: the domains ranking most across a keyword set or tag. It marks your site and known competitors.\n- `domain_overview`: estimated organic traffic, keyword counts by position band, and top pages.\n- `serp_locations`: free location and language code lookup.\n\n### Rank tracker\n\nPersistent keyword sets per site, market (location, language) and device, with pinned keywords.\n\n- `rank_tracker_estimate` is free. `rank_tracker_run` (paid, gated) makes one live Google SERP request per keyword. It stores the position, ranking URL, SERP features, AI Overview citation and top competitors, and reports the change vs the previous run.\n- `rank_tracker_history` returns positions over time.\n- Scheduling stays in cron:\n\n```bash\nga4m rank-tracker-run --site example.com --tracker-id <id>\n```\n\n### AI visibility (DataForSEO)\n\nWorkflow:\n\n1. Fill project context.\n2. Draft prompts with `ai_visibility_prompts_generate` (free), or research real questions with `ai_visibility_research` (paid).\n3. Save the prompt set with `ai_visibility_tracker_save`.\n4. Check the cost with `ai_visibility_estimate`.\n5. Run it with `ai_visibility_run`.\n6. Read `ai_visibility_results`, `ai_visibility_trend`, `ai_visibility_sources`, `ai_visibility_answer` and `ai_visibility_export`.\n\n`ai_visibility_explore` runs one prompt across models without saving it.\n\n| Engine id | What it queries | Approx. cost per prompt |\n|-----------|-----------------|-------------------------|\n| `chatgpt` | ChatGPT web UI with search (LLM Scraper) | $0.004 |\n| `gemini` | Gemini web UI (LLM Scraper) | $0.004 |\n| `google_ai_overview` | Google AI Overview (SERP, async AIO) | $0.004 |\n| `google_ai_mode` | Google AI Mode | $0.004 |\n| `claude` | Claude API with web search | ~$0.012 |\n| `perplexity` | Perplexity API (sonar) | ~$0.006 |\n| `chatgpt_api` | OpenAI API with web search | ~$0.021 |\n| `gemini_api` | Gemini API with web search | ~$0.033 |\n\nThe default engines are `chatgpt`, `google_ai_overview` and `google_ai_mode`. Answers are cached for 7 days per site.\n\n### Saved reports\n\n`report_save` turns any tool output into one self-contained HTML file per site: inline CSS, no scripts or remote resources, light/dark, phone-friendly. Untrusted text from crawled pages and AI answers is always HTML-escaped.\n\n- Input: `site`, `title`, and one of `sections`, `tool_output`, or `template` + `section_data`.\n- `report_get` returns `meta`, `path` or the `html`. To share a report, send the file or have the assistant publish the HTML; nothing is uploaded.\n- Templates: `report_template_save`, `report_template_list` and `report_template_delete`, global or per site. The built-in `monthly_seo_checkin` is what the `monthly_report` prompt fills.\n\n### Workflow prompts\n\n`prompts/list` includes eight workflows that chain the tools above: `project_setup`, `seo_audit`, `keyword_research`, `keyword_clustering`, `competitor_analysis`, `competitive_landscape`, `ai_visibility_audit` and `monthly_report`. Every paid workflow reads the research log before buying, checks the balance, and runs each paid step as an estimate first.\n\n## Configuration Files\n\n### YAML Config Structure\n\nAll tools support YAML configuration files for project settings:\n\n```yaml\nproject:\n  name: Example Site\n  description: Production analytics configuration\n  version: 1.0.0\n\n# GA4 Configuration\nga4:\n  property_id: \"123456789\"\n  tier: standard  # or \"360\"\n\nconversions:\n  - name: purchase\n    counting_method: ONCE_PER_EVENT\n    description: User completed purchase\n\n  - name: signup\n    counting_method: ONCE_PER_SESSION\n    description: User created account\n\ndimensions:\n  - parameter: user_tier\n    display_name: User Tier\n    description: User subscription level\n    scope: USER\n\n  - parameter: product_category\n    display_name: Product Category\n    scope: EVENT\n\nmetrics:\n  - parameter: cart_value\n    display_name: Cart Value\n    description: Total cart value\n    unit: CURRENCY\n    scope: EVENT\n\n# Search Console Configuration\nsearch_console:\n  site_url: \"https://example.com\"\n\nsitemaps:\n  - url: \"https://example.com/sitemap.xml\"\n    priority: true\n\nmonitoring:\n  priority_urls:\n    - url: \"https://example.com/\"\n      label: \"Homepage\"\n    - url: \"https://example.com/products/\"\n      label: \"Products Landing Page\"\n```\n\n### Example Templates\n\nReady-to-use templates in `examples/`:\n- **`minimal.yaml`** - Basic setup for learning\n- **`blog.yaml`** - Content sites (5 conversions, 5 dimensions, 3 metrics)\n- **`ecommerce.yaml`** - Online stores (7 conversions, 6 dimensions, 4 metrics)\n- **`saas.yaml`** - Web applications (6 conversions, 5 dimensions, 3 metrics)\n\nSee [`examples/README.md`](./examples/README.md) for template documentation.\n\n---\n\n## Usage Workflows\n\n### Initial Setup Workflow\n\n```typescript\n// 1. Validate configuration\nawait ga4_validate({\n  config_file: \"configs/example-site.yaml\",\n  verbose: true\n});\n\n// 2. Preview setup (dry-run)\nawait ga4_setup({\n  config_path: \"configs/example-site.yaml\",\n  dry_run: true\n});\n\n// 3. Review output, then apply\nawait ga4_setup({\n  config_path: \"configs/example-site.yaml\",\n  dry_run: false\n});\n\n// 4. Verify with report\nawait ga4_report({\n  config_path: \"configs/example-site.yaml\"\n});\n\n// 5. Submit sitemaps\nawait gsc_sitemaps_submit({\n  site: \"sc-domain:example.com\",\n  url: \"https://example.com/sitemap.xml\"\n});\n```\n\n### Analytics Analysis Workflow\n\n```typescript\n// 1. Check index coverage\nconst coverage = await gsc_index_coverage({\n  site: \"sc-domain:example.com\",\n  days: 90,\n  limit: 1000\n});\n\n// 2. Get search performance\nconst analytics = await gsc_analytics_run({\n  site: \"sc-domain:example.com\",\n  days: 30,\n  dimensions: \"query,page\",\n  limit: 100\n});\n\n// 3. Inspect top pages\nfor (const page of analytics.rows.slice(0, 5)) {\n  await gsc_inspect_url({\n    site: \"sc-domain:example.com\",\n    url: page.keys[1]  // page URL\n  });\n}\n```\n\n### Monitoring Workflow\n\n```typescript\n// 1. Monitor critical URLs\nconst monitoring = await gsc_monitor_urls({\n  site: \"sc-domain:example.com\",\n  urls: [\n    \"https://example.com/\",\n    \"https://example.com/products/\",\n    \"https://example.com/blog/\"\n  ]\n});\n\n// 2. If issues found, inspect details\nif (monitoring.summary.with_issues > 0) {\n  for (const result of monitoring.results) {\n    if (result.issues.length > 0) {\n      console.log(`Issues on ${result.url}:`, result.issues);\n    }\n  }\n}\n```\n\n---\n\n## Best Practices for AI Assistants\n\n### 1. Always Use Dry-Run First\n\nBefore any modifying operation (setup, cleanup, delete), preview changes:\n\n```typescript\n// ❌ DON'T do this first\nawait ga4_setup({ config_path: \"config.yaml\" });\n\n// ✅ DO this instead\nawait ga4_setup({ config_path: \"config.yaml\", dry_run: true });\n// Review output, then apply:\nawait ga4_setup({ config_path: \"config.yaml\", dry_run: false });\n```\n\n### 2. Validate Configurations\n\nAlways validate before setup:\n\n```typescript\nawait ga4_validate({ config_file: \"config.yaml\", verbose: true });\n```\n\n### 3. Monitor Quota Usage\n\nCheck `quota.remaining` in responses:\n\n```typescript\nconst result = await gsc_inspect_url({ ... });\nif (result.quota.remaining < 100) {\n  console.warn(\"Low GSC quota remaining:\", result.quota.remaining);\n}\n```\n\n### 4. Use Specific Dimensions\n\nRequest only needed dimensions to reduce response size:\n\n```typescript\n// ✅ Good - specific dimensions\nawait gsc_analytics_run({\n  dimensions: \"query,page\",\n  limit: 50\n});\n\n// ❌ Avoid - too many dimensions\nawait gsc_analytics_run({\n  dimensions: \"query,page,country,device,date\",\n  limit: 25000  // Also too many rows\n});\n```\n\n### 5. Handle Errors Gracefully\n\nAll errors include actionable suggestions:\n\n```typescript\ntry {\n  await ga4_setup({ config_path: \"config.yaml\" });\n} catch (error) {\n  console.error(error.code);        // e.g., \"AUTH_ERROR\"\n  console.error(error.message);     // Human-readable message\n  console.error(error.suggestion);  // How to fix\n}\n```\n\n### 6. Provide Context to Users\n\nWhen presenting results, explain what the data means:\n\n```typescript\nconst analytics = await gsc_analytics_run({ ... });\n\n// ❌ Don't just dump raw data\nconsole.log(analytics);\n\n// ✅ Explain the insights\nconsole.log(`Top query: \"${analytics.rows[0].keys[0]}\" with ${analytics.rows[0].clicks} clicks`);\nconsole.log(`Average CTR: ${(analytics.aggregates.average_ctr * 100).toFixed(2)}%`);\n```\n\n---\n\n## Error Handling\n\n### Error Response Structure\n\nAll errors follow this format:\n\n```json\n{\n  \"code\": \"AUTH_ERROR\",\n  \"message\": \"Missing Google credentials\",\n  \"details\": {\n    \"suggestion\": \"Set GOOGLE_APPLICATION_CREDENTIALS environment variable\",\n    \"stderr\": \"Error: could not find credentials file\",\n    \"exit_code\": 1\n  }\n}\n```\n\n### Common Error Codes\n\n| Code | Meaning | Solution |\n|------|---------|----------|\n| `AUTH_ERROR` | Missing/invalid credentials | Set `GOOGLE_APPLICATION_CREDENTIALS` |\n| `VALIDATION_ERROR` | Invalid input parameters | Check parameter types and values |\n| `API_ERROR` | Google API error | Check quota, permissions, property ID |\n| `CLI_EXECUTION_FAILED` | CLI command failed | Check `GA4_BINARY_PATH`, build binary |\n| `TIMEOUT` | Operation timed out | Increase timeout, check network |\n| `FILE_NOT_FOUND` | Config file missing | Verify file path is absolute |\n\n### Quota Errors\n\nSearch Console has strict quotas:\n\n```json\n{\n  \"code\": \"API_ERROR\",\n  \"message\": \"GSC quota exceeded\",\n  \"details\": {\n    \"quota\": {\n      \"used\": 2000,\n      \"limit\": 2000,\n      \"remaining\": 0\n    },\n    \"suggestion\": \"Wait 24 hours for quota reset\"\n  }\n}\n```\n\n---\n\n## Rate Limits\n\n### Google Search Console\n- **Daily limit:** 2,000 queries per site\n- **Per-minute limit:** 600 queries per site\n- **Shared across:** All GSC operations (inspect, analytics, sitemaps, coverage)\n\n### Google Analytics 4 Admin API\n- **Requests:** 50 per second per project\n- **No daily limit** (but stay within reasonable use)\n\n### MCP Server\n- No built-in rate limiting (relies on CLI rate limiting)\n- CLI has configurable rate limiter (default: 10 RPS)\n\n---\n\n## Development\n\n### Build\n\n```bash\nnpm run build        # Compile TypeScript to dist/\nnpm run dev          # Run with tsx (no compile)\n```\n\n### Testing\n\n```bash\nnpm test             # Run all tests\nnpm run test:watch   # Watch mode\nnpm run test:run     # Single run (CI)\n```\n\n### Linting\n\n```bash\nnpm run lint         # ESLint check\n```\n\n### Architecture\n\n```\nmcp/\n├── src/\n│   ├── index.ts              # MCP server entry\n│   ├── cli/\n│   │   ├── executor.ts       # Subprocess execution\n│   │   └── parser.ts         # Output parsing\n│   ├── tools/                # 16 tool implementations\n│   │   ├── ga4-setup.ts\n│   │   ├── ga4-report.ts\n│   │   ├── ga4-cleanup.ts\n│   │   ├── ga4-link.ts\n│   │   ├── ga4-validate.ts\n│   │   ├── gsc-sitemaps.ts   # 4 sitemap tools\n│   │   ├── gsc-inspect.ts\n│   │   ├── gsc-analytics.ts\n│   │   ├── gsc-monitor.ts\n│   │   └── gsc-coverage.ts\n│   ├── utils/\n│   │   ├── ansi-strip.ts     # Terminal color removal\n│   │   └── errors.ts         # Error mapping\n│   └── types/\n│       ├── cli.ts            # CLI response types\n│       └── mcp.ts            # MCP schemas\n└── tests/                     # comprehensive tests\n```\n\n---\n\n## Troubleshooting\n\n### Server Not Connecting\n\n**Symptom:** Claude Desktop doesn't show ga4-manager\n\n**Solution:**\n1. Verify `node` in PATH: `which node`\n2. Check config uses absolute paths (not relative)\n3. Test manually: `node /path/to/mcp/dist/index.js`\n4. Check Claude Desktop logs for errors\n\n### Binary Not Found\n\n**Symptom:** `Error: spawn ga4 ENOENT`\n\n**Solution:**\n1. Set `GA4_BINARY_PATH` environment variable\n2. Build binary: `cd .. && make build`\n3. Verify: `ls -la /path/to/ga4`\n\n### Authentication Errors\n\n**Symptom:** `Missing Google credentials`\n\n**Solution:**\n1. Set `GOOGLE_APPLICATION_CREDENTIALS` in MCP config\n2. Verify file exists: `ls -la /path/to/credentials.json`\n3. Check credentials have required OAuth scopes:\n   - `https://www.googleapis.com/auth/analytics.edit`\n   - `https://www.googleapis.com/auth/analytics.readonly`\n   - `https://www.googleapis.com/auth/webmasters`\n\n### Quota Exceeded\n\n**Symptom:** `GSC quota exceeded`\n\n**Solution:**\n- GSC daily limit: 2,000 queries\n- Wait 24 hours for reset\n- Monitor `quota.remaining` in responses\n- Use `dry_run: true` for testing\n\n---\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `GOOGLE_APPLICATION_CREDENTIALS` | Yes | Path to service account JSON |\n| `GOOGLE_CLOUD_PROJECT` | Yes | GCP project ID |\n| `GA4_BINARY_PATH` | Yes | Path to ga4 binary |\n| `GA4_DEFAULT_PROPERTY_ID` | No | Default property ID (optional) |\n| `GSC_DEFAULT_SITE` | No | Default GSC site URL (optional) |\n\n---\n\n## Additional Documentation\n\n- **[CONFIGURATION.md](./CONFIGURATION.md)** - Multi-client setup guides\n- **[CLOUD.md](./CLOUD.md)** - Claude Code cloud sessions: setup script, credentials, network\n- **[CHANGELOG.md](./CHANGELOG.md)** - Version history\n- **[examples/README.md](./examples/README.md)** - Template documentation\n- **[../CLAUDE.md](../CLAUDE.md)** - CLI documentation for Claude Code\n- **[../README.md](../README.md)** - Main project README\n\n---\n\n## Support\n\n- **Issues:** [GitHub Issues](https://github.com/garbarok/ga4-manager/issues)\n- **Discussions:** [GitHub Discussions](https://github.com/garbarok/ga4-manager/discussions)\n- **Security:** See [SECURITY.md](../SECURITY.md) for vulnerability reporting\n\n---\n\n## License\n\nMIT - See [LICENSE](../LICENSE) for details\n\n---\n\n## Version History\n\nSee [CHANGELOG.md](./CHANGELOG.md) for complete version history and release notes.\n\n**Current Version:** 2.2.0\n\n---\n\n<p align=\"center\">\n  Built with <a href=\"https://modelcontextprotocol.io\">Model Context Protocol</a><br/>\n  Powered by <a href=\"https://github.com/modelcontextprotocol/typescript-sdk\">MCP TypeScript SDK</a>\n</p>\n","readmeFilename":"README.md"}