mult-fetch-mcp-server

mult-fetch-mcp-server

このプロジェクトは、AI アシスタントと外部ツール間の通信を行う、MCP に準拠したクライアントとサーバーを実装しています。

English | 中文文档

プロジェクト構成

fetch-mcp/
├── src/                         # Source code directory
│   ├── lib/                     # Library files
│   │   ├── fetchers/            # Web fetching implementation
│   │   │   ├── browser/         # Browser-based fetching
│   │   │   │   ├── BrowserFetcher.ts      # Browser fetcher implementation
│   │   │   │   ├── BrowserInstance.ts     # Browser instance management
│   │   │   │   └── PageOperations.ts      # Page interaction operations
│   │   │   ├── node/            # Node.js-based fetching
│   │   │   └── common/          # Shared fetching utilities
│   │   ├── utils/               # Utility modules
│   │   │   ├── ChunkManager.ts        # Content chunking
│   │   │   ├── ContentProcessor.ts    # HTML to text conversion
│   │   │   ├── ContentExtractor.ts    # Intelligent content extraction
│   │   │   ├── ContentSizeManager.ts  # Content size limiting
│   │   │   └── ErrorHandler.ts        # Error handling
│   │   ├── server/              # Server-related modules
│   │   │   ├── index.ts         # Server entry
│   │   │   ├── browser.ts       # Browser management
│   │   │   ├── fetcher.ts       # Web fetching logic
│   │   │   ├── tools.ts         # Tool registration and handling
│   │   │   ├── resources.ts     # Resource handling
│   │   │   ├── prompts.ts       # Prompt templates
│   │   │   └── types.ts         # Server type definitions
│   │   ├── i18n/                # Internationalization support
│   │   └── types.ts             # Common type definitions
│   ├── client.ts                # MCP client implementation
│   └── mcp-server.ts            # MCP server main entry
├── index.ts                     # Server entry point
├── tests/                       # Test files
└── dist/                        # Compiled files

MCP 仕様

Model Context Protocol（MCP）は、次の 2 つの主要なトランスポート方式を定義しています。

1. 標準入力／出力（Stdio）：クライアントが子プロセスとして MCP サーバーを起動し、標準入力（stdin）と標準出力（stdout）を介して通信します。
2. Server-Sent Events（SSE）：クライアントとサーバー間でメッセージを渡すために使用されます。

このプロジェクトでは、標準入力／出力（Stdio）トランスポート方式を実装しています。

特長

• 公式 MCP SDK に基づく実装
• 標準入力／出力（Stdio）トランスポートに対応
• 複数の Web スクレイピング方式（HTML、JSON、テキスト、Markdown、プレーンテキストへの変換）
• インテリジェントなモード切り替え：標準リクエストとブラウザーモードを自動的に切り替えます
• コンテンツサイズの管理：大きなコンテンツを扱いやすいチャンクに自動分割し、AI モデルのコンテキストサイズの制限に対応します
• チャンク化されたコンテンツの取得：コンテキストの連続性を維持しながら、大きなコンテンツの特定のチャンクをリクエストできます
• stderr への詳細なデバッグログ出力
• 英語と中国語のバイリンガル対応
• メンテナンスや拡張が容易なモジュール設計
• インテリジェントなコンテンツ抽出：Mozilla の Readability ライブラリに基づき、広告やナビゲーション要素を除外しながら、Web ページから意味のあるコンテンツを抽出できます
• メタデータへの対応：タイトル、作者、公開日、サイト情報などの Web ページのメタデータを抽出できます
• スマートなコンテンツ検出：ページに意味のあるコンテンツが含まれているかを自動検出し、ログインページ、エラーページ、実質的なコンテンツがないその他のページを除外します
• ブラウザー自動化の強化：ページのスクロール、Cookie 管理、セレクターの待機など、高度なブラウザー操作に対応します

インストール

Smithery 経由でインストール

Smithery 経由で Claude Desktop 用の Mult Fetch MCP Server を自動的にインストールするには、以下を実行します。

npx -y @smithery/cli install @lmcc-dev/mult-fetch-mcp-server --client claude

ローカルインストール

pnpm install

グローバルインストール

pnpm add -g @lmcc-dev/mult-fetch-mcp-server

