MCP Nexus

🚀 mcp-nexus

English | 中文

mcp-nexus は、Tavily と Brave Search の両方のAPIを橋渡しする、堅牢なマルチプロバイダーのModel Context Protocol (MCP) サーバーです。統一されたツールインターフェースを提供し、上流のAPIキーのプールを循環させ、すべて包括的な管理UIを通じて管理されます。

✨ 主な機能

• 統一された検索API：単一のMCPエンドポイントを通じて、TavilyとBrave Searchの両方のツールを公開します。
• APIキー管理：複数のTavilyとBraveのAPIキーを簡単に追加、管理、循環させることができ、負荷分散とレート制限の管理が可能です。
• クライアント認証：管理UIを通じて作成および取り消し可能なベアラートークンでMCPエンドポイントを保護します。
• Web管理UI：APIキー、クライアントトークンの管理、使用統計の表示、サーバー設定の構成ができるユーザーフレンドリーなインターフェースです。
• 使用状況監視：ツールの使用状況を追跡し、クエリ履歴を調査し、最もよく使用されるツールとクエリの概要を取得できます。
• 柔軟な検索戦略：サーバーを再起動することなく、検索ソース (tavily_only, brave_only, combined など) とキー選択戦略 (round_robin, random) を動的に構成できます。
• レート制限：MCPクライアントと上流のAPI呼び出しの両方に組み込まれたレート制限があり、乱用を防止しコストを管理します。
• 柔軟なデプロイメント：Node.jsでローカルで実行するか、提供されたDocker Compose設定を使用して任意の場所にデプロイできます。

🚀 クイックスタート（ローカル）

Docker Compose（推奨）

cp .env.example .env
# .envを編集してADMIN_API_TOKENなどの設定を行います
docker compose up --build

SQLiteデータは /data にマウントされたDockerボリュームに保存されます。

次に、以下のURLを開きます。

• 管理UI: http://localhost:8787/admin
• MCPエンドポイント: http://localhost:8787/mcp

ローカルNode.js

.env.example の環境変数を設定する必要があります。

npm install
npx prisma migrate deploy --schema packages/db/prisma/schema.prisma
npm run dev:bridge-server

ワークスペース

• packages/core：Tavily/Braveクライアント、キー管理、およびMCPツールスキーマのコアロジックです。
• packages/bridge-server：主なHTTPサーバーで、MCPエンドポイントと管理API/UIを提供します。
• packages/bridge-stdio：ローカルクライアント統合用の軽量なstdioサーバーです。
• packages/stdio-http-bridge：stdioクライアントをHTTPサーバーに接続するためのヘルパーパッケージです。
• packages/db：すべてのデータ永続化のためのPrismaスキーマとデータベースクライアントです。
• packages/admin-ui：Reactベースの管理UIフロントエンドです。

管理UI

管理UIは、mcp-nexus インスタンスを管理するための中心的な場所を提供します。

• キー：上流の Tavily と Brave のAPIキーのプールを管理します。追加、削除、ステータス（アクティブ、無効）の更新、およびTavilyキーの残りクレジットの監視ができます。
• トークン：MCPエンドポイントで認証するために使用されるクライアントトークンを作成および取り消します。
• 使用状況：詳細なツール使用統計とクエリ履歴を表示し、日付範囲、ツール、およびクライアントでフィルタリングするオプションがあります。
• 設定：ライブサーバー設定を構成します。上流のキー選択戦略や検索ソースモードなどです。

MCPツール

サーバーは、MCPクライアントに以下のツールを公開します。

設定

設定は環境変数を通じて管理されます。.env.example を .env にコピーして開始します。

コア設定

レート制限

検索とキー戦略

これらの設定は、管理UI → 設定 ページでライブで構成することもできます。

結合モード

SEARCH_SOURCE_MODE=combined の場合：

• TavilyとBrave Searchの両方のアクティブなAPIキーが必要です。
• クエリを並列に実行してレイテンシを最小限に抑えます。
• 結果をURLでマージし、重複を削除します。
• 注意：各検索リクエストは両方のプロバイダーのクォータを消費します（コストが2倍になります）。
• ページネーション：offset>0 の場合、Tavilyはオフセットをサポートしないため、Braveの結果のみが返されます。

Tavily設定

Brave設定

Braveキーが構成されていない場合、BraveツールはTavilyを使用するようにフォールバックします。

MCPクライアントを接続する

1. 管理UIを開き、トークン ページから クライアントトークン を作成します。
2. そのトークンを Authorization ヘッダーのベアラートークンとして渡すことで、MCPリクエストを認証します。これは管理API自体にアクセスするために使用される 管理トークン とは異なります。

HTTP

• MCPエンドポイント: POST /mcp
• 認証: Authorization: Bearer <client_token>

stdio

HTTP MCPエンドポイントに接続する軽量なstdioラッパーを npx で実行することをお勧めします。これにより、シークレットをCLI引数ではなく env に保持できます。 TAVILY_BRIDGE_BASE_URL をあなたのデプロイメントURLに設定します（ローカルのDocker Composeの場合は http://localhost:8787）。

{
  "mcpServers": {
    "mcp-nexus": {
      "command": "npx",
      "args": ["-y", "@nexus-mcp/stdio-http-bridge"],
      "env": {
        "TAVILY_BRIDGE_BASE_URL": "http://localhost:8787",
        "TAVILY_BRIDGE_MCP_TOKEN": "<client_token>"
      }
    }
  }
}

デプロイメント

Cloudflare Workers（推奨 - 無料）

D1データベースを備えたCloudflareの無料枠にワンクリックでデプロイできます。詳細は packages/worker/README.md を参照してください。

Docker Compose（セルフホスト）

含まれている docker-compose.yml と Dockerfile は、セルフホスト用の本番環境向けの設定を提供します。

メンテナー: @nexus-mcp/stdio-http-bridge の公開

このリポジトリはnpmワークスペースのモノレポです。@nexus-mcp/stdio-http-bridge のみがnpmに公開されることを想定しています。

前提条件

• @nexus-mcp スコープのnpm公開権限が必要です（またはパッケージ名/スコープを変更します）。
• ログインして確認します。

npm login
npm whoami

リリース（推奨: タグトリガーのCI）

1. ワークスペースのバージョンを上げ、タグを作成します。

npm version patch -w @nexus-mcp/stdio-http-bridge --tag-version-prefix stdio-http-bridge-v
git push --follow-tags

2. GitHub Actionsのシークレット NPM_TOKEN（公開権限を持つnpmアクセストークン）を設定します。
3. ワークフロー .github/workflows/publish-stdio-http-bridge.yml は、stdio-http-bridge-v* に一致するタグで公開します。

リリース（手動）

npm publish -w @nexus-mcp/stdio-http-bridge