HelloGrowth CRM MCP

mcp-bot-crawler

Un servidor MCP (Model Context Protocol) que te ayuda a descubrir, identificar y gobernar cada bot que interactúa con tu sitio web — motores de búsqueda, rastreadores de IA, herramientas SEO, capturadores de vistas previas sociales, escáneres de seguridad y la larga cola de scripts sospechosos. Conéctalo a cualquier cliente compatible con MCP (Claude Desktop, Cursor, Claude Code, una app personalizada con Agent SDK, etc.) y haz preguntas en lenguaje natural sobre tu tráfico.

Es cortés por diseño: respeta robots.txt, limita la velocidad de sus propias solicitudes, anuncia un User-Agent honesto y nunca intenta evadir ningún control.

Características

• Ocho herramientas MCP que cubren el ciclo de vida completo de gobernanza de bots (escanear, analizar, verificar, listar, generar, sugerir, exportar) — además de 80 más, consulta el catálogo completo.
• Base de datos curada de 58 bots conocidos — Googlebot, Bingbot, GPTBot, ChatGPT-User, ClaudeBot, PerplexityBot, Amazonbot, Google-Extended, Applebot-Extended, FacebookBot, LinkedInBot, AhrefsBot, SemrushBot, Bytespider y más — cada uno etiquetado con categoría, operador, riesgo base y sufijos de verificación DNS inversa.
• Puntuación de riesgo conductual: combina coincidencia de UA, cumplimiento de robots.txt, tasa de errores, tasa de solicitudes y expansión de rutas únicas en una puntuación de 0–100 y una acción recomendada (allow / monitor / rate-limit / block / verify-identity).
• Verificación de identidad de grado criptográfico mediante PTR + DNS directo (el mismo método documentado por Google, Microsoft, OpenAI).
• Analizador de robots.txt + sitemap.xml con semántica correcta de Allow/Disallow de coincidencia más larga.
• Informes en Markdown, JSON y CSV.
• Prioridad TypeScript, estructura de archivos modular, cero análisis inseguro.

Estructura del repositorio

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

No hay samples/access.log en el repositorio, aunque DEFAULT_ACCESS_LOG por defecto apunta a esa ruta. Apunta DEFAULT_ACCESS_LOG a un registro real, o pasa logPath / logText explícitamente a analyze_access_logs y export_bot_report. reports/ se crea en la primera exportación.

Inicio rápido

Este es un repositorio independiente — ya no es un subdirectorio de 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

Ejecútalo en stdio:

node dist/index.js

O en modo de desarrollo (sin paso de compilación, usa tsx):

npm run dev

El servidor habla MCP a través de stdio. Cualquier cliente compatible con MCP puede iniciarlo.

Descubrimiento de código con Graphify

Graphify construye un AST local para consultas de código eficientes en tokens. Úsalo para responder preguntas como "quién llama a esta función" en ~2K tokens en lugar de 183K tokens con grep—una reducción de 71× por consulta.

Configuración

Instala Graphify:

pip install graphifyy

Construye el grafo de conocimiento:

graphify update .

Uso

Consulta el grafo:

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

Alternativamente, ejecuta /graphify en Claude Code para consultar de forma interactiva.

Claude Desktop / Claude Code

Añade lo siguiente a tu claude_desktop_config.json (o el bloque mcpServers equivalente en tu cliente):

{
  "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)"
      }
    }
  }
}

O usa el servidor alojado (sin clonar, sin compilar)

Hay un despliegue activo en https://mcp.hellogrowthcrm.com — Streamable HTTP en /sse. Manifiesto: https://hellogrowthcrm.com/.well-known/mcp.json. Superficie de versión/estado: GET /version devuelve el nombre del servidor, la versión, los recuentos de herramientas y recursos, y un enlace al changelog — consulta CHANGELOG.md para ver qué cambió entre versiones.

Cambio de endpoint: el endpoint Streamable HTTP se movió de /mcp a /sse, y el transporte SSE heredado (GET /sse + POST /message) se ha eliminado. Apunta los clientes a https://mcp.hellogrowthcrm.com/sse.