または、npx で直接実行できます（インストール不要）。

npx @lmcc-dev/mult-fetch-mcp-server

Claude との統合

このツールを Claude デスクトップアプリと統合するには、サーバー設定を追加する必要があります。

設定ファイルの場所

• MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

設定例

方法 1：npx を使用（推奨）

この方法は最も簡単で、フルパスの指定は不要です。グローバルインストール、または npx で直接使用する場合に適しています。

{
  "mcpServers": {
    "mult-fetch-mcp-server": {
      "command": "npx",
      "args": ["@lmcc-dev/mult-fetch-mcp-server"],
      "env": {
        "MCP_LANG": "en"  // Set language to English, options: "zh" or "en"
      }
    }
  }
}

方法 2：フルパスを指定

特定のインストール先を使用する必要がある場合は、フルパスを指定できます。

{
  "mcpServers": {
    "mult-fetch-mcp-server": {
      "command": "path-to/bin/node",
      "args": ["path-to/@lmcc-dev/mult-fetch-mcp-server/dist/index.js"],
      "env": {
        "MCP_LANG": "en"  // Set language to English, options: "zh" or "en"
      }
    }
  }
}

path-to/bin/node をシステム上の Node.js 実行ファイルのパスに置き換え、path-to/@lmcc-dev/mult-fetch-mcp-server をこのプロジェクトの実際のパスに置き換えてください。

使用例

以下は、このツールを Claude デスクトップクライアントで使用する例です。

この画像は、Claude が fetch ツールを使って Web コンテンツを取得し、指示に従って処理する方法を示しています。

使用方法

設定後、Claude デスクトップアプリを再起動すると、会話で以下のツールを使用できます。

• fetch_html：Web ページの HTML コンテンツを取得します
• fetch_json：JSON データを取得します
• fetch_txt：プレーンテキストのコンテンツを取得します
• fetch_markdown：Markdown 形式のコンテンツを取得します
• fetch_plaintext：HTML から変換したプレーンテキストのコンテンツを取得します（HTML タグを除去します）

ビルド

pnpm run build

サーバーの実行

pnpm run server
# or
node dist/index.js
# if globally installed, you can run directly
@lmcc-dev/mult-fetch-mcp-server
# or use npx
npx @lmcc-dev/mult-fetch-mcp-server

クライアントのデモツール

注：以下の client.js の機能は、デモとテストのみを目的として提供されています。Claude やその他の AI アシスタントと使用する場合、MCP サーバーは AI によって操作され、チャンク分割のプロセスは自動的に管理されます。

コマンドラインクライアント

このプロジェクトには、テストおよび開発用のコマンドラインクライアントが含まれています。

pnpm run client <method> <params_json>
# example
pnpm run client fetch_html '{"url": "https://example.com", "debug": true}'

デモクライアントのチャンク制御パラメーター

コマンドラインクライアントでテストする際は、以下のパラメーターを使用してコンテンツのチャンク分割機能を確認できます。

• --all-chunks：すべてのチャンクを順番に自動取得するコマンドラインフラグ（デモ専用）
• --max-chunks：取得するチャンクの最大数を制限するコマンドラインフラグ（省略可能、デフォルトは 10）

リアルタイム出力のデモ

client.js のデモツールでは、リアルタイム出力機能を利用できます。

node dist/src/client.js fetch_html '{"url":"https://example.com", "startCursor": 0, "contentSizeLimit": 500}' --all-chunks --debug

デモクライアントはすべてのチャンクを順番に自動取得し、すぐに表示します。これにより、大容量のコンテンツをリアルタイムで処理する方法を紹介します。

テストの実行

# Run MCP functionality tests
npm run test:mcp

# Run mini4k.com website tests
npm run test:mini4k

# Run direct client call tests
npm run test:direct

言語設定

このプロジェクトは、中国語と英語の二言語による国際化に対応しています。環境変数を使用して言語を設定できます。

環境変数を使用する

言語を制御するには、MCP_LANG 環境変数を設定します。

# Set to English
export MCP_LANG=en
npm run server

# Set to Chinese
export MCP_LANG=zh
npm run server

# Windows system
set MCP_LANG=zh
npm run server

環境変数を使用すると、関連するすべてのプロセス（MCP サーバーを含む）で同じ言語設定が確実に使用されます。

