refactor(compose)!: make seo-tools a standalone application

[siva01c]

Stacked on #7 — merge that first, and GitHub will retarget this to main.

seo-tools is a standalone application and this is a public repository, so docker-compose.yml should describe the app and nothing about where it runs. It didn't: the mcp service carried one particular deployment's shared token file, reverse-proxy vhost labels, external network and a bind mount into a sibling website checkout. A clean clone could not start it at all.

Note on the history. The first commit here took the opposite approach — it kept the deployment as the base and added docker-compose.standalone.yml as an escape hatch, with the frontend mount defaulting to ../ludekkvapil/public/seo. That was reviewed and rejected. The second commit inverts it; the overlay file is deleted. Read 5be77d0 for the shape that lands.

Why base-as-app is the only layering that works

Compose merges overlays additively. A network or volume in the base file can never be subtracted by an overlay — only added to. So "deployment as base, standalone as overlay" needs ${VAR:-…} parameterisation to fake subtraction, while "app as base, deployment as overlay" composes naturally. The rejected approach was fighting the tool.

What the base file loses

removed	why
env_file: ../.env.shared	a file that only exists in one deployment tree
VIRTUAL_HOST, LETSENCRYPT_HOST, VIRTUAL_PORT, VIRTUAL_PROTO, VIRTUAL_NETWORK, HTTPS_METHOD	reverse-proxy discovery labels, inert without that proxy
networks: [agentic-ops] + the top-level networks: block	an external network the clone cannot create
../ludekkvapil/public/seo mount	a sibling repo; now ${SEO_FRONTEND_DIR:-./storage/frontend}
docker-compose.standalone.yml	with the base standalone, nothing left to override

Comments that narrated one particular VPS were rewritten to state the constraint rather than the host — "only a trusted reverse proxy may set X-Forwarded-For" survives, the topology doesn't. Same for mcp-server.ts and docs/security.md.

NODE_ENV=production and the mandatory SEO_MCP_TOKEN stay. Requiring a token is the right posture for anything listening on a socket, standalone included — a tokenless default is how an open endpoint happens. .env.example already documents openssl rand -hex 24.

BREAKING CHANGE

Deployments needing a proxy, an external network or extra mounts must supply their own overlay and pass both -f flags:

docker compose -f docker-compose.yml -f /path/to/your-deployment.yml up -d mcp

Relative paths inside the overlay resolve against the base file's directory, not the overlay's.

Verification

• base + a deployment overlay reproduces the previous production config byte-identically (captured before, diffed after)
• docker compose config mcp on the base alone: no external network, every volume source inside the repo
• no deployment specifics left in tracked files — only example domains in docs and the repo's own check-no-internal-refs.sh pattern; that guard still passes
• tsc --noEmit clean, 275 tests pass

End-to-end in a fresh clone with no sibling files, on branch #7's code: crawled 25 pages of a real site in 46s with 0 errors, generated all reports, ran the MCP server with auth enabled, and completed a full MCP handshake — initialize, tools/list (crawl, get_report, list_reports), prompts/list (seo-consultant-marek), and prompts/get returning the persona with the audit report injected. No external network, nothing attached to agentic-ops.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.