⚠️ El despliegue alojado puede ir por detrás de main, y el recuento de herramientas no te lo dirá. El 2026-08-05, main local y producción anunciaban ambos las mismas 83 herramientas con nombres idénticos — mientras que fetch_page_content en /pricing devolvía wordCount: 3194 localmente y wordCount: 0 en producción, porque producción era anterior a la corrección de extracción del 2026-07-13.

Un recuento de herramientas coincidente no significa una compilación coincidente. Solo el comportamiento lo hace.

A partir del 2026-08-11 coinciden: producción y main están ambos en 88 herramientas. En lugar de confiar en esa línea — se vuelve obsoleta en cada lanzamiento — vuelve a derivarla:

./scripts/geo-audit.sh     # comprueba que C4 llama a la misma herramienta a través de ambos y falla en divergencia

Las ocho herramientas MCP

Herramienta	Qué hace
scan_website_bots	Escaneo en vivo cortés: robots.txt + sitemap + páginas de muestra, correlacionado con tu registro de acceso.
analyze_access_logs	Analiza registros en formato Combined de Apache/Nginx y devuelve resúmenes por bot con puntuaciones de riesgo.
verify_bot_identity	Verificación PTR + DNS directo de un par (ip, userAgent) específico.
list_allowed_bots	Bots permitidos bajo la política actual (curada por defecto, o robots.txt en vivo).
list_blocked_bots	Bots bloqueados bajo la política actual (alto riesgo por defecto, o robots.txt en vivo).
generate_robots_txt	Generador de robots.txt basado en políticas (bloquear IA / SEO / scrapers / escáneres de seguridad, declarar sitemaps, establecer Crawl-delay).
suggest_bot_policy	Para cada bot observado en un registro, recomienda permitir / monitorear / limitar velocidad / bloquear con justificación y un fragmento de nginx listo para pegar.
export_bot_report	Escribe un informe en Markdown / JSON / CSV bajo REPORT_OUTPUT_DIR.

Ejemplos completos de payloads en examples/usage.md.

Anotaciones de herramientas

Cada una de las 88 herramientas lleva anotaciones MCP explícitas (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) para que los clientes puedan decidir qué necesita aprobación humana. 80 herramientas son de solo lectura. Exactamente ocho pueden escribir — blog_create, blog_update, blog_revalidate, help_create_article, help_update_article, newsletter_subscribe, newsletter_unsubscribe, forms_submit — y nueve alcanzan el mundo abierto (rastreos en vivo, verificación DNS, revalidación del sitio). La clasificación vive en src/tools/annotations.ts; una guardia de inicio y una prueba fallan la compilación si una herramienta se registra sin una entrada.

Catálogo completo de herramientas MCP (88 herramientas)

Más allá de las ocho herramientas originales de gobernanza de bots, este servidor expone todo el sitio web hellogrowthcrm.com — cada módulo, característica, producto, tabla de precios, agente de IA e integración — como herramientas MCP. El contenido en vivo (blog, ayuda, boletín, formularios, prueba social) se sirve desde Supabase; todo lo demás es un espejo de lectura de los archivos fuente del sitio (consulta WEBSITE_DATA_TOOLS.md).