デフォルト言語

デフォルトでは、システムは次の優先順位に従って言語を選択します。

1. MCP_LANG 環境変数
2. オペレーティングシステムの言語（「zh」で始まる場合は中国語を使用）
3. 英語（最終的なフォールバック）

デバッグ

このプロジェクトはMCPプロトコル仕様に準拠しており、JSON-RPC 通信への干渉を避けるため、デフォルトではログを出力しません。デバッグ情報は呼び出しパラメーターで制御します。

debug パラメーターを使用する

ツールの呼び出し時に、debug: true パラメーターを設定します。

{
  "url": "https://example.com",
  "debug": true
}

デバッグメッセージは、次の形式で標準エラー出力（stderr）に送信されます。

[MCP-SERVER] MCP server starting...
[CLIENT] Fetching URL: https://example.com

デバッグログファイル

デバッグモードが有効な場合、すべてのデバッグメッセージは次の場所にあるログファイルにも書き込まれます。

~/.mult-fetch-mcp-server/debug.log

このログファイルには、MCP リソース API からアクセスできます。

// Access the debug log file
const result = await client.readResource({ uri: "file:///logs/debug" });
console.log(result.contents[0].text);

// Clear the debug log file
const clearResult = await client.readResource({ uri: "file:///logs/clear" });
console.log(clearResult.contents[0].text);

プロキシ設定

このツールでは、さまざまな方法でプロキシ設定を構成できます。

1. proxy パラメーターを使用する

最も直接的な方法は、リクエストパラメーターでプロキシを指定することです。

{
  "url": "https://example.com",
  "proxy": "http://your-proxy-server:port",
  "debug": true
}

2. 環境変数を使用する

このツールは、標準の環境変数からプロキシ設定を自動的に検出して使用します。

# Set proxy environment variables
export HTTP_PROXY=http://your-proxy-server:port
export HTTPS_PROXY=http://your-proxy-server:port

# Run the server
npm run server

3. システムプロキシの検出

このツールは、オペレーティングシステムに基づいてシステムプロキシ設定の検出を試みます。

• Windows：set コマンドを使用して、環境変数からプロキシ設定を読み取ります
• macOS/Linux：env コマンドを使用して、環境変数からプロキシ設定を読み取ります

4. プロキシのトラブルシューティング

プロキシの検出に問題がある場合：

1. debug: true パラメーターを使用して、プロキシ検出の詳細なログを確認します
2. proxy パラメーターを使用して、プロキシを明示的に指定します
3. プロキシ URL が正しい形式（http://host:port または https://host:port）であることを確認します
4. ブラウザー機能が必要なウェブサイトでは、useBrowser: true を設定してブラウザーモードを使用します

5. ブラウザーモードとプロキシ

ブラウザーモード（useBrowser: true）を使用する場合、ツールは次のように動作します。

1. まず、明示的に指定されたプロキシがあれば、それを使用します
2. 次に、システムプロキシ設定の使用を試みます
3. 最後に、プロキシが見つからない場合は、プロキシを使用せずに処理を続行します

ブラウザーモードは、スクレイピング対策を実装しているウェブサイトや、JavaScript の実行が必要なウェブサイトで特に役立ちます。

パラメーターの処理

このプロジェクトでは、パラメーターを次のように処理します。

• debug：呼び出しパラメーターで渡されるため、リクエストごとにデバッグ出力を有効にするかどうかを個別に制御できます
• MCP_LANG：環境変数から取得され、サーバー全体の言語設定を制御します

使用方法

クライアントの作成

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import path from 'path';
import { fileURLToPath } from 'url';

// Get the directory path of the current file
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Create client transport layer
const transport = new StdioClientTransport({
  command: 'node',
  args: [path.resolve(__dirname, 'dist/index.js')],
  stderr: 'inherit',
  env: {
    ...process.env  // Pass all environment variables, including MCP_LANG
  }
});

// Create client
const client = new Client({
  name: "example-client",
  version: "1.0.0"
});

// Connect to transport layer
await client.connect(transport);

// Use client
const result = await client.callTool({
  name: 'fetch_html',
  arguments: {
    url: 'https://example.com',
    debug: true  // Control debug output through parameters
  }
});

