site-spec

site-spec

ウェブサイトに欠けている、目に見えない基盤です。あらゆるサイトを監査し、問題を修正します。

エージェント向け

これをインストールするかどうか判断している AI コーディングエージェントの方へ：MCP サーバーを登録し、list_checks を呼び出してチェック ID を確認してから、URL に対して audit_site を呼び出してください。

claude mcp add site-spec -- npx -y site-spec-mcp

Gemini CLI：gemini extensions install https://github.com/ariaxhan/site-spec。

ツール引数、戻り値の形式、およびこのツールが適さないケースの詳細： llms.txt。

問題

AI は数秒で美しいウェブサイトを生成できます。AI が見られないのは、そのウェブサイトが見つけられ、ランキングされ、引用され、信頼されるかどうかを左右する部分、つまりピクセルの下にある機械可読な基盤です。robots.txt、構造化データ、llms.txt、canonical と noindex のシグナル、レスポンスヘッダー、アクセシビリティのセマンティクス、トラッカーと Cookie の使用状況などです。

このレイヤーはブラウザーでは見えません。また、AI が生成したほぼすべてのサイトで問題が生じています。ChatGPT をブロックする robots.txt の上に美しいヒーローセクションが載っていたり、無効または自己都合の JSON-LD があったり、Google からページを隠す余計な noindex があったり、GDPR に違反して訪問者の IP アドレスを漏らすフォントが使われていたりします。トラフィックがひそかに失われるまで、誰も気づきません。そして、ウェブ上で AI による生成が増えるほど、状況は悪化します。

解決策

site-spec は、あらゆるウェブサイトの基盤を検証し、修正するレイヤーです。構築方法は問いません。 URL を指定するだけです。サイトをクロールし、一連の決定論的なポリシーに照らして目に見えないレイヤー全体をチェックし、問題の正確なレポートを提示します。その後、機械的な問題を自動で修正し、人の対応が必要な箇所を正確に示します。

サイトが AI ビルダー、フレームワーク、CMS、手書きの HTML のどれで作られたかは問いません。基盤が正しいかどうかだけを確認します。

インストール不要ですぐに試す

site-spec.ariaxhan.workers.dev — URL を貼り付けると、レポートが表示されます。アカウントも登録も不要です。

ホスト版は CLI と同じ決定論的なエンジンを、ページ数を制限したクロール（4 ページ）で実行し、実行されたチェック、合格したチェック、実行されなかったチェックを明示します。機械可読な出力を得るには ?format=json を追加してください。

curl "https://site-spec.ariaxhan.workers.dev/audit?format=json&url=example.com"

壊れたリンク、欠落したアセット、axe によるアクセシビリティチェック、HTML 検証、schema.org 検証など、すべてのチェック項目を実行する場合や、fix コマンドを使う場合は、以下の CLI を使用してください。ホストされたエンドポイントが取得するのはパブリックな HTTP(S) ホストのみです。プライベート、ループバック、リンクローカルのアドレスは拒否されます。

使い方

Node 20 以降が必要です。アカウント、API キー、SaaS は不要です。

# 1. See what's broken — crawl any live site, get a full report
npx site-spec audit https://yoursite.com

# 2. Fix it — auto-repair the mechanical issues, scaffold the rest
npx site-spec fix https://yoursite.com --out ./fixed

fix は修正済みファイルを ./fixed に書き込みます（デフォルトでは既存のファイルを上書きしません）。実行した内容を正確に表示します。

✓ Fixed automatically (8)
  audit/robots-stale-token   robots.txt — Removed deprecated crawler block "anthropic-ai".
  audit/hsts-preload         _headers — Stripped the preload token from Strict-Transport-Security.
  audit/canonical-missing    admin/index.html — Inserted <link rel="canonical" href="https://…/admin/">.
  audit/og-missing           admin/index.html — Added Open Graph card from the page's title + description.
  audit/noindex              admin/index.html — Removed accidental noindex from <meta name="robots">.

✎ Scaffolded — needs your facts (2)
  audit/llms-missing         llms.txt — Scaffolded from page titles/descriptions; fill the TODO facts.
  audit/jsonld-missing       index.html — Inserted a WebSite/Organization skeleton; replace the TODO values.

⚠ Needs manual attention (3)
  audit/google-fonts-cdn     index.html — Self-host the woff2 files to stop the IP leak (GDPR).
  audit/img-dims-missing     index.html — <img> without width/height (layout shift).
  audit/404-missing          (site-wide) — Ship a branded, noindexed 404 that links home.

fixed 8, scaffolded 2, manual 3
wrote 4 file(s) to ./fixed

audit を CI に組み込み、エラーがある場合はゼロ以外の終了コードを返すようにして、デプロイを制御できます。どちらのコマンドもビルド／出力ディレクトリに対して実行できます。URL の代わりにパスを指定してください。

コーディングエージェントから利用する（MCP）

同じエンジンをMCPサーバーとして利用できます。つまり、サイトを生成したエージェントが、ウィンドウ間でレポートをコピーすることなく、目に見えないレイヤーのチェックや修復も行えます。

