fetchmux

FetchMux

AI エージェントのための、ひとつの検索エンドポイントです。 Brave、Tavily、Exa、Firecrawl、Crossref の前段にルーターを配置します。すべてのリクエストに厳格なコスト上限と期限が設定され、すべてのレスポンスには、どのプロバイダーが、なぜ実行され、いくらかかったかを示すレシートが付属します。

エージェントのプロンプトやアプリコードにプロバイダーをハードコードする必要はなくなります。統一された形式でリクエストを送ると、ゲートウェイが管理下のポリシーに基づいて利用可能なプロバイダーを選び、呼び出し前に予算と期限を適用し、失敗時には安全に再試行して、正規化された結果と完全なトレースを返します。プロバイダーのキーはお手元に保持され、ゲートウェイの外に出ることはありません。

レシート

ブラックボックスはありません。すべての /v1/search レスポンスに、ルーティングの判断が含まれます。

"route": {
  "selectedProvider": "brave",
  "attemptedProviders": ["brave"],
  "reasonCodes": ["TASK_MATCH", "WITHIN_BUDGET", "RELIABILITY_WEIGHT"],
  "attempts": [
    { "provider": "brave", "outcome": "success", "latencyMs": 640, "estimatedCostUsd": 0.005 }
  ],
  "estimatedCostUsd": 0.005,
  "latencyMs": 640,
  "fallbackUsed": false,
  "traceId": "rt_b400e7c8"
}

ルーティングの仕組み

  agent  ──▶  { query · task · maxCostUsd · maxLatencyMs }
                             │
                             ▼
                      ┌──────────────┐        your keys
                      │   FetchMux    │ ─────▶ Brave · Tavily · Exa
                      │    policy     │        Firecrawl · Crossref
                      └──────────────┘ ◀─────  (bring your own)
                             │
                             ▼
  agent  ◀──  evidence[]  +  route receipt

プロバイダーが利用可能と判断されるのは、認証情報、タスクとの適合性、サーキットの状態、支出、期限のすべての条件を満たした場合に限られます。予算と期限は利用可否のルールであり、ベストエフォートのヒントではありません。フォールバックは、再試行可能な障害が発生した場合にのみ行われます。

クイックスタート

プロバイダーのアカウントは不要です。公開 Crossref ルートはそのまま利用できます。

git clone https://github.com/krutftw/fetchmux
cd fetchmux
npm install
npm run build

export FETCHMUX_API_KEY="a-long-random-key"
export CROSSREF_ENABLED=true
export CROSSREF_CONTACT_EMAIL="[email protected]"
npm run dev:gateway

別のシェルから実行します。

curl http://127.0.0.1:8787/v1/search \
  -H "Authorization: Bearer a-long-random-key" \
  -H "Content-Type: application/json" \
  -d '{ "query": "retrieval augmented generation", "task": "scholarly", "maxLatencyMs": 8000 }'

実際のウェブ検索をルーティングするには、プロバイダーキーを設定し、代わりにウェブ検索タスクを使います。

export FETCHMUX_API_KEY="a-long-random-key"
export BRAVE_API_KEY="your-brave-key"
export BRAVE_COST_PER_REQUEST_USD="0.005"   # from your provider plan
npm run dev:gateway

Firecrawl を初めてお使いですか？新規アカウントは、こちらのリンクから初月が10％割引になります（紹介リンクです。FetchMux は少額の紹介手数料を受け取りますが、お客様の追加負担はありません）。

エージェントから利用する

公開サーバーを任意の MCP クライアント（Claude、Cursor など）に指定します。

{
  "mcpServers": {
    "fetchmux": {
      "command": "npx",
      "args": ["-y", "@fetchmux/mcp"],
      "env": {
        "FETCHMUX_BASE_URL": "http://127.0.0.1:8787/",
        "FETCHMUX_API_KEY": "your-gateway-key"
      }
    }
  }
}

読み取り専用ツールは search_web と preview_search_route の2つです。

または、型付き SDK @fetchmux/sdk を使います。

import { FetchMux } from "@fetchmux/sdk";

const client = new FetchMux({
  baseUrl: "http://127.0.0.1:8787/",
  apiKey: process.env.FETCHMUX_API_KEY,
  fetch: globalThis.fetch.bind(globalThis),
});

const res = await client.search({
  query: "latest stable Node.js release",
  task: "fresh_facts",
  maxCostUsd: 0.02,
});

