seo-notary

SEO Notary

ウェブページが実際に返す内容を検証し、コーディングエージェントが修正して、その結果を証明できるようにします。

Claude Code、Cursor、VS Code、CI 向けの HTTP および実ブラウザーによるチェックです。決定論的で、LLM は使用せず、コマンドは 1 つです。

ステータス：0.1（早期リリース）。 API、ルールの出力、ルールの重大度は 0.x リリース間で変更される可能性があります。変更履歴をご覧ください。

コーディングエージェントはページのコードを編集できますが、ページが実際に返す内容を確認できません。クライアント側スクリプトがタイトルや canonical を上書きしたり、サーバー側レンダリングが失敗したり、リダイレクトがループしたりしても、エージェントは証拠なしに「完了」と報告します。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

この出力は、このリポジトリのデモを実際に実行した結果を抜粋したものです。タイトルと canonical を書き換えるスクリプトを削除すると、同じコマンドで 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 は操作上の失敗（不正な入力、ネットワーク、タイムアウト、ポリシー、ブラウザー）です。標準出力に JSON ドキュメントを 1 つだけ出力するには、--format json を使用します。詳細：docs/CLI.md。

エージェントから使用する

seo-notary mcp は、stdio 経由で 2 つのツール verify_url と get_rule_catalog を提供するローカル MCP サーバーを起動します。verify_url は 1 回の呼び出しで、構造化コンテンツとして完全なレポートを返し、短い要約も添えます。テスト済みの内容と未テストの内容、およびフロントエンド変更後の検証をエージェントに指示する AGENTS.md のスニペットについては、docs/MCP.md をご覧ください。

チェック内容

HTTP ステータス、リダイレクトチェーン、コンテンツタイプ、タイトル、メタディスクリプション、canonical リンク、robots ディレクティブ（meta と X-Robots-Tag）、生のレスポンス内の JSON-LD 構文をチェックします。--tier browser では、JavaScript 実行後にタイトル、canonical、robots meta、ディスクリプションが変化するかどうか、フレームワークのハイドレーションエラーメッセージ、捕捉されていないページエラー、コンソールエラー、失敗したリクエストをチェックします。ルールは合計 23 件です：docs/RULES.md。各ルールには、そのルールで証明できない内容も記載されています。

チェック対象外

• クロール、順位追跡、キーワードや被リンクのデータは扱わず、インデックス登録や順位についても主張しません。測定されたシグナルのみを報告します。
• LLM の呼び出しやコードのアップロードはありません。指定された URL を取得します。
• ホスト型サービスはありません。お使いのマシン上で動作します。
• 「ハイドレーションエラーを検出」は、コンソールメッセージに対するパターンマッチングであり、マークアップの不一致を証明するものではありません。
• どちらのモードでも、ブラウザーティアはピクセル単位の正確さを保証しません。

セキュリティ

ページのコンテンツは信頼できない証拠として扱われます。出力文字列から制御文字を除去し、長さを制限します。また、ページ内の内容を指示として扱うことはありません。ネットワークプロファイルは 2 種類あります。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 をご覧ください。

ライセンス

ソースコードはMIT ライセンスの下で公開されています。Raxocode および SEO Notary の名称とロゴはこのライセンスの対象外です。詳しくはTRADEMARK.mdをご覧ください。

Raxocodeが開発しました。プロジェクトサイト：seonotary.com。