Docs Fetch MCP Server

Docs Fetch MCP Server

ドキュメントページの取得と、範囲を限定したドキュメントのクロールを行う、Bun ベースの Model Context Protocol（MCP）サーバーです。

このサーバーは、1 つの MCP ツール fetch_doc_content を公開します。ルート URL を取得して読みやすい Markdown を抽出し、リンクをランク付けします。また、明示的な深度、ページ数、タイムアウト、範囲の制限内で、リンク先のページをクロールできます。結果は、クロールのメタデータ、ページの内容、ランク付けされたリンク、切り詰めフラグ、ページごとのエラーを含む構造化 JSON として返されます。

Features

• axios を使った高速な静的取得
• クライアント側でレンダリングされるページや内容の少ないページ向けの、任意の Puppeteer レンダリング
• 見出し、リスト、コードブロック、表、引用、リンクを含む Markdown 抽出
• 正確な深度セマンティクスによるクロール：
  • depth: 1 はルートページのみを返します
  • depth: 2 は直接の子リンクを含みます
  • depth: 3 は孫ページを含み、最大値は 5 です
• 重複排除前の URL 正規化：フラグメント、トラッキングパラメーター、デフォルトポート、末尾のスラッシュによる重複を取り除きます
• 同一オリジンおよび任意の pathPrefix によるクロール範囲の制限
• maxPages、maxConcurrency、全体タイムアウト、ページごとのタイムアウト、ページごとのコンテンツ切り詰めによる制限
• ページごとの失敗を明示した部分的な結果
• 公開されるツールスキーマと共有する実行時引数の検証

Requirements

• Bun >=1.3.0
• render が auto または always の場合は、Puppeteer のブラウザーインストールが必要です

このプロジェクトでは、依存関係の管理、実行、ビルド、テストに Bun を使用します。

Installation

bun install
bun run build

MCP クライアントを設定します：

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

ビルドせずにローカル開発する場合：

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

Tool

fetch_doc_content

URL を 1 つ取得し、任意でリンク先のページをクロールします。

Parameters：

Name	Type	Default	Limit	Description
url	string	必須	HTTP/HTTPS のみ	取得するルート URL です。
depth	number	1	1 から 5	ルートからのリンク距離です。
maxPages	number	10	1 から 50	クロール全体で返す最大ページ数です。
maxConcurrency	number	3	1 から 8	一度に取得する最大ページ数です。
timeoutMs	number	45000	5000 から 120000	クロール全体のタイムアウトです。
perPageTimeoutMs	number	10000	1000 から 60000	ページごとの取得タイムアウトです。
render	string	auto	auto、always、never	ブラウザーレンダリングの方式です。
sameOrigin	boolean	true	該当なし	クロールするリンクを同一オリジンに制限します。
pathPrefix	string	省略	該当なし	/docs のような、クロール範囲を制限する任意のパスプレフィックスです。
contentLimit	number	12000	1000 から 50000	切り詰める前の、ページごとの Markdown 文字数です。
includeLinks	boolean	true	該当なし	返されるページオブジェクトにランク付けされたリンクを含めます。

リクエスト例：

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

レスポンスの形式：

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

Crawl Behavior

• クロールは幅優先で行われます。
• URL は重複排除とキューへの追加の前に正規化されます。
• sameOrigin: true の場合、正規化されたルート URL とオリジンが異なるリンクは除外されます。
• pathPrefix を指定すると、ルートのオリジン上でパスプレフィックスによるリンクの制限が追加されます。
• includeLinks: false は返されるページオブジェクト内のリンクを非表示にしますが、クロール用のリンク検出は無効にしません。
• render: "never" は HTTP による取得のみを使用します。
• render: "always" は取得するすべてのページで Puppeteer を使用します。
• render: "auto" は最初に HTTP を試し、HTTP に失敗した場合、または抽出されたコンテンツが非常に少ない場合に Puppeteer を使用します。
• 現在、ブラウザーへのフォールバックではレンダリング後のレスポンスステータスが保持され、ページが 2xx 以外のステータスでも本文が抽出されます。

Architecture

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

MCP スキーマと実行時のオプション正規化は、src/config/tool-options.ts 内の同じメタデータソースを共有します。新しいオプションはまずここに追加し、その後、検証とクローラーのオプションに動作を組み込んでください。

Development

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

スクリプト：

• bun run dev：TypeScript ソースから MCP サーバーを実行します。
• bun run test：src 以下の Bun テストを実行します。
• bun run typecheck：--noEmit を指定して TypeScript を実行します。
• bun run build：Bun のシバン付きで build/index.js を出力します。
• bun run start：ビルド済みの MCP サーバーを実行します。

テスト

テストは、対象となるモジュールと同じ場所に配置されています。

• src/crawler/docs-crawler.test.ts：クロール深度、スコープ、失敗、リンクの可視性。
• src/crawler/page-fetcher.test.ts：取得／レンダリングのフォールバックの特性。
• src/content/content-extractor.test.ts：Markdown の抽出と切り詰め。
• src/tool/fetch-doc-content-args.test.ts：境界値の検証とスキーマ／デフォルト値の同期。
• src/utils/url.test.ts：URL の正規化とスコープ関連のヘルパー。

動作を変更する場合は、まず特性テストを追加または更新してください。リファクタリングでは、bun run test、bun run typecheck、bun run build がすべて成功する状態を維持してください。

注意事項

• 静的なドキュメントのクロールやテストを高速に行うには、render: "never" を使用してください。
• ドキュメントサイトがマーケティングページ、ブログ、アプリとドメインを共有している場合は、pathPrefix を使用してください。
• Puppeteer のブラウザーのインストールを省略できるのは、呼び出し側が render: "never" を使用する場合に限られます。
• カスタム Markdown レンダラーは特性テストで意図的にテストされています。明示的に動作を変更する場合を除き、出力との互換性を維持してください。

ライセンス

MIT