seo-notary

Name: seo-notary
Author: raxocode

本地服务

seonotary.com商业与营销32 周前更新

代码仓库访问官网

关于 seo-notary

SEO Notary 是面向开发者和编码 Agent 的本地 CLI 与 MCP 服务，用于检查网页的 HTTP 响应和浏览器渲染结果。它以确定性规则生成结构化发现，不调用大模型，也不上传代码。

主要功能

01检查 HTTP 响应与 HTML
02可选 Chromium 渲染
03对比原始与渲染页面状态
04结构化报告与稳定退出码
0523 条确定性规则

适用场景

01前端改动后验证 SEO 信号
02检测 JavaScript 对元数据的修改
03在 CI 中检查重定向和 HTTP 响应

MCP 相关

通过 stdio 运行本地 MCP 服务，提供 `verify_url` 和 `get_rule_catalog` 工具。验证工具会返回结构化报告和简短摘要。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "raxocode-seo-notary": {
      "command": "npx",
      "args": [
        "-y",
        "seo-notary"
      ]
    }
  }
}

启动命令npx -y seo-notary

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmseo-notary0.1.0stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
url	string	是	要检查的绝对 http(s) URL，例如 http://localhost:3000/pricing
mode	enum	否	仅适用于 browser 层级。faithful（默认）会加载所有内容；lean 会阻止图片、媒体和字体加载lean \| faithful
tier	enum	否	http（默认）检查原始响应；browser 还会渲染页面并比较原始内容与渲染结果http \| browser
fail_on	enum	否	使报告状态判定为失败的最低严重级别。默认值为 errorerror \| warning \| info
timeout_ms	integer	否	总时间预算，单位为毫秒

详细介绍

SEO Notary

验证网页实际返回的内容，让你的编码 Agent 能够修复问题并提供验证证据。

适用于 Claude Code、Cursor、VS Code 和 CI 的 HTTP 与真实浏览器检查。结果确定。无需大模型。一条命令即可运行。

状态：0.1（早期版本）。 API、规则输出和规则严重性在 0.x 版本间仍可能发生变化；请参阅更新日志。

编码 Agent 可以编辑页面代码，却无法查看页面实际提供的内容。客户端脚本会覆盖标题和规范链接，服务端渲染会出错，重定向会循环跳转，而 Agent 却在没有证据的情况下报告“已完成”。SEO Notary 会获取页面，对响应和渲染后的 DOM 运行确定性规则，并返回包含稳定退出码的结构化结果。

$ 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

该输出是本仓库中演示实际运行结果的删节版。移除重写标题和规范链接的脚本后，同一条命令会输出 PASS 并以 0 退出。

快速开始

需要 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

若要从代码检出目录运行：先执行 npm install && npm run build，然后运行 node packages/cli/dist/bin.js verify <url>。

退出码：0 表示通过，1 表示发现达到或超过 --fail-on（默认为 error）阈值的问题，2 表示操作失败（输入错误、网络、超时、策略或浏览器问题）。使用 --format json 可让标准输出仅包含一个 JSON 文档。详情见：docs/CLI.md。

在 Agent 中使用

seo-notary mcp 会通过 stdio 运行本地 MCP 服务，提供两个工具：verify_url 和 get_rule_catalog。verify_url 一次调用即可返回完整报告作为结构化内容，并附带简短摘要。关于已测试和未测试的内容，以及一段指导 Agent 在前端变更后进行验证的 AGENTS.md 片段，请参阅 docs/MCP.md。

检查内容

检查原始响应中的 HTTP 状态、重定向链、内容类型、标题、元描述、规范链接、robots 指令（meta 和 X-Robots-Tag）以及 JSON-LD 语法。使用 --tier browser 时，还会检查 JavaScript 运行后标题、规范链接、robots meta 和描述是否发生变化、框架水合错误消息、未捕获的页面错误、控制台错误以及失败的请求。共 23 条规则：docs/RULES.md。每条规则都会列出其无法证明的内容。

不会做什么

不会抓取网站、追踪排名或提供关键词、反向链接数据，也不会声称页面已被收录或获得排名。它只报告测得的信号。
不会调用大模型，也不会上传代码。它只获取你提供的 URL。
不提供托管服务。它在你的机器上运行。
“检测到水合错误”是基于控制台消息进行的模式匹配，并不能证明标记存在不匹配。
两种模式下，浏览器层都无法做到像素级准确。

安全

页面内容是不可信的证据：输出字符串会剥除控制字符并限制长度，且页面中的任何内容都不会被视为指令。提供两种网络配置：local（默认）允许验证 localhost 和私有主机；strict 仅允许公共主机。重定向绝不会从公共主机转到私有地址。限制和注意事项（包括浏览器层尽力而为的拦截机制）见 docs/SECURITY.md。如需报告漏洞，请参阅 SECURITY.md。尚未进行第三方安全审计。

软件包

软件包	用途
`seo-notary`	CLI 和本地 MCP 服务
`seo-notary-core`	架构、网络策略、获取器、规则和报告。不依赖浏览器
`seo-notary-browser`	可选的 Playwright 适配器

开发

需要 Node >=22.19.0。

npm install
npm run build
npm run typecheck && npm run lint
npm test                 # unit and integration
npm run test:security    # network policy
npm run test:browser     # needs Chromium: npx playwright-core install --only-shell chromium
npm run test:smoke       # packs and installs the packages into an empty directory
npm run demo             # serves the broken/fixed demo on http://127.0.0.1:4173

文档：架构、CLI、MCP、规则、威胁模型、决策。贡献指南：CONTRIBUTING.md。