geolint

geolint

AI 検索のための ESLint です。 AI 検索への対応状況を調べるためにウェブサイトをリントします — AI クローラーのアクセス、llms.txt、構造化データ、引用可能性をチェックします。

🇩🇪 Deutsch · 🇪🇸 Español · 🇯🇵 日本語

30 秒で始める

インストールも設定も不要です：

npx @iliasabk/geolint check yoursite.com

geolint はページ、その robots.txt、llms.txt を取得し、robots.txt に対して既知の AI クローラートークン 51 個を評価し、52 個の監査ルールを実行して、すべての指摘事項に具体的な修正方法を添えたスコア付きレポートを出力します。

理由

• AI による回答が新しいトップページです。 ChatGPT、Perplexity、Claude、Copilot、Google AI Overviews は、クローラーがページを取得して引用できるかどうかに応じて、トラフィックを送るかどうかを決めます。
• 多くのサイトは、意図せず AI クローラーをブロックしたり混乱させたりしています。 古い Disallow: /、ステージング環境で設定したままの noindex、JavaScript を実行しないボットには空に見えるクライアントレンダリングのページなどです。
• 既存のツールは、ブロックリストかスコアだけを表示するウェブアプリです。 すべてをブロックするよう指示するか、改善方法を示さず数値だけを提示します。geolint はリンターです。具体的な指摘と修正方法を示し、すべての PR で CI から実行できます。

チェック項目

5 カテゴリーにわたる 52 個のルールがあります。geolint rules ですべてのルールを一覧表示でき、docs/rules.md では各ルールのチェック内容、重要な理由、違反の修正方法を説明しています。

カテゴリー	ルール数	例
AI クローラーのアクセス	10	ai-crawler/search-bots-blocked、ai-crawler/wildcard-block-all、ai-crawler/user-fetch-bypass、ai-crawler/stale-tokens
llms.txt	12	llms-txt/missing、llms-txt/invalid-structure、llms-txt/broken-links、llms-txt/relative-links
構造化データ	7	schema/no-jsonld、schema/invalid-jsonld、schema/missing-article-fields
引用可能性	12	content/thin-content、content/no-h1、content/missing-dates、content/no-question-headings
技術基盤	11	technical/client-rendered、technical/https、technical/slow-response、technical/sitemap-missing

レポートの例

バンドルされているデモサイト（examples/demo-site、意図的に 2 つのボットをブロックしています）を監査した実際の出力です。幅に合わせて省略しています：

$ geolint check localhost:4173 --ignore technical/https

  geolint v0.2.1 — AI-search readiness
  http://localhost:4173/
  200 OK · text/html · TTFB 113ms · robots 200 · llms.txt 404

  ██████████████████████████░░░░  86/100  Grade B

  CATEGORIES
    AI Crawler Access     ███████░░░   70  ✗ 2 errors
    llms.txt              █████████░   92  ⚠ 1 warning · 1 hint
    Structured Data       █████████░   88  ⚠ 1 warning · 3 hints
    Citability            ████████░░   82  ⚠ 2 warnings · 3 hints
    Technical Foundation  ██████████  100  ✓ clean

  AI CRAWLER ACCESS — 49/51 allowed · 2 blocked
    OpenAI
      GPTBot                        ✓  training
      OAI-SearchBot                 ✓  search
      ChatGPT-User                  ✓  user-fetch
    Perplexity
      PerplexityBot                 ✗  search
      Perplexity-User               ✓  user-fetch
    Google
      Googlebot                     ✓  search
      Google-Extended               ✓  training
    … 51 tokens total, grouped by vendor …

  FINDINGS
    AI Crawler Access
      ✗ ai-crawler/search-bots-blocked  PerplexityBot is blocked by robots.txt — Perplexity cannot use your pages as AI answer sources
          fix: Remove the Disallow covering PerplexityBot in robots.txt, or add an explicit "Allow: /" for it.
          evidence: Disallow: / (matched by PerplexityBot)
    llms.txt
      ⚠ llms-txt/missing                No llms.txt found
          fix: Create /llms.txt at the site root: an H1 title, a short blockquote summary, and ## sections linking to your key content.
          evidence: http://localhost:4173/llms.txt → HTTP 404

  ────────────────────────────────────────────────────────────────────
  2 errors · 4 warnings · 7 hints · 32/44 checks passed

すべての指摘事項には、ルール ID、重要度、geolint が検出した証拠、修正方法が含まれます。2 つのページや競合サイトを並べて比較できます：

