Hellogrowthcrmmcp

mcp-bot-crawler

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

它的设计秉持礼貌原则：遵守 robots.txt，限制自身抓取频率，使用真实准确的 User-Agent，绝不尝试绕过任何控制措施。

功能

• 八种 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 记录的相同方法）。
• robots.txt + sitemap.xml 解析器，正确处理最长匹配优先的 Allow/Disallow 语义。
• 支持以 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)"
      }
    }
  }
}

八种 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。

检测原理

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。

扩展

添加新机器人：

// 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             # (add your own tests under src/__tests__/)

许可证

MIT——参见 LICENSE。

免责声明

本项目帮助你观察和管理与你自己的网站交互的机器人。未经许可，请勿使用本项目抓取、采集或分析第三方网站。请始终遵守 robots.txt、服务条款和适用法律。 "# mcp-bot-crawler-hellogrowthcrm"