Categoría	Herramientas
Gobernanza de bots (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
Contenido de páginas (2)	fetch_page_content, crawl_pages — obtén una página en vivo (o recorre el sitemap) y devuelve título, meta, canonical, encabezados, enlaces y texto legible
Corpus llms.txt (2)	generate_llms_txt, check_llms_txt — construye un corpus de base llms-full.txt desde el espejo y compáralo con el archivo en vivo
Diagnóstico GEO/AEO (2)	check_ai_extractability, validate_sitemaps — mide <main> vs <body> texto legible para detectar páginas que devuelven HTTP 200 pero están vacías para un extractor, y expande un índice de sitemap para detectar hijos que agotan el tiempo, se reinician o devuelven 5xx
Blog (7)	blog_list, blog_get, blog_search, blog_create, blog_update, blog_revalidate, blog_get_categories
Centro de ayuda (6)	help_list_categories, help_list_articles, help_get_article, help_search, help_create_article, help_update_article
Boletín (4)	newsletter_subscribe, newsletter_unsubscribe, newsletter_get_subscribers, newsletter_get_stats
Formularios de contacto (4)	forms_submit, forms_list_submissions, forms_get_submission, forms_export_csv
Contenido estático (6)	content_list_case_studies, content_list_comparisons, content_get_comparison, content_list_industries, content_list_tools, content_get_seo_rules
Precios (6)	pricing_get_plans, pricing_get_addons, pricing_get_faq, pricing_compare_plans, pricing_get_country_plans, pricing_get_managed_revops — la escalera del CRM es Free → Growth → Enterprise; Managed RevOps es un retenedor mensual de servicio plano, no un nivel por asiento
Características (3)	features_list, features_get, features_list_products
Analítica (1)	analytics_social_proof
Países (2)	countries_list, country_get
Empresa (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
Productos (2)	products_list, product_get
Integraciones (3)	integrations_list, integrations_get, integrations_list_categories — catálogo de 630 entradas, 116 categorías
Agentes de IA / IA Agéntica (4)	agents_list, agents_get, agents_get_autonomy_levels, agents_list_comparisons — 12 agentes, matriz de autonomía, 4 páginas vs-competidores
Glosario (2)	glossary_list_terms, glossary_get_term — 58 términos
Plantillas (2)	templates_list, templates_get — 42 plantillas en 7 categorías
Guías de características (2)	guides_list, guides_get — 32 guías
Alternativas y migración (4)	alternatives_list, alternatives_get, switch_list_competitors, switch_get_guide — 42 páginas de alternativas, 26 guías de cambio desde
Changelog (2)	changelog_list_releases, changelog_get_release — 6 lanzamientos
Preguntas frecuentes del sitio (1)	faqs_get_site
Medios (2)	media_list_videos, media_list_testimonials
Programa de socios (2)	partners_get_program, partners_get_application_schema
Soluciones (2)	solutions_list_whatsapp_use_cases, solutions_get_managed_revops — incl. 9 variantes de mercado + 25 páginas de ciudades de EE. UU.

Todas las herramientas espejo llevan procedencia synced_at y validan entradas con zod; los slugs desconocidos devuelven un error claro que enumera valores válidos.

synced_at es por grupo de herramientas, no global — a partir del 2026-08-05 los valores en el árbol van desde 2026-06-11 (plantillas, guías) hasta 2026-06-17 (integraciones) y 2026-07-08 (glosario, alternativas, agentes). Lee el synced_at en la respuesta en lugar de asumir una única fecha de sincronización para todo el sitio.

Ejecuta npm run build && node test-tools.mjs para las aserciones de humo del catálogo.

Cómo funciona la detección

1. Coincidencia de User-Agent. La base de datos de firmas en src/data/known-bots.ts define cada bot conocido con uno o más patrones de UA insensibles a mayúsculas. La primera coincidencia gana, por lo que las firmas más específicas van primero (p. ej., Googlebot-Image antes que Googlebot genérico).
2. Heurísticas genéricas. Si ninguna firma coincide, buscamos pistas de automatización (bot, crawler, spider, python-requests, headless, …) y clasificamos la fuente como unknown — marcada para verificación.
3. Enriquecimiento conductual. Cuando hay registros de acceso disponibles, el agregador (src/core/aggregator.ts) calcula el recuento de visitas, IPs únicas, tasa de errores, tasa de solicitudes, rutas únicas y cuántas solicitudes alcanzaron rutas Disallowed en robots.txt para ese UA. Estas señales ajustan la puntuación de riesgo y emiten notas legibles para humanos.
4. Verificación de identidad. Para firmas de alta confianza mantenemos sufijos PTR documentados (.googlebot.com, .search.msn.com, etc.). verify_bot_identity ejecuta DNS inverso, comprueba el sufijo y luego resuelve hacia adelante para asegurar que la IP coincide. Los Googlebots falsificados aparecen como spoofed.

Puntuación de riesgo

El riesgo base por bot vive en la base de datos de firmas (0 = motor de búsqueda confiable, 100 = scraper hostil). El agregador añade bonificaciones por:

• Bot que ignora robots.txt (+20)
• Tasa de solicitudes muy alta (>1000 req/h, +25; >300 req/h, +10)
• Tasa de errores >50% — comportamiento de sondeo (+15)
• Tocar >5000 rutas únicas (+10)

La acción recomendada se deriva de la puntuación final más la categoría:

• search/social ≤ 25 → permitir
• ai ≤ 40 → monitorear
• Puntuación ≥ 70 → bloquear
• Puntuación ≥ 45 → limitar velocidad
• unknown → verificar identidad

Ajusta estos umbrales en src/core/bot-detector.ts si tu entorno es más o menos permisivo.

Seguridad y cortesía

• Respeta robots.txt para las búsquedas salientes. scan_website_bots no recuperará rutas Disallowed para su propio UA.
• Limitador de tasa por host (CRAWL_DELAY_MS, predeterminado 1 s).
• Límite máximo de páginas del sitemap (MAX_SITEMAP_PAGES, predeterminado 25).
• Tiempo de espera HTTP (HTTP_TIMEOUT_MS, predeterminado 10 s).
• Sin almacenamiento de contenido: solo se registra la URL + el estado HTTP de las búsquedas muestreadas.
• User-Agent honesto con una URL de contacto — cámbialo mediante CRAWLER_USER_AGENT.
• stdout reservado para MCP: todos los registros van a stderr.

Las herramientas nunca intentan eludir la autenticación, CAPTCHAs, muros de pago, WAFs ni ningún otro control de acceso. Tampoco aceptan código arbitrario de las entradas.

Configuración

Todos los controles están en .env (ver .env.example):

Variable	Predeterminado	Propósito
DEFAULT_ACCESS_LOG	./samples/access.log	Ruta de registro de respaldo. Este archivo no está en el repositorio — configúralo con un registro real.
DEFAULT_TARGET_URL	https://example.com	Sitio de respaldo para escaneos.
MAX_SITEMAP_PAGES	25	Límite máximo por escaneo.
CRAWL_DELAY_MS	1000	Retraso por host.
HTTP_TIMEOUT_MS	10000	Tiempo de espera por solicitud.
CRAWLER_USER_AGENT	mcp-bot-crawler/1.0 (+...)	UA saliente.
REPORT_OUTPUT_DIR	./reports	Dónde aterrizan las exportaciones.
LOG_LEVEL	info	error / warn / info / debug.
RATE_LIMIT_WINDOW_MS	60000	Ventana de limitación de tasa para el transporte HTTP.
RATE_LIMIT_MAX_REQUESTS	60	Máximo de solicitudes por ventana por IP de cliente.
UPSTASH_REDIS_REST_URL	—	Opcional: almacén de limitación de tasa compartido (configúralo con el token) para que los buckets se compartan entre instancias escaladas en lugar de por proceso.
UPSTASH_REDIS_REST_TOKEN	—	Opcional: token para el almacén de limitación de tasa compartido.
TRUST_PROXY_HEADERS	true	Honra el salto CF-Connecting-IP/último X-Forwarded-For para la clave de limitación de tasa. Configura false solo cuando esté expuesto sin proxy delante.
ENABLE_MCP_ANALYTICS	false	Interruptor maestro para análisis de MCP/SSE — debe ser true para enviar.
GA4_MEASUREMENT_ID	—	ID de flujo GA4 para análisis de MCP/SSE (opcional).
GA4_API_SECRET	—	Secreto de API del Protocolo de Medición GA4 (opcional).

Los análisis de uso de MCP/SSE centrados en la privacidad (conexiones, solicitudes, herramientas, bots) se emiten a GA4 solo cuando ENABLE_MCP_ANALYTICS=true y las variables GA4_* están configuradas — y no hacen nada en silencio en caso contrario. Nunca se rastrean IP sin procesar, User-Agent, cuerpo de solicitud ni argumentos de herramientas. Ver docs/MCP_ANALYTICS.md.

Extensión

Agrega un nuevo bot:

// 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.",
}

Agrega una nueva herramienta:

1. Crea src/tools/<name>.ts exportando { definition, schema, handle }.
2. Colócala en el array tools en src/tools/index.ts.

Todo lo demás (registro, validación de esquema, manejo de errores) es automático.

Desarrollo

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

Las pruebas viven en directorios __tests__/ junto al código que cubren (src/core/__tests__, src/tools/__tests__, src/lib/__tests__, src/middleware/__tests__, src/data/__tests__).

Licencia

MIT — ver LICENSE.

Aviso legal

Este proyecto te ayuda a observar y gobernar bots que interactúan con tu propio sitio web. No lo uses para rastrear, hacer scraping o analizar sitios de terceros sin permiso. Respeta siempre robots.txt, los términos de servicio y la ley aplicable.