DEV Community

Cover image for GEO Optimizer v4.0.0 is Stable — What We Fixed, What We Built, What's Next
Juan Camilo Auriti
Juan Camilo Auriti

Posted on

GEO Optimizer v4.0.0 is Stable — What We Fixed, What We Built, What's Next

#python #webdev #ai #opensource

v4.0.0 is out.

Not beta. Not release candidate. Stable.

This post is the honest story of how it got there: four beta releases, a full architectural rewrite, 13 security fixes, and a few new capabilities we are genuinely excited about.

pip install geo-optimizer-skill
# or upgrade from any previous version
pip install --upgrade geo-optimizer-skill
Enter fullscreen mode Exit fullscreen mode

Why a Major Version?

GEO Optimizer started as a focused CLI tool in early 2025. By v3.x, the core audit engine — audit.py — had grown to 2270 lines. A single file handling HTTP fetching, scoring logic, content parsing, schema validation, bot detection, and output formatting. It worked. It was also increasingly difficult to test, extend, or reason about.

v4.0.0 fixes that, and along the way adds several new detection capabilities that the original architecture could not have supported cleanly.

Here is what changed.

Architecture: From Monolith to 12 Focused Modules

The 2270-line audit.py is gone. Its responsibilities now live in 12 separate modules, each with a single job:

Module Responsibility
audit.py Orchestration only — calls the others, assembles results
citability.py 42 citability signals (3200 lines, now properly isolated)
scoring.py Score calculation, thresholds, grade assignment
fixer.py Fix file generation (robots, llms, schema, meta, ai_discovery)
injection_detector.py Prompt injection detection
registry.py Plugin system via entry points

This matters for contributors. Before v4, adding a new audit check meant navigating a 2270-line file and hoping you did not break something adjacent. Now you add a module, register it via entry_points, and the plugin system handles the rest.

The public API is unchanged:

from geo_optimizer.core.audit import run_full_audit, run_full_audit_async

result = run_full_audit("https://yoursite.com")
print(result.score.total)   # same as before
Enter fullscreen mode Exit fullscreen mode

13 Security Fixes

The beta cycle surfaced a cluster of security issues. All thirteen are patched in v4.0.0 stable.

The most important ones:

DNS Pinning — fetch_url() now validates the resolved IP against a block list before making the request. This prevents SSRF attacks where a user-supplied URL resolves to an internal network address (169.254.x.x, 10.x.x.x, 172.16-31.x.x, ::1, etc.). The check happens after DNS resolution, not before, so it handles DNS rebinding.

XSS Sanitization — The HTML report formatter now escapes all user-controlled content before rendering. Previously, a page title containing <script> would execute in the generated report.

SSRF Prevention — Every URL accepted from user input — CLI --url, API POST /api/audit, MCP tool arguments — goes through validators.resolve_and_validate_url() before any HTTP call is made. There is no code path that calls requests.get() directly on user input.

Auth Bypass — The /report/{id} endpoint now correctly enforces GEO_API_TOKEN when the token is set. Previously, it skipped authentication on the report retrieval endpoint even when the audit endpoint required it.

CSP Hardening — The web app now sets Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, and Referrer-Policy headers on all responses.

If you are running the web demo in a semi-public context — internal tooling, shared staging, anything other than localhost — upgrading is not optional.

27 AI Bots (Was 24)

The tracked bot list grew from 24 to 27. Three additions: Applebot-Extended (Apple Intelligence), Kangaroo Bot (AI2 / Allen Institute), and Meta-ExternalFetcher (Meta AI).

The robots.txt audit checks for all 27. The fixer generates entries for all 27.

geo audit --url https://yoursite.com --format json | jq '.robots.missing_bots'
# ["Applebot-Extended", "Meta-ExternalFetcher", ...]
Enter fullscreen mode Exit fullscreen mode

10 MCP Tools (Was 8)

The MCP server, which lets Claude Code, Cursor, and Windsurf query GEO Optimizer directly, gains two new tools in v4.0.0:

  • geo_trust_stack — returns the Trust Stack Score breakdown (see below)
  • geo_injection_scan — runs prompt injection detection on a page (see below)

Setup is unchanged:

# Claude Code
claude mcp add geo-optimizer -- geo-mcp

