HelloGrowth CRM MCP

mcp-bot-crawler

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

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

特徴

• ボット管理のライフサイクル全体（スキャン、分析、検証、一覧表示、生成、提案、エクスポート）を網羅する8 つの MCP ツールに加え、さらに 80 個のツールがあります。全ツールカタログをご覧ください。
• よく知られたボットを 58 種収録した厳選データベース — 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 を優先したモジュール式のファイル構成で、安全でないパース処理はありません。

リポジトリ構成

HelloGrowthCRMwebsite_MCP/
├─ src/
│  ├─ index.ts                # entrypoint: loads .env, starts the MCP server
│  ├─ server.ts               # wires tools into ListTools / CallTool
│  ├─ tools/                  # 36 files — one per tool group, plus:
│  │  ├─ tool-types.ts        #   defineTool() / ok() / fail() helpers
│  │  ├─ index.ts             #   the registry every tool must be added to
│  │  └─ …                    #   bot governance, page content, and the
│  │                          #   website-mirror groups (see catalog below)
│  ├─ 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 (58 bots)
│  │  └─ website-mirror.ts    # read-mirror of the website source
│  ├─ lib/                    # supabase client, telemetry, client detection
│  ├─ middleware/             # MCP/SSE analytics hooks
│  ├─ reports/report-generator.ts
│  └─ utils/                  # types, logger, rate limiter
├─ crm-mcp-tools/             # standalone CRM tools (WhatsApp, calls, sequences)
├─ docs/                      # analytics, GA4 verification, release notes
│  └─ plans/                  # GEO/AEO master plan
├─ scripts/
│  ├─ verify-mcp-ga4.sh        # live GA4 telemetry check
│  ├─ geo-audit.sh             # re-derives every GEO plan finding; exit 1 on regression
│  └─ check-versions.mjs       # release gate: the 3 version strings must agree
├─ samples/
│  ├─ robots.txt
│  ├─ sitemap.xml
│  └─ sitemap-main.xml
├─ examples/usage.md
├─ server.json                # official MCP Registry manifest
├─ smithery.yaml              # Smithery configuration
├─ .env.example
├─ package.json
├─ tsconfig.json
├─ RELEASING.md               # version-bump procedure enforced by check-versions
└─ README.md

リポジトリには samples/access.log がありませんが、DEFAULT_ACCESS_LOG のデフォルト値はこのパスです。DEFAULT_ACCESS_LOG を実際のログに設定するか、 analyze_access_logs と export_bot_report に logPath / logText を明示的に渡してください。 reports/ は初回のエクスポート時に作成されます。

クイックスタート

これは単独のリポジトリです。以前のように hellocrmwebsite のサブディレクトリではありません。

git clone https://github.com/MeruLocal/HelloGrowthCRMwebsite_MCP.git
cd HelloGrowthCRMwebsite_MCP

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 対応クライアントであれば起動できます。

Graphify によるコード探索

Graphify は、トークン効率の高いコードクエリを実現するために、ローカル AST を構築します。「この関数を呼び出しているのは誰か」といった質問に、grep の 183K トークンではなく約 2K トークンで回答できます。クエリあたり 71 倍の削減です。

セットアップ

Graphify をインストールします。

pip install graphifyy

ナレッジグラフを構築します。

graphify update .

使用方法

グラフにクエリします。

graphify query "What calls the function X?"
graphify explain "Symbol Y"

または、Claude Code で /graphify を実行すると、対話形式でクエリできます。

Claude Desktop / Claude Code

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

{
  "mcpServers": {
    "bot-crawler": {
      "command": "node",
      "args": ["/absolute/path/to/HelloGrowthCRMwebsite_MCP/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)"
      }
    }
  }
}

またはホステッドサーバーを利用する（クローンもビルドも不要）

https://mcp.hellogrowthcrm.com でデプロイが稼働しています。Streamable HTTP のエンドポイントは /sse です。マニフェスト：https://hellogrowthcrm.com/.well-known/mcp.json。 バージョン／ステータス情報：GET /version はサーバー名、バージョン、ツール数とリソース数、変更履歴へのリンクを返します。バージョン間の変更内容については、CHANGELOG.md をご覧ください。

エンドポイントの変更： Streamable HTTP エンドポイントは /mcp から /sse に移動し、従来の SSE トランスポート（GET /sse + POST /message）は削除されました。 クライアントの接続先を https://mcp.hellogrowthcrm.com/sse に変更してください。

