Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AgricIDaniel/claude-seo/llms.txt

Use this file to discover all available pages before exploring further.

v2.0.0 is the largest release in Claude SEO’s history. Six build phases add a shared headless renderer, QRG-aligned content quality gates, deep Core Web Vitals analysis, four new schema generators, five new MCP extensions, and a full suite of local, international, and privacy improvements. The migration is designed to be low-friction: every v1.x command still works unchanged, and the two breaking changes are narrow security fixes with clear remediation paths.
Before upgrading, read the two breaking changes below. Both involve security fixes that intentionally change existing behaviour. Sites generating retired Schema.org types will see new Critical findings after upgrade. Scripts that relied on the old backlinks_auth.py unsafe fallback will fail at import time.

​
Breaking Changes

In v1.x, backlinks_auth.py allowed a silent unsafe fallback when url_safety.py could not be imported. That fallback ran without any IP-range checks, meaning private-IP fetches were silently allowed. In v2, importing backlinks_auth.validate_url raises RuntimeError at import time if scripts/url_safety.py cannot be loaded: 
# v1.x — silently uses unsafe fallback
from backlinks_auth import validate_url  # ran with SSRF protection disabled
                                          # if url_safety not importable

# v2.x — hard failure instead
from backlinks_auth import validate_url  # raises RuntimeError if
                                          # url_safety can't be imported
Action: Ensure scripts/url_safety.py is present in your installation. Re-running install.sh resolves this. If you have custom scripts that import from backlinks_auth.py, verify they run in an environment where the full scripts/ directory is available.

​
2. seo-schema flags retired Schema.org types as Critical

v2 adds schema-deprecation awareness aligned with Google’s 2024–2025 retirement wave. If your site’s <script type="application/ld+json"> blocks include any of these types, the seo-schema skill will emit a Critical finding:
  • ClaimReview
  • VehicleListing
  • EstimatedSalary
  • LearningVideo
  • SpecialAnnouncement
  • CourseInfo (carousel variant)
Action: Consult skills/seo-schema/references/deprecated-types-2024-2026.md for the recommended replacement per type. If you need to keep the markup for non-Google purposes (e.g., a third-party aggregator reads it), you can suppress the finding by removing that type from the deprecated list in the local seo-schema skill file and documenting the reason.

​
What’s New in v2

v2.0.0 shipped six build phases plus two additional phases (G: multi-platform portability, H: release signing) that are fully additive with no configuration required.
1

Phase A — Headless Rendering Everywhere

The single largest architectural change in v2. A shared scripts/render_page.py backed by Playwright Chromium replaces per-skill ad-hoc fetching. Every audit subagent now uses it via --render auto, which auto-detects SPA hallmarks (empty <div id="root"> shell, single bundle script, hydration markers) and switches to rendered fetching only when needed.Content extraction: trafilatura removes boilerplate and extracts the article body accurately on both static and rendered pages.Date extraction: htmldate extracts publication and modification dates for freshness signals, with multiple fallback strategies (meta tags, JSON-LD, visible date patterns, HTTP headers).Rendering flags:
  • --render auto — default; SPA detection + conditional rendering
  • --render always — force Playwright on every page
  • --render never — raw HTML only, no Playwright dependency
Known edge cases: Pages with scroll-bound hydration, post-interaction content fetches, or race-condition-prone third-party widget mounts may still produce noisy findings. The recommended workflow for these is to run the seo-visual subagent separately and compare its Playwright snapshot against the raw-HTML subagent findings.
2

Phase B — QRG-Aligned Content Quality Gates

Five new scripts add deep content quality analysis keyed directly to the September 2025 Quality Rater Guidelines.
ScriptWhat it does
scripts/content_quality.pyQRG-aligned filler detector, AI-pattern scorer, and information-density analyser
scripts/content_humanize.py40+ deterministic AI-phrasing replacements keyed to QRG §4.6.5 and §4.6.6
scripts/content_verify.pyClaim extraction and citation-gap detection
scripts/domain_history.pyWHOIS-driven expired-domain heritage check
scripts/seo_updates.pyPrimary-source Google updates changelog query tool
A companion data file, data/google-updates.json, ships with 18 confirmed Google algorithm updates from 2024-03 through 2025-12 so seo_updates.py can answer “was there a Google update near my traffic drop?” without a live API call.
3

Phase C — Technical and CWV Depth

Four new scripts extend the technical and Core Web Vitals analysis surface.
ScriptWhat it does
scripts/lcp_subparts.pyLCP decomposition via CrUX: TTFB, load delay, load duration, render delay — localises the bottleneck to a specific subpart
scripts/preload_check.pySpeculation Rules + bfcache + prerender + LCP preload audit
scripts/indexnow_submit.pySubmit up to 10,000 URLs to IndexNow (Bing, Yandex, Seznam, Naver) in a single call
scripts/unlighthouse_run.pyMulti-page Lighthouse via the MIT Unlighthouse CLI — runs site-wide rather than single-URL
LCP subpart analysis requires CrUX API access (Tier 0 credential: free Google API key). IndexNow requires a Bing Webmaster account or the Bing Webmaster extension.
4

Phase D — Schema Completeness

