# seoskillsai/seo-skills-ai architecture

> Architecture diagram of the GitHub repository seoskillsai/seo-skills-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seoskillsai/seo-skills-ai
- Repository: https://github.com/seoskillsai/seo-skills-ai

## Overview

SEO Skills is an AI-agent-oriented SEO audit and optimization suite with a deterministic Python engine. A user invokes an audit through the MCP server or directly; the audit fetches a page, parses its HTML, validates structured data, and returns scores and issues. Review-only remediation can turn audit findings into suggested snippets. Separate tools cover crawling, regression tracking, search analytics, performance, indexing, and content discovery. The supplied excerpts show the main audit and MCP paths; several other capabilities are documented in the README but their internal wiring was not sampled.

Main entry points: [`scripts/mcp_server.py`](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/mcp_server.py) (MCP tools), [`scripts/full_audit.py`](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/full_audit.py) (Full audit), [`scripts/drift_compare.py`](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/drift_compare.py) (Drift comparison), [`scripts/fetch_page.py`](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/fetch_page.py) (Page fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent interfaces"]
  node_mcp["MCP tools<br/>[mcp_server.py]"]
end

subgraph group_audit["Audit engine"]
  node_full_audit["Full audit<br/>[full_audit.py]"]
  node_fetch["Page fetcher<br/>[fetch_page.py]"]
  node_parser["HTML parser<br/>[parse_html.py]"]
  node_schema["Schema validator"]
  node_remediation["Patch suggestions"]
  node_crawler["Site crawler<br/>[site_crawler.py]"]
  node_drift["Drift comparison<br/>[drift_compare.py]"]
end

subgraph group_analytics["Search analytics"]
  node_google_auth["Google credentials"]
  node_gsc["Search Console<br/>[gsc_query.py]"]
  node_ga4["GA4 reporting<br/>[ga4_report.py]"]
end

subgraph group_optimization["SEO tools"]
  node_keyword["Keyword analysis"]
  node_information_gain["Information gain"]
  node_llms["LLMs.txt builder"]
  node_discover["Discover RSS"]
  node_consent["Consent validator<br/>[consent_mode.py]"]
  node_speculation["Speculation rules"]
  node_parasite["Reputation scanner<br/>[parasite_seo.py]"]
  node_pagespeed["PageSpeed check<br/>[pagespeed_check.py]"]
  node_indexing["Indexing notifier<br/>[indexing_notify.py]"]
  node_bing["Bing Webmaster<br/>[bing_webmaster.py]"]
  node_dataforseo["DataForSEO adapter<br/>[dataforseo_api.py]"]
  node_firecrawl["Firecrawl adapter<br/>[firecrawl_api.py]"]
end

subgraph group_safety["Shared safeguards"]
  node_http["JSON HTTP client<br/>[http_json.py]"]
  node_url_safety["URL policy<br/>[url_safety.py]"]
  node_path_safety["Output path policy<br/>[path_safety.py]"]
end

node_user(("SEO user"))

node_user -->|"invokes tools"| node_mcp
node_mcp -->|"dispatches audit"| node_full_audit
node_mcp -->|"dispatches validation"| node_schema
node_mcp -->|"dispatches comparison"| node_drift
node_mcp -->|"dispatches query"| node_gsc
node_mcp -->|"dispatches report"| node_ga4
node_full_audit -->|"fetches page"| node_fetch
node_full_audit -->|"parses HTML"| node_parser
node_full_audit -->|"validates schemas"| node_schema
node_remediation -->|"runs audit"| node_full_audit
node_fetch -->|"checks targets"| node_url_safety
node_gsc -->|"refreshes token"| node_google_auth
node_gsc -->|"sends query"| node_http
node_ga4 -->|"uses credentials"| node_google_auth
node_ga4 -->|"requests report"| node_http
node_http -->|"validates endpoint"| node_url_safety
node_crawler -->|"fetches pages"| node_fetch
node_crawler -->|"parses pages"| node_parser
node_drift -->|"fetches page"| node_fetch
node_drift -->|"parses page"| node_parser
node_llms -->|"writes safely"| node_path_safety
node_discover -->|"writes safely"| node_path_safety
node_user -->|"runs crawl"| node_crawler
node_user -->|"checks drift"| node_drift
node_user -->|"analyzes topics"| node_keyword
node_user -->|"scores novelty"| node_information_gain
node_user -->|"builds llms.txt"| node_llms
node_user -->|"builds feeds"| node_discover
node_user -->|"checks consent"| node_consent
node_user -->|"checks standards"| node_speculation
node_user -->|"scans reputation"| node_parasite
node_user -->|"checks performance"| node_pagespeed
node_user -->|"notifies indexing"| node_indexing
node_user -->|"queries webmaster"| node_bing
node_user -.->|"uses adapter"| node_dataforseo
node_user -.->|"uses adapter"| node_firecrawl

click node_mcp "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/mcp_server.py"
click node_full_audit "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/full_audit.py"
click node_fetch "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/fetch_page.py"
click node_parser "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/parse_html.py"
click node_schema "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/schema_validator.py"
click node_remediation "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/remediation_engine.py"
click node_crawler "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/site_crawler.py"
click node_drift "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/drift_compare.py"
click node_google_auth "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/google_installed_app.py"
click node_gsc "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/gsc_query.py"
click node_ga4 "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/ga4_report.py"
click node_http "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/http_json.py"
click node_url_safety "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/url_safety.py"
click node_path_safety "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/path_safety.py"
click node_keyword "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/analyze_keywords.py"
click node_information_gain "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/information_gain.py"
click node_llms "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/llms_txt_builder.py"
click node_discover "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/discover_rss_builder.py"
click node_consent "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/consent_mode.py"
click node_speculation "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/speculation_rules.py"
click node_parasite "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/parasite_seo.py"
click node_pagespeed "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/pagespeed_check.py"
click node_indexing "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/indexing_notify.py"
click node_bing "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/bing_webmaster.py"
click node_dataforseo "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/dataforseo_api.py"
click node_firecrawl "https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/firecrawl_api.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_user toneBlue
class node_full_audit,node_fetch,node_parser,node_schema,node_remediation,node_crawler,node_drift toneAmber
class node_google_auth,node_gsc,node_ga4 toneMint
class node_keyword,node_information_gain,node_llms,node_discover,node_consent,node_speculation,node_parasite,node_pagespeed,node_indexing,node_bing,node_dataforseo,node_firecrawl toneRose
class node_http,node_url_safety,node_path_safety toneIndigo
```

## Components

### Agent interfaces

- [MCP tools](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/mcp_server.py): `scripts/mcp_server.py`

### Audit engine

- [Full audit](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/full_audit.py): `scripts/full_audit.py`
- [Page fetcher](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/fetch_page.py): `scripts/fetch_page.py`
- [HTML parser](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/parse_html.py): `scripts/parse_html.py`
- [Schema validator](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/schema_validator.py): `scripts/schema_validator.py`
- [Patch suggestions](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/remediation_engine.py): `scripts/remediation_engine.py`
- [Site crawler](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/site_crawler.py): `scripts/site_crawler.py`
- [Drift comparison](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/drift_compare.py): `scripts/drift_compare.py`

### Search analytics

- [Google credentials](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/google_installed_app.py): `scripts/google_installed_app.py`
- [Search Console](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/gsc_query.py): `scripts/gsc_query.py`
- [GA4 reporting](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/ga4_report.py): `scripts/ga4_report.py`

### SEO tools

- [Keyword analysis](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/analyze_keywords.py): `scripts/analyze_keywords.py`
- [Information gain](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/information_gain.py): `scripts/information_gain.py`
- [LLMs.txt builder](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/llms_txt_builder.py): `scripts/llms_txt_builder.py`
- [Discover RSS](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/discover_rss_builder.py): `scripts/discover_rss_builder.py`
- [Consent validator](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/consent_mode.py): `scripts/consent_mode.py`
- [Speculation rules](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/speculation_rules.py): `scripts/speculation_rules.py`
- [Reputation scanner](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/parasite_seo.py): `scripts/parasite_seo.py`
- [PageSpeed check](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/pagespeed_check.py): `scripts/pagespeed_check.py`
- [Indexing notifier](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/indexing_notify.py): `scripts/indexing_notify.py`
- [Bing Webmaster](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/bing_webmaster.py): `scripts/bing_webmaster.py`
- [DataForSEO adapter](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/dataforseo_api.py): `scripts/dataforseo_api.py`
- [Firecrawl adapter](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/firecrawl_api.py): `scripts/firecrawl_api.py`

### Shared safeguards

- [JSON HTTP client](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/http_json.py): `scripts/http_json.py`
- [URL policy](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/url_safety.py): `scripts/url_safety.py`
- [Output path policy](https://github.com/seoskillsai/seo-skills-ai/blob/main/scripts/path_safety.py): `scripts/path_safety.py`

### Other components

- **SEO user**

## Connections

- SEO user → MCP tools: invokes tools (evidence: `README.md`)
- MCP tools → Full audit: dispatches audit (evidence: `scripts/mcp_server.py`)
- MCP tools → Schema validator: dispatches validation (evidence: `scripts/mcp_server.py`)
- MCP tools → Drift comparison: dispatches comparison (evidence: `scripts/mcp_server.py`)
- MCP tools → Search Console: dispatches query (evidence: `scripts/mcp_server.py`)
- MCP tools → GA4 reporting: dispatches report (evidence: `scripts/mcp_server.py`)
- Full audit → Page fetcher: fetches page (evidence: `scripts/full_audit.py`)
- Full audit → HTML parser: parses HTML (evidence: `scripts/full_audit.py`)
- Full audit → Schema validator: validates schemas (evidence: `scripts/full_audit.py`)
- Patch suggestions → Full audit: runs audit (evidence: `scripts/remediation_engine.py`)
- Page fetcher → URL policy: checks targets (evidence: `scripts/fetch_page.py`)
- Search Console → Google credentials: refreshes token (evidence: `scripts/gsc_query.py`)
- Search Console → JSON HTTP client: sends query (evidence: `scripts/gsc_query.py`)
- GA4 reporting → Google credentials: uses credentials (evidence: `scripts/ga4_report.py`)
- GA4 reporting → JSON HTTP client: requests report (evidence: `scripts/ga4_report.py`)
- JSON HTTP client → URL policy: validates endpoint (evidence: `scripts/http_json.py`)
- Site crawler → Page fetcher: fetches pages (evidence: `scripts/site_crawler.py`)
- Site crawler → HTML parser: parses pages (evidence: `scripts/site_crawler.py`)
- Drift comparison → Page fetcher: fetches page (evidence: `scripts/drift_compare.py`)
- Drift comparison → HTML parser: parses page (evidence: `scripts/drift_compare.py`)
- LLMs.txt builder → Output path policy: writes safely (evidence: `scripts/llms_txt_builder.py`)
- Discover RSS → Output path policy: writes safely (evidence: `scripts/discover_rss_builder.py`)
- SEO user → Site crawler: runs crawl (evidence: `README.md`)
- SEO user → Drift comparison: checks drift (evidence: `README.md`)
- SEO user → Keyword analysis: analyzes topics (evidence: `README.md`)
- SEO user → Information gain: scores novelty (evidence: `README.md`)
- SEO user → LLMs.txt builder: builds llms.txt (evidence: `README.md`)
- SEO user → Discover RSS: builds feeds (evidence: `README.md`)
- SEO user → Consent validator: checks consent (evidence: `README.md`)
- SEO user → Speculation rules: checks standards (evidence: `README.md`)
- SEO user → Reputation scanner: scans reputation (evidence: `README.md`)
- SEO user → PageSpeed check: checks performance (evidence: `README.md`)
- SEO user → Indexing notifier: notifies indexing (evidence: `README.md`)
- SEO user → Bing Webmaster: queries webmaster (evidence: `README.md`)
- SEO user → DataForSEO adapter: uses adapter (evidence: `README.md`)
- SEO user → Firecrawl adapter: uses adapter (evidence: `README.md`)