# SEO, AEO, GEO & Digital Marketing Audit + Safe Fix MCP Server

[![CI & PR Validation](https://github.com/sparrow84001/mcp-seo/actions/workflows/ci.yml/badge.svg)](https://github.com/sparrow84001/mcp-seo/actions/workflows/ci.yml)
[![Version](https://img.shields.io/badge/version-1.0.5-blue.svg)](https://github.com/sparrow84001/mcp-seo)
[![TypeScript](https://img.shields.io/badge/TypeScript-7.0.2-blue.svg)](https://www.typescriptlang.org/)
[![Bun](https://img.shields.io/badge/Bun-1.4.0-black.svg)](https://bun.sh)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
[![Author](https://img.shields.io/badge/Author-Sayanta_Neogi-orange.svg)](https://github.com/sparrow84001)
[![Glama Score](https://glama.ai/mcp/servers/sparrow84001/mcp-seo/badges/score.svg)](https://glama.ai/mcp/servers/sparrow84001/mcp-seo)

An advanced, AI-powered Model Context Protocol (MCP) server that acts as a comprehensive **Growth Auditor, Search & AI Engine Optimizer, and Framework-Aware Code Fixer**.

> **Developed by:** **Sayanta Neogi** ([@sparrow84001](https://github.com/sparrow84001)) • 📧 [sparrow8400@gmail.com](mailto:sparrow8400@gmail.com)  
> **Repository:** [github.com/sparrow84001/mcp-seo](https://github.com/sparrow84001/mcp-seo) • **Version:** `1.0.5`

Designed for seamless integration with **Antigravity 2.0**, **GitHub Copilot**, **Claude Desktop**, **Cursor**, and **Windsurf**. Built with **TypeScript 7** and powered by **Bun 1.4**.

---

## Key Capabilities

```
                  ┌─────────────────────────────────────────────────────────┐
                  │                 MCP-SEO AUDIT ENGINE                    │
                  └────────────────────────────┬────────────────────────────┘
                                               │
    ┌──────────────────┬───────────────────────┼───────────────────────┬──────────────────┐
    │                  │                       │                       │                  │
    ▼                  ▼                       ▼                       ▼                  ▼
┌──────────────┐ ┌──────────────┐      ┌──────────────┐      ┌──────────────┐ ┌──────────────┐
│Technical SEO │ │ On-Page SEO  │      │  AEO / GEO   │      │  Local SEO   │ │  Conversion  │
│ Indexing     │ │  Headings    │      │ Direct Answer│      │ NAP & Maps   │ │ CTAs & Forms │
│ Canonicals   │ │  Title/Meta  │      │ Knowledge G. │      │ City Pages   │ │ Trust Signals│
│ Robots/Maps  │ │  Social Cards│      │ llms.txt     │      │ Local Schema │ │ Risk Reversal│
└──────────────┘ └──────────────┘      └──────────────┘      └──────────────┘ └──────────────┘
                                               │
                                               ▼
                  ┌─────────────────────────────────────────────────────────┐
                  │        SURGICAL CODE FIXER & VALIDATOR (DIFFS)          │
                  │ Laravel Blade • Next.js (App/Pages) • PHP • HTML • Vue  │
                  └─────────────────────────────────────────────────────────┘
```

* **Framework Discovery:** Automatic architecture detection for Laravel Blade (`@section`, `@push`, components), Next.js App Router (`Metadata` API, `sitemap.ts`), Next.js Pages Router (`next/head`), Nuxt, Astro, Raw PHP, and static HTML.
* **8-Dimension Scoring:** Calculates 0-100 scores and letter grades (`A+` to `F`) across Technical SEO, On-Page SEO, AEO, GEO, Local SEO, Content Quality, Conversion/CRO, and Core Web Vitals risks.
* **AEO & GEO Ready (2026 Search):** Optimizes for Google AI Overviews, Perplexity, ChatGPT Search, and Claude; audits `llms.txt` and validates `sameAs` entity reconciliation.
* **Local & Area SEO:** Audits `LocalBusiness` schema, NAP consistency, click-to-call phone links, and flags spammy doorway city page duplication.
* **Surgical Code Fixes & Rollback Safety:** Generates unified diffs before applying any changes to files, followed by post-fix validation to prevent duplicate tags or broken schemas.
* **Zero Hallucination Policy:** Confirmed code evidence is strictly tagged as `confirmed`, architectural patterns as `inferred`, and strategic ideas as `recommended`.

---

## 🛠️ Complete MCP Tool Suite (21 Tools)

| Tool Name | Dimension | Description |
| :--- | :--- | :--- |
| `seo_discover_project` | Architecture | Discovers website framework, detected routes, sitemaps, robots, llms.txt, and page inventory. |
| `seo_crawl_and_extract` | Extraction | Crawls live URLs or reads local source files to extract SEO metadata, headings, schemas, and links. |
| `seo_audit_technical` | Technical | Audits canonicals, robots.txt, XML sitemaps, noindex directives, viewport, charset, and status codes. |
| `seo_audit_onpage` | On-Page | Audits titles, meta descriptions, single H1 enforcement, heading hierarchies, OpenGraph, and Twitter cards. |
| `seo_audit_aeo` | AEO | Audits Google AI Overviews & Perplexity citations, question subheadings, and 40-60 word definition blocks. |
| `seo_audit_geo` | GEO | Audits brand clarity, Schema.org Organization/Person entities, and `sameAs` knowledge graph links. |
| `seo_audit_local` | Local SEO | Audits LocalBusiness JSON-LD, NAP consistency, map pack signals, and flags duplicated city landing pages. |
| `seo_audit_content` | Content | Evaluates content quality, word count depth, search intent (informational, commercial, transactional), and reading ease. |
| `seo_audit_conversion` | CRO | Audits high-contrast CTAs, form friction, social proof review badges, mobile floating action buttons, and risk reversal. |
| `seo_audit_performance`| Performance | Audits Core Web Vitals risks: unoptimized image weights, missing width/height attributes, and heavy render-blocking scripts. |
| `seo_audit_schema` | Structured Data | Validates Schema.org JSON-LD structured data coverage, schema types, and syntax correctness. |
| `seo_audit_internal_links` | Internal Links | Audits internal linking graph, contextual links between blogs and services, and descriptive anchor text. |
| `seo_generate_full_audit` | Full Audit | Generates an 8-dimension weighted scorecard, letter grades, P0-P3 prioritized action items, and 5-phase growth plan. |
| `seo_generate_marketing_strategy` | Growth | Formulates a high-impact digital marketing strategy, CRO roadmap, and 30-60-90 day execution milestones. |
| `seo_suggest_related_ecosystem` | Ecosystem | Discovers related market vertical, benchmark competitors, directory/backlink targets, and keyword topic clusters. |
| `seo_test_web_mcp` | Web MCP | Tests live websites for Web MCP enablement (Streamable HTTP, SSE, DOM tools) and provides language blueprints. |
| `seo_audit_sitemap_multipage` | Sitemap & Security | Crawls all sitemap registered URLs, evaluates robots permissions, audits HTTP security headers (HSTS, CSP), and aggregates site-wide scorecard. |
| `seo_audit_robots_and_sitemap` | Robots & Security | Inspects robots.txt rules, sitemap index validity, and HTTP security headers. |
| `seo_generate_sitemap_and_robots` | Generator | Generates production-ready sitemap.xml and robots.txt configuration files. |
| `seo_generate_code_fix`| Safe Fixer | Generates surgical code fixes with unified diffs for Blade, Next.js, Astro, PHP, and HTML. |
| `seo_validate_code_fix`| Validator | Validates modified source files against syntax errors, duplicate tags, and computes Before vs After score improvements. |

---

## 💻 Installation & Usage

### 1. Global Installation (via npm/bun)
```bash
bun add -g @sparrow84001/mcp-seo
# Or with npm:
npm install -g @sparrow84001/mcp-seo
```

### 2. Run via npx / bunx
```bash
npx @sparrow84001/mcp-seo
# Or with bun:
bunx @sparrow84001/mcp-seo
```

### 3. Precompiled Standalone Executable (Zero Dependencies)
Download `mcp-seo.exe` directly from the [GitHub Releases](https://github.com/sparrow84001/mcp-seo/releases) page.

---

## ⚙️ Configuration

### Antigravity 2.0 / Claude Desktop / Cursor (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "seo-growth-auditor": {
      "command": "bunx",
      "args": ["@sparrow84001/mcp-seo"]
    }
  }
}
```

### Glama.ai Listing & Score
[![Glama Card](https://glama.ai/mcp/servers/sparrow84001/mcp-seo/badges/card.svg)](https://glama.ai/mcp/servers/sparrow84001/mcp-seo)

---

## 📄 License & Author

* **License:** MIT License • Copyright (c) 2026 **Sayanta Neogi**
* **Author:** Sayanta Neogi ([@sparrow84001](https://github.com/sparrow84001)) • 📧 [sparrow8400@gmail.com](mailto:sparrow8400@gmail.com)