idiradocs-mcp

Servidor MCP que le da a Claude acceso a la documentación oficial de CyberArk / Idira (docs.cyberark.com), para que pueda responder preguntas citando contenido real de la doc en lugar de inventar o alucinar información.

Sin bases de datos vectoriales, sin pipelines de embeddings y sin ninguna API de pago: la búsqueda corre sobre un índice local generado por un crawler propio, y la lectura de páginas se hace en vivo contra el sitio real.

Índice

• Por qué existe esto
• Cómo funciona
• Instalación
• Generar el índice de búsqueda
• Conectarlo a Claude
• Herramientas expuestas
• Configuración
• Detalles de implementación
• Limitaciones conocidas
• Scripts disponibles

Por qué existe esto

Preguntarle a un LLM sobre productos específicos de CyberArk (PAM, CPM, PSM, etc.) sin darle acceso a la documentación real tiene un riesgo alto de respuestas plausibles pero incorrectas. Este servidor MCP resuelve eso dándole a Claude dos herramientas concretas: buscar en la doc y leer una página puntual, siempre citando la fuente.

Cómo funciona

                 ┌──────────────────────┐
                 │   npm run crawl      │   (una vez, o para refrescar el índice cuando sea necesario)
                 └──────────┬───────────┘
                             │  recorre docs.cyberark.com
                             ▼
                 ┌──────────────────────┐
                 │ data/docs-index.json │   índice local (una entrada por sección de cada página)
                 └──────────┬───────────┘
                             │  MiniSearch
                             ▼
   Claude ──▶ search_cyberark_docs ──▶ lista de secciones candidatas (título, URL#anchor, snippet)
                             │
                             ▼
   Claude ──▶ get_cyberark_doc_page ──▶ fetch en vivo + Markdown limpio de esa URL

• search_cyberark_docs: busca por palabras clave en el índice local generado por el crawler. Rápido, sin llamadas externas.
• get_cyberark_doc_page: trae la página real desde docs.cyberark.com en el momento de la consulta, limpia el HTML de navegación y la devuelve en Markdown con los links resueltos a URLs absolutas. Siempre refleja el contenido actual del sitio, aunque el índice esté desactualizado.

El índice no guarda la página completa como un solo bloque: la divide por encabezado (cada <h1>-<h6> con id, que en el sitio coincide con el anchor de navegación) y guarda cada sección por separado. Esto hace que un resultado de búsqueda apunte directo a .../pagina.htm#SeccionEspecifica en lugar de a la página entera, y que el snippet devuelto sea del fragmento relevante y no de un promedio de toda la página.

El flujo esperado es que el modelo primero busque, elija la página más relevante, y después la lea completa antes de responder.

Instalación

Requiere Node.js 18 o superior.

git clone https://github.com/AlexPerez7/idiradocs-mcp.git
cd idiradocs-mcp
npm install
npm run build

Generar el índice de búsqueda

search_cyberark_docs necesita un índice previo — sin este paso no tiene nada para buscar:

npm run crawl

Por defecto arranca desde la página de inicio de la doc y se detiene a las 150 páginas, para que la primera corrida sea rápida. Para un índice más completo, se puede ajustar el alcance con variables de entorno:

# Ejemplo: indexar 2000 páginas de PAM - Self-Hosted en particular
CRAWL_SEEDS=https://docs.cyberark.com/pam-self-hosted/latest/en/content/resources/_topnav/cc_home.htm CRAWL_MAX_PAGES=2000 npm run crawl

Es necesario volver a ejecutar npm run crawl para refrescar el índice — la documentación cambia con el tiempo y el índice no se actualiza solo.

Conectarlo a Claude

Claude Desktop

Agregar el servidor en claude_desktop_config.json:

En instalaciones desde Microsoft Store, este archivo suele estar en %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json en vez del %APPDATA%\Claude\ habitual.

{
  "mcpServers": {
    "idiradocs": {
      "command": "node",
      "args": ["/ruta/absoluta/a/idiradocs-mcp/dist/index.js"]
    }
  }
}

Es necesario reiniciar Claude Desktop por completo (no alcanza con minimizar) para que tome el nuevo servidor.

Claude Code

Se puede registrar como servidor MCP de usuario o de proyecto:

claude mcp add idiradocs -- node /ruta/absoluta/a/idiradocs-mcp/dist/index.js

Herramientas expuestas

search_cyberark_docs

Busca en el índice local.

Parámetro	Tipo	Descripción
query	string	Términos de búsqueda, en español o inglés
count	number (opcional, default 5)	Cantidad máxima de resultados (1-10)

Devuelve título (página — sección), URL (con anchor a la sección específica cuando existe) y un fragmento de texto por cada resultado.

get_cyberark_doc_page

Trae y limpia el contenido de una página puntual.

Parámetro	Tipo	Descripción
url	string	URL completa, debe pertenecer a https://docs.cyberark.com/

Devuelve el contenido en Markdown, con título y URL fuente al inicio. Rechaza cualquier URL fuera de ese dominio.

Configuración

No hay ninguna variable obligatoria. Estas solo afectan a npm run crawl:

Variable	Default	Descripción
CRAWL_SEEDS	página de inicio de la doc	URLs separadas por coma desde donde arrancar el crawl
CRAWL_MAX_PAGES	150	Tope de páginas a visitar
CRAWL_CONCURRENCY	3	Requests en paralelo
CRAWL_DELAY_MS	150	Pausa entre lotes de requests, para no sobrecargar el sitio

Estas variables pueden definirse en un archivo .env (ver .env.example) o pasarse inline al comando.

Detalles de implementación

• Las páginas de docs.cyberark.com son HTML estático generado por MadCap Flare. El contenido real de cada página vive en <div id="mc-main-content">, y los elementos de navegación/chrome llevan class="nocontent" — esa es la convención que se usa tanto para indexar como para leer una página.
• El sitio devuelve una página 404 personalizada a requests cuyo User-Agent no parece un navegador (mitigación anti-bot); por eso tanto el crawler como el fetch de páginas envían un User-Agent de Chrome.
• La búsqueda usa MiniSearch con boost en el título de página y de sección, y coincidencia difusa (fuzzy) y por prefijo — no es una búsqueda semántica, es coincidencia de palabras con tolerancia a errores de tipeo. Se evaluó agregar una capa de embeddings locales, pero se descartó: la librería estándar para eso en Node (transformers.js) trae dependencias transitivas (sharp/libvips, adm-zip) con vulnerabilidades altas sin parche disponible.
• get_cyberark_doc_page valida que la URL sea https://docs.cyberark.com/* antes de hacer el fetch, para que el servidor no pueda usarse como proxy hacia otros dominios.

Limitaciones conocidas

• El índice de búsqueda es una foto del momento del crawl — no se actualiza solo. Si la doc cambia, hay que volver a correr npm run crawl.
• La relevancia de search_cyberark_docs es por palabras clave, no semántica: sinónimos o paráfrasis pueden no encontrar la página correcta aunque exista.
• El crawler solo sigue links dentro de docs.cyberark.com y con extensión .htm/.html; no cubre PDFs, videos embebidos ni contenido cargado dinámicamente con JavaScript.

Scripts disponibles

Comando	Qué hace
npm run build	Compila TypeScript a dist/
npm start	Corre el servidor MCP (dist/index.js) sobre stdio
npm run dev	Compila en watch mode
npm run crawl	Compila y corre el crawler, genera/actualiza data/docs-index.json