Schema coverage expands with four new generators and an e-commerce policy validator.New JSON-LD generators (via scripts/schema_generate.py):
  • reservation — Reservation schema for bookings and appointments
  • order — OrderAction schema for e-commerce confirmation flows
  • discussion — DiscussionForumPosting schema for forum and Q&A content
  • profile — ProfilePage schema for author and team member pages
E-commerce schema validator (scripts/schema_ecommerce_validate.py) checks Google Merchant Center listing requirements: hasMerchantReturnPolicy, shippingDetails, MemberProgram, EU energyEfficiencyClass, and ProductGroup variant structure.Deprecated types reference — skills/seo-schema/references/deprecated-types-2024-2026.md documents every retired rich-result type with the date Google retired it, the official retirement announcement, and the recommended replacement schema.
5

Phase E — AI Search Reframing and 5 New MCP Extensions

Claude SEO’s GEO skill gains evidence-based primary-source reframes for three common myths, plus five new MCP extensions expand the live-data surface.Parasite-SEO scanner (scripts/parasite_risk.py) detects site-reputation-abuse risk patterns per Google’s November 2024 policy update, including third-party content on high-authority domains that violates quality signals.Five new extensions (all in extensions/):
ExtensionWhat it adds
Ahrefs (extensions/ahrefs/)Official @ahrefs/mcp server — backlink and organic keyword data
SE Ranking (extensions/seranking/)AI Share-of-Voice across ChatGPT, Gemini, Perplexity, AI Overviews, and AI Mode
Profound (extensions/profound/)Time-series LLM citation tracker for brand monitoring in AI answers
Bing Webmaster (extensions/bing-webmaster/)Bing Webmaster Tools plus IndexNow unified under a single extension
Unlighthouse (extensions/unlighthouse/)MIT multi-page Lighthouse runner for site-wide CWV analysis
Evidence-based reframes added to skills/seo-geo/references/llmstxt-evidence.md:
  • llms.txt is not currently a confirmed citation lever for AI Overviews
  • Content chunking for AI is not required — synonym understanding is sufficient
  • AI-specific keyword rewriting is unnecessary
6

Phase F — Local, International, and Privacy Polish

Three targeted improvements for local SEO, international SEO, and EU privacy compliance.
AdditionWhat it does
scripts/gbp_deprecation_lint.pyDetects retired Google Business Profile features: the GBP chat field, .business.site hosted website URLs, and Q&A references that no longer serve their original purpose
skills/seo-google/references/dma-consent-mode-v2.mdEU click-through rate diagnostic for Consent Mode v2 + softened cookieless measurement framing aligned with current Google guidance
skills/seo-hreflang/references/machine-translation-qa.mdUntranslated machine-translation detection per January 2025 QRG §4.6.5 — flags pages where automated translation has produced unreviewed low-quality content

​
Security Hardening

v2 ships 83 new SSRF and DNS-rebinding bypass tests, closing the full obfuscated-IPv4, FQDN-trailing-dot, and redirect-rebinding bypass classes.
VulnerabilitySeverityStatus
DNS rebinding via redirect targetHIGHClosed
Obfuscated IPv4 bypass in validate_url (decimal, hex, octal, leading zeros)HIGHClosed
FQDN trailing-dot bypass of metadata-endpoint blocklistHIGHClosed
IPv6 blind spot in Playwright route handlerMEDIUMClosed
OAuth file-permission TOCTOULOWClosed
OAuth token files (oauth-token.json) are now automatically chmod’d to 0o600 on every load and save. Files with legacy 0o644 permissions from pre-v2 installs are silently remediated in place — no user action required.

​
Test Coverage

Suitev1.9.9v2.0.0
Manifest consistency1313
Lazy detection1111
Sync FLOW1515
url_safety (new)—83
render_page (new)—27
Content quality (new)—25
Technical depth (new)—17
Schema v2 (new)—17
Parasite risk + extensions (new)—22
GBP lint + polish (new)—8
Portability (new)—10
Total39248
v2 adds 209 new test cases — a 5.4× increase over the v1.9.9 baseline — covering every new function’s failure modes and every known SSRF bypass class.

​
How to Upgrade

Re-running the installer is sufficient for most users. The installer is idempotent: it overwrites skill and agent files with the v2 versions and recreates the virtual environment if needed. 
# Download and review the install script before running
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh > install.sh
cat install.sh
bash install.sh
rm install.sh

# Reinstall Python dependencies with v2 pins
pip install -r requirements.txt

# Install Playwright Chromium (required for Phase A rendering)
playwright install chromium

# Verify manifest consistency
python3 -m pytest tests/test_manifest_consistency.py -v
After upgrade, the first invocation of any command that touches ~/.config/claude-seo/oauth-token.json will silently re-chmod it to 0o600. No manual permission fix is required.

​
Things That Did Not Break

The following were considered for breaking changes but ultimately kept backward-compatible:
  • validate_url boolean return contract — v2 still returns bool. Use validate_url_strict for the new strict DNS-rebinding behaviour.
  • fetch_page() function signature — the --render flag was added at the CLI layer only; the underlying function stays raw-mode by default.
  • capture_screenshot() API — the pre-flight check is upgraded but the call signature and result dictionary are unchanged.
  • All v1.x command names — /seo audit, /seo content, /seo schema, and every other v1 command work identically in v2.

Build docs developers (and LLMs) love

Get started for freeTalk to us