Brsearch MCP Server

🚀 URL Text Fetcher MCP Server

このサーバーは、FastMCPフレームワークを使用して構築された最新のModel Context Protocol (MCP) サーバーです。LM Studioやその他のMCP互換クライアントと共に使用でき、URLのテキスト取得、ウェブスクレイピング、ウェブ検索機能を提供します。

このサーバーは、最新のFastMCPフレームワークを使用して構築されており、以下の特長を備えています。

• クリーンなデコレータベースのツール定義
• 型ヒントからの自動スキーマ生成
• 簡素化されたサーバーのセットアップと構成
• より良いエラーハンドリングとロギング

すべてのセキュリティ機能と機能は、MCPのベストプラクティスに沿って近代化されながらも維持されています。

✨����������������������������

主な機能

このMCPサーバーは、AIモデルに以下の機能を提供します。

• テキストコンテンツの取得：任意のURLからすべての可視テキストを抽出します。
• リンクの抽出：ウェブページから関連するリソースを発見するためにリンクを抽出します。
• ウェブ検索：Brave Searchを使用してウェブを検索し、上位の検索結果から自動的にコンテンツを取得します。
• エラーの適切なハンドリング：適切なタイムアウトと例外ハンドリングにより、エラーを適切に処理します。

📦 セキュリティ機能

企業レベルのセキュリティ実装：

• SSRF保護：内部ネットワークとメタデータエンドポイントへのリクエストをブロックします。
• 入力サニタイズ：すべてのURLとクエリ入力を検証し、クリーンアップします。
• メモリ保護：コンテンツサイズ制限により、メモリ枯渇を防止します。
• レート制限：スレッドセーフなAPIレート制限で、設定可能なしきい値を持ちます。
• エラーハンドリング：情報漏洩なしで包括的な例外ハンドリングを行います。

🛠️ ツール

このサーバーは、3つの主要なツールを提供します。

fetch_url_text

• 説明：URLからすべての可視テ�キストをダウンロードします。
• パラメータ：
  • url (文字列、必須)：テキストを取得するURL
• 戻り値：ウェブページからのクリーンなテキストコンテンツ

fetch_page_links

• 説明：ウェブページからすべてのリンクを抽出します。
• パラメータ：
  • url (文字列、必須)：リンクを取得するURL
• 戻り値：ページ上で見つかったすべてのhrefリンクのリスト

brave_search_and_fetch

• 説明：Brave Searchを使用してウェブを検索し、上位の検索結果から自動的にコンテンツを取得します。
• パラメータ：
  • query (文字列、必須)：検索クエリ
  • max_results (整数、オプション)：コンテンツを取得する最大結果数 (デフォルト: 3、最大: 10)
• 戻り値：各結果URLからの完全なテキストコンテンツを含む検索結果

📋 前提条件

Brave Search APIキー

検索機能を使用するには、無料のBrave Search APIキーが必要です。

1. Brave Search APIにアクセスします。
2. 無料アカウントにサインアップします (月2,000クエリ、1秒あたり1リクエスト)
3. APIキーを取得します。
4. .env.exampleを.envにコピーし、APIキーを追加します。

   cp .env.example .env
   # .envを編集し、BRAVE_API_KEY=your_actual_api_keyを設定します
   

📦 インストール

1. このリポジトリをクローンします。
2. 依存関係をインストールします。

   uv sync --dev --all-extras
   

3. 環境を構成します。

   cp .env.example .env
   # .envファイルを編集し、BRAVE_API_KEYを設定します
   

💻 使用例

LM Studioでの使用

1. LM Studioを開き、統合セクションに移動します。
2. 「インストール」をクリックし、次に「mcp.jsonを編集」をクリックします。

FastMCP実装 (推奨)

3. オプションA: 構成ヘルパースクリプトを使用する

   ./configure_lmstudio_fastmcp.sh
   

   これにより、システムに適した正しいパスで構成が生成されます。

4. オプションB: 手動構成 - サーバー構成を追加します。

{
  "mcpServers": {
    "url-text-fetcher-fastmcp": {
      "command": "uv",
      "args": [
        "run", 
        "url-text-fetcher-fastmcp"
      ],
      "cwd": "/Users/wallison/TechProjects/mcp-server"
    }
  }
}

レガシー実装 (低レベル)

レガシー実装の場合：

./configure_lmstudio.sh  # レガシーサーバーの構成を生成します

注意：APIキーは、プロジェクトディレクトリ内の.envファイルから自動的に読み込まれます。

5. 構成を保存し、LM Studioを再起動します。
6. サーバーが統合セクションに表示されます。

スタンドアローンでの使用

サーバーを直接実行することもできます。

# FastMCP実装 (推奨)
uv run url-text-fetcher-fastmcp

# レガシー実装
uv run url-text-fetcher

💻 使用例

LM Studioで構成された後、AIに以下のような要求をすることができます。

• "https://example.com からテキストコンテンツを取得して"
• "https://news.example.com からすべてのリンクを取得して"
• "「Pythonウェブスクレイピング」を検索し、上位3件の結果のコンテンツを表示して"
• "AIに関する最新のニュースは何ですか？検索して全文記事を取得して"
• "MCPサーバーに関する情報を見つけ、詳細なコンテンツを取得して"

📚 依存関係

• mcp>=1.12.3 - Model Context Protocolフレームワーク
• requests>=2.31.0 - ウェブリクエストとBrave Search API用のHTTPライブラリ
• beautifulsoup4>=4.12.0 - HTML解析とテキスト抽出

🛠️ 構成

サーバーは.envファイルを介して構成できます。

# 必須: Brave Search APIキー
BRAVE_API_KEY=your_api_key_here

# Brave Search APIレート制限 (秒あたりのリクエスト数)
# 無料プラン: 秒あたり1リクエスト (デフォルト)
# 有料プラン: 秒あたり20リクエスト
# 上位プラン: 秒あたり50リクエスト
# これをあなたのサブスクリプションレベルに合わせて設定します
BRAVE_RATE_LIMIT_RPS=1

# オプション: リクエストタイムアウト (秒) (デフォルト: 10)
REQUEST_TIMEOUT=10

# オプション: 文字数でのコンテンツ長制限 (デフォルト: 5000)
CONTENT_LENGTH_LIMIT=5000

# オプション: バイトでの最大レスポンスサイズ (デフォルト: 10MB)
MAX_RESPONSE_SIZE=10485760

Brave Searchサブスクリプションレベル

サーバーは、あなたのBrave Searchサブスクリプションに基づいて自動的にレート制限を調整します。

• 無料プラン：秒あたり1リクエスト (BRAVE_RATE_LIMIT_RPS=1)
• 有料プラン：秒あたり20リクエスト (BRAVE_RATE_LIMIT_RPS=20)
• 上位プラン：秒あたり50リクエスト (BRAVE_RATE_LIMIT_RPS=50)

サーバーは、すべての同時リクエストに対して構成されたレート制限を適用し、APIクォータ内に収まるようにします。

.env.exampleをテンプレートとして参照してください。

🚧 トラブルシューティング

LM Studio構成問題

LM Studioログに「Failed to spawn: url-text-fetcher」のようなエラーが表示される場合：

1. 構成ヘルパーを実行する

   ./configure_lmstudio.sh
   

2. 完全なパスを使用することを確認する

   • uvの完全なパスを使用します (例: /Users/username/.local/bin/uv)
   • 構成にcwd (現在の作業ディレクトリ) を含めます
   • BRAVE_API_KEY環境変数を設定します

3. サーバーを手動でテストする

   uv run url-text-fetcher
   

   サーバーが起動し、入力を待機するはずです (Ctrl+Cで終了)。

4. APIキーを確認する

   # .envファイルにAPIキーが設定されているか確認する
   cat .env | grep BRAVE_API_KEY
   

   または手動でテストする：

   export BRAVE_API_KEY=your_actual_api_key
   echo $BRAVE_API_KEY  # キーが表示されるはず
   

一般的な問題

• "BRAVE_API_KEY environment variable is required"：.envファイルにBRAVE_API_KEY=your_actual_api_keyが含まれていることを確認してください。
• "Network error"：インターネット接続とAPIキーの有効性を確認してください。
• "Content truncated"：非常に長いウェブページの場合は正常な動作です (デフォルトでコンテンツは5000文字に制限されています)。

🛠️ エラーハンドリング

サーバーには、以下の強力なエラーハンドリングが含まれています。

• ネットワークタイムアウト (デフォルト10秒)
• 無効なURL
• HTTPエラー (4xx、5xxレスポンス)
• 解析失敗
• 欠落したAPIキー
• 一般的な例外

すべてのエラーは、説明的なテキストメッセージとして返され、ユーザーが何が問題であるかを理解しやすくします。

🚧 開発

このプロジェクトでは、以下を使用しています。

• Python 3.13+
• uv 依存関係管理
• MCP SDK プロトコル実装

開発用にセットアップするには：

1. リポジトリをクローンします。
2. uv sync --dev --all-extrasを実行します。
3. 変更を加えます。
4. MCP互換クライアントでテストします。

デバッグ

MCPサーバーはstdioを介して実行されるため、デバッグは困難な場合があります。最高のデバッグ体験を得るために、MCP Inspectorの使用を強くお勧めします。

以下のコマンドでnpmを介してMCP Inspectorを起動できます。

npx @modelcontextprotocol/inspector uv --directory /Users/wallison/TechProjects/mcp-server run url-text-fetcher

起動すると、Inspectorはブラウザでアクセスしてデバッグを開始できるURLを表示します。

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。