mcp-web-tools-server

カスタム Model Context Protocol (MCP) サーバーです。AIエージェントに、ウェブページを取得してコンテンツを抽出するための実用的なツール（読みやすい記事テキスト、CSSセレクタによる構造化データ、robots.txtのパーミッションチェック）を提供します。

MCPとは？

MCPは、Anthropicが最初に公開したオープンプロトコルであり、AIアプリケーション（Claude DesktopやClaude Codeなど）が外部ツールやデータソースに接続する方法を標準化します。各AIアプリが独自のプラグインフォーマットを考案するのではなく、MCPサーバーは固定されたツールセット（およびオプションでリソースとプロンプト）をシンプルなJSON-RPCインターフェースで公開し、MCP互換のクライアントはそれらを同じ方法で発見して呼び出すことができます。このリポジトリはそのようなサーバーの一つです。小さなローカルプロセスとして実行され、stdioを介してMCPを話すため、どのMCPクライアントでも、内部でhttpx、selectolax、trafilaturaが何かを知らなくても、そのツールを一覧表示して呼び出すことができます。

これが有用な理由

そのままの状態では、LLMはライブのウェブページを取得できません。このサーバーは、小さく、テスト済みで、適切にスコープされたツールセットでそのギャップを埋めます。エージェントは、記事から読み取り可能なテキストを取得したり、CSSセレクタによってページから特定のフィールド（価格、タイトル、タグなど、ページ構造に応じて）を取得したり、リクエストを行う前にサイトのrobots.txtが許可しているかどうかを確認したりできます。これは、汎用的なスクレイピングフレームワークではなく、意図的に狭い範囲に焦点を当てています。正しく動作し、予測可能な方法で失敗する少数のツールの方が、時々動作しない広い表面積よりもエージェントにとって有用であるという考えに基づいています。

ツール

fetch_and_extract(url: str) -> str

URLを取得し、クリーンで読み取り可能なメインコンテンツテキストを返します。スクリプト、スタイル、ナビゲーション、広告、フッターは除去されます。記事の抽出にはtrafilaturaを使用し、trafilaturaが確実に処理できないページには（selectolaxに基づく）段落密度ヒューリスティックをフォールバックとして使用します。

extract_structured(url: str, css_selectors: dict) -> dict

URLを取得し、CSSセレクタでフィールドを抽出します。例：

{"title": "h1", "price": ".price", "tags": ".tag-list a"}

返り値：

{"title": "Trail Blazer 29 Mountain Bike", "price": "$1,249.00", "tags": ["mountain", "hardtail", "29er"]}

1つの要素に一致するセレクタはそのテキストを返し、複数に一致する場合はそれらのテキストのリストを返し、一致しない場合はnullを返します。パースはselectolaxで行われます。

check_robots_txt(url: str) -> dict

ターゲットサイトのrobots.txtを取得し、このサーバーのユーザーエージェントが指定されたURLへのリクエストを許可されているかどうかを、Pythonの標準urllib.robotparserを使用して報告します。robots.txtが見つからない場合は、黙って許可されたとみなすのではなく、明示的に報告します（robots_txt_found: false）。

これは、スクレイピングのエチケットが後付けではなく第一級の関心事であるべきだからです。エージェント（またはそれを操作する人）は、物事がうまくいかなくなったときだけでなく、取得する前にパーミッションを確認できるべきです。

設計原則

• 正直な識別。 リクエストは、偽装されたブラウザUAではなく、このツールを識別しこのリポジトリにリンクする実際のUser-Agent文字列を使用します。

• 制限されたリクエスト。 すべてのフェッチには固定のタイムアウト（デフォルト10秒）があるため、遅いハングアップするサーバーがセッション全体を停止させることはありません。

• robots.txtはツールであり、黙って強制されない。 check_robots_txtは、エージェント（またはそれを操作する人）がスクレイピングの前にパーミッションを確認できるように提供されていますが、現在のところfetch_and_extractやextract_structuredを自動的にブロックすることはありません。以下の「制限事項」を参照してください。

• 不正な入力でクラッシュしない。 ネットワーク障害、タイムアウト、無効なURLはキャッチされ、クリーンなエラーテキストまたは{"error": ...} dictとして返され、サーバープロセスを強制終了させる未処理の例外は発生しません。

プロジェクト構成

mcp_web_tools/
  server.py        MCP server definition and the three tool entry points
  extractors.py     Pure HTML-parsing logic (no network), used for readable-text and CSS-selector extraction
  robots.py         robots.txt fetching and permission checking
  http_client.py    Shared httpx fetch helper: user agent, timeout, error handling
