Docs Fetch MCP Server

Obtén contenido de páginas web con exploración recursiva.

Documentación

Docs Fetch MCP Server

Un servidor de Model Context Protocol (MCP) basado en Bun para obtener páginas de documentación y rastreos de documentación acotados.

El servidor expone una herramienta MCP, fetch_doc_content. Obtiene una URL raíz, extrae Markdown legible, clasifica enlaces y puede rastrear páginas enlazadas dentro de límites explícitos de profundidad, páginas, tiempo de espera y alcance. Los resultados se devuelven como JSON estructurado con metadatos de rastreo, contenido de páginas, enlaces clasificados, indicadores de truncamiento y errores por página.

Características

Ruta de obtención estática rápida con axios
Renderizado opcional con Puppeteer para páginas renderizadas en cliente o páginas con poco contenido
Extracción de Markdown con encabezados, listas, bloques de código, tablas, citas en bloque y enlaces
Semántica real de profundidad de rastreo:
- depth: 1 devuelve solo la página raíz
- depth: 2 incluye enlaces hijos directos
- depth: 3 incluye nietos, hasta el máximo de 5
Normalización de URL antes de deduplicación: se eliminan fragmentos, parámetros de seguimiento, puertos predeterminados y duplicados de barra final
Alcance de rastreo por mismo origen y pathPrefix opcional
maxPages, maxConcurrency, tiempo de espera global, tiempo de espera por página y truncamiento de contenido por página acotados
Resultados parciales con fallos explícitos por página
Validación de argumentos en tiempo de ejecución compartida con el esquema de herramienta anunciado

Requisitos

Bun >=1.3.0
Instalación del navegador de Puppeteer si render es auto o always

Este proyecto usa Bun para la gestión de dependencias, ejecución en tiempo de ejecución, compilaciones y pruebas.

Instalación

bun install
bun run build

Configure su cliente MCP:

{
  "mcpServers": {
    "docs-fetch": {
      "command": "bun",
      "args": ["/path/to/docs-fetch-mcp/build/index.js"]
    }
  }
}

Para desarrollo local sin compilación:

{
  "mcpServers": {
    "docs-fetch": {
      "command": "bun",
      "args": ["/path/to/docs-fetch-mcp/src/index.ts"]
    }
  }
}

Herramienta

`fetch_doc_content`

Obtiene una URL y opcionalmente rastrea páginas enlazadas.

Parámetros:

Nombre	Tipo	Predeterminado	Límite	Descripción
`url`	string	requerido	Solo HTTP/HTTPS	URL raíz a obtener.
`depth`	number	`1`	`1` a `5`	Distancia de enlace desde la raíz.
`maxPages`	number	`10`	`1` a `50`	Máximo de páginas devueltas en el rastreo.
`maxConcurrency`	number	`3`	`1` a `8`	Máximo de páginas obtenidas a la vez.
`timeoutMs`	number	`45000`	`5000` a `120000`	Tiempo de espera global del rastreo.
`perPageTimeoutMs`	number	`10000`	`1000` a `60000`	Tiempo de espera de obtención por página.
`render`	string	`auto`	`auto`, `always`, `never`	Estrategia de renderizado del navegador.
`sameOrigin`	boolean	`true`	n/a	Restringir enlaces rastreados al mismo origen.
`pathPrefix`	string	omitido	n/a	Prefijo de ruta opcional para el alcance del rastreo, como `/docs`.
`contentLimit`	number	`12000`	`1000` a `50000`	Caracteres de Markdown por página antes del truncamiento.
`includeLinks`	boolean	`true`	n/a	Incluir enlaces clasificados en los objetos de página devueltos.

Ejemplo de solicitud:

{
  "url": "https://example.com/docs",
  "depth": 2,
  "maxPages": 8,
  "pathPrefix": "/docs",
  "render": "auto"
}

Forma de la respuesta:

{
  "rootUrl": "https://example.com/docs",
  "normalizedRootUrl": "https://example.com/docs",
  "explorationDepth": 2,
  "maxPages": 8,
  "pagesExplored": 3,
  "pagesFailed": 1,
  "timedOut": false,
  "durationMs": 1234,
  "crawl": {
    "sameOrigin": true,
    "pathPrefix": "/docs",
    "maxConcurrency": 3,
    "render": "auto",
    "perPageTimeoutMs": 10000
  },
  "content": [
    {
      "url": "https://example.com/docs",
      "finalUrl": "https://example.com/docs",
      "depth": 0,
      "status": 200,
      "title": "Documentation",
      "description": "Example documentation",
      "canonicalUrl": "https://example.com/docs",
      "headings": ["Documentation"],
      "content": "# Documentation\n\n...",
      "contentLength": 2400,
      "truncated": false,
      "fetchedWith": "http",
      "links": [
        {
          "url": "https://example.com/docs/api",
          "text": "API reference",
          "score": 18.5,
          "internal": true
        }
      ]
    }
  ],
  "errors": [
    {
      "url": "https://example.com/docs/missing",
      "depth": 1,
      "error": "Request failed with status code 404",
      "status": 404
    }
  ]
}

Comportamiento del rastreo

El rastreo es en anchura (breadth-first).
Las URL se normalizan antes de la deduplicación y la puesta en cola.
sameOrigin: true rechaza enlaces cuyo origen difiere de la URL raíz normalizada.
pathPrefix restringe aún más los enlaces a un prefijo de ruta en el origen raíz.
includeLinks: false oculta enlaces en los objetos de página devueltos pero no desactiva el descubrimiento de enlaces para el rastreo.
render: "never" usa solo la ruta de obtención HTTP.
render: "always" usa Puppeteer para cada página obtenida.
render: "auto" intenta HTTP primero, luego usa Puppeteer cuando HTTP falla o el contenido extraído es muy escaso.
El respaldo del navegador actualmente conserva el estado de respuesta renderizado y extrae el cuerpo de la página incluso para páginas no-2xx.

Arquitectura

src/index.ts                         CLI entrypoint
src/server.ts                        MCP server wiring and tool registration
src/config/tool-options.ts           Shared tool schema/default/range metadata
src/tool/fetch-doc-content-args.ts   Runtime argument validation
src/crawler/docs-crawler.ts          Crawl orchestration and queue management
src/crawler/page-fetcher.ts          HTTP fetch, browser fallback, extraction coordination
src/browser/browser-manager.ts       Reusable Puppeteer browser/page handling
src/content/content-extractor.ts     Page metadata/content extraction facade
src/content/main-content-selector.ts Main content selection
src/content/link-extractor.ts        Link normalization, dedupe, and ranking
src/content/markdown-renderer.ts     HTML-to-Markdown rendering
src/content/text-cleanup.ts          Shared text normalization helpers
src/utils/url.ts                     URL normalization and scope utilities
src/types/index.ts                   Shared TypeScript types

El esquema MCP y la normalización de opciones en tiempo de ejecución comparten la misma fuente de metadatos en src/config/tool-options.ts. Mantenga las nuevas opciones allí primero, luego conecte el comportamiento a través de la validación y las opciones del rastreador.

Desarrollo

bun install
bun run dev
bun run test
bun run typecheck
bun run build

Scripts:

bun run dev: ejecuta el servidor MCP desde el código fuente TypeScript.
bun run test: ejecuta las pruebas de Bun bajo src.
bun run typecheck: ejecuta TypeScript con --noEmit.
bun run build: emite build/index.js con un shebang de Bun.
bun run start: ejecuta el servidor MCP compilado.

Pruebas

Las pruebas están ubicadas junto a los módulos que cubren:

src/crawler/docs-crawler.test.ts: profundidad de rastreo, alcance, fallos y visibilidad de enlaces.
src/crawler/page-fetcher.test.ts: caracterización del respaldo de obtención/renderizado.
src/content/content-extractor.test.ts: extracción y truncamiento de Markdown.
src/tool/fetch-doc-content-args.test.ts: validación de límites y sincronización de esquema/predeterminados.
src/utils/url.test.ts: normalización de URL y funciones auxiliares de alcance.

Al cambiar el comportamiento, agregue o actualice las pruebas de caracterización primero. Para refactorizaciones, mantenga bun run test, bun run typecheck y bun run build en verde.

Notas

Use render: "never" para rastreos de documentación estática rápida y pruebas.
Use pathPrefix para sitios de documentación que comparten dominio con páginas de marketing, blogs o aplicaciones.
La instalación del navegador de Puppeteer se puede omitir solo si los llamadores usan render: "never".
El renderizador de Markdown personalizado está cubierto intencionalmente por pruebas de caracterización; conserve la compatibilidad de salida a menos que realice un cambio de comportamiento explícito.

Licencia

MIT