if (result.isError) {
  console.error('Fetch failed:', result.content[0].text);
} else {
  console.log('Fetch successful!');
  console.log('Content preview:', result.content[0].text.substring(0, 500));
}

対応ツール

• fetch_html：ウェブページの HTML コンテンツを取得します
• fetch_json：JSON データを取得します
• fetch_txt：プレーンテキストを取得します
• fetch_markdown：Markdown 形式のコンテンツを取得します
• fetch_plaintext：HTML から変換したプレーンテキストを取得します（HTML タグを除去します）

リソースのサポート

サーバーは resources/list メソッドと resources/read メソッドをサポートしていますが、現在、実装内にリソースは定義されていません。リソースシステムは、プロジェクトファイルやドキュメントへのアクセスを提供するように設計されていますが、この機能はまだ完全には実装されていません。

リソースの使用例

// Example: List available resources
const resourcesResult = await client.listResources({});
console.log('Available resources:', resourcesResult);

// Note: Currently this will return empty lists for resources and resourceTemplates

サポートされているプロンプトテンプレート

サーバーでは、次のプロンプトテンプレートを利用できます。

• fetch-website：形式とブラウザーモードを指定して、ウェブサイトのコンテンツを取得します
• extract-content：CSS セレクターとデータ型を指定して、ウェブサイトから特定のコンテンツを抽出します
• debug-fetch：ウェブサイトの取得に関する問題をデバッグし、考えられる原因を分析して解決策を提示します

プロンプトテンプレートの使用方法

1. prompts/list を使用して、利用可能なプロンプトテンプレートの一覧を取得します
2. prompts/get を使用して、特定のプロンプトテンプレートの内容を取得します

// Example: List available prompt templates
const promptsResult = await client.listPrompts({});
console.log('Available prompts:', promptsResult);

// Example: Get website content prompt
const fetchPrompt = await client.getPrompt({
  name: "fetch-website",
  arguments: {
    url: "https://example.com",
    format: "html",
    useBrowser: "false"
  }
});
console.log('Fetch website prompt:', fetchPrompt);

// Example: Debug website fetching issues
const debugPrompt = await client.getPrompt({
  name: "debug-fetch",
  arguments: {
    url: "https://example.com",
    error: "Connection timeout"
  }
});
console.log('Debug fetch prompt:', debugPrompt);

パラメーターのオプション

各ツールでは、次のパラメーターを使用できます。

基本パラメーター

• url：取得する URL（必須）
• headers：カスタムリクエストヘッダー（任意、デフォルトは {}）
• proxy：http://host:port または https://host:port 形式のプロキシサーバー URL（任意）

ネットワーク制御パラメーター

• timeout：タイムアウト時間（ミリ秒単位、任意、デフォルトは 30000）
• maxRedirects：追跡するリダイレクトの最大数（任意、デフォルトは 10）
• noDelay：リクエスト間のランダムな遅延を無効にするかどうか（任意、デフォルトは false）
• useSystemProxy：システムプロキシを使用するかどうか（任意、デフォルトは true）

コンテンツサイズ制御パラメーター

• enableContentSplitting：大きなコンテンツをチャンクに分割するかどうか（任意、デフォルトは true）
• contentSizeLimit：分割を開始する前の最大コンテンツサイズ（バイト単位、任意、デフォルトは 50000）
• startCursor：特定の位置からコンテンツを取得する際の開始カーソル位置（バイト単位、任意、デフォルトは 0）

これらのパラメーターを使用すると、AI モデルのコンテキストサイズ制限を超える大きなコンテンツを管理できます。ウェブコンテンツを扱いやすいチャンクに分けて取得しながら、情報全体を処理できます。

チャンク管理

• chunkId：コンテンツが分割されたときに設定されるチャンクセットの一意の識別子（後続のチャンクを要求する際に使用）

コンテンツがチャンクに分割されると、レスポンスには、AI が chunkId と startCursor パラメーターを使用して後続のチャンクを要求できるメタデータが含まれます。システムではバイト単位でチャンクを管理するため、コンテンツの取得を正確に制御でき、任意の位置からコンテンツをシームレスに処理できます。

モード制御パラメーター