tests/
  test_extractors.py    Unit tests against local HTML fixtures, no network
  test_robots.py        Unit tests with the network call mocked out
  test_http_client.py   Unit tests for URL validation
  test_integration.py   Integration tests against live public sites, marked and run separately
  fixtures/              Static HTML used by the unit tests
scripts/
  test_client.py    Standalone script that launches the server and talks real MCP protocol to it

サーバーの実行

python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

pip install -r requirements.txt
python -m mcp_web_tools.server

サーバーはMCPプロトコルを使用してstdioを介して通信します。ターミナルから直接実行しても、クライアントが接続するのを待っているだけです。MCPクライアント（下記参照）または付属のテストクライアントスクリプトを介して使用してください。

Claude DesktopまたはClaude CodeでMCPサーバーとして設定する

MCPクライアントのサーバー設定にエントリを追加し、commandをvenvのPythonインタープリターに向け、argsをモジュールに向けます。Claude Desktopの場合、これはclaude_desktop_config.jsonに記述します：

{
  "mcpServers": {
    "web-tools": {
      "command": "C:\\path\\to\\mcp-web-tools-server\\venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_web_tools.server"],
      "cwd": "C:\\path\\to\\mcp-web-tools-server"
    }
  }
}

macOS/Linuxでは、commandは/path/to/mcp-web-tools-server/venv/bin/pythonになります。

Claude Codeの場合、以下を実行します：

claude mcp add web-tools -- /path/to/mcp-web-tools-server/venv/bin/python -m mcp_web_tools.server

（該当する場合はWindowsのvenvパスに置き換えてください）、またはプロジェクトの.mcp.jsonに同等のエントリを追加します。

テストの実行

ユニットテストはローカルのHTMLフィクスチャに対して実行され、ネットワークにはアクセスしません：

pytest

統合テストは実際の安定したパブリックテストサイト（example.comとbooks.toscrape.com、標準的なパブリックスクレイピングテスト/デモターゲット）にアクセスし、デフォルトの実行からは除外されています。ネットワークにアクセスできる場合は明示的に実行してください：

pytest -m integration

また、Python関数を直接呼び出すのではなく、実際のMCPクライアント/サーバープロトコルを介してサーバーを実際のサブプロセスとして起動し駆動するスタンドアロンスクリプトもあります：

python scripts/test_client.py

制限事項と次に追加したいもの

• JavaScriptレンダリングなし。 このサーバーはhttpxで生のHTMLを取得します。コンテンツをクライアントサイドでレンダリングするページ（ヘビーなReact/Vue SPA）は、ほとんど、またはまったく有用なものを返しません。ヘッドレスブラウザフェッチ用のPlaywrightをラップした4つ目のツールが当然の次の追加になりますが、実行がはるかに重くなります。

• レート制限なし。 各ツール呼び出しは、呼び出されたときに1つのリクエストを行います。エージェントが同じホストに対してタイトなループでツールを呼び出した場合、組み込みのドメインごとのスロットリングやリクエストキューはありません。check_robots_txtは、サイトが公開している場合にcrawl_delay_secondsを表示しますが、現在それを強制するものはありません。

• robots.txtは助言的であり、強制されない。 fetch_and_extractおよびextract_structuredは、取得する前に自動的にcheck_robots_txtを参照しません。これはこのバージョンにおける意図的なスコープ決定です（エージェントは最初にcheck_robots_txtを自分で呼び出す必要があります）が、許可されていないフェッチを自動的に拒否するより厳格なモードも合理的な追加でしょう。

• 可読性ヒューリスティックは基本的。 trafilaturaが確実な結果を生成しない場合に使用されるselectolaxのフォールバックは、単純な段落密度スコアラーです。典型的な記事やブログのレイアウトには十分ですが、特殊なページ構造では、専用の可読性ライブラリよりもパフォーマンスが低下します。

• キャッシュなし。 すべての呼び出しが再フェッチします。同じURLでも数秒後には。デモ/ポートフォリオサーバーには問題ありませんが、よりヘビーな使用には理想的ではありません。

• 実際にはシングルトランスポート。 サーバーはstdio用に設定されており、これはClaude DesktopとClaude Codeが使用するものです。mcp SDKはSSEおよびストリーマブルHTTPトランスポートもサポートしています。これらを配線することは、ローカルサブプロセスではなくホスト型サービスとして実行するために必要になります。