⚠️ ホステッド環境へのデプロイは main に遅れることがあり、ツール数ではそれがわかりません。 2026-08-05 時点では、ローカルの main と本番環境はどちらも同じ名前の 83 個のツールを公開していました。一方、本番環境では /pricing に対する fetch_page_content が wordCount: 0 を返していましたが、ローカルでは wordCount: 3194 を返していました。これは、本番環境が 2026-07-13 の抽出修正より前のものだったためです。

ツール数が一致していても、ビルドが一致しているとは限りません。一致しているかどうかは、動作でのみ判断できます。

2026-08-11 時点では両者は一致しており、本番環境と main はどちらも 88 個のツールを公開しています。この記載はリリースのたびに古くなるため、鵜呑みにせず、次の方法で再確認してください。

./scripts/geo-audit.sh     # C4 が両方で同じツールを呼び出し、差異があると失敗することを確認します

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 スニペットとともに、許可／監視／レート制限／ブロックを推奨します。
export_bot_report	REPORT_OUTPUT_DIR に Markdown／JSON／CSV レポートを書き出します。

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

ツールのアノテーション

88 個すべてのツールには、明示的な MCP アノテーション（readOnlyHint、 destructiveHint、idempotentHint、openWorldHint）が付いているため、クライアントは 人間の承認が必要な操作を判断できます。80 個のツールは読み取り専用です。書き込み可能なツールはちょうど 8 個で、 blog_create、blog_update、blog_revalidate、help_create_article、 help_update_article、newsletter_subscribe、newsletter_unsubscribe、 forms_submit です。また、9 個のツールは外部環境にアクセスします（ライブクロール、DNS 検証、 サイトの再検証）。分類は src/tools/annotations.ts にあり、起動時のガードと テストにより、エントリのないツールが登録されるとビルドが失敗します。

MCP ツールの全カタログ（88 個）

元の 8 つのボットガバナンスツールに加え、このサーバーは hellogrowthcrm.com のウェブサイト全体（すべてのモジュール、機能、製品、料金表、AI エージェント、インテグレーション）を MCP ツールとして公開します。ライブコンテンツ（ブログ、ヘルプ、ニュースレター、フォーム、ソーシャルプルーフ）は Supabase から提供され、それ以外はすべてウェブサイトのソースファイルを読み取り専用でミラーリングしたものです（WEBSITE_DATA_TOOLS.md をご覧ください）。

カテゴリ	ツール
ボットガバナンス（8）	scan_website_bots、analyze_access_logs、verify_bot_identity、list_allowed_bots、list_blocked_bots、generate_robots_txt、suggest_bot_policy、export_bot_report
ページコンテンツ（2）	fetch_page_content、crawl_pages — ライブページを取得（またはサイトマップをたどり）、タイトル、メタ情報、正規 URL、見出し、リンク、読み取り可能なテキストを返します
llms.txt コーパス（2）	generate_llms_txt、check_llms_txt — ミラーからグラウンディング用コーパス llms-full.txt を構築し、ライブファイルと比較します
GEO/AEO 診断（2）	check_ai_extractability、validate_sitemaps — <main> と <body> の読み取り可能なテキスト量を測定し、HTTP 200 を返しても抽出ツールからは空に見えるページを検出します。また、サイトマップインデックスを展開し、タイムアウト、接続リセット、5xx エラーが発生する子ページを検出します
ブログ（7）	blog_list、blog_get、blog_search、blog_create、blog_update、blog_revalidate、blog_get_categories
ヘルプセンター（6）	help_list_categories、help_list_articles、help_get_article、help_search、help_create_article、help_update_article
ニュースレター（4）	newsletter_subscribe、newsletter_unsubscribe、newsletter_get_subscribers、newsletter_get_stats
お問い合わせフォーム（4）	forms_submit、forms_list_submissions、forms_get_submission、forms_export_csv
静的コンテンツ（6）	content_list_case_studies、content_list_comparisons、content_get_comparison、content_list_industries、content_list_tools、content_get_seo_rules
料金（6）	pricing_get_plans、pricing_get_addons、pricing_get_faq、pricing_compare_plans、pricing_get_country_plans、pricing_get_managed_revops — CRM の段階は Free → Growth → Enterprise です。Managed RevOps はユーザーごとの料金プランではなく、月額固定のサービスリテイナーです
機能（3）	features_list、features_get、features_list_products
分析（1）	analytics_social_proof
国（2）	countries_list、country_get
会社（2）	company_get_profile、company_get_contacts
SEO（5）	seo_get_site_config、seo_get_hreflang、seo_get_canonical、seo_get_sitemaps、seo_get_schema
製品（2）	products_list、product_get
インテグレーション（3）	integrations_list、integrations_get、integrations_list_categories — 630 件のカタログ、116 カテゴリ
AI エージェント／エージェント型 AI（4）	agents_list、agents_get、agents_get_autonomy_levels、agents_list_comparisons — 12 のエージェント、自律性マトリックス、競合比較ページ 4 件
用語集（2）	glossary_list_terms、glossary_get_term — 58 件の用語
テンプレート（2）	templates_list、templates_get — 7 カテゴリに 42 件のテンプレート
機能ガイド（2）	guides_list、guides_get — 32 件のガイド
代替製品と移行（4）	alternatives_list、alternatives_get、switch_list_competitors、switch_get_guide — 42 件の代替製品ページ、26 件の乗り換えガイド
変更履歴（2）	changelog_list_releases、changelog_get_release — 6 件のリリース
サイトの FAQ（1）	faqs_get_site
メディア（2）	media_list_videos、media_list_testimonials
パートナープログラム（2）	partners_get_program、partners_get_application_schema
ソリューション（2）	solutions_list_whatsapp_use_cases、solutions_get_managed_revops — 9 件の市場別バリエーションと、米国の都市ページ 25 件を含みます