claude mcp add site-spec -- npx -y site-spec-mcp

[mcp_servers.site-spec]
command = "npx"
args = ["-y", "site-spec-mcp"]

Docker で利用する場合：docker run -i --rm -v $PWD:/data mcp/site-spec（監査または書き込みを行うディレクトリをマウントします）。

ツールは4つあります。

サーバーはエンジンを同一プロセス内で呼び出します。CLI をシェルから実行することも、ホスト型ワーカーを経由することもありません。3つの機能はすべて、1つのライブラリを共有する兄弟機能です。

flowchart LR
  A["MCP client<br/>(Claude Code, Codex)"] -- stdio JSON-RPC --> B["site-spec-mcp"]
  B --> C["@site-spec/core/io<br/>fetchSite · readSiteDir"]
  C -- "file map" --> D["@site-spec/core<br/>auditFiles · fixFiles · buildSite"]
  D -- "findings / files" --> B
  B -- "JSON" --> A

正直な制限が2つあります。詳しくはパッケージの READMEに記載されています。URLに対するfix_issueが返せるのは差分だけです（リモートサーバーには書き込めません）。また、ライブクロールでは、上限のあるクロールではファイルがサーバーに存在しないことを証明できないため、存在チェックは無効になります。

すべての検出結果は次の3つのいずれかに分類され、レポートでその分類を確認できます。

• ✓ 自動修正済み — 機械的に適用でき、事実に基づく判断を必要としない安全な修正です。 AI クローラーのブロック解除、不要になった robots トークンの削除、誤って設定された noindex の削除、クロールで判明した正規 URL の追加、既存のタイトルを使った Open Graph のひな形の作成、ズームがロックされたビューポートの修正、 自己評価を目的とする評価マークアップの削除、クロールしたページからの sitemap.xml の生成、ヘッダーの整理が含まれます。
• ✎ ひな形を作成 — llms.txt、JSON-LD エンティティ、メタディスクリプションなど、 実際の事実が必要な項目です。site-spec が TODO マーカー付きの正しいひな形を作成するので、 空欄を埋めるだけで済みます。
• ⚠ 手動対応 — ツールが勝手に推測してはならない問題です。alt テキストの欠落、 フォントのセルフホスト化、クライアント側でレンダリングされるシェルの修正、 リンク切れが該当します。無断で編集することなく、正確な対応方法を提示します。

fix はデフォルトでは非破壊的で、出力ディレクトリに書き込みます。ローカルディレクトリを 直接編集するには、--write を渡します。

基本理念

• 正しさはポリシーであり、プロンプトではありません。 SEO、アクセシビリティ、プライバシー、 構造化データのルールは、ツールが適用する明示的なチェックとして表現されます。 LLM に守るよう求める曖昧な指針にはしません。
• 決定論的です。 監査エンジンは純粋で、同じ入力にはバイト単位で同じレポートを返します。 ライブクロールでは検出したページを並べ替えてから上限を適用するため、同じサイトに 同じ --max を指定すれば、毎回同じページセットを監査します。エンジン内ではネットワークも ランダム性も使いません。
• 説教ではなく、修正します。 安全に修正できる検出結果は修正します。人間の対応が必要な場合は、 何をすべきかを明確に伝えます。
• ソースに依存しません。 ツールチェーンではなく、出力を監査します。AI、フレームワーク、 CMS、手書きのコードのいずれも、同じように扱います。

site-spec は当初、正しい基盤を備えたサイトを構築する決定論的なコンパイラーとして 始まりました（build コマンドと docs/ では今もその機能を扱っています）。 長く価値を発揮する機能は、その逆だとわかりました。サイト全体を生成するのではなく、 すでに存在するサイトの基盤を監査し、修復することです。

CLI の全オプション

site-spec audit <dir|url> [--max N] [--json] [--report report.md]
site-spec fix   <dir|url> [--out dir] [--write] [--max N] [--json]
site-spec build <site.config.mjs> --out <dir> [--target cloudflare|netlify|vercel|static]

• --max N — ライブクロールのページ上限（デフォルトは25）です。上限による切り捨ては報告され、無言で処理されることはありません。
• --report report.md — 監査結果を共有可能な Markdown ドキュメントとして書き出します。
• --json — スクリプトや CI 向けの、構造化された完全なレポートです。

インストール／開発

git clone https://github.com/ariaxhan/site-spec.git
cd site-spec
npm install
npm test          # unit + golden tests
npm run verify    # html-validate + JSON-LD + axe over the demo output

パッケージ

コントリビューション

コントリビューションを歓迎します。特に、新しいチェックや修正機能を歓迎します。 CONTRIBUTING.md をご覧ください。基本ルールとして、誤検知を減らすようチェックを調整し、 エンジンは純粋かつ決定論的に保ち、修正機能は人間が判断すべきことを決して勝手に推測しません。

ライセンス

Apache License 2.0。© 2026 Aria Han。