# Web MCP Server

Claude Code / Codex から利用する Web 検索・Web ページ取得用の MCP サーバーです。

## コマンド

開発は Windows でも行えますが、運用時は Docker 上の Ubuntu で動かす前提です。

Linux / Docker コンテナ内の想定:

```bash
npm install
npm run build
npm run dev
```

Windows 開発環境:

```powershell
npm install
npm run build
npm run dev
```

Docker イメージで HTTP MCP サーバーとして起動:

```bash
docker build -t web-mcp .
docker run --rm -p 3000:3000 web-mcp
```

Docker Compose で起動:

```bash
cd mcp
docker compose up -d --build
```

HTTP MCP endpoint:

```text
http://localhost:3000/mcp
```

stdio サーバーとして使う場合は、クライアントが `node dist/index.js` を起動します。
Docker で stdio として使う場合は、`docker run -i --rm web-mcp node dist/index.js` のように標準入力・標準出力をクライアントへ接続してください。

ビルド後、MCP クライアントからは以下のように起動できます。

```json
{
  "mcpServers": {
    "web-mcp": {
      "command": "node",
      "args": ["/app/mcp/dist/index.js"],
      "env": {
        "WEB_MCP_DEFAULT_RENDER": "auto",
        "WEB_MCP_FETCH_TIMEOUT_MS": "15000",
        "WEB_MCP_USER_AGENT": "LocalLLM-WebMCP/0.1"
      }
    }
  }
}
```

## 提供ツール

- `web_search`: DuckDuckGo HTML 検索で実検索し、検索結果一覧を返します。
- `web_fetch`: `http` / `https` URL を取得し、HTML から本文・タイトル・リンクを抽出します。
- `web_find`: `web_fetch` 相当の取得結果から指定文字列を検索します。

## 検索プロバイダー方針

検索プロバイダーは無料で使えるものを優先します。

現在の実装:

- DuckDuckGo HTML 検索: API キー不要で利用

将来候補:

- SearxNG: 社内またはローカルで立てるメタ検索
- Brave Search などの API キーが必要な provider は、無料枠が必要になった場合の拡張候補

## 設定

環境変数で主な既定値を変更できます。

| 環境変数 | 既定値 | 用途 |
| --- | --- | --- |
| `WEB_MCP_SERVER_NAME` | `web-mcp` | MCP サーバー名 |
| `WEB_MCP_DEFAULT_MAX_RESULTS` | `10` | `web_search` の既定件数 |
| `WEB_MCP_DEFAULT_MAX_CHARS` | `20000` | `web_fetch` の既定最大文字数 |
| `WEB_MCP_DEFAULT_RENDER` | `auto` | 既定の render 指定 |
| `WEB_MCP_FETCH_TIMEOUT_MS` | `15000` | 静的 fetch のタイムアウト |
| `WEB_MCP_BROWSER_TIMEOUT_MS` | `20000` | 将来のブラウザ取得用タイムアウト |
| `WEB_MCP_USER_AGENT` | `LocalLLM-WebMCP/0.1` | 静的 fetch で送信する User-Agent |
| `WEB_MCP_TRANSPORT` | 未指定 | `http` を指定すると HTTP MCP サーバーとして起動 |
| `WEB_MCP_HTTP_HOST` | `0.0.0.0` | HTTP MCP サーバーの bind host |
| `WEB_MCP_HTTP_PORT` | `3000` | HTTP MCP サーバーの port |

## 現在の実装範囲

実装済み:

- MCP stdio server
- MCP Streamable HTTP server
- `web_search` / `web_fetch` / `web_find` の登録
- DuckDuckGo HTML による実検索
- `web_search` の `time_range` / `include_domains` / `exclude_domains` 対応
- AbortController による静的 fetch timeout
- 設定値からの User-Agent 送信
- redirect 後の `final_url` 返却
- 静的 HTML / XHTML / plain text fetch
- `Content-Type` 判定と未対応形式の error レスポンス
- Readability + Turndown による Markdown 風テキスト化
- Readability が本文を十分に抽出できない場合の DOM fallback 抽出
- `max_chars` / `truncated` 対応と Markdown 破損を抑える切り詰め
- `include_links` 指定時のリンク抽出
- fetch 失敗 / timeout の error レスポンス

未実装:

- Playwright によるブラウザレンダリング取得
- PDF テキスト抽出
- 取得済みページのキャッシュ

## エラー形式

失敗時も MCP ツールとしては JSON を返し、`error` に原因を入れます。

```json
{
  "error": {
    "code": "FETCH_TIMEOUT",
    "message": "The operation was aborted.",
    "url": "https://example.com",
    "retryable": true
  }
}
```

主な `code` は `FETCH_FAILED`、`FETCH_TIMEOUT`、`UNSUPPORTED_CONTENT_TYPE`、`BROWSER_RENDER_FAILED` です。
PDF は現時点では `UNSUPPORTED_CONTENT_TYPE` として返します。