• useBrowser：ブラウザーモードを使用するかどうか（任意、デフォルトは false）
• useNodeFetch：Node.js モードの使用を強制するかどうか（任意、デフォルトは false、useBrowser とは相互排他）
• autoDetectMode：標準モードで 403／Forbidden エラーが発生した場合に、ブラウザーモードを自動検出して切り替えるかどうか（任意、デフォルトは true）。自動で切り替えず、指定したモードを厳密に使用するには false に設定します。

ブラウザーモード固有のパラメーター

• waitForSelector：ブラウザーモードで待機するセレクター（任意、デフォルトは 'body'）
• waitForTimeout：ブラウザーモードでの待機時間（ミリ秒単位、任意、デフォルトは 5000）
• scrollToBottom：ブラウザーモードでページの一番下までスクロールするかどうか（任意、デフォルトは false）
• saveCookies：ブラウザーモードで Cookie を保存するかどうか（任意、デフォルトは true）
• closeBrowser：ブラウザーインスタンスを閉じるかどうか（任意、デフォルトは false）

コンテンツ抽出パラメーター

• extractContent：Readability アルゴリズムを使用してメインコンテンツを抽出するかどうか（任意、デフォルトは false）
• includeMetadata：抽出したコンテンツにメタデータを含めるかどうか（任意、デフォルトは false、extractContent が true の場合のみ有効）
• fallbackToOriginal：抽出に失敗した場合に元のコンテンツにフォールバックするかどうか（任意、デフォルトは true、extractContent が true の場合のみ有効）

デバッグパラメーター

• debug：デバッグ出力を有効にするかどうか（任意、デフォルトは false）

コンテンツ抽出機能

コンテンツ抽出機能を使用すると、ナビゲーションバー、広告、サイドバーなどの不要な要素を除外して、Web ページの主要なコンテンツを取得できます。

{
  "url": "https://example.com/article",
  "extractContent": true,
  "includeMetadata": true
}

抽出されたコンテンツには、次のメタデータが含まれます（利用可能な場合）。

• タイトル
• 執筆者（著者）
• サイト名
• 抜粋
• コンテンツの長さ
• 可読性フラグ（isReaderable）

特殊な使い方

コンテンツ抽出の例

記事の Web ページから意味のあるコンテンツだけを抽出するには、次のようにします。

{
  "url": "https://example.com/news/article",
  "extractContent": true,
  "includeMetadata": true
}

コンテンツ抽出に失敗する可能性がある Web サイトでは、fallbackToOriginal を使用すると、何らかのコンテンツを確実に取得できます。

{
  "url": "https://example.com/complex-layout",
  "extractContent": true,
  "fallbackToOriginal": true
}

フェッチせずにブラウザーを閉じる

フェッチ操作を行わずにブラウザーインスタンスを閉じるには、次のようにします。

{
  "url": "about:blank",
  "closeBrowser": true
}

プロキシの優先順位

プロキシは次の順序で決定されます。

1. コマンドラインで指定されたプロキシ
2. リクエストの proxy パラメーター
3. 環境変数（useSystemProxy が true の場合）
4. Git の設定（useSystemProxy が true の場合）

proxy が設定されている場合、useSystemProxy は自動的に false に設定されます。

デバッグ出力

debug: true が設定されている場合、ログは次のプレフィックスを付けて stderr に出力されます。

• [MCP-SERVER]：MCP サーバーからのログ
• [NODE-FETCH]：Node.js フェッチャーからのログ
• [BROWSER-FETCH]：ブラウザーフェッチャーからのログ
• [CLIENT]：クライアントからのログ
• [TOOLS]：ツールの実装からのログ
• [FETCHER]：メインフェッチャーインターフェースからのログ
• [CONTENT]：コンテンツ処理に関するログ
• [CONTENT-PROCESSOR]：HTML コンテンツプロセッサーからのログ
• [CONTENT-SIZE]：コンテンツサイズの管理に関するログ
• [CHUNK-MANAGER]：コンテンツのチャンク化処理に関するログ
• [ERROR-HANDLER]：エラー処理に関するログ
• [BROWSER-MANAGER]：ブラウザーインスタンスマネージャーからのログ
• [CONTENT-EXTRACTOR]：コンテンツ抽出機能からのログ

ライセンス

MIT

---

lmcc-dev による更新