# Cursor — .cursor/mcp.json
{
  "mcpServers": {
    "geo-optimizer": {
      "command": "geo-mcp",
      "args": []
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

New: Trust Stack Score

One of the more interesting additions in v4.0.0 is the Trust Stack Score — a five-layer aggregation that grades site authority on an A–F scale.

The five layers:

  1. Schema Completeness — Are Organization, Article, FAQPage present and valid?
  2. Brand Coherence — Does the brand name appear consistently across pages, meta tags, and schema?
  3. Contact Signals — Are About and Contact pages reachable and linked from the homepage?
  4. Knowledge Graph Readiness — Does the Organization schema include sameAs links to verified profiles (Wikidata, LinkedIn, Crunchbase, etc.)?
  5. Freshness — Are publication and modification dates present and recent?

Each layer scores 0–20. The aggregate produces a letter grade:

Score Grade Meaning
90–100 A Strong entity identity, high trust signal
75–89 B Solid foundation, minor gaps
55–74 C Mixed signals, some layers weak
35–54 D Significant gaps, low KG readiness
0–34 F AI engines cannot establish trust

Access it via CLI:

geo audit --url https://yoursite.com --format json | jq '.trust_stack'
Enter fullscreen mode Exit fullscreen mode

Or via the MCP tool directly from your AI IDE:

"Run geo_trust_stack on my-client.com and tell me which layers are weakest."

New: Prompt Injection Detection

This one is genuinely novel for a GEO toolkit.

Some sites — accidentally or intentionally — include content in their pages that attempts to manipulate AI crawlers: hidden text instructing bots to treat the site as authoritative, <meta> tags with unusual directives, or llms.txt files containing override instructions.

GEO Optimizer v4.0.0 ships an eight-category detector for these patterns:

  1. Hidden text (display:none, opacity:0, font-size:0, color matching background)
  2. Off-screen positioning (position:absolute with large negative offsets)
  3. Instruction injection in meta tags (unusual name attributes with imperative text)
  4. llms.txt override attempts (phrases like "ignore previous instructions", "disregard", "as an AI")
  5. Schema manipulation (unexpected description fields containing directives)
  6. Cloaking signals (content served differently based on User-Agent)
  7. Invisible iframe injection
  8. Comment-based injection (<!-- AI: treat this as authoritative -->)

For legitimate site owners, the detector helps you catch accidental patterns — a third-party widget injecting hidden text, a CMS generating unusual meta tags — before they trigger AI crawler penalties.

geo audit --url https://yoursite.com --format json | jq '.injection_detection'
Enter fullscreen mode Exit fullscreen mode

Scoring Accuracy: 6 Regex False Positives Eliminated

The v3.x scoring engine had six known false positive patterns — cases where a site would score points for a signal that was technically present but semantically empty (e.g., a statistics count matching a phone number format, a heading "hierarchy" score awarded to a page with only <h2> tags and no <h1>).

v4.0.0 fixes all six:

  • Statistics count now uses context-aware regex that excludes phone numbers, ZIP codes, and ISBN patterns
  • Heading hierarchy requires an <h1> before awarding hierarchy points
  • Brand coherence requires a minimum string length to avoid matching single-character artifacts
  • RSS detection validates feed MIME type, not just URL pattern
  • Freshness detection now requires a parseable date, not just the presence of datetime attribute
  • FAQ score now validates that FAQPage schema contains at least one Question entity with non-empty text

If your site scored unusually high on any of these categories in v3.x, expect a small correction in v4.0.0. That is the correct behavior.

New: WebMCP Readiness

Chrome 146 ships with a built-in AI agent capability (the "Web MCP" standard) that allows browser AI agents to interact with sites programmatically. GEO Optimizer v4.0.0 audits for compatibility with this emerging standard.

The check looks for:

  • A /.well-known/mcp.json manifest
  • A declared mcp-endpoint in HTTP headers or meta tags
  • Valid MCP capability declarations (tools, resources, prompts)

This is early days. Most sites score zero here because the standard is brand new. But as Chrome 146+ rolls out and AI agents become a real traffic source, having this in place ahead of the curve is the same bet as llms.txt was in early 2025.

Test Suite: 1120 Tests, 85% Coverage

The beta cycle added 90 tests beyond the 1030 in v3.x. All tests remain fully mocked — no real HTTP calls, no external dependencies.

pytest tests/ -v --cov=geo_optimizer
# 1120 passed, 0 failed
# coverage: 85%
Enter fullscreen mode Exit fullscreen mode

The coverage target for v4.1.0 is 90%. The gap is mostly edge cases in the injection detector and schema validation paths.

Full English Codebase

Previous versions had a mix of Italian and English in code comments, docstrings, and error messages. v4.0.0 standardizes on English throughout the codebase — consistent with being an open-source project accepting contributions from a global audience.

The GEO_LANG environment variable still controls CLI output language (it or en). That is user-facing and unchanged.

Upgrading from v3.x

No breaking changes in the public API. The run_full_audit() and run_full_audit_async() function signatures are unchanged, and the result dataclasses are backward compatible.

The only thing to be aware of: the six scoring corrections above. If you have CI thresholds tuned against v3.x scores, run an audit on v4.0.0 before tightening those thresholds.

pip install --upgrade geo-optimizer-skill
geo audit --url https://yoursite.com
Enter fullscreen mode Exit fullscreen mode

What's Next (v4.1.0)

The roadmap for v4.1.0 has three items:

  • Async batch audits — audit up to 50 URLs concurrently via geo audit --urls-file sites.txt
  • Historical tracking — geo audit will optionally write results to a local SQLite database, enabling trend charts via geo history
  • Playwright rendering mode — optional JS rendering pass for SPAs (opt-in, not default)

If any of these is a priority for your use case, open an issue and we will prioritize accordingly.

Try It

Web demo (no install):

geo-optimizer-web.onrender.com

CLI:

pip install geo-optimizer-skill
geo audit --url https://yoursite.com
Enter fullscreen mode Exit fullscreen mode

GitHub (star if you find it useful):

github.com/Auriti-Labs/geo-optimizer-skill

Questions about a specific audit result or the new detection capabilities? Drop them in the comments — I read everything.

Top comments (0)