# 🔍 SEO-Auditor MCP Server (v2.0)

[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.14-blue.svg)](https://www.python.org/)
[![Protocol](https://img.shields.io/badge/MCP-Standard%20Stdio-green.svg)](https://modelcontextprotocol.io/)
[![Engine](https://img.shields.io/badge/Engine-Playwright%20Chromium%20%2B%20HTTPX-purple.svg)](https://playwright.dev/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **High-performance Model Context Protocol (MCP) Server & CLI for 360° Technical SEO, Headless JavaScript Rendering, DOM Hydration Gap Analysis, Schema.org Validation, AEO, and Semantic Cannibalization Detection.**

Built for **Claude Desktop, Cursor, and Autonomous AI Coding Agents** to execute instant technical and JavaScript SEO audits on modern web applications (Next.js, React, Vue, Shopify) directly from natural language prompts.

---

## ⚡ Key Features

- **🌐 Headless JavaScript Rendering (V2):** Executes full client-side JavaScript via Playwright Chromium to audit dynamic SPAs and client-rendered apps exactly as Googlebot sees them.
- **🔬 JS SEO Hydration Gap Analyzer (V2):** Compares raw static HTML against post-hydration Rendered DOM to pinpoint missing titles, injected canonicals, and client-rendered internal links.
- **📸 Full-Page Visual Screenshot Capture (V2):** Captures high-resolution full-page screenshots directly into Claude for visual UI/UX & accessibility analysis.
- **⏱️ Browser Performance & Core Web Vitals:** Measures DOMContentLoaded, TTFB, and browser page load time in milliseconds.
- **🎯 360° Technical SEO Audit:** Audits titles, meta descriptions, canonical URLs, robots meta tags, OpenGraph & Twitter Cards.
- **🏗️ Content & Heading Hierarchy:** Validates H1-H6 semantic nesting, detects missing/multiple H1s, and flags broken hierarchy.
- **🤖 AEO / GEO Readiness Analyzer:** Scans `robots.txt` for AI search crawlers (`GPTBot`, `ClaudeBot`, `PerplexityBot`, `Google-Extended`) to ensure AI search visibility.
- **📐 JSON-LD Schema Validator:** Recursively parses and validates Schema.org entities (`Article`, `Product`, `Organization`, `LocalBusiness`, `FAQPage`) and reports missing required properties.
- **⚔️ Semantic Cannibalization Matrix:** Detects cross-URL keyword cannibalization where multiple pages compete for identical search intent.
- **🗺️ Recursive XML Sitemap Parser:** Crawls sitemap indexes and nested XML sitemaps to perform batch audits.

---

## 🚀 Quickstart

### 1. Installation

```bash
git clone https://github.com/MojoRohjo/seo-auditor-mcp.git
cd seo-auditor-mcp
pip install -r requirements.txt
playwright install chromium
```

---

### 2. Connect to Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "seo-auditor": {
      "command": "python",
      "args": ["-m", "seo_auditor_mcp.server"],
      "env": {}
    }
  }
}
```

Now inside Claude Desktop, you can ask:
> *"Audit `https://mybrand.com` with JavaScript rendering enabled."*  
> *"Analyze the JS hydration gap on `https://mybrand.com` and show me what client-side links are hidden from basic crawlers."*  
> *"Capture a full-page screenshot of `https://mybrand.com` and check its visual layout."*  
> *"Check if our robots.txt blocks AI search bots like Perplexity or Claude."*

---

### 3. Standalone CLI Usage

Run audits directly in your terminal:

```bash
# 1. Standard 360 Technical SEO Audit (Blazing fast async HTTP)
python -m seo_auditor_mcp.cli audit https://mybrand.com

# 2. JavaScript Rendered Audit (Headless Chromium)
python -m seo_auditor_mcp.cli audit https://mybrand.com --render-js

# 3. JS Hydration Gap Analysis (Raw HTML vs Rendered DOM)
python -m seo_auditor_mcp.cli hydration https://mybrand.com

# 4. Full-Page Visual Screenshot Capture
python -m seo_auditor_mcp.cli screenshot https://mybrand.com

# 5. AI Search (AEO) Bot Inspection
python -m seo_auditor_mcp.cli aeo https://mybrand.com

# 6. JSON-LD Schema Validation
python -m seo_auditor_mcp.cli schema https://mybrand.com

# 7. XML Sitemap Batch Crawl
python -m seo_auditor_mcp.cli sitemap https://mybrand.com/sitemap.xml --max 10
```

---

## 🧪 Testing

Run the full automated test suite (29 tests):

```bash
python -m unittest discover tests
```

---

## 👤 Author

**Mohit Yadav**  
*AI-Native Technical SEO & Agentic Workflow Architect*  
- [LinkedIn Profile](https://www.linkedin.com/in/mohit-kr-yadav/)
- [GitHub Profile](https://github.com/MojoRohjo)

---

## 📄 License

MIT License © 2026 Mohit Yadav. Open for commercial and personal use.