aeo-scanner 1.0.0__tar.gz

aeo_scanner-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.DS_Store

aeo_scanner-1.0.0/LICENSE

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

aeo_scanner-1.0.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: aeo-scanner
+Version: 1.0.0
+Summary: MCP server for AI search visibility auditing. Checks AEO score and Agent Readiness score for any website.
+Author-email: Convrgent <hello@convrgent.ai>
+License: MIT
+License-File: LICENSE
+Keywords: aeo,agent-readiness,ai-search,ai-visibility,mcp,seo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# AEO Scanner — MCP Server
+
+AI search visibility audit for any website. Two scores, one scan.
+
+## What it does
+
+- **AEO Score (0-100):** How well AI search engines (ChatGPT, Perplexity, Google AI Overviews) can find, read, and cite your content
+- **Agent Readiness (0-100):** How easily AI agents can understand, interact with, and transact on your site
+
+## Quick start
+
+```bash
+# Claude Code — one command
+claude mcp add aeo-scanner -- uvx aeo-scanner
+
+# Cursor — add to .cursor/mcp.json
+{ "aeo-scanner": { "command": "uvx", "args": ["aeo-scanner"] } }
+```
+
+Then ask your AI assistant: *"Scan example.com for AI visibility"*
+
+## Tools
+
+| Tool | What it does | Price |
+|------|-------------|-------|
+| `scan_site` | Quick dual-score scan + top issues | **Free** |
+| `audit_site` | Full 25+ check breakdown across 8 categories | $1.00 |
+| `fix_site` | Generated fix code — apply directly with Claude Code | $5.00 |
+
+## Free tier
+
+`scan_site` works without any authentication. No API key, no wallet, no setup. Just install and scan.
+
+Rate limits: 20 scans/hour per IP, 5 per URL per day.
+
+## Paid tools
+
+`audit_site` and `fix_site` require an API key:
+
+1. Get your key at [scan.convrgent.ai](https://scan.convrgent.ai)
+2. Add it to your MCP config:
+
+```json
+{
+  "aeo-scanner": {
+    "command": "uvx",
+    "args": ["aeo-scanner"],
+    "env": {
+      "AEO_API_KEY": "your-api-key"
+    }
+  }
+}
+```
+
+Or pay per call with USDC via [x402 protocol](https://www.x402.org/) (Base network).
+
+## Workflow
+
+The included `optimize_site` prompt guides the full workflow:
+
+1. **Scan** — get baseline scores (free)
+2. **Audit** — see detailed breakdown by category ($1)
+3. **Fix** — get working code to apply ($5)
+4. **Rescan** — verify improvement (free)
+
+## Context cost
+
+~1,000 tokens at startup. 40x lighter than GitHub MCP.
+
+## Scoring
+
+25+ checks across 8 categories. See the built-in `aeo://reference/scoring-methodology` resource for full details, or read [scoring-methodology.md](scoring-methodology.md).
+
+**AEO categories:** Structured Data (30%), Meta & Technical (20%), AI Accessibility (25%), Content Quality (25%)
+
+**Agent Readiness categories:** Machine Identity (25%), API Discoverability (25%), Structured Actions (20%), Programmatic Access (20%), Data Clarity (10%)
+
+**Grades:** A (90+), B (75-89), C (60-74), D (40-59), F (0-39)
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AEO_API_KEY` | For paid tools | API key from scan.convrgent.ai |
+| `AEO_API_URL` | No | Override API base URL (default: https://scan.convrgent.ai) |
+
+---
+
+Built by [Convrgent](https://convrgent.ai) — personality intelligence and AI visibility tools for agents.

aeo_scanner-1.0.0/README.md

@@ -0,0 +1,89 @@
+# AEO Scanner — MCP Server
+
+AI search visibility audit for any website. Two scores, one scan.
+
+## What it does
+
+- **AEO Score (0-100):** How well AI search engines (ChatGPT, Perplexity, Google AI Overviews) can find, read, and cite your content
+- **Agent Readiness (0-100):** How easily AI agents can understand, interact with, and transact on your site
+
+## Quick start
+
+```bash
+# Claude Code — one command
+claude mcp add aeo-scanner -- uvx aeo-scanner
+
+# Cursor — add to .cursor/mcp.json
+{ "aeo-scanner": { "command": "uvx", "args": ["aeo-scanner"] } }
+```
+
+Then ask your AI assistant: *"Scan example.com for AI visibility"*
+
+## Tools
+
+| Tool | What it does | Price |
+|------|-------------|-------|
+| `scan_site` | Quick dual-score scan + top issues | **Free** |
+| `audit_site` | Full 25+ check breakdown across 8 categories | $1.00 |
+| `fix_site` | Generated fix code — apply directly with Claude Code | $5.00 |
+
+## Free tier
+
+`scan_site` works without any authentication. No API key, no wallet, no setup. Just install and scan.
+
+Rate limits: 20 scans/hour per IP, 5 per URL per day.
+
+## Paid tools
+
+`audit_site` and `fix_site` require an API key:
+
+1. Get your key at [scan.convrgent.ai](https://scan.convrgent.ai)
+2. Add it to your MCP config:
+
+```json
+{
+  "aeo-scanner": {
+    "command": "uvx",
+    "args": ["aeo-scanner"],
+    "env": {
+      "AEO_API_KEY": "your-api-key"
+    }
+  }
+}
+```
+
+Or pay per call with USDC via [x402 protocol](https://www.x402.org/) (Base network).
+
+## Workflow
+
+The included `optimize_site` prompt guides the full workflow:
+
+1. **Scan** — get baseline scores (free)
+2. **Audit** — see detailed breakdown by category ($1)
+3. **Fix** — get working code to apply ($5)
+4. **Rescan** — verify improvement (free)
+
+## Context cost
+
+~1,000 tokens at startup. 40x lighter than GitHub MCP.
+
+## Scoring
+
+25+ checks across 8 categories. See the built-in `aeo://reference/scoring-methodology` resource for full details, or read [scoring-methodology.md](scoring-methodology.md).
+
+**AEO categories:** Structured Data (30%), Meta & Technical (20%), AI Accessibility (25%), Content Quality (25%)
+
+**Agent Readiness categories:** Machine Identity (25%), API Discoverability (25%), Structured Actions (20%), Programmatic Access (20%), Data Clarity (10%)
+
+**Grades:** A (90+), B (75-89), C (60-74), D (40-59), F (0-39)
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AEO_API_KEY` | For paid tools | API key from scan.convrgent.ai |
+| `AEO_API_URL` | No | Override API base URL (default: https://scan.convrgent.ai) |
+
+---
+
+Built by [Convrgent](https://convrgent.ai) — personality intelligence and AI visibility tools for agents.

aeo_scanner-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "aeo-scanner"
+version = "1.0.0"
+description = "MCP server for AI search visibility auditing. Checks AEO score and Agent Readiness score for any website."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "Convrgent", email = "hello@convrgent.ai"}]
+keywords = ["mcp", "aeo", "seo", "ai-search", "agent-readiness", "ai-visibility"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+aeo-scanner = "src.server:mcp.run"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

aeo_scanner-1.0.0/scoring-methodology.md

@@ -0,0 +1,96 @@
+# AEO Scanner — Scoring Methodology
+
+Two independent scores, one scan.
+
+## AEO Score (0-100)
+
+Measures how well AI search engines (ChatGPT, Perplexity, Google AI Overviews) can find, read, and cite your content.
+
+### Categories
+
+**Structured Data (30% of score)**
+JSON-LD schema markup — Organization, WebSite, BreadcrumbList, FAQ, Article, Product schemas. Validates JSON-LD blocks are valid and contain required fields (name, url, logo, description, sameAs for Organization; headline, author, datePublished for Articles).
+
+**Meta & Technical (20% of score)**
+Canonical URLs, meta descriptions (50-160 chars), Open Graph tags, heading hierarchy (single H1, no gaps), language attribute, Twitter cards, robots.txt (must allow AI crawlers: GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, OAI-SearchBot), and sitemap.xml with lastmod dates.
+
+**AI Accessibility (25% of score)**
+llms.txt (structured machine-readable site summary with sections, links, API info), llms-full.txt, definition blocks in first 500 words ("X is a Y" patterns), content structure (subheadings, lists, scannable paragraphs), and Q&A content format.
+
+**Content Quality (25% of score)**
+Data density (3+ statistics per 500 words), expert attribution (author meta, Person schema, credentials), content freshness signals (published/modified dates), content depth (300+ words minimum, 800+ for bonus), and unique value indicators (original research, case studies, proprietary data).
+
+### How checks are scored
+
+Each check has a severity (critical = 3x weight, warning = 2x, info = 1x). Category score = weighted sum of passed checks / total possible weight. Overall AEO score = weighted average of category scores.
+
+---
+
+## Agent Readiness Score (0-100)
+
+Measures how easily AI agents can understand, interact with, and transact on your site.
+
+### Categories
+
+**Machine Identity (25% of score)**
+llms.txt depth (scored on API info, pricing, auth details), site description clarity (action verb + noun + audience in first 100 words), consistent machine-readable name across Organization schema, og:site_name, and page title.
+
+**API Discoverability (25% of score)**
+OpenAPI/Swagger specification at standard paths, developer documentation with technical signals (API key, SDK, curl, REST, GraphQL, webhook references), and visible API endpoints in content.
+
+**Structured Actions (20% of score)**
+Machine-readable pricing (Product/Service schema with offers), action affordances (forms, sign-up links, CTAs, Action schema), and machine-readable contact info (contactPoint in Organization schema).
+
+**Programmatic Access (20% of score)**
+Payment protocols (x402, Stripe, crypto/USDC detection), authentication documentation, and webhook/event support (callback URLs, event-driven patterns).
+
+**Data Clarity (10% of score)**
+Reserved for future checks.
+
+### How checks are scored
+
+Agent checks use the actual score (0-100) of each check, weighted by severity. Category score = weighted average of check scores. Overall Agent Readiness = weighted average of category scores.
+
+---
+
+## Letter Grades
+
+| Grade | Score | Meaning |
+|-------|-------|---------|
+| A | 90-100 | Excellent — optimized for AI visibility |
+| B | 75-89 | Good — strong fundamentals, minor gaps |
+| C | 60-74 | Fair — basics met, significant room for improvement |
+| D | 40-59 | Poor — major gaps in AI optimization |
+| F | 0-39 | Failing — critical elements missing |
+
+---
+
+## What raises your AEO Score
+
+- Complete JSON-LD schema (Organization + WebSite on homepage)
+- robots.txt allowing AI crawlers
+- /llms.txt with structured content
+- Definition blocks in opening paragraphs
+- 300+ words with data density
+- Author attribution and freshness signals
+
+## What raises your Agent Readiness Score
+
+- Deep llms.txt with API docs, pricing, auth info
+- OpenAPI spec or developer documentation
+- Clear site description (what + who + for whom)
+- Pricing in schema (Product with offers)
+- Action affordances (forms, buttons, CTAs)
+- Contact info in Organization schema
+- Payment protocol support (x402, Stripe, crypto)
+- Authentication docs and webhook support
+
+---
+
+## Multi-page scanning
+
+When scanning multiple pages, site-wide checks (robots.txt, sitemap, llms.txt) are counted once. Per-page checks are aggregated across all scanned pages. Top issues are sorted by severity (critical first).
+
+---
+
+Built by [Convrgent](https://convrgent.ai) — tools for AI agents.

aeo_scanner-1.0.0/server.json

@@ -0,0 +1,26 @@
+{
+  "name": "aeo-scanner",
+  "version": "1.0.0",
+  "description": "AI search visibility audit. Two scores: AEO Score (AI search findability) and Agent Readiness (agent interaction capability). Returns actionable fix code.",
+  "author": {
+    "name": "Convrgent",
+    "url": "https://convrgent.ai"
+  },
+  "repository": "https://github.com/convrgent/aeo-scanner-mcp",
+  "homepage": "https://scan.convrgent.ai",
+  "categories": ["web-development", "seo", "ai-visibility", "agent-readiness"],
+  "packages": {
+    "pypi": "aeo-scanner"
+  },
+  "tools": [
+    {"name": "scan_site", "description": "Quick AI visibility scan with dual scores (free)"},
+    {"name": "audit_site", "description": "Full 25+ check AI visibility audit ($1.00)"},
+    {"name": "fix_site", "description": "Generate fix code for all AI visibility issues ($5.00)"}
+  ],
+  "resources": [
+    {"uri": "aeo://reference/scoring-methodology", "description": "Scoring methodology documentation"}
+  ],
+  "prompts": [
+    {"name": "optimize_site", "description": "Full scan-audit-fix-verify workflow"}
+  ]
+}

aeo_scanner-1.0.0/src/server.py

@@ -0,0 +1,159 @@
+import os
+import json
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="aeo-scanner",
+    instructions="AI search visibility audit. Checks AEO score and Agent Readiness score for any website. Returns actionable fix code.",
+)
+
+API_BASE = os.environ.get("AEO_API_URL", "https://scan.convrgent.ai")
+AEO_API_KEY = os.environ.get("AEO_API_KEY")
+
+
+def _get_paid_headers() -> dict:
+    """Build headers for paid API calls."""
+    headers = {"Content-Type": "application/json"}
+    if AEO_API_KEY:
+        headers["Authorization"] = f"Bearer {AEO_API_KEY}"
+    return headers
+
+
+def _payment_required_response() -> str:
+    """Structured 402 response that agents can relay to their operators."""
+    return json.dumps(
+        {
+            "error": "payment_required",
+            "message": "This tool requires a paid API key.",
+            "how_to_pay": {
+                "stripe": "Get your API key at https://scan.convrgent.ai",
+                "crypto": "Pay per call via x402 (USDC on Base). See https://scan.convrgent.ai",
+            },
+            "setup": "Set AEO_API_KEY in your MCP server config env vars.",
+            "pricing": {"audit_site": "$1.00", "fix_site": "$5.00"},
+            "tip": "scan_site is free — try it first to see your scores.",
+        },
+        indent=2,
+    )
+
+
+async def _handle_paid_request(endpoint: str, payload: dict) -> str:
+    """Call a paid endpoint with proper 402 handling."""
+    headers = _get_paid_headers()
+    async with httpx.AsyncClient(timeout=180) as client:
+        resp = await client.post(f"{API_BASE}{endpoint}", json=payload, headers=headers)
+        if resp.status_code == 402:
+            return _payment_required_response()
+        if resp.status_code >= 400:
+            try:
+                error_data = resp.json()
+            except Exception:
+                error_data = {"raw": resp.text[:500]}
+            return json.dumps(
+                {
+                    "error": "request_failed",
+                    "status": resp.status_code,
+                    "details": error_data,
+                },
+                indent=2,
+            )
+        return resp.text
+
+
+@mcp.tool()
+async def scan_site(url: str, pages: int = 5) -> str:
+    """Quick AI visibility scan. Returns AEO Score (0-100) and Agent
+    Readiness Score (0-100) with letter grades, plus top issues found.
+    Free to use — no API key needed. Use for fast assessment before
+    diving deeper with audit_site. Run again after applying fixes to
+    verify improvement."""
+    async with httpx.AsyncClient(timeout=120) as client:
+        resp = await client.post(
+            f"{API_BASE}/api/aeo/scan",
+            json={"url": url, "pages": min(max(1, pages), 5)},
+            headers={"Content-Type": "application/json"},
+        )
+        if resp.status_code >= 400:
+            try:
+                error_data = resp.json()
+            except Exception:
+                error_data = {"raw": resp.text[:500]}
+            return json.dumps(
+                {
+                    "error": "scan_failed",
+                    "status": resp.status_code,
+                    "details": error_data,
+                },
+                indent=2,
+            )
+        return resp.text
+
+
+@mcp.tool()
+async def audit_site(
+    url: str, pages: int = 5, categories: list[str] | None = None
+) -> str:
+    """Full AI visibility audit across 25+ checks in 8 categories:
+    structured data, meta & technical, AI accessibility, content quality,
+    machine identity, API discoverability, structured actions, and
+    programmatic access. Returns detailed per-check scores with
+    specific issues and fix recommendations.
+    Requires API key (set AEO_API_KEY env var). $1.00 per call."""
+    payload: dict = {"url": url, "pages": min(max(1, pages), 5)}
+    if categories:
+        payload["categories"] = categories
+    return await _handle_paid_request("/api/aeo/audit", payload)
+
+
+@mcp.tool()
+async def fix_site(url: str, pages: int = 5, format: str = "generic") -> str:
+    """Generate complete fix code for all AI visibility issues.
+    Returns a structured fix file that coding agents (Claude Code,
+    Codex, Cursor) can apply directly. Includes schema generation,
+    robots.txt fixes, sitemap fixes, llms.txt generation, and
+    structured data additions. Not just recommendations — working code.
+    Set format to 'claude_code' for Claude Code optimized output.
+    Requires API key (set AEO_API_KEY env var). $5.00 per call."""
+    return await _handle_paid_request(
+        "/api/aeo/fix",
+        {"url": url, "pages": min(max(1, pages), 5), "format": format},
+    )
+
+
+@mcp.resource("aeo://reference/scoring-methodology")
+async def scoring_methodology() -> str:
+    """How AEO and Agent Readiness scores are calculated across 25+ checks."""
+    path = os.path.join(os.path.dirname(__file__), "..", "scoring-methodology.md")
+    with open(path) as f:
+        return f.read()
+
+
+@mcp.prompt()
+async def optimize_site(url: str, priority: str = "both") -> str:
+    """Full scan → audit → fix → verify workflow for optimizing a site's
+    AI visibility. Guides the agent through the complete process."""
+    return f"""You are optimizing {url} for AI search visibility and agent readiness.
+
+Workflow:
+1. Call scan_site to get baseline scores (free)
+2. Report the two scores and top issues to the user
+3. If user wants to proceed, call audit_site for the full breakdown ($1.00 — requires API key)
+4. Present the detailed findings organized by category
+5. If user wants fixes, call fix_site to generate fix code ($5.00 — requires API key)
+6. Apply the fix code to the project (if you have file access)
+7. After applying fixes, call scan_site again to verify improvement (free)
+8. Report the before/after comparison (e.g., "AEO: 61 → 96")
+
+Priority focus: {priority}
+Always present both scores but emphasize the priority area.
+
+If audit_site or fix_site returns a payment_required error, tell the user:
+- Get an API key at https://scan.convrgent.ai
+- Set it as AEO_API_KEY in your MCP config
+- Or pay per call with USDC via x402 protocol
+"""
+
+
+if __name__ == "__main__":
+    mcp.run()