# SEO Audit MCP

[![npm (core)](https://img.shields.io/npm/v/@seo-audit/core?label=core)](https://npmjs.com/@seo-audit/core)
[![npm (cli)](https://img.shields.io/npm/v/@seo-audit/cli?label=cli)](https://npmjs.com/@seo-audit/cli)
[![npm (local-mcp)](https://img.shields.io/npm/v/@seo-audit/local-mcp?label=local-mcp)](https://npmjs.com/@seo-audit/local-mcp)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

A comprehensive SEO auditing tool suite. Run audits via **CLI**, **Local MCP** (stdio), or **Remote MCP** (HTTP).

## Features

| Check                | What It Detects                                               |
| -------------------- | ------------------------------------------------------------- |
| **Meta Tags**        | Missing/invalid title, description, viewport, Open Graph tags |
| **Sitemap**          | Validate `sitemap.xml` existence and structure                |
| **Robots.txt**       | Validate `robots.txt` rules and directives                    |
| **Broken Links**     | Scan page for broken/404 links                                |
| **Headings**         | Analyze h1–h6 hierarchy compliance                            |
| **Duplicate Titles** | Detect duplicate or poorly formed page titles                 |
| **Keyword Density**  | Analyze keyword frequency and density                         |

## Packages

All packages are published to npm under the `@seo-audit` scope.

| Package                 | npm                                            | Description                               | Type         |
| ----------------------- | ---------------------------------------------- | ----------------------------------------- | ------------ |
| `@seo-audit/core`       | [npm](https://npmjs.com/@seo-audit/core)       | Shared audit logic                        | Library      |
| `@seo-audit/cli`        | [npm](https://npmjs.com/@seo-audit/cli)        | Command-line interface (`seo-audit`)      | CLI          |
| `@seo-audit/local-mcp`  | [npm](https://npmjs.com/@seo-audit/local-mcp)  | MCP server over stdio (`seo-audit-mcp`)   | MCP (local)  |
| `@seo-audit/remote-mcp` | [npm](https://npmjs.com/@seo-audit/remote-mcp) | MCP server over HTTP (`seo-audit-remote`) | MCP (remote) |

## Quick Start (No Install)

```bash
# CLI — audit any website
npx @seo-audit/cli https://example.com

# Local MCP — run as an MCP server
bunx @seo-audit/local-mcp
```

## Installation

### CLI

```bash
npm install -g @seo-audit/cli
seo-audit https://example.com
```

### Local MCP (for MCP clients)

```bash
npm install -g @seo-audit/local-mcp
seo-audit-mcp
```

## CLI Usage

```bash
seo-audit [options] <url>

Arguments:
  url                    Website URL to audit (e.g. https://example.com)

Options:
  -c, --checks <checks>  Comma-separated checks to run.
                         Available: meta-tags, sitemap, robots-txt,
                         broken-links, headings, duplicate-titles,
                         keyword-density
  -t, --timeout <ms>     Request timeout (default: 15000)
  -C, --concurrency <n>  Concurrency for link checking (default: 5)
  -j, --json             Output as JSON
  -V, --version          Show version
  -h, --help             Display help
```

### Examples

```bash
# Full audit
npx @seo-audit/cli https://example.com

# Specific checks only
npx @seo-audit/cli https://example.com --checks meta-tags,headings

# JSON output
npx @seo-audit/cli https://example.com --json

# Higher timeout for slow sites
npx @seo-audit/cli https://example.com --timeout 30000
```

## MCP Server Setup

### Claude Desktop

Add to `claude.json`:

```json
{
  "mcpServers": {
    "seo-audit": {
      "command": "bunx",
      "args": ["@seo-audit/local-mcp"]
    }
  }
}
```

### OpenCode

Add to `opencode.json`:

```json
{
  "mcp": {
    "seo-audit": {
      "type": "local",
      "command": ["bun", "x"."-y", "@seo-audit/local-mcp"],
      "enabled": true
    }
  }
}
```

### MCP Tools

Once connected, the following tools are available:

| Tool                     | Description                    |
| ------------------------ | ------------------------------ |
| `audit`                  | Run all SEO checks (or subset) |
| `check_meta_tags`        | Check meta tags                |
| `check_sitemap`          | Validate sitemap.xml           |
| `check_robots_txt`       | Validate robots.txt            |
| `check_broken_links`     | Find broken links              |
| `check_headings`         | Analyze heading structure      |
| `check_duplicate_titles` | Check duplicate titles         |
| `check_keyword_density`  | Analyze keyword density        |

## Remote MCP

```bash
# Install
npm install -g @seo-audit/remote-mcp

# Run the server
seo-audit-remote

# (Default: http://localhost:3456)
```

```bash
curl -X POST http://localhost:3456/call \
  -H "Content-Type: application/json" \
  -d '{"name":"audit","arguments":{"url":"https://example.com"}}'
```

## Architecture

```
MCP Clients (Claude Desktop, OpenCode, etc.)
        │                     │
    stdio │                 HTTP │
        ▼                     ▼
┌──────────────┐    ┌──────────────────┐
│ local-mcp    │    │ remote-mcp       │
│ (stdio)      │    │ (Express)        │
└──────┬───────┘    └────────┬─────────┘
       │                     │
       └──────────┬──────────┘
                  ▼
         ┌──────────────┐
         │ core         │
         │ (audit logic)│
         └──────────────┘
                  │
                  ▼
         ┌──────────────┐
         │ cli          │
         │ (commander)  │
         └──────────────┘
```

## Development

This is a **Bun monorepo** using workspaces.

```bash
# Prerequisites
curl -fsSL https://bun.sh/install | bash

# Install dependencies
bun install

# Build all packages
bun run build

# Run from source (no build needed)
bun run dev:cli      # CLI
bun run dev:local    # Local MCP
bun run dev:remote   # Remote MCP

# Lint, format, typecheck
bun run lint
bun run format:check
bun run typecheck
```

### Publish a Package

```bash
cd packages/<name>
npm publish --access public
```

## Tech Stack

**Runtime:** Bun / Node.js 20+  
**Language:** TypeScript  
**Bundler:** tsdown  
**Linting/Formatting:** oxlint / oxfmt  
**MCP:** @modelcontextprotocol/sdk  
**HTML Parsing:** Cheerio  
**Validation:** Zod  
**CLI:** Commander  
**HTTP:** Express (remote-mcp)

## License

MIT