すべてのミラーツールは synced_at の出典情報を含み、入力を zod で検証します。 不明なスラッグが指定された場合は、有効な値を一覧表示する明確なエラーを返します。

synced_at は全体共通ではなく、ツールグループごとに設定されています — 2026-08-05 時点で、ツリー内の値は 2026-06-11（テンプレート、ガイド）から 2026-06-17 （インテグレーション）、さらに 2026-07-08（用語集、代替製品、エージェント）まで幅があります。サイト全体で同期日が一つだと想定せず、レスポンス内の synced_at を確認してください。

カタログのスモークテストを実行するには、npm run build && node test-tools.mjs を実行してください。

検出の仕組み

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 s）。
• サイトマップのページ数に上限を設定（MAX_SITEMAP_PAGES、デフォルトは 25）。
• HTTP タイムアウト（HTTP_TIMEOUT_MS、デフォルトは 10 s）。
• コンテンツは保存しません：サンプル取得から記録するのは 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	1 回のスキャンあたりの上限です。
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 です。
RATE_LIMIT_WINDOW_MS	60000	HTTP トランスポートのレート制限ウィンドウです。
RATE_LIMIT_MAX_REQUESTS	60	クライアント IP ごとのウィンドウあたりの最大リクエスト数です。
UPSTASH_REDIS_REST_URL	—	任意：共有レート制限ストアです（トークンと併せて設定してください）。これにより、スケールアウトしたインスタンス間でバケットが共有され、プロセスごとの管理ではなくなります。
UPSTASH_REDIS_REST_TOKEN	—	任意：共有レート制限ストア用のトークンです。
TRUST_PROXY_HEADERS	true	レート制限キーに CF-Connecting-IP／最後の X-Forwarded-For ホップを使用します。前段にプロキシを置かずに公開する場合に限り、false に設定してください。
ENABLE_MCP_ANALYTICS	false	MCP/SSE 分析のマスタースイッチです。送信するには true にする必要があります。
GA4_MEASUREMENT_ID	—	MCP/SSE 分析用の GA4 ストリーム ID（任意）です。
GA4_API_SECRET	—	GA4 Measurement Protocol API シークレット（任意）です。

プライバシーを最優先する MCP/SSE の利用状況分析（接続、リクエスト、ツール、ボット）は、 ENABLE_MCP_ANALYTICS=true かつ GA4_* 変数が設定されている場合にのみ GA4 に 送信されます。それ以外の場合は何も行われません。生の IP、User-Agent、リクエスト本文、 ツール引数が追跡されることはありません。docs/MCP_ANALYTICS.md を参照してください。

拡張

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

// 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             # vitest — 149 tests across 10 files
npm run test:watch   # vitest in watch mode
npm run test:coverage

テストは、対象コードの隣にある __tests__/ ディレクトリにあります （src/core/__tests__、src/tools/__tests__、src/lib/__tests__、 src/middleware/__tests__、src/data/__tests__）。

ライセンス

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

免責事項

このプロジェクトは、ご自身のウェブサイトとやり取りするボットの監視と管理を支援します。許可なく第三者のサイトをクロール、スクレイピング、分析する目的で使用しないでください。常に robots.txt、利用規約、および適用される法律を遵守してください。