geolint check a.com --compare b.com

コマンド

コマンド	説明	主なフラグ
geolint check <url>	単一の URL を監査します	--format、--fail-under、--only/--ignore/--category、--compare、--baseline、--badge、--verbose
geolint crawl <url>	同一オリジンのページをクロールし、サイト全体を監査します	--max-pages、--max-depth、--concurrency、--fail-under
geolint init <url>	サイトをクロールして llms.txt を生成します	-o、--max-pages
geolint diff <old.json> <new.json>	2 つの JSON レポートを比較します：スコアの差分、追加／解決済みの指摘事項	—
geolint rules	52 個の監査ルールを一覧表示します	--category、--format table|json|markdown
geolint bots	既知の AI クローラー 51 種と、それぞれをブロックした場合の影響を一覧表示します	--format table|json
geolint mcp	AI アシスタント向けに stdio で MCP サーバーを実行します	--timeout

すべてのフラグについては、docs/configuration.md を参照してください。

CI で実行する

GitHub Action

- uses: iliasabk/geolint@v1
  id: geolint
  with:
    url: https://example.com
    fail-under: 80

- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: ${{ steps.geolint.outputs.sarif-file }}

このアクションは、スコア／グレードのステップ出力、GitHub code scanning 用の SARIF レポート、ジョブのサマリーや PR コメント用の Markdown レポートを生成します。SARIF のアップロード、PR コメントの単一コメントへの更新、ベースラインの乖離検出などのレシピについては、docs/github-action.md を参照してください。

その他の CI

npx @iliasabk/geolint check https://example.com --fail-under 80

スコアが基準値を下回った場合（または --baseline に対して指摘事項が悪化した場合）は終了コード 1、それ以外は 0 です。GitLab CI、CircleCI、npm スクリプト、デプロイ前フックで動作します。

スコアを README バッジとして表示する

npx @iliasabk/geolint check https://example.com --badge
# → writes geolint-badge.svg + prints the markdown snippet to paste

SVG をコミットするか、CI で shields endpoint JSON（--badge-endpoint）を再生成すると、古くならないバッジを利用できます。

出力形式

-f pretty（デフォルト）では、上記のターミナルレポートを表示します。機械処理用の形式は次のとおりです。

• -f json — 完全な ScanReport：指摘事項、カテゴリ別スコア、ボットアクセスマトリクス
• -f sarif — SARIF 2.1.0。GitHub code scanning に直接アップロードできます
• -f markdown — PR コメントやジョブのサマリーにそのまま使えるテーブル
• -f html — 自己完結型のインタラクティブレポート（スコアリング、指摘事項のフィルター、ボットマトリクス）。共有したり、任意の場所でホストしたりできます

-o report.json を追加するとファイルに書き込まれます。パイプで利用できるよう、標準出力はクリーンな状態に保たれます。

実際のウェブでの geolint

このリポジトリでは geolint 自身を実際に利用しています。夜間ワークフローで有名な 8 つのサイトを再監査し、スコアをコミットしています。また、ショーケースサイトでは、github.com、anthropic.com、stripe.com などのインタラクティブレポート全文を公開しており、main へのプッシュごとに再生成されます。

プログラムから利用する API

import { scan } from '@iliasabk/geolint';

const report = await scan('https://example.com', {
  ignore: ['technical/https'],
  timeout: 10_000,
});

console.log(report.score, report.grade);          // e.g. 86 'B'
for (const f of report.findings) {
  console.log(f.severity, f.ruleId, f.message, f.fix);
}

scan(url, options) は型付きの ScanReport を返します。ほかに、ボットレジストリ（AI_BOTS、botsByPurpose）、ルールレジストリ（allRules、ruleById）、robots.txt／llms.txt パーサー、バッジ生成機能、スコア計算機能、4 種類すべてのレポーターもエクスポートされています。

AI アシスタントから利用する（MCP）

geolint mcp は、stdio 経由で Model Context Protocol を利用します。Claude Desktop、Cursor、VS Code、Windsurf から、ネイティブツールとしてサイトの監査、llms.txt の生成、URL の比較を行えます。

// claude_desktop_config.json / ~/.cursor/mcp.json
{
  "mcpServers": {
    "geolint": {
      "command": "npx",
      "args": ["-y", "@iliasabk/geolint", "mcp"]
    }
  }
}

5 つのツール（audit_url、generate_llms_txt、compare_urls、list_rules、list_ai_bots）を利用できます。すべて読み取り専用で、構造化出力と呼び出しごとのタイムアウトに対応しています。各クライアントのセットアップ方法については、docs/mcp.md を参照してください。

ボットレジストリが要点です

geolint bots は、目的に応じた影響評価とともに、51 種類の AI クローラートークンを一覧表示します。「このボットをブロックすべきか？」への答えは、それぞれで異なるためです。

目的	例	ブロックした場合
training	GPTBot、ClaudeBot、CCBot	今後のトレーニングデータに含まれなくなります
search	OAI-SearchBot、PerplexityBot、Claude-SearchBot	現在の AI の回答に表示されなくなります
user-fetch	ChatGPT-User、Claude-User	現在の AI の回答に表示されなくなります
mixed	Bytespider、Amazonbot、Diffbot	両方に影響します

また、ほかのツールが見落とす 2 つの注意点があります。

• robots.txt を無視するフェッチャーもあります。 OpenAI、Perplexity、Meta は、ユーザー操作で起動するフェッチャー（ChatGPT-User、Perplexity-User、Meta-ExternalFetcher）が robots.txt を遵守しない場合があると説明しています。ai-crawler/user-fetch-bypass は、Disallow が機能しない場合を知らせます。その場合は、代わりに WAF／認証レイヤーで適用してください。
• 古いトークン。 anthropic-ai、Claude-Web、FacebookBot は廃止されています。ai-crawler/stale-tokens はこれらを検出し、置き換え先のトークンを示します。User-agent: anthropic-ai ルールは、現在は何の効果もありません。

Google-Extended や Applebot-Extended などの制御専用トークンは、フェッチを一切行わず、設定の指定のみを行います。geolint はこの違いを踏まえて扱います。

geolint が正直に説明すること

• llms.txt は提案であり、標準ではありません。 大手 AI ベンダーで読み取りを約束しているところはありません。そのため、llms-txt/* の検出結果はエラーではなく、警告やヒントとして重み付けされます。それでも geolint がチェックし（geolint init で生成もします）、導入が広がっており、必要なのはファイル 1 つだけだからです。
• 相関関係 ≠ 因果関係。 引用／統計／出典が回答内でのシェアを測定可能なほど高めることや、Googlebot と Applebot 以外の AI クローラーが JavaScript を実行しないことなど、引用可能性に関するルールは公開済みの GEO 研究に基づいています。一方で、疑問形の見出しのようなシグナルはヒントであり、事実ではありません。そのため、これらは重大度が info であると geolint は明示しています。
• すべてのルールに、その理由が示されています。 docs/rules.md では各ルールの存在理由を説明しています。調査元は docs/research-notes.md にあり、各ボットの robots.txt に対する挙動の根拠となるベンダーのドキュメントも含まれています。
• ボットレジストリは単独でも参照できます。 docs/ai-crawlers.md には、追跡対象のすべてのトークンについて、目的、ベンダーごとの robots.txt に対する挙動、ベンダーのドキュメントを掲載しています。これは geolint bots と MCP ツール list_ai_bots が公開するデータと同じです。

代替ツールとの比較

	目的に応じたボットレジストリ	ベンダーごとの robots.txt に対する挙動	CI で実行	検出結果ごとの修正方法	llms.txt を生成	無料／OSS
geolint	✅	✅	✅	✅	✅	✅
ai.robots.txt 形式のブロックリスト	❌	❌	n/a	❌	❌	✅
GEO 最適化スキル／プロンプトパック	❌	❌	❌	❌	❌	さまざま
llms.txt バリデーター	❌	❌	一部	一部	一部	✅
ホスト型 GEO 監査ウェブアプリ	一部	❌	❌	一部	❌	❌

各列の詳細とその根拠については、docs/comparison.md をご覧ください。geolint には MCP サーバー、スコアバッジ、回帰ベースラインも付属します。

ロードマップ

v0.4 以降で予定している項目：

• geolint watch — デプロイ時／ファイル変更時に再監査
• プロジェクト固有のチェックに対応するカスタムルール API
• スキーマの対応範囲を拡大（@type バリデーターを追加）
• Homebrew のフォーミュラ
• 英語以外のレポートのローカライズ

コントリビューション

Issue や PR を歓迎します。CONTRIBUTING.md をご覧ください。新しいルールは特に歓迎します。それぞれに check(ctx)、fix を含む検出結果、テスト、ドキュメントへの記載が必要です。

ライセンス

MIT · 変更履歴 · セキュリティ

---

geolint が役に立ったら、⭐ を付けていただけると、ほかの人にも見つけてもらいやすくなります。