How cnych/seo-mcp works
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).