プロバイダー

それぞれのプロバイダーのキーをご用意ください。対応する *_API_KEY と、ドル単位の予算を適用する場合は任意で *_COST_PER_REQUEST_USD を設定します。

プロバイダー	用途	キー
Brave	ウェブ検索	BRAVE_API_KEY
Tavily	ウェブ検索、調査	TAVILY_API_KEY
Exa	ウェブ検索、ドキュメント	EXA_API_KEY
Firecrawl	ページコンテンツ	FIRECRAWL_API_KEY
Crossref	学術メタデータ	なし（CROSSREF_ENABLED=true）

REST エンドポイント

メソッド	パス	認証	動作
GET	/health	公開	プロセスの稼働状況とバージョン
GET	/ready	公開	プロバイダーの準備状況
GET	/v1/providers	ベアラー	プロバイダーの設定状況
POST	/v1/route/preview	ベアラー	プロバイダーへの呼び出しを行わず、候補を順位付けして返します
POST	/v1/search	ベアラー	ルーティングされた検索とルートのレシート

完全な仕様：docs/openapi.yaml。

すべての設定変数

ローカルの Node 開発では、プロセスは .env を自動的に読み込みません。シェルまたはプロセスマネージャーで変数を設定してください。Docker Compose は無視対象の .env ファイルを読み込みます。

変数	デフォルト	用途
FETCHMUX_API_KEY	なし	保護されたルート用のベアラーキー
FETCHMUX_API_KEYS	なし	ローテーション用のカンマ区切りキー
FETCHMUX_AUTH_DISABLED	false	値が正確に true の場合、認証を無効化します（信頼できるローカル環境でのみ使用）
FETCHMUX_ALLOWED_ORIGINS	なし	ブラウザーのオリジンをカンマ区切りで指定します。空の場合、CORS は無効です
FETCHMUX_HOST	127.0.0.1	バインドアドレス
FETCHMUX_PORT	8787	TCP ポート
BRAVE_API_KEY / TAVILY_API_KEY / EXA_API_KEY / FIRECRAWL_API_KEY	なし	プロバイダーの認証情報
CROSSREF_ENABLED	false	値が正確に true の場合、認証情報不要の学術ルートを有効化します
CROSSREF_CONTACT_EMAIL	なし	Crossref の適正利用プール向けの、確認可能な連絡先
*_COST_PER_REQUEST_USD	なし	ドル建ての予算に使用する、プロバイダーごとのリクエストあたりの推定コスト

maxCostUsd を有効にする前に、プロバイダー設定を確認してください。

Docker で実行する

cp .env.example .env    # add your keys, never commit it
docker compose up --build -d
curl http://127.0.0.1:8787/health

非 root の Distroless イメージです。Linux ケイパビリティを削除し、ルートファイルシステムを読み取り専用にして、プロバイダーの認証情報はコンテナ起動時にのみ渡します。

ベンチマーク

ネットワーク呼び出しやクレジットの消費なしで、すべてのケースとプロバイダーの組み合わせを検証します。

npm run benchmark -- --workload benchmarks/workloads/founding-v1.json --mode dry-run

ライブモードにはプロバイダーキーと明示的な --confirm-live が必要です。結果を公開する前に、各プロバイダーの利用規約を確認してください。詳しくはベンチマークの方法論を参照してください。

これは何で、何ではないか

オープンソース、セルフホスト可能、シングルテナント、BYOK です。ルートイベントは JSON として標準出力に送信され、デフォルトではクエリテキスト、キー、結果の内容は含まれません。データベースもテレメトリーもありません。

ホスト型サービスでも、クレジットをプールして再販するサービスでも、これらのプロバイダーが相互に置き換え可能だと主張するものでもありません。プロバイダー名は、このツールに同梱されているアダプターを示すもので、提携先を示すものではありません。ホスト版はロードマップにあります。最新情報を確認するにはリポジトリにスターを付けてください。

開発

npm test          # 232 tests
npm run typecheck
npm run lint
npm run build
npm run dev:gateway
npm run dev:site

その他のドキュメント：製品設計 · ローカル開発 · デプロイ · プロバイダー設定 · データの取り扱い · インシデント対応

セキュリティ上の問題：[email protected]。

ライセンス

Apache-2.0。自由にセルフホスト、変更、再配布できます。