# cnych/seo-mcp architecture

> Architecture diagram of the GitHub repository cnych/seo-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cnych/seo-mcp
- Repository: https://github.com/cnych/seo-mcp

## Overview

##### Project Type and Purpose
- This is a Python-based microservice (“seo-mcp”) that exposes an MCP (Model Control Protocol) API for SEO data retrieval from Ahrefs.
- It handles end‐to‐end flow: solving Cloudflare CAPTCHAs via CapSolver, authenticating with Ahrefs, fetching data (backlinks, keywords, traffic), caching results, and returning structured responses.

##### File Structure Analysis
- Top level:
- main.py – entrypoint script
- pyproject.toml – build/dependency config
- src/seo_mcp/ – core package
- src/seo_mcp/server.py – HTTP/MCP server definitions
- src/seo_mcp/*.py – feature modules (backlinks, keywords, traffic, logger)
- assets/ – static assets or documentation
- No separate “frontend” directory: it’s purely a backend service.
- Configuration and deployment hints: uses “uv” (Uvicorn) for serving, environment variable CAPSOLVER_API_KEY.

##### Key Components
A. MCP Client / CLI
- Cursor IDE or any MCP-compatible client invokes the service via a command (e.g. `uvx --python 3.10 seo-mcp`).
B. Entrypoint (main.py)
- Parses args, loads environment vars, kicks off the server.
C. Server Layer (server.py)
- Defines endpoints/tools: get_backlinks_list, keyword_generator, get_traffic, keyword_difficulty.
- Uses FastAPI or a similar ASGI framework under Uvicorn (“uv”).
D. Feature Modules
- backlinks.py, keywords.py, traffic.py – each encapsulates logic to:
1. Solve CAPTCHA via CapSolver service
2. Authenticate with Ahrefs
3. Request specific data
4. Process and format the response
E. Cache / Logger (logger.py)
- Implements caching of results to reduce repeated API calls and costs.
F. External Services
- CapSolver API – solves Cloudflare Turnstile CAPTCHAs
- Ahrefs API – provides backlink, keyword, traffic data

##### Relationships and Data Flows
1. MCP Client → Entrypoint/CLI
2. Entrypoint → ASGI Server
3. Server Endpoint → Cache layer (check)
4. If miss: Server Endpoint → CapSolver → CAPTCHA token
5. Server Endpoint → Ahrefs (with CAPTCHA token) → Raw SEO data
6. Server Endpoint → Format data → Cache/store → Response to client

##### Architectural Patterns and Design Principles
- Single‐service, modular design: separate modules for each SEO feature.
- Dependency inversion: server module depends on feature interfaces, not concrete implementations.
- Caching layer isolating API cost concerns.
- Externalizing secrets via environment variables.
- ASGI non-blocking I/O for external HTTP calls (to CapSolver and Ahrefs).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        MCPClient["MCP Client / CLI"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        Entry["Entrypoint (main.py)"]:::internal
        Server["server.py (ASGI Server)"]:::internal
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        Init["__init__.py"]:::internal
        Backlinks["backlinks.py (Backlink Logic)"]:::internal
        Keywords["keywords.py (Keyword Logic)"]:::internal
        Traffic["traffic.py (Traffic Logic)"]:::internal
        LoggerCache["logger.py (Cache/Logger)"]:::cache
    end

    %% External Services Layer
    subgraph "External Services"
        CapSolver["CapSolver API"]:::external
        Ahrefs["Ahrefs API"]:::external
        EnvVar["CAPSOLVER_API_KEY (Env Var)"]:::env
    end

    %% Miscellaneous
    Config["pyproject.toml"]:::internal
    Assets["assets/"]:::internal

    %% Connections
    MCPClient -->|"invokes"| Entry
    Entry -->|"starts ASGI server"| Server

    Server -->|"routes to modules"| Backlinks
    Server --> Backlinks
    Server --> Keywords
    Server --> Traffic

    Backlinks -->|"cache lookup"| LoggerCache
    Keywords -->|"cache lookup"| LoggerCache
    Traffic -->|"cache lookup"| LoggerCache

    Backlinks -->|"solve captcha"| CapSolver
    Keywords --> CapSolver
    Traffic --> CapSolver

    CapSolver -->|"captcha token"| Backlinks
    CapSolver --> Keywords
    CapSolver --> Traffic

    Backlinks -->|"fetch data"| Ahrefs
    Keywords --> Ahrefs
    Traffic --> Ahrefs

    Ahrefs -->|"raw SEO data"| Backlinks
    Ahrefs --> Keywords
    Ahrefs --> Traffic

    Backlinks -->|"format & store"| LoggerCache
    Keywords --> LoggerCache
    Traffic --> LoggerCache

    LoggerCache -->|"cached result"| Server
    Server -->|"response"| MCPClient

    %% Click Events
    click MCPClient "https://github.com/cnych/seo-mcp/blob/main/main.py"
    click Entry "https://github.com/cnych/seo-mcp/blob/main/main.py"
    click Server "https://github.com/cnych/seo-mcp/blob/main/src/seo_mcp/server.py"
    click Backlinks "https://github.com/cnych/seo-mcp/blob/main/src/seo_mcp/backlinks.py"
    click Keywords "https://github.com/cnych/seo-mcp/blob/main/src/seo_mcp/keywords.py"
    click Traffic "https://github.com/cnych/seo-mcp/blob/main/src/seo_mcp/traffic.py"
    click LoggerCache "https://github.com/cnych/seo-mcp/blob/main/src/seo_mcp/logger.py"
    click Init "https://github.com/cnych/seo-mcp/blob/main/src/seo_mcp/__init__.py"
    click Config "https://github.com/cnych/seo-mcp/blob/main/pyproject.toml"
    click Assets "https://github.com/cnych/seo-mcp/tree/main/assets/"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000
    classDef external fill:#90EE90,stroke:#000
    classDef cache fill:#FFA500,stroke:#000
    classDef client fill:#E6E6FA,stroke:#000
    classDef env fill:#FFFFE0,stroke:#000
```
