librecrawl-technical-seo-audit-mcp: Skill for Claude Code

⚠️ MANDATORY RULES — read first, no exceptions

These are hard rules. If you skip any of them, the audit is broken from the user's perspective even if the MCP call succeeded.

Rule 1: ALWAYS save the zip locally

After librecrawl_audit_zip returns, you MUST decode the content_base64 and write it to a local file on the operator's machine. Use the user's current working directory (or ~/Downloads/<filename>). Use exactly the filename field from the response.

Pseudo-code your runtime should execute:

import base64, hashlib
data = base64.b64decode(content_base64)
local_path = filename   # the filename field from the response, e.g. "example.com-1a2b3c4d.zip"
with open(local_path, "wb") as f:
    f.write(data)
local_sha = hashlib.sha256(data).hexdigest()

You report the LOCAL path back to the user. NEVER report the zip_path field from the response as the deliverable — that path is on the remote server, not on the operator's local machine. The user cannot open it.

Rule 2: ALWAYS confirm the save

After writing the file, call librecrawl_audit_confirm_saved(session_id, sha256=local_sha) with the hash of the bytes you wrote. The server compares it with its own copy and only then deletes the session, artifacts, zip and upstream crawl record. A mismatch deletes nothing, so a failed save never loses the audit. Unconfirmed zips are swept after an hour.

auto_cleanup=True on librecrawl_audit_zip wipes in the same call. Use it only when your client cannot write files and call back.

Rule 3: After saving, verify + tell the user the LOCAL path

Pattern your final response on this:

Audit done. Saved locally: ./example.com-1a2b3c4d.zip (320 KB, sha256 confirmed by the server) Contents: SUMMARY.txt + PDF report + CSVs (per-page · sitemap-recon · external-links · content-audit · extended-checks). Server cleanup: passed.

If confirm_saved returns success: false, say which cleanup step failed (see its cleanup field) instead of claiming the server forgot everything.