Maibaamcrawler

mcp-research

ウェブ調査、学術論文、Twitter/X、YouTube、ファイル取り込みに対応する MCP サーバーです。AI アシスタント向けの8つのツールを、すべて MCP stdio プロトコル経由で提供します。機関アクセス用の認証情報保管庫、CAPTCHA 検出、トークン効率の高い出力を備えています。

ツール

ツール	説明
web_search	3段階の検索カスケード：Brave API → DuckDuckGo → HTML スクレイパー
fetch_url	あらゆる URL を取得 → クリーンな Markdown に変換。SSRF 保護と24時間キャッシュ付き
research	複合パイプライン：クエリの書き換え → 検索 → 並列取得 → 要約 → 統合
youtube_essence	YouTube 動画 → 文字起こし、要約、重要ポイント、チャプター、引用
deep_ingest	ファイルからテキストを抽出：PDF、DOCX、XLSX、PPTX、音声、動画、画像
academic_lookup	DOI / ArXiv / PubMed を解決 → 機関アクセス経由でメタデータと全文を取得
twitter_extract	X.com/Twitter からツイートとスレッドを抽出
vault_status	読み込まれた認証情報プロファイルと依存関係の状態を表示（シークレットは公開しません）

すべてのツールは読み取り専用です。コンテンツの取得と変換のみを行い、何も変更しません。

インストール

pip install mcp-research

または、uvx を使って直接実行できます（インストール不要）：

uvx mcp-research

オプションの追加機能：

pip install 'mcp-research[twitter]'    # yt-dlp for Twitter extraction
pip install 'mcp-research[youtube]'    # yt-dlp + faster-whisper for YouTube
pip install 'mcp-research[academic]'   # PyPDF2 for academic PDFs
pip install 'mcp-research[ingest]'     # PDF, DOCX, XLSX, PPTX, audio support
pip install 'mcp-research[all]'        # everything

セットアップを確認します：

mcp-research doctor

Claude Code での使用方法

Claude Code の MCP 設定（~/.claude/settings.json またはプロジェクトの .mcp.json）に追加します：

{
  "mcpServers": {
    "research": {
      "command": "uvx",
      "args": ["mcp-research"],
      "env": {
        "BRAVE_API_KEY": "BSA...",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

Claude Desktop での使用方法

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "research": {
      "command": "uvx",
      "args": ["mcp-research"],
      "env": {
        "BRAVE_API_KEY": "BSA..."
      }
    }
  }
}

設定

すべての設定は環境変数で行います。設定ファイルは不要です（オプションの認証情報保管庫を除く）。

変数	デフォルト	説明
BRAVE_API_KEY	(empty)	Brave Search API キー。未設定の場合は DuckDuckGo にフォールバックします。
OLLAMA_URL	http://localhost:11434	要約／統合に使用する Ollama エンドポイント。空にすると無効になります。
OLLAMA_MODEL	qwen2.5:14b	要約と統合に使用するモデル。
MCP_RESEARCH_CACHE_DIR	~/.mcp-research/cache/	URL 取得キャッシュのディレクトリ。
MCP_RESEARCH_CACHE_TTL	24	キャッシュの有効期間（時間）。
MCP_RESEARCH_LOG_DIR	~/.mcp-research/logs/	検索ログのディレクトリ（NDJSON）。
MCP_RESEARCH_MAX_RESULTS	10	検索結果のデフォルト最大数。
MCP_RESEARCH_VAULT_FILE	~/.mcp-research/vault.yaml	認証情報保管庫ファイルのパス。
MCP_RESEARCH_VAULT_HOT_RELOAD	true	ファイルの変更時に認証情報保管庫を自動で再読み込みします。
MCP_RESEARCH_SESSION_TTL	1800	セッションのアイドルタイムアウト（秒）。

ツールの詳細

web_search

web_search(query, max_results=5, summarize=False, auto_fetch_top=False)

信頼性を最大限に高めるため、3段階のカスケードでウェブを検索します。

1. Brave Search API — 高速で高品質（BRAVE_API_KEY が必要）
2. DuckDuckGo ライブラリ — API キー不要。レート制限時には再試行します
3. DuckDuckGo HTML スクレイパー — 最終手段のフォールバック

オプション：

• summarize：Ollama を使用して結果を要約します（Ollama の実行が必要）
• auto_fetch_top：最上位の検索結果の全文も取得して返します

fetch_url

fetch_url(url, summarize=False, max_chars=15000)

URL を取得し、クリーンな Markdown に変換します。

• SSRF 保護：localhost、プライベート IP、HTTP 以外のスキームをブロックします
• スマートな再試行：429／5xx では指数バックオフを行い、リダイレクトの各段階で検証します
• 24時間キャッシュ：SHA-256 キーを使用し、有効期間を設定できます
• コンテンツ対応：HTML → Markdown、JSON → コードブロック、バイナリ → 拒否
• スマートな切り詰め：テキストの途中ではなく、見出しや段落の区切りで切り詰めます
• CAPTCHA 検出：Cloudflare、hCaptcha、reCAPTCHA、Akamai のブロックページを検出します
• トークン効率：デフォルトは15K文字（約4Kトークン）。max_chars で調整できます

research

research(query, depth="standard", context="")

複合リサーチパイプライン：

1. クエリの書き換え — Ollama が質問を検索キーワードに最適化します
2. ウェブ検索 — 関連するページを見つけます（検索結果がゼロの場合は、検索語を拡張して再試行します）
3. 並列取得 — 上位 N 件のページを並行して取得します
4. 要約 — Ollama が各ページを要約します
5. 統合 — Ollama が出典を引用した最終回答を作成します

深度レベル：

深度	ページ数	統合
quick	2	いいえ
standard	5	はい
deep	10	はい

Ollama がなくてもすべての手順は適切に縮退します。検索結果とページの内容は引き続き取得できます。

youtube_essence

youtube_essence(url, mode="standard")

YouTube 動画から構造化されたコンテンツを抽出します：

• 文字起こし：自動字幕または Whisper による文字起こし（ローカルで処理され、プライベートに保たれます）
• 要約：Ollama による AI 要約
• 要点：箇条書きの重要ポイント
• チャプター：タイムスタンプ付きのセクション
• 引用：注目すべき引用（deep モード）

モード：quick（要約）、standard（＋チャプター）、deep（＋引用）

yt-dlp が必要です。オプション：音声のみの動画には faster-whisper、メディアの抽出には ffmpeg を使用します。

deep_ingest

deep_ingest(path, include_types="", max_files=200, summarize=False)

ディレクトリ内のファイルまたは単一ファイルからテキストを抽出します：

• テキストファイル：.txt、.md、.json、.csv、ソースコードなど
• PDF：PyPDF2 経由（オプションの依存関係）
• Office：.docx、.xlsx、.pptx（オプションの依存関係）
• 音声／動画：Whisper による文字起こし（オプション）
• 画像：Ollama のビジョンモデルによる OCR（オプション）

種類フィルター：text、pdf、audio、video、image、office

academic_lookup

academic_lookup(identifier, fetch_fulltext=True)

複数の識別子タイプから学術論文を特定します：

• DOI：10.xxxx/... → Crossref メタデータ＋出版社へのリダイレクト
• ArXiv：2301.12345 → 要旨＋PDF
• PubMed：PMID → E-utilities メタデータ → DOI チェーン
• URL：出版社ページを検出

認証情報ボールトを使用して全文にアクセスできます：

• EZproxy の書き換え（プレフィックスモードおよびサフィックスモード）
• ベアラートークン、API キー、基本認証、Cookie jar
• 出版社の自動検出（IEEE、Springer、Elsevier、ACM、Wiley、Nature、JSTOR など）

twitter_extract

twitter_extract(url, include_thread=False)

戦略を順に試す方式で、X.com/Twitter からツイートとスレッドを抽出します：

1. yt-dlp（優先） — 認証済みアクセスには Cookie jar を使用できます
2. Twitter API v2 — ボールトでベアラートークンが設定されている場合
3. HTML 取得 — Cookie を使用する最後の手段

返される内容：テキスト、投稿者、タイムスタンプ、指標（いいね、リツイート、返信）、メディア URL。

vault_status

vault_status()

読み込まれた認証情報プロファイル、照合パターン、認証タイプを表示します — シークレットは決して公開しません。オプションの依存関係が利用可能かどうかも確認します。

認証情報ボールト

保護されたソースの認証を設定するには、~/.mcp-research/vault.yaml を作成します：

version: 1
profiles:
  # University EZproxy for IEEE
  ieee-university:
    match: "*.ieee.org/**"
    ezproxy:
      base_url: "https://ezproxy.myuniversity.edu/login?url="
      mode: prefix

  # Springer via API key
  springer:
    match: "*.springer.com/**"
    auth:
      type: api_key
      header: "X-ApiKey"
      value: "${SPRINGER_API_KEY}"

  # X.com via browser cookies
  twitter:
    match: "*.x.com/**"
    auth:
      type: cookie_jar
      path: "${HOME}/.mcp-research/cookies/twitter.txt"

• ${VAR} は環境変数から解決されます — シークレットがプレーンテキストで保存されることはありません
• 最初に一致したプロファイルが使用されます（順序が重要です）
• 認証タイプ：bearer、basic、api_key、cookie_jar、headers
• EZproxy モード：prefix（ベース URL を先頭に追加）または suffix（ドメインを書き換え）
• ホットリロード：ボールトファイルの変更は自動的に反映されます

トークン効率

すべてのツールは、AI のコンテキストウィンドウのトークンを無駄にしないよう、デフォルトで簡潔な出力を生成します：

ツール	デフォルトの出力	上書き方法
fetch_url	約 15K 文字（約 4K トークン）	max_chars パラメーター
research	ソースごとに約 500 トークン	生のコンテンツより要約を優先
academic_lookup	全文で約 10K 文字	通知を表示して切り詰め
deep_ingest	15 ファイル、抜粋は 300 文字	max_files パラメーター
youtube_essence	3K 文字の文字起こし抜粋	結果オブジェクトに全文を含む

安全性と堅牢性

• SSRF 保護：すべてのホップで、localhost、プライベート IP、リンクローカル、HTTP 以外のスキームをブロックします
• CAPTCHA 検出：Cloudflare、hCaptcha、reCAPTCHA、Akamai、DDoS-Guard のブロック画面を識別します
• 入力検証：サイズ制限、URL 検証、安全なリダイレクト追跡を実施します
• eval/exec なし：動的なコード実行はありません
• Vault のセキュリティ：シークレットは環境変数から解決され、repr() はすべての認証情報をマスキングします
• キャッシュの分離：所有者のみがアクセスできるディレクトリ権限（0o700）
• グレースフルデグラデーション：オプションの依存関係が不足していてもクラッシュせず、機能をわかりやすいメッセージとともに縮退させます

CLI

mcp-research serve                          # Run MCP stdio server (default)
mcp-research search "query"                 # Search the web
mcp-research fetch https://example.com      # Fetch URL to markdown
mcp-research youtube https://youtu.be/...   # Extract YouTube video
mcp-research ingest ./docs/                 # Extract text from files
mcp-research academic "10.1109/..."         # Resolve academic paper
mcp-research tweet https://x.com/.../123    # Extract tweet
mcp-research vault                          # Show vault profiles
mcp-research doctor                         # Check dependencies

開発

git clone https://github.com/MABAAM/Maibaamcrawler.git
cd Maibaamcrawler
pip install -e ".[all]"
pytest tests/ -v
python -m mcp_research

変更履歴

v0.3.0

• 認証情報 Vault：環境変数の補間、URL の glob マッチング、EZproxy の書き換え、ホットリロードに対応した ~/.mcp-research/vault.yaml の YAML 設定
• セッションプーリング：Vault による認証情報の注入、Cookie jar のサポート、アイドル状態のセッションの破棄に対応したドメインごとのセッション
• CAPTCHA 検出：Cloudflare、hCaptcha、reCAPTCHA、Akamai、DDoS-Guard、一般的なボットブロック画面を識別します
• 学術情報の検索：DOI／ArXiv／PubMed の解決、Crossref のメタデータ、Vault を介した機関向け全文へのアクセス
• Twitter/X 抽出：スレッドに対応した yt-dlp、API v2、Cookie ベースのアクセス
• トークン効率：AI のコンテキストを保持するため、出力の上限をデフォルトで設定（fetch は約 4K トークン、調査ソースごとに約 500 トークン）
• Doctor コマンド：mcp-research doctor ですべての依存関係と設定を確認します
• Windows のエンコーディング修正：UTF-8 の stdout/stderr ラッパーにより cp1252 のクラッシュを防ぎます

v0.2.0

• YouTube の要点抽出：文字起こしの抽出、AI による要約、要点、チャプター、引用
• 詳細な取り込み：PDF、DOCX、XLSX、PPTX、音声、動画、画像からテキストを抽出します
• Ollama 連携：クエリの書き換え、要約、統合、ビジョン OCR
• 検索ログ：すべての操作を NDJSON イベントログに記録します
• Brave Search：API キーに対応した主要な検索層

v0.1.0

• 初回リリース：3 つのツール（web_search、fetch_url、research）、SSRF 保護、キャッシュ

ライセンス

MIT