Hellogrowthcrmmcp

mcp-bot-crawler

ウェブサイトとやり取りするすべてのボット（検索エンジン、AI クローラー、SEO ツール、ソーシャルプレビュー取得ツール、セキュリティスキャナー、その他多数の不審なスクリプト）を検出、特定、管理するための MCP（Model Context Protocol）サーバーです。MCP 対応のクライアント（Claude Desktop、Cursor、Claude Code、カスタム Agent SDK アプリなど）に接続し、トラフィックについて自然言語で質問できます。

設計上、礼儀正しい動作を徹底しています。robots.txt を尊重し、自身のフェッチをレート制限し、正直な User-Agent を通知し、いかなる制御も回避しようとしません。

特徴

• ボット管理のライフサイクル全体（スキャン、分析、検証、一覧表示、生成、提案、エクスポート）をカバーする 8 つの MCP ツール。
• 55 種類以上の著名なボットを収録した厳選データベース — Googlebot、Bingbot、GPTBot、ChatGPT-User、ClaudeBot、PerplexityBot、Amazonbot、Google-Extended、Applebot-Extended、FacebookBot、LinkedInBot、AhrefsBot、SemrushBot、Bytespider など。それぞれにカテゴリ、運営者、基準リスク、逆引き DNS 検証用サフィックスがタグ付けされています。
• 動作に基づくリスクスコアリング：UA の照合、robots.txt の遵守状況、エラー率、リクエスト率、ユニークパスへのアクセスの広がりを組み合わせて、0～100 のスコアと推奨アクション（allow / monitor / rate-limit / block / verify-identity）を算出します。
• PTR とフォワード DNS による暗号学的強度の本人確認（Google、Microsoft、OpenAI が文書化しているのと同じ方法）。
• Allow/Disallow の最長一致のセマンティクスに適切に対応した robots.txt + sitemap.xml パーサー。
• Markdown、JSON、CSV 形式のレポート。
• TypeScript を優先したモジュール型のファイル構成で、安全でないパース処理はありません。

リポジトリの構成

mcp-bot-crawler/
├─ src/
│  ├─ index.ts                # entrypoint: loads .env, starts the MCP server
│  ├─ server.ts               # wires tools into ListTools / CallTool
│  ├─ tools/                  # one file per MCP tool
│  │  ├─ scan-website-bots.ts
│  │  ├─ analyze-access-logs.ts
│  │  ├─ verify-bot-identity.ts
│  │  ├─ list-allowed-bots.ts
│  │  ├─ list-blocked-bots.ts
│  │  ├─ generate-robots-txt.ts
│  │  ├─ suggest-bot-policy.ts
│  │  ├─ export-bot-report.ts
│  │  ├─ tool-types.ts
│  │  └─ index.ts
│  ├─ core/                   # detection engine
│  │  ├─ bot-detector.ts
│  │  ├─ aggregator.ts
│  │  ├─ log-parser.ts
│  │  ├─ robots-parser.ts
│  │  ├─ reverse-dns.ts
│  │  └─ crawler.ts           # polite HTTP client
│  ├─ data/known-bots.ts      # signature database
│  ├─ reports/report-generator.ts
│  └─ utils/                  # types, logger, rate limiter
├─ samples/
│  ├─ access.log              # realistic mixed-bot traffic
│  ├─ robots.txt
│  └─ sitemap.xml
├─ examples/usage.md
├─ reports/                   # generated reports land here
├─ .env.example
├─ package.json
├─ tsconfig.json
└─ README.md

クイックスタート

# From the hellocrmwebsite repo root:
cd mcp-bot-crawler

cp .env.example .env          # already pre-configured for hellogrowthcrm.com

npm install
npm run build

stdio で実行します。

node dist/index.js

または、開発モードで実行します（ビルド手順不要。tsx を使用）。

npm run dev

サーバーは stdio 経由で MCP を使用します。MCP 対応のクライアントであれば、どれでも起動できます。

Claude Desktop / Claude Code

claude_desktop_config.json（またはクライアント内の同等の mcpServers ブロック）に以下を追加します。

{
  "mcpServers": {
    "bot-crawler": {
      "command": "node",
      "args": ["/absolute/path/to/hellocrmwebsite/mcp-bot-crawler/dist/index.js"],
      "env": {
        "DEFAULT_TARGET_URL": "https://hellogrowthcrm.com",
        "DEFAULT_ACCESS_LOG": "/var/log/nginx/access.log",
        "CRAWLER_USER_AGENT": "mcp-bot-crawler/1.0 (+https://hellogrowthcrm.com/bot-info)"
      }
    }
  }
}

8 つの MCP ツール

ツール	機能
scan_website_bots	礼儀正しいライブスキャン：robots.txt、サイトマップ、サンプルページをアクセスログと照合します。
analyze_access_logs	Apache/Nginx Combined 形式のログを解析し、リスクスコア付きのボット別概要を返します。
verify_bot_identity	特定の (ip, userAgent) ペアに対して、PTR とフォワード DNS による検証を行います。
list_allowed_bots	現在のポリシーで許可されているボットを一覧表示します（デフォルトの厳選リスト、またはライブの robots.txt）。
list_blocked_bots	現在のポリシーでブロックされているボットを一覧表示します（デフォルトの高リスクリスト、またはライブの robots.txt）。
generate_robots_txt	ポリシーに基づく robots.txt 生成ツール（AI / SEO / スクレーパー / セキュリティスキャナーのブロック、サイトマップの宣言、Crawl-delay の設定）。
suggest_bot_policy	ログで確認された各ボットに対し、理由と貼り付けてすぐに使える nginx スニペットを添えて、allow / monitor / rate-limit / block を提案します。
export_bot_report	REPORT_OUTPUT_DIR に Markdown / JSON / CSV 形式のレポートを書き出します。

