HelloGrowth CRM MCP

mcp-bot-crawler

一个 MCP（Model Context Protocol）服务，可帮助你发现、识别和管理所有与网站交互的机器人——搜索引擎、AI 爬虫、SEO 工具、社交媒体预览抓取器、安全扫描器，以及大量可疑脚本。将它接入任何兼容 MCP 的客户端（Claude Desktop、Cursor、Claude Code、自定义 Agent SDK 应用等），然后用自然语言询问流量相关问题。

它的设计以礼貌为先：遵守 robots.txt、限制自身抓取速率、使用真实的 User-Agent，并且绝不试图绕过任何控制措施。

功能

• 八个 MCP 工具，覆盖完整的机器人治理生命周期（扫描、分析、验证、列出、生成、建议、导出）——另外还有 80 个工具，参见完整 MCP 工具目录。
• 包含 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 记录的相同方法）。
• robots.txt + sitemap.xml 解析器：正确处理最长匹配的 Allow/Disallow 规则。
• 提供 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，以便高效利用 token 进行代码查询。你可以用它回答“谁调用了此函数”之类的问题：每次查询约需 2K 个 token，而使用 grep 则需 183K 个 token——每次查询减少 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: 3194，在生产环境却返回 wordCount: 0，因为生产环境尚未包含 2026-07-13 的提取修复。

工具数量相同不代表构建版本相同，只有行为才能说明这一点。

截至 2026-08-11，两者已一致：生产环境和 main 均有 88 个工具。 与其相信这行信息 — 每次发布后它都会过时 — 不如重新验证：

./scripts/geo-audit.sh     # 检查 C4 是否通过两个环境调用相同工具，并在出现差异时失败

八个 MCP 工具

工具	功能
scan_website_bots	礼貌地实时扫描：robots.txt + 站点地图 + 示例页面，并与您的访问日志进行关联。
analyze_access_logs	解析 Apache/Nginx Combined 格式的日志，并返回带风险评分的各 Bot 摘要。
verify_bot_identity	对特定 (ip, userAgent) 组合进行 PTR + 正向 DNS 验证。
list_allowed_bots	当前策略允许的 Bot（默认为精选列表，或使用实时 robots.txt）。
list_blocked_bots	当前策略屏蔽的 Bot（默认为高风险列表，或使用实时 robots.txt）。
generate_robots_txt	由策略驱动的 robots.txt 生成器（屏蔽 AI／SEO／爬虫／安全扫描器，声明站点地图，设置 Crawl-delay）。
suggest_bot_policy	针对日志中观察到的每个 Bot，给出允许／监控／限速／屏蔽建议及其理由，并提供可直接粘贴的 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 个 Bot 治理工具，此服务还将 hellogrowthcrm.com 网站的全部内容 — 每个模块、功能、产品、定价表、AI Agent 和集成 — 都作为 MCP 工具提供。实时内容（博客、帮助、新闻通讯、表单、社会证明）由 Supabase 提供；其他内容均为网站源文件的只读镜像（见 WEBSITE_DATA_TOOLS.md）。

类别	工具
Bot 治理（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 — 获取实时页面（或遍历站点地图），并返回标题、meta、canonical、标题层级、链接和可读文本
llms.txt 语料（2）	generate_llms_txt、check_llms_txt — 根据镜像构建 llms-full.txt grounding 语料，并将其与实时文件进行比较
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
Newsletter（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 Agent / Agentic AI（4）	agents_list、agents_get、agents_get_autonomy_levels、agents_list_comparisons — 12 个 Agent、自主性矩阵、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 个版本
网站常见问题（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 验证输入； 未知 slug 会返回清晰的错误，并列出有效值。

synced_at 按工具组区分，并非全局统一 — 截至 2026-08-05，目录树中的日期从 2026-06-11（模板、指南）到 2026-06-17 （集成），再到 2026-07-08（术语表、替代方案、Agent）。请读取响应中的 synced_at，不要假设全站只有一个同步日期。

运行 npm run build && node test-tools.mjs 执行目录冒烟断言。

检测原理

1. User-Agent 匹配。 src/data/known-bots.ts 中的签名数据库通过一个或多个不区分大小写的 UA 模式定义每个已知机器人。首次匹配优先，因此更具体的签名会排在前面（例如，Googlebot-Image 排在通用的 Googlebot 之前）。
2. 通用启发式检测。 如果没有匹配到签名，我们会查找自动化提示（bot、crawler、spider、python-requests、headless 等），并将来源归类为 unknown，标记为待验证。
3. 行为信息补充。 有访问日志时，聚合器（src/core/aggregator.ts）会计算命中次数、唯一 IP 数、错误率、请求速率、唯一路径数，以及该 UA 有多少请求命中了 robots.txt 中 Disallowed 的路径。这些信号会影响风险评分，并生成易于理解的说明。
4. 身份验证。 对于高可信度签名，我们会保留有文档记录的 PTR 后缀（.googlebot.com、.search.msn.com 等）。verify_bot_identity 会执行反向 DNS 查询、检查后缀，然后再进行正向解析以确保 IP 匹配。伪造的 Googlebot 会显示为 spoofed。

风险评分

每个机器人的基准风险值存储在签名数据库中（0 = 可信搜索引擎，100 = 恶意抓取器）。聚合器会根据以下情况加分：

• 机器人忽略 robots.txt（+20）
• 请求速率极高（>1000 次请求/小时，+25；>300 次请求/小时，+10）
• 错误率 >50%——探测行为（+15）
• 访问 >5000 个唯一路径（+10）

建议操作根据最终评分和类别得出：

• search/social ≤ 25 → 允许
• ai ≤ 40 → 监控
• 评分 ≥ 70 → 拦截
• 评分 ≥ 45 → 限制速率
• unknown → 验证身份

如果你的环境限制更宽松或更严格，可在 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 状态。
• 使用诚实的 User-Agent，并附带联系 URL——通过 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。
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. 创建 src/tools/<name>.ts，导出 { definition, schema, handle }。
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、服务条款和适用法律。