SEO Notary MCP server

SEO Notary

Verify what a web page really returns, so your coding agent can fix it and prove it.

HTTP and real-browser checks for Claude Code, Cursor, VS Code and CI. Deterministic. No LLM. One command.

Status: 0.1 (early release). APIs, rule output and rule severities may still change between 0.x releases; see the changelog.

Coding agents edit page code but cannot see what the page actually serves. Client-side scripts overwrite titles and canonicals, server rendering breaks, redirects bounce, and the agent reports "done" without evidence. SEO Notary fetches the page, runs deterministic rules over the response and the rendered DOM, and returns structured findings with stable exit codes.

$ seo-notary verify http://127.0.0.1:4173/broken --tier browser
FAIL http://127.0.0.1:4173/broken
tier browser (faithful), 1153 ms, 0 redirects, HTTP 200
  title        Acme Widgets | Handmade widgets for every workshop
  canonical    http://127.0.0.1:4173/broken
  rendered DOM
  title        Loading...
  canonical    https://staging.acme.example/broken

2 errors, 0 warnings, 0 info; 20 rules passed

ERROR   RENDER_TITLE_DIFFERS  head > title
  The title changes after JavaScript runs.
  raw:      Acme Widgets | Handmade widgets for every workshop
  rendered: Loading...
  fix: Make the server-rendered title and the client-rendered title agree.
$ echo $?
1

That output is abridged from a real run of the demo in this repository. Remove the script that rewrites the title and canonical and the same command prints PASS and exits 0.

Quickstart

Requires Node >=22.19.0.

# Tier 1: raw HTTP and HTML. No browser, nothing to download.
npx seo-notary verify http://localhost:3000/

# Tier 2: also render the page in Chromium and compare raw vs rendered.
npx seo-notary install-browser
npx seo-notary verify http://localhost:3000/ --tier browser

To run from a checkout instead: npm install && npm run build, then node packages/cli/dist/bin.js verify .

Exit codes: 0 pass, 1 findings at or above --fail-on (default error), 2 operational failure (bad input, network, timeout, policy, browser). Use --format json for exactly one JSON document on stdout. Details: docs/CLI.md.

Use it from an agent

seo-notary mcp runs a local MCP server over stdio with two tools: verifyurl and getrulecatalog. verifyurl returns the full report as structured content plus a short summary, in one call. See docs/MCP.md for what has and has not been tested, and for an AGENTS.md snippet that tells agents to verify after frontend changes.

What it checks

HTTP status, redirect chain, content type, title, meta description, canonical link, robots directives (meta and X-Robots-Tag) and JSON-LD syntax in the raw response. With --tier browser: whether the title, canonical, robots meta and description change after JavaScript runs, framework hydration error messages, uncaught page errors, console errors and failed requests. 23 rules in total: docs/RULES.md. Each lists what it does not prove.

What it does not do

• No crawling, rank tracking, keyword or backlink data, and no claims about indexing or ranking. It reports measured signals only.
• No LLM calls and no code uploads. It fetches the URL you give it.
• No hosted service. It runs on your machine.
• "Hydration error detected" is pattern matching on console messages, not proof of a markup mismatch.
• The browser tier is not pixel-accurate in either mode.

Security

Shortened. The full README is on GitHub.