ペイロードの例は examples/usage.md にあります。

検出の仕組み

1. User-Agent の照合。 src/data/known-bots.ts のシグネチャデータベースでは、既知の各ボットに対して、大文字と小文字を区別しない UA パターンを 1 つ以上定義しています。最初に一致したものが採用されるため、より具体的なシグネチャを先に配置します（例：汎用の Googlebot よりも Googlebot-Image を先に配置）。
2. 汎用的なヒューリスティック。 シグネチャに一致しない場合は、自動化を示す手がかり（bot、crawler、spider、python-requests、headless など）を探し、検証対象としてフラグを付けたうえで、ソースを unknown に分類します。
3. 行動情報による補足。 アクセスログを利用できる場合、アグリゲーター（src/core/aggregator.ts）がヒット数、ユニーク IP 数、エラー率、リクエスト率、ユニークパス数、およびその UA に対して robots.txt で Disallowed とされているパスへのリクエスト数を算出します。これらのシグナルはリスクスコアを調整し、人が読める注記を出力します。
4. ID の検証。 信頼度の高いシグネチャには、記録された PTR サフィックス（.googlebot.com、.search.msn.com など）を使用します。verify_bot_identity は逆引き DNS を実行してサフィックスを確認した後、IP が一致することを確かめるために正引きを行います。なりすましの Googlebot は spoofed として表示されます。

リスクスコア

ボットごとの基本リスクはシグネチャ DB にあります（0 = 信頼できる検索エンジン、100 = 悪意のあるスクレーパー）。アグリゲーターは、次の条件に応じてスコアを加算します。

• ボットが robots.txt を無視する（+20）
• リクエスト率が非常に高い（1000 req/hr 超で +25、300 req/hr 超で +10）
• エラー率が 50% 超 — 探索行動（+15）
• ユニークパス数が 5000 超（+10）

推奨アクションは、最終スコアとカテゴリに基づいて決まります。

• search/social が 25 以下 → 許可
• ai が 40 以下 → 監視
• スコアが 70 以上 → ブロック
• スコアが 45 以上 → レート制限
• unknown → ID を検証

環境の許容度に応じて、src/core/bot-detector.ts でこれらのしきい値を調整してください。

セキュリティと礼儀

• 外部へのフェッチでは robots.txt を尊重します。scan_website_bots は、自身の UA に対して Disallowed とされているパスを取得しません。
• ホストごとのレートリミッター（CRAWL_DELAY_MS、既定値は 1 秒）。
• サイトマップページ数の上限（MAX_SITEMAP_PAGES、既定値は 25）。
• HTTP タイムアウト（HTTP_TIMEOUT_MS、既定値は 10 秒）。
• コンテンツは保存しません。サンプル取得で記録するのは URL と HTTP ステータスのみです。
• 連絡先 URL を含む 正直な User-Agent を使用します。CRAWLER_USER_AGENT で変更できます。
• stdout は MCP 専用です。すべてのログは stderr に出力します。

ツールが認証、CAPTCHA、ペイウォール、WAF、その他のアクセス制御を回避しようとすることはありません。また、入力から任意のコードを受け付けることもありません。

設定

すべての設定値は .env にあります（.env.example を参照）。

変数	既定値	用途
DEFAULT_ACCESS_LOG	./samples/access.log	フォールバックのログパス。
DEFAULT_TARGET_URL	https://example.com	スキャン対象サイトのフォールバック。
MAX_SITEMAP_PAGES	25	スキャンごとの上限。
CRAWL_DELAY_MS	1000	ホストごとの遅延。
HTTP_TIMEOUT_MS	10000	リクエストごとのタイムアウト。
CRAWLER_USER_AGENT	mcp-bot-crawler/1.0 (+...)	外部へのリクエストで使用する UA。
REPORT_OUTPUT_DIR	./reports	エクスポート先。
LOG_LEVEL	info	error / warn / info / debug。

拡張

新しいボットを追加するには：

// src/data/known-bots.ts
{
  name: "MyCorpBot",
  category: "search",
  operator: "MyCorp",
  userAgentPatterns: [/MyCorpBot/i],
  verifiedHostnameSuffixes: [".mycorp.com"],
  respectsRobotsTxt: true,
  baselineRisk: 10,
  description: "MyCorp search index crawler.",
}

新しいツールを追加するには：

1. { definition, schema, handle } をエクスポートする src/tools/<name>.ts を作成します。
2. src/tools/index.ts の tools 配列に追加します。

それ以外（登録、スキーマ検証、エラー処理）はすべて自動で行われます。

開発

npm run dev          # run with tsx, no build needed
npm run typecheck    # strict TS check
npm run build        # compile to dist/
npm test             # (add your own tests under src/__tests__/)

ライセンス

MIT — LICENSE を参照してください。

免責事項

このプロジェクトは、ご自身のウェブサイトとやり取りするボットの観察と管理を支援します。許可なく第三者のサイトをクロール、スクレイピング、分析するために使用しないでください。常に robots.txt、利用規約、および適用される法律を尊重してください。 "# mcp-bot-crawler-hellogrowthcrm"