Docs Fetch MCP Server

Obter conteúdo de páginas da web com exploração recursiva.

GitHub
7
Experimente este MCPPatrocinado

Documentação

Servidor MCP de Busca de Documentação

Um servidor de Model Context Protocol (MCP) baseado em Bun para buscar páginas de documentação e realizar rastreamentos limitados de documentação.

O servidor expõe uma ferramenta MCP, fetch_doc_content. Ela busca uma URL raiz, extrai Markdown legível, classifica links e pode rastrear páginas vinculadas dentro de limites explícitos de profundidade, página, tempo limite e escopo. Os resultados são retornados como JSON estruturado com metadados de rastreamento, conteúdo da página, links classificados, sinalizadores de truncamento e erros por página.

Recursos

  • Caminho de busca estática rápida com axios
  • Renderização opcional com Puppeteer para páginas renderizadas no cliente ou páginas finas
  • Extração de Markdown com cabeçalhos, listas, blocos de código, tabelas, citações em bloco e links
  • Semântica real de profundidade de rastreamento:
    • depth: 1 retorna apenas a página raiz
    • depth: 2 inclui links filhos diretos
    • depth: 3 inclui netos, até o máximo de 5
  • Normalização de URL antes da deduplicação: fragmentos, parâmetros de rastreamento, portas padrão e duplicatas de barra final são removidos
  • Escopo de rastreamento por mesma origem e pathPrefix opcional
  • Limites de maxPages, maxConcurrency, tempo limite global, tempo limite por página e truncamento de conteúdo por página
  • Resultados parciais com falhas explícitas por página
  • Validação de argumentos em tempo de execução compartilhada com o esquema de ferramenta anunciado

Requisitos

  • Bun >=1.3.0
  • Instalação do navegador do Puppeteer se render for auto ou always

Este projeto usa Bun para gerenciamento de dependências, execução em tempo de execução, builds e testes.

Instalação

bun install
bun run build

Configure seu cliente MCP:

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

Para desenvolvimento local sem build:

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

Ferramenta

fetch_doc_content

Busca uma URL e opcionalmente rastreia páginas vinculadas.

Parâmetros:

NomeTipoPadrãoLimiteDescrição
urlstringobrigatórioSomente HTTP/HTTPSURL raiz a ser buscada.
depthnúmero11 a 5Distância do link a partir da raiz.
maxPagesnúmero101 a 50Máximo de páginas retornadas no rastreamento.
maxConcurrencynúmero31 a 8Máximo de páginas buscadas de uma vez.
timeoutMsnúmero450005000 a 120000Tempo limite global do rastreamento.
perPageTimeoutMsnúmero100001000 a 60000Tempo limite de busca por página.
renderstringautoauto, always, neverEstratégia de renderização do navegador.
sameOriginbooleanotruen/aRestringe links rastreados à mesma origem.
pathPrefixstringomitidon/aEscopo opcional de prefixo de caminho para rastreamento, como /docs.
contentLimitnúmero120001000 a 50000Caracteres de Markdown por página antes do truncamento.
includeLinksbooleanotruen/aInclui links classificados nos objetos de página retornados.

Exemplo de solicitação:

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

Formato da resposta:

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

Comportamento de Rastreamento

  • O rastreamento é em largura (breadth-first).
  • URLs são normalizadas antes da deduplicação e enfileiramento.
  • sameOrigin: true rejeita links cuja origem difere da URL raiz normalizada.
  • pathPrefix restringe ainda mais os links a um prefixo de caminho na origem raiz.
  • includeLinks: false oculta links nos objetos de página retornados, mas não desativa a descoberta de links para rastreamento.
  • render: "never" usa apenas o caminho de busca HTTP.
  • render: "always" usa Puppeteer para cada página buscada.
  • render: "auto" tenta HTTP primeiro e depois usa Puppeteer quando HTTP falha ou o conteúdo extraído é muito fino.
  • O fallback do navegador atualmente preserva o status de resposta renderizado e extrai o corpo da página mesmo para páginas não-2xx.

Arquitetura

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

O esquema MCP e a normalização de opções em tempo de execução compartilham a mesma fonte de metadados em src/config/tool-options.ts. Mantenha novas opções lá primeiro, depois conecte o comportamento por meio de validação e opções do rastreador.

Desenvolvimento

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

Scripts:

  • bun run dev: executa o servidor MCP a partir do código-fonte TypeScript.
  • bun run test: executa testes Bun em src.
  • bun run typecheck: executa TypeScript com --noEmit.
  • bun run build: gera build/index.js com um shebang Bun.
  • bun run start: executa o servidor MCP compilado.

Testes

Os testes são colocados junto aos módulos que cobrem:

  • src/crawler/docs-crawler.test.ts: profundidade de rastreamento, escopo, falhas e visibilidade de links.
  • src/crawler/page-fetcher.test.ts: caracterização de fallback de busca/renderização.
  • src/content/content-extractor.test.ts: extração e truncamento de Markdown.
  • src/tool/fetch-doc-content-args.test.ts: validação de limites e sincronização de esquema/padrão.
  • src/utils/url.test.ts: normalização de URL e auxiliares de escopo.

Ao alterar o comportamento, adicione ou atualize testes de caracterização primeiro. Para refatorações, mantenha bun run test, bun run typecheck e bun run build verdes.

Notas

  • Use render: "never" para rastreamentos rápidos de documentação estática e testes.
  • Use pathPrefix para sites de documentação que compartilham um domínio com páginas de marketing, blogs ou aplicativos.
  • A instalação do navegador Puppeteer pode ser ignorada somente se os chamadores usarem render: "never".
  • O renderizador Markdown personalizado é intencionalmente coberto por testes de caracterização; preserve a compatibilidade de saída a menos que faça uma mudança explícita de comportamento.

Licença

MIT