# search-mcp

Playwright経由で検索エンジンを叩くstdio MCP。Google / Bing / DuckDuckGo / Yahoo! JAPAN / Brave Search対応。

詳しい背景・設計・検証の経緯は [SPEC.md](SPEC.md) を参照。

## セットアップ

```
git clone https://github.com/antigravity-press/search-mcp.git
cd search-mcp
uv sync
uv run playwright install chromium
```

### 仮想ディスプレイの用意(headless=Falseを使う場合、オプション)

Google/DuckDuckGo/Brave等をheadlessで使う場合、bot判定回避のため`headless=False`
での起動を求められることがある(下記の表を参照)。この用途では**人間が画面を見る
必要は無い**ので、OS側に人間の接続に依存しない仮想ディスプレイさえ用意しておけば、
誰の接続にも依存せず常時headful検索が可能になる(SPEC.md 3節参照)。

用意しなくても動く(その場合はheadless専用になるだけ)。用意する場合、手段は環境
依存。Linuxサーバーの一例として、`Xvfb`が使えないディストロ(近年のRHEL系はWayland
移行でXvfbが標準から外れていることがある)では、`weston`(Waylandコンポジタ)の
headless backendでも同等のことができる:

```
sudo dnf install weston xorg-x11-server-Xwayland  # ディストロにより異なる
mkdir -p /tmp/.X11-unix   # 通常はX11パッケージが作るが無い場合は要作成
weston --backend=headless --xwayland &
```

これで`:0`にX11ディスプレイが立つ。`search()`ツールは`headless=False`指定時、
環境変数`SEARCH_MCP_HEADFUL_DISPLAY`(既定値`:0`)で指定したディスプレイを自動的に
使う。永続化したい場合はsystemdサービス化する(このリポジトリのスコープ外、
OS側の環境セットアップとして各自で行う)。

## How To Use(全体の流れ)

```
MCPセットアップ → 利用可能(空プロファイル)
  ├─ 検索でheadful使いたい・Google/DuckDuckGo/Brave等をheadlessで安全に使いたい
  │    → OS側に人間の接続に依存しない仮想ディスプレイを用意する
  │       (このMCPの機能範囲外、一回きりの環境セットアップ。手段は環境依存)
  │       用意済みなら誰の接続にも依存せず常時headful検索が可能
  │
  └─ ログイン済みプロファイルで動かしたい
       ├─ 既存の育ったプロファイルが手元にある → import_profileで取り込むだけ(Display不要)
       └─ 無い・新規にログインしたい → bake_profileで焼き込み
            (ここでのheadfulは人間が操作できる本物のDisplayが必要、SSH X11フォワーディング/CDP等)
```

- 「検索フェーズのheadful」(bot判定回避目的、人間が見る必要なし)と「焼き付けフェーズのheadful」(人間が実際に操作する)は、要求がまったく別物。前者は仮想ディスプレイで完結し、後者は本物の(人間から見える)ディスプレイが要る
- プロファイルは`default`のみでも運用できる(空のまま使い始めて、必要に応じて育てる/インポートする)。複数プロファイルの使い分けは任意

## 使い方(ツール)

- `search(query, engine="google", profile="default", num_results=10, headless=True)` — 検索を実行
- `fetch_page(url, profile="default", headless=True)` — 検索結果の深掘り用に本文を取得
- `list_profiles()` — 保持しているプロファイルの一覧
- `import_profile(source_dir, name, overwrite=False)` — 既存のログイン済みプロファイルを取り込む
- `bake_profile(profile, method="auto", start_url=None, ...)` — プロファイルへのログイン等を焼き付ける(SPEC.md 4節)

## エンジンごとのheadless/headfulブロック状況(2026-09-05実地検証)

`profile`の育ち具合(ログイン等で使い込まれているか、作成直後で無履歴か)によって、
headlessで安全に使えるかどうかが変わる。詳細はSPEC.md 8節参照。

| エンジン | 育ったprofile, headless | 育ったprofile, headful | 新規profile, headless | 新規profile, headful |
|---|---|---|---|---|
| Google | ✅ OK | ✅ OK | ❌ ブロック | ✅ OK |
| Bing | ✅ OK | 未検証 | ✅ OK | ✅ OK |
| Yahoo! JAPAN | ✅ OK | 未検証 | ✅ OK | ✅ OK |
| DuckDuckGo | ❌ ブロック | ✅ OK | ❌ ブロック | ✅ OK |
| Brave | ❌ ブロック | ✅ OK | ❌ ブロック | ✅ OK |

**運用の指針**:
- Bing/Yahoo! JAPANはどちらの状態でもheadlessで問題ない
- Google/DuckDuckGo/Braveをheadlessで使うには、ログイン等で育ったprofileが実質必須。新規profileはまずheadfulで使い始めるか、`import_profile`で既存の育ったprofileを取り込むこと
- DuckDuckGo/Braveは育ったprofileでもheadlessだと即ブロックされる。常にheadful推奨(人間の接続に依存しない仮想ディスプレイがOS側にあれば、人間の接続なしに常時利用可能)

## Claude Codeへの登録

```
claude mcp add search-mcp --scope user -- /path/to/search-mcp/.venv/bin/search-mcp
```