# 🔍 SEO-Auditor MCP Server

[![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/)
[![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, Schema.org Validation, AEO (AI Engine Optimization), and Semantic Cannibalization Detection.**

Built for **Claude Desktop, Cursor, and Autonomous AI Coding Agents** to execute instant technical audits on any web property directly from natural language prompts.

---

## ⚡ Key Features

- **🎯 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.
- **💻 Dual DX:** Works as an **MCP Stdio Server** for LLMs AND as a **Standalone CLI** tool for humans.

---

## 🚀 Quickstart

### 1. Installation

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

---

### 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` and generate a client-ready Technical SEO report."*  
> *"Check if our robots.txt blocks AI search bots like Perplexity or Claude."*  
> *"Inspect the JSON-LD schema on `https://mybrand.com/pricing` for validation errors."*

---

### 3. Standalone CLI Usage

Run audits directly in your terminal:

```bash
# 1. Full 360 Technical SEO Audit
python -m seo_auditor_mcp.cli audit https://mybrand.com

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

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

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

# 5. Output raw JSON for pipeline integrations
python -m seo_auditor_mcp.cli audit https://mybrand.com --format json
```

---

## 📊 Sample CLI Output

```text
============================================================
[REPORT] TECHNICAL SEO AUDIT: https://example.com/saas-guide
Health Score: 90/100 | Crawl Time: 142.3ms
============================================================

* Title: The Definitive SaaS Technical SEO Guide for 2026 (54 chars)
* Description: Master modern technical SEO, crawl budget, and schema optimization. (72 chars)
   [!] Description is too short (72 chars). Optimal: 110-160 chars.

* Canonical: https://example.com/saas-guide (Self-referential: True)
* Headings: H1: 1 | H2: 4 | H3: 8
* Schema Entities: Article, Organization, BreadcrumbList

[ACTION ITEMS]
   [-] Expand meta description length to 110-160 characters.
============================================================
```

---

## 🧪 Testing

Run the full automated test suite:

```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/klok123)

---

## 📄 License

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