seohead-scripts

# seohead-scripts > Headless **Python** SEO toolkit by [seohead.tech](https://seohead.tech/tools) — > **11 SEO tools** exposed three ways: a **CLI** (`seohead`), an **MCP server** for > AI agents (Claude and any MCP client), and a local **HTTP API**. > No GUI, no desktop app — runs anywhere Python runs.    Everything is built on one platform-independent core (`seohead_scripts/core`). The CLI, MCP server, and HTTP API are thin faces over the same shared handlers, so a tool behaves identically no matter how you call it. ## Tools | # | Tool | CLI command | MCP tool | What it does | |---|------|-------------|----------|--------------| | 1 | SEO Parser | `parse` | `seo_parse` | Title, meta, canonical, OG/Twitter, H1–H6, JSON-LD, links, text, word count. | | 2 | Redirect Builder | `redirects-generate` | `seo_redirects_generate` | Generate Apache / Nginx / custom redirect rules from URL pairs. | | 3 | Redirect Checker | `redirects-check` | `seo_redirects_check` | Follow a live redirect chain and report every hop. | | 4 | Sitemap Analyser | `sitemap-crawl` | `seo_sitemap_crawl` | Recursively parse sitemap index/urlset (gzip), URL tree + duplicates. | | 5 | Image Downloader | `images-download` | `seo_images_download` | Download images by URL list, correct extension by content-type, skip existing. | | 6 | Image Optimizer | `images-optimize` | `seo_images_optimize` | Compress/convert/resize JPG, PNG, WebP, GIF, TIFF, SVG; before/after report. | | 7 | Keyword Clusterer | `keywords-cluster` | `seo_keywords_cluster` | Cluster keywords (K-Means, DBSCAN, Agglomerative) with TF-IDF. | | 8 | Robots Analyser | `robots-check` | `seo_robots_check` | Parse robots.txt, list sitemaps, test whether paths are crawlable (wildcards, `$`). | | 9 | Header Inspector | `headers-check` | `seo_headers_check` | SEO response headers (X-Robots-Tag, canonical Link, cache, HSTS), HTTP version, TTFB. | | 10 | Link Checker | `links-check` | `seo_links_check` | Find broken (4xx/5xx) links and links pointing at redirects on a page. | | 11 | hreflang Validator | `hreflang-check` | `seo_hreflang_check` | Extract and validate hreflang alternates (x-default, self-ref, duplicates). | Plus a bundled library of **SEO skills** for Claude Code under [`seohead_scripts/skills/`](seohead_scripts/skills). ## Install ```bash pip install "seohead-scripts[all]" # from source: pip install -e ".[all,dev]" ``` Extras: `mcp` (MCP server), `http` (HTTP API), `cluster` (Keyword Clusterer / scikit-learn), `all` (everything). Python 3.10+. ## CLI ```bash seohead --help seohead parse --url https://example.com seohead sitemap-crawl --url https://example.com/sitemap.xml --concurrency 3 seohead redirects-generate --format nginx --input '{"redirects":[{"from":"/a","to":"/b"}]}' seohead robots-check --url https://example.com --input '{"paths":["/blog?page=2"]}' seohead headers-check --url https://example.com seohead links-check --url https://example.com --internal-only seohead hreflang-check --url https://example.com seohead keywords-cluster --input '{"keywords":["...","..."],"algorithm":"kmeans","n_clusters":5}' ``` Primary input is `--input '<json>'` (mapped onto the tool arguments) or piped stdin JSON; a few convenience flags (`--url`, `--format`, `--concurrency`, ...) are also accepted. Output is pretty JSON on stdout; errors go to stderr with a non-zero exit. ## MCP server (for Claude / any MCP client) ```bash seohead mcp # stdio server ``` Register it with your MCP client (e.g. Claude Code) — see [`.mcp.json`](.mcp.json): ```json { "mcpServers": { "seohead-scripts": { "command": "seohead", "args": ["mcp"] } } } ``` All 11 tools are exposed as `seo_*` MCP tools with typed arguments. ## HTTP API ```bash seohead serve --host 127.0.0.1 --port 8722 ``` `GET /health` plus one `POST` endpoint per tool (`/parse`, `/redirects/generate`, `/sitemap/crawl`, `/robots/check`, ...). Set `SEO_API_TOKEN` to require a bearer token. ## Architecture ``` CLI (seohead <cmd>) ─┐ MCP (seohead mcp) ─┤──► seohead_scripts/servers/handlers.py ──► seohead_scripts/core/ HTTP (seohead serve) ─┘ (one shared layer) (pure tool logic) ``` - `core/` — pure per-tool logic (httpx, BeautifulSoup+lxml, Pillow, openpyxl, scikit-learn). - `servers/handlers.py` — the single source of truth mapping tool name → function. - `servers/mcp_server.py`, `servers/http_server.py`, `cli.py` — the three faces. ## Develop ```bash pip install -e ".[all,dev]" pytest # unit tests (tests_py/) ruff check . ``` Add a tool: write `core/<tool>.py` (pure functions) → add a handler in `servers/handlers.py` and to the `HANDLERS` registry (auto-exposed on the HTTP API) → add a `@mcp.tool()` in `servers/mcp_server.py` and a CLI command in `cli.py`. ## License MIT — see [LICENSE](LICENSE).