# AI Agent Setup Guide -- Connascent SEO Extension

This document is for AI agents (Claude Code, Cursor, Windsurf, or any MCP-compatible IDE).
It explains how the MCP bridge works, how to set it up, what tools are available, what data
you receive, and how to use it effectively.

---

## Table of Contents

- [Overview](#overview)
- [Architecture](#architecture)
- [Setup Instructions](#setup-instructions)
- [Verifying the Connection](#verifying-the-connection)
- [Available MCP Tools](#available-mcp-tools)
- [Tool Reference](#tool-reference)
- [Data Schema Reference](#data-schema-reference)
- [Issue Detection Logic](#issue-detection-logic)
- [Page Lookup Behavior](#page-lookup-behavior)
- [Working with Multiple Pages](#working-with-multiple-pages)
- [Lighthouse and Core Web Vitals Data](#lighthouse-and-core-web-vitals-data)
- [Schema Validation](#schema-validation)
- [Example Workflows](#example-workflows)
- [Troubleshooting](#troubleshooting)
- [Configuration](#configuration)
- [Limitations](#limitations)

---

## Overview

The Connascent SEO Chrome extension analyzes on-page SEO elements of any webpage. After
each analysis, the extension silently POSTs the complete SEO data to a local MCP bridge
server running on `localhost:27608`. Your AI IDE connects to this server via the MCP
protocol (stdio transport) and can query the data using 4 tools.

You do not need an API key. The bridge uses your existing AI IDE session. The extension
does all the heavy lifting -- DOM scraping, PageSpeed API calls, data structuring. You
receive clean, structured JSON and just read, interpret, and recommend.

---

## Architecture

```text
Chrome Extension (side panel)
        |
        |  POST /seo-data  (after every page analysis)
        v
+------------------------+
|   MCP Bridge Server    |     Node.js, runs locally
|   localhost:27608      |     Stores last 5 analyzed pages in memory
+----------+-------------+
           |  MCP protocol (stdio)
           v
  AI IDE (Claude Code, Cursor, Windsurf, etc.)
        |
        |  You ask questions in plain English
        v
  SEO analysis and recommendations
```

**Two communication channels in one server:**

1. **HTTP** (port 27608) -- receives SEO data from the Chrome extension via POST, and
   responds to GET /status pings from the extension's connection indicator
2. **stdio** -- MCP protocol for tool calls from the AI IDE

---

## Setup Instructions

### Prerequisites

- Node.js 18 or higher -- check with `node --version`
- The Connascent SEO Chrome extension installed and loaded
- An MCP-compatible AI IDE (Claude Code, Cursor, Windsurf, etc.)

### Step 1 -- Install dependencies

Run this once from the project root:

```bash
cd mcp-server
npm install
```

This installs the single dependency: `@modelcontextprotocol/sdk`.

### Step 2 -- Register the MCP server in your IDE

**Claude Code (VS Code extension):**

The project already includes `.mcp.json` in the project root which registers the server:

```json
{
  "mcpServers": {
    "connascent-seo": {
      "command": "node",
      "args": ["./mcp-server/server.js"]
    }
  }
}
```

Restart VS Code or run `/mcp` in the Claude Code chat to load the server.
When prompted, approve the MCP server to allow it to run.

**Auto-approve MCP tool permissions (recommended):**

Without this step, your IDE will prompt you to approve each MCP tool call. Create the
appropriate config for your IDE to auto-allow the 4 read-only SEO tools:

**Claude Code** -- create `.claude/settings.json` in the project root:

```json
{
  "permissions": {
    "allow": [
      "mcp__connascent-seo__list_analyzed_pages",
      "mcp__connascent-seo__get_seo_data",
      "mcp__connascent-seo__get_seo_summary",
      "mcp__connascent-seo__get_page_issues"
    ]
  }
}
```

**Cursor** -- add the server to `.cursor/mcp.json` in the project root. Cursor trusts
servers defined in this file automatically.

**Windsurf** -- add the server to `.windsurf/mcp.json` in the project root. Windsurf
trusts servers defined in this file automatically.

**Other IDEs** -- check your IDE's MCP documentation for the equivalent auto-approve
setting. The 4 tool names are: `list_analyzed_pages`, `get_seo_data`,
`get_seo_summary`, `get_page_issues`.

These files are gitignored -- create them locally based on your IDE.

**Cursor / Windsurf / Other MCP IDEs:**

Add this to your IDE's MCP configuration file (location varies by IDE):

```json
{
  "mcpServers": {
    "connascent-seo": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/server.js"]
    }
  }
}
```

Replace `/absolute/path/to/` with the actual path to the `mcp-server/` directory.

### Step 3 -- Verify

After restarting the IDE or reloading MCP servers:

1. Check that `connascent-seo` appears as a connected MCP server
2. Open any webpage in Chrome
3. Click the Connascent SEO extension icon and hit "Analyze Page"
4. The extension header should show a green dot and your agent name (e.g., "Claude Code")
5. Call `list_analyzed_pages` to confirm data is flowing

---

## Verifying the Connection

### From your IDE

Call the `list_analyzed_pages` tool. If the server is running and pages have been
analyzed, you will see a list like:

```text
#1  https://example.com/
   Analyzed: 2026-03-03T10:15:00.000Z
   Lighthouse: ok

#2  https://another-site.com/blog
   Analyzed: 2026-03-03T10:12:00.000Z
   Lighthouse: none
```

If no pages have been analyzed yet, you will see:

```text
No pages analyzed yet. Open a webpage in Chrome and click 'Analyze Page' in the
Connascent SEO extension.
```

### From the command line

```bash
curl http://localhost:27608/status
```

Expected response:

```json
{ "ok": true, "agent": "Claude Code", "pagesInHistory": 2 }
```

If the server is not running, the request will fail with a connection error.

---

## Available MCP Tools

| Tool | Purpose | Returns |
| ---- | ------- | ------- |
| `get_seo_data` | Full raw SEO data for a page | Complete stored object with all fields |
| `get_seo_summary` | Concise summary with key metrics | Title, description, counts, flags |
| `get_page_issues` | Problems only, grouped by severity | Critical, warnings, info arrays |
| `list_analyzed_pages` | All pages in current session | Up to 5 entries, newest first |

All tools except `list_analyzed_pages` accept optional parameters:

- `scanId` (number) -- scan ID shown as #N in the extension. Takes priority over url.
- `url` (string) -- partial URL to match against history (e.g., "example.com").

If neither is provided, the most recently analyzed page is used.

---

## Tool Reference

### get_seo_data

Returns the complete raw data blob for a page. Use this when you need fields that
`get_seo_summary` and `get_page_issues` do not expose, or when you want to inspect the
raw data structure.

**Parameters:**

```json
{
  "scanId": 1,
  "url": "example.com"
}
```

Both optional. `scanId` takes priority.

**Response structure:**

```json
{
  "scanId": 1,
  "url": "https://example.com/",
  "analyzedAt": "2026-03-03T10:15:00.000Z",
  "data": {
    "title": "...",
    "metaDescription": "...",
    "canonical": "...",
    "robots": "...",
    "wordCount": 1250,
    "headings": { ... },
    "links": { ... },
    "images": { ... },
    "schema": [ ... ],
    "social": { ... },
    "lang": "en",
    "publisher": "...",
    "hreflang": [ ... ],
    "pageSpeed": { ... },
    "pageSpeedFailed": false
  }
}
```

### get_seo_summary

Returns a normalized summary with the most commonly needed metrics. Lighter than
`get_seo_data` -- use this for quick checks and overviews.

**Parameters:** Same as `get_seo_data`.

**Response structure:**

```json
{
  "url": "https://example.com/",
  "analyzedAt": "2026-03-03T10:15:00.000Z",
  "title": "Example Page Title",
  "titleLength": 18,
  "metaDescription": "This is the meta description...",
  "descriptionLength": 145,
  "wordCount": 1250,
  "headings": {
    "total": 12,
    "h1": 1,
    "h2": 5,
    "h3": 6
  },
  "links": {
    "total": 34,
    "internal": 22,
    "external": 10,
    "nofollow": 2
  },
  "images": {
    "total": 8,
    "withAlt": 6,
    "missingAlt": 2
  },
  "schemaTypes": ["Organization", "WebPage"],
  "openGraph": true,
  "twitterCard": true,
  "canonical": "https://example.com/",
  "robots": "index, follow",
  "lang": "en"
}
```

### get_page_issues

Returns only detected problems, grouped by severity. Use this when the user asks
"what's wrong with this page" or "what should I fix".

**Parameters:** Same as `get_seo_data`.

**Response structure:**

```json
{
  "url": "https://example.com/",
  "analyzedAt": "2026-03-03T10:15:00.000Z",
  "summary": "1 critical, 2 warnings, 1 info",
  "critical": [
    "Missing meta description"
  ],
  "warnings": [
    "Title too long -- 72 chars (recommended: 30-60)",
    "3 images missing alt text"
  ],
  "info": [
    "No schema markup detected -- structured data can improve search appearance"
  ]
}
```

### list_analyzed_pages

Lists all pages analyzed in the current session (up to 5), newest first.
Includes the Lighthouse status for each page.

**Parameters:** None.

**Response format:**

```text
#1  https://example.com/
   Analyzed: 2026-03-03T10:15:00.000Z
   Lighthouse: ok

#2  https://another-site.com/blog
   Analyzed: 2026-03-03T10:12:00.000Z
   Lighthouse: none
```

Lighthouse status values:

- `ok` -- PageSpeed data is available (scores, CWV metrics, audit issues)
- `failed` -- PageSpeed API was called but failed (rate limit, invalid URL, etc.)
- `none` -- PageSpeed was not called (no API key, feature disabled, or skipped)

---

## Data Schema Reference

This is the complete structure of the `data` object inside each page entry. You receive
this when calling `get_seo_data`.

### Top-level fields

| Field | Type | Description |
| ----- | ---- | ----------- |
| `title` | string | Page title (document.title), capped at 2048 chars |
| `metaDescription` | string or null | Content of meta[name="description"] |
| `canonical` | string or null | Canonical URL from link[rel="canonical"] |
| `robots` | string or null | Robots directive from meta[name="robots"] |
| `wordCount` | number | Body text word count (uses main element when available) |
| `lang` | string or null | Language from html[lang] or meta http-equiv |
| `publisher` | string or null | Publisher from article:publisher, author, or og:site_name |

### headings

```json
{
  "total": 12,
  "h1Count": 1,
  "h2Count": 5,
  "h3Count": 4,
  "h4Count": 2,
  "h5Count": 0,
  "h6Count": 0,
  "list": [
    { "level": "h1", "text": "Page Title" },
    { "level": "h2", "text": "Section Heading" }
  ]
}
```

### links

```json
{
  "internal": 22,
  "external": 10,
  "nofollow": 2,
  "list": [
    {
      "text": "About Us",
      "href": "https://example.com/about",
      "type": "internal",
      "rel": ""
    },
    {
      "text": "Partner Site",
      "href": "https://partner.com",
      "type": "external",
      "rel": "nofollow"
    }
  ]
}
```

List is capped at 500 items. The `type` field is "internal" or "external". Links with
`rel` containing "nofollow" are flagged.

### images

```json
{
  "total": 8,
  "withAlt": 6,
  "missingAlt": 2,
  "list": [
    {
      "src": "https://example.com/hero.jpg",
      "alt": "Hero banner image",
      "hasAlt": true
    },
    {
      "src": "https://example.com/photo.png",
      "alt": "",
      "hasAlt": false
    }
  ]
}
```

List is capped at 500 items. `hasAlt` is false when the alt attribute is missing entirely
(not just empty -- empty alt is valid for decorative images).

### schema

Array of parsed JSON-LD blocks found on the page:

```json
[
  {
    "@context": "https://schema.org",
    "@type": "Organization",
    "name": "Example Corp",
    "url": "https://example.com"
  },
  {
    "@context": "https://schema.org",
    "@type": "WebPage",
    "name": "Home"
  }
]
```

Each entry is the parsed content of a `<script type="application/ld+json">` block.
`@type` arrays are flattened (if a block has `"@type": ["Article", "NewsArticle"]`, both
types appear in the flattened types list).

### social

```json
{
  "og": {
    "title": "Example Page",
    "description": "...",
    "image": "https://example.com/og.jpg",
    "url": "https://example.com/"
  },
  "twitter": {
    "card": "summary_large_image",
    "title": "Example Page",
    "description": "...",
    "image": "https://example.com/twitter.jpg"
  }
}
```

Contains all detected `og:*` and `twitter:*` meta tags with their values.

### hreflang

```json
[
  { "lang": "en", "href": "https://example.com/en/" },
  { "lang": "es", "href": "https://example.com/es/" },
  { "lang": "x-default", "href": "https://example.com/" }
]
```

Array of `link[rel="alternate"][hreflang]` tags. Empty array if hreflang analysis is
disabled in extension settings or no tags found.

### pageSpeed

Present when PageSpeed data was successfully fetched. Missing when not requested or failed.

```json
{
  "scores": {
    "performance": 85,
    "accessibility": 92,
    "seo": 100,
    "bestPractices": 78
  },
  "cwv": {
    "lcp": { "value": "2.1 s", "rating": "good" },
    "cls": { "value": "0.05", "rating": "good" },
    "inp": { "value": "180 ms", "rating": "ok" }
  },
  "auditIssues": {
    "performance": [
      { "title": "Reduce unused JavaScript", "score": 0.45 }
    ],
    "accessibility": [],
    "seo": [],
    "bestPractices": [
      { "title": "Uses deprecated APIs", "score": 0 }
    ]
  },
  "strategy": "mobile"
}
```

Score values are 0-100. CWV ratings are "good", "ok", or "poor". Audit issues are failed
Lighthouse audits grouped by category with their scores (0 = completely failing,
0.xx = partially passing).

### pageSpeedFailed

Boolean. Set to `true` when the PageSpeed API was called but returned an error. When this
is true, `pageSpeed` will not be present. Common reasons: rate limiting (429), invalid
URL (400), invalid API key (403), timeout.

---

## Issue Detection Logic

The `get_page_issues` tool checks for these conditions:

### Critical issues

| Condition | Message |
| --------- | ------- |
| No `title` | "Missing page title" |
| No `metaDescription` | "Missing meta description" |
| 0 H1 tags | "No H1 tag found -- every page should have exactly one H1" |
| Robots contains "noindex" or "none" | "Page is set to noindex -- will not appear in search results" |

### Warnings

| Condition | Message |
| --------- | ------- |
| Title < 30 chars | "Title too short -- N chars (recommended: 30-60)" |
| Title > 60 chars | "Title too long -- N chars (recommended: 30-60)" |
| Description < 120 chars | "Meta description too short -- N chars (recommended: 120-160)" |
| Description > 160 chars | "Meta description too long -- N chars (recommended: 120-160)" |
| H1 count > 1 | "Multiple H1 tags found (N) -- should have exactly one" |
| Images with missing alt > 0 | "N images missing alt text" |
| No canonical URL | "No canonical URL set" |

### Info

| Condition | Message |
| --------- | ------- |
| Word count < 300 | "Low word count -- N words (300+ recommended for SEO)" |
| No schema markup | "No schema markup detected -- structured data can improve search appearance" |
| No Open Graph tags | "No Open Graph tags -- affects how the page appears when shared on social media" |

---

## Page Lookup Behavior

When you pass a `url` parameter to any tool, the server matches against history using this
priority order:

1. **Exact hostname match** -- `example.com` matches `https://example.com/any/path`
2. **Subdomain match** -- `example.com` matches `https://www.example.com/` or `https://blog.example.com/`
3. **Pathname contains** -- `blog/my-post` matches `https://example.com/blog/my-post`

When you pass a `scanId` parameter, it matches the exact scan number shown as `#N` in the
extension. `scanId` always takes priority over `url` if both are provided.

If no match is found for either parameter, the most recent page is returned (not an error).

---

## Working with Multiple Pages

The server keeps the last 5 analyzed pages in memory, newest first. Older pages are
automatically dropped when new ones arrive.

**Workflow for comparing pages:**

1. User analyzes Page A in Chrome
2. User analyzes Page B in Chrome
3. Call `list_analyzed_pages` to see both pages with their scan IDs
4. Call `get_seo_summary` with `scanId: 1` for Page A
5. Call `get_seo_summary` with `scanId: 2` for Page B
6. Compare the two summaries and provide recommendations

**Workflow for auditing a single page:**

1. User analyzes a page in Chrome
2. Call `get_page_issues` for a quick problem overview
3. If deeper analysis is needed, call `get_seo_data` for the full raw data
4. Reference specific fields from the data in your recommendations

History resets when the MCP server restarts (which happens when your AI IDE restarts).

---

## Lighthouse and Core Web Vitals Data

PageSpeed data is optional. It is only present when:

- The user has PageSpeed enabled (it runs by default, but can fail)
- The Google PageSpeed Insights API returned a successful response

To check if PageSpeed data is available:

1. Call `list_analyzed_pages` -- check the `Lighthouse:` status line for each page
2. Or call `get_seo_data` and check if `data.pageSpeed` exists

**Lighthouse status values:**

- `ok` -- `data.pageSpeed` contains scores, CWV metrics, and audit issues
- `failed` -- `data.pageSpeedFailed` is true, `data.pageSpeed` is absent
- `none` -- neither field is present (PageSpeed was not attempted)

**Score interpretation:**

| Score range | Rating |
| ----------- | ------ |
| 90-100 | Good (green) |
| 50-89 | Needs improvement (orange) |
| 0-49 | Poor (red) |

**CWV thresholds:**

| Metric | Good | Needs Improvement | Poor |
| ------ | ---- | ----------------- | ---- |
| LCP | <= 2.5s | <= 4.0s | > 4.0s |
| CLS | <= 0.1 | <= 0.25 | > 0.25 |
| INP | <= 200ms | <= 500ms | > 500ms |

---

## Schema Validation

The extension validates JSON-LD schema markup against Google's current requirements.
When interpreting schema data, be aware of these validation rules:

**Deprecated types** (removed from Google rich results):

- HowTo
- SpecialAnnouncement
- CourseInfo
- EstimatedSalary
- LearningVideo
- ClaimReview
- VehicleListing
- PracticeProblem
- Dataset

These types no longer generate rich results in Google Search. Recommend removing them or
replacing with supported types.

**Restricted types:**

- FAQPage -- limited to government and healthcare websites only (since August 2023)

**Common schema issues to flag:**

- Missing `@context` (required for all JSON-LD blocks)
- Using `http://schema.org` instead of `https://schema.org`
- Using deprecated types (see list above)
- Using FAQPage on non-government/healthcare sites

---

## Example Workflows

### Quick audit

User: "What are the SEO issues on this page?"

```text
1. Call get_page_issues
2. Read the critical/warnings/info arrays
3. Present findings grouped by severity
4. Suggest fixes for each issue, starting with critical ones
```

### Full audit

User: "Give me a complete SEO audit"

```text
1. Call get_seo_summary for the overview metrics
2. Call get_page_issues for the problem list
3. Call get_seo_data if you need detailed link/image/schema data
4. Present a structured report covering:
   - Page metadata (title, description, canonical)
   - Content structure (headings, word count)
   - Link profile (internal vs external, nofollow usage)
   - Image optimization (alt text coverage)
   - Schema markup (types, validation issues)
   - Social sharing (OG and Twitter Card completeness)
   - Performance (Lighthouse scores, CWV if available)
5. Prioritize recommendations by impact
```

### Page comparison

User: "Compare these two pages"

```text
1. Call list_analyzed_pages to see available pages
2. Call get_seo_summary for each page (using scanId or url)
3. Build a side-by-side comparison of key metrics
4. Highlight differences and recommend which page performs better
```

### Specific question

User: "Does this page have proper schema markup?"

```text
1. Call get_seo_data to get the full schema array
2. Check schema types against deprecated/restricted lists
3. Verify @context is present and uses https
4. Report on schema completeness and validity
```

### Content analysis

User: "Is the content well-optimized?"

```text
1. Call get_seo_summary for word count, heading structure
2. Call get_seo_data for detailed heading list and link data
3. Analyze:
   - Word count (300+ recommended)
   - Heading hierarchy (H1 > H2 > H3, no skipped levels)
   - Internal linking (are related pages linked?)
   - Image alt text (descriptive, keyword-relevant)
4. Provide content improvement suggestions
```

---

## Troubleshooting

### Server not starting

**Symptom:** MCP server not listed as connected in your IDE.

**Check:**

```bash
# Verify Node.js version
node --version
# Must be 18 or higher

# Verify dependencies are installed
ls mcp-server/node_modules/@modelcontextprotocol
# Should list the sdk directory

# If missing, install:
cd mcp-server && npm install
```

### Port 27608 already in use

**Symptom:** Server crashes with "EADDRINUSE" error.

**Fix:** Find and stop the process using the port:

```bash
# Linux/macOS
lsof -i :27608

# Windows
netstat -ano | findstr 27608
```

Then restart your IDE to restart the MCP server.

### No pages in history

**Symptom:** All tools return "No pages analyzed yet."

**Fix:**

1. Open a webpage in Chrome
2. Click the Connascent SEO extension icon
3. Click "Analyze Page"
4. Wait for the progress bar to complete
5. Check that the extension header shows a green dot

If the green dot does not appear, the extension cannot reach the MCP server. Verify the
server is running (check `/mcp` in Claude Code or `curl http://localhost:27608/status`).

### PageSpeed data missing

**Symptom:** `data.pageSpeed` is not present or `Lighthouse: none` in the page list.

**Causes:**

- The Google PageSpeed API returned an error (check `data.pageSpeedFailed`)
- Rate limiting (429) -- the user should add a free API key in extension Settings
- The analyzed URL was invalid for PageSpeed (localhost, chrome:// pages, etc.)
- PageSpeed request timed out (120s limit)

### Data is stale

**Symptom:** Data does not match what you see on the page.

**Note:** The MCP server stores snapshots in memory. Data reflects the page state at the
time of analysis, not the current state. Ask the user to re-analyze the page if they have
made changes.

---

## Configuration

### Environment variables

| Variable | Default | Description |
| -------- | ------- | ----------- |
| `AGENT_NAME` | "Claude Code" | Name shown in the extension's connection indicator |

Set `AGENT_NAME` to customize what appears in the extension header:

```json
{
  "mcpServers": {
    "connascent-seo": {
      "command": "node",
      "args": ["./mcp-server/server.js"],
      "env": {
        "AGENT_NAME": "My Custom Agent"
      }
    }
  }
}
```

### Fixed values

| Value | Setting | Notes |
| ----- | ------- | ----- |
| Port | 27608 | Fixed, bound to 127.0.0.1 (loopback only) |
| Max pages | 5 | Oldest pages auto-drop when new ones arrive |
| Payload limit | 1 MB | POST body size limit on /seo-data |
| Origin check | chrome-extension://, moz-extension:// | POST requests from other origins are rejected (403) |

---

## Limitations

- **No live DOM access** -- you receive a snapshot of the page at the time of analysis.
  You cannot query the page in real time or trigger actions on it.
- **No shadow DOM** -- the DOM analysis does not pierce shadow roots. Web components that
  use shadow DOM may have elements that are not captured.
- **List capping** -- links and images are capped at 500 items each. Pages with more
  elements will have truncated lists, but counts are always accurate.
- **Memory only** -- all data is stored in Node.js process memory. When the MCP server
  restarts (IDE restart), all history is lost.
- **Single user** -- the server is designed for a single user on localhost. It does not
  support authentication or multi-user access.
- **Mobile strategy only** -- PageSpeed Insights data is always for the mobile strategy.
  Desktop analysis is not available through the extension.

---

## SEO Reference Materials

The `seo-references/` directory in the project root contains reference documentation,
agent definitions, and skill guides for SEO analysis.

### Reference docs

| File | Contents |
| ---- | -------- |
| `google-seo-reference.md` | Google Search essentials, E-E-A-T, CWV, spam policies |
| `cwv-thresholds.md` | Core Web Vitals metrics, thresholds, and measurement details |
| `schema-types.md` | Schema.org structured data types and usage guidance |
| `eeat-framework.md` | E-E-A-T evaluation framework (Experience, Expertise, Authority, Trust) |
| `quality-gates.md` | Quality checks and gates for SEO audits |
| `schema-templates.json` | JSON-LD schema examples for common page types |

### Agent definitions (`seo-references/agents/`)

Specialized agent roles, each wired to use MCP tools from this extension as their
primary data source. Use these as system prompts or agent configs in your IDE.

| Agent | Specialty |
| ----- | --------- |
| `seo-content.md` | Content quality, E-E-A-T signals, readability, AI citation readiness |
| `seo-performance.md` | Core Web Vitals, PageSpeed scores, performance optimization |
| `seo-schema.md` | Schema.org detection, validation, JSON-LD generation |
| `seo-technical.md` | Crawlability, indexability, security, robots, canonical, hreflang |

### Skill guides (`seo-references/skills/`)

Detailed step-by-step workflows for specific SEO tasks. Each skill that works with
page data includes an MCP Data Source section explaining which tools to call first.

| Skill | Purpose |
| ----- | ------- |
| `seo-audit/` | Full website SEO audit with sub-skill delegation |
| `seo-page/` | Deep single-page analysis (on-page, content, technical, schema, images) |
| `seo-content/` | Content quality and E-E-A-T analysis with AI citation readiness |
| `seo-technical/` | Technical SEO across 9 categories (crawl, index, security, CWV, JS) |
| `seo-schema/` | Schema markup detection, validation, and JSON-LD generation |
| `seo-images/` | Image optimization (alt text, formats, responsive, lazy loading, CLS) |
| `seo-hreflang/` | Hreflang and international SEO validation and generation |
| `seo-performance/` | Core Web Vitals analysis (not a separate skill -- use the agent) |
| `seo-geo/` | AI search optimization (AI Overviews, ChatGPT, Perplexity, GEO) |
| `seo-competitor-pages/` | Competitor comparison and alternatives page generation |
| `seo-programmatic/` | Programmatic SEO planning for pages generated at scale |
| `seo-plan/` | Strategic SEO planning with industry-specific templates |

The `seo-plan/assets/` directory contains industry templates: `saas.md`,
`local-service.md`, `ecommerce.md`, `publisher.md`, `agency.md`, `generic.md`.

These files are not loaded by the MCP server -- they are reference material you can
read from disk when you need deeper context for SEO analysis and recommendations.
