MaxKB ナレッジベース検索 MCP

MaxKB Admin API に基づく MCP サービスで、ユーザーの質問に応じてナレッジベースのセグメントを検索します。ベクトル検索、ハイブリッド検索、全量検索をサポートします。デフォルトの Top K は 10、検索モードはベクトル検索です。

デフォルトでは Streamable HTTP で提供されます：

• MCP アドレス：http://<主机>:8000/mcp

• ヘルスチェック：http://<主机>:8000/health

機能

search_mode（ツールで指定しない場合は環境変数を使用、デフォルトはベクトル検索）：

• 向量 / 向量检索 / embedding

• 混合 / 混合检索 / blend

• 全量 / 全量检索 / keywords

• auto：ハイブリッド検索 → ベクトル検索 → 全文検索、ヒットするまで

knowledge_ids を指定しない場合、現在のワークスペース内でベクトルモデルが設定されているすべてのナレッジベースを検索します。

Related MCP server: mcp-rag-assistant

環境変数

サンプルファイルをコピーして、実際の環境に合わせて変更してください：

cp .env.example .env

search_knowledge を単一呼び出しする際に top_n または search_mode を渡すと、サーバー側のデフォルト値を上書きします。

ローカル起動

Python 3.10+ と uv が必要です。

cp .env.example .env
uv sync
uv run maxkb-mcp

起動後：

• MCP：http://127.0.0.1:8000/mcp

• ヘルスチェック：http://127.0.0.1:8000/health

• ログファイル：logs/mcp.log（日次ローテーション、デフォルトで 7 日間保持）

クライアント接続例：

{
  "mcpServers": {
    "maxkb-knowledge": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "你的 MaxKB API Key"
      },
      "disabled": false
    }
  }
}

Authorization は生のキーでも、Bearer <key> でも構いません。

stdio モードが必要な場合：

MCP_TRANSPORT=stdio uv run maxkb-mcp

Docker イメージのビルド

Docker 20.10+ が必要です。

docker build -t maxkb-mcp:latest .

国内ネットワークでは PyPI ミラーを指定することを推奨します：

docker build \
  --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
  -t maxkb-mcp:latest .

イメージレジストリへのプッシュ（任意）：

docker tag maxkb-mcp:latest <registry>/<namespace>/maxkb-mcp:0.1.0
docker push <registry>/<namespace>/maxkb-mcp:0.1.0

Docker デプロイ

docker-compose.yml はイメージをビルドせず、既存のイメージを使用して起動します。デプロイ前にローカルでビルドするか、レジストリからイメージをプルしてください。

cp .env.example .env
docker-compose up -d
docker-compose logs -f maxkb-mcp

リモートイメージを使用する場合：

MAXKB_MCP_IMAGE=<registry>/<namespace>/maxkb-mcp:0.1.0 docker-compose up -d

起動後：

• MCP：http://<主机>:8000/mcp

• ヘルスチェック：http://<主机>:8000/health

• ログディレクトリ：ホスト ./logs（コンテナ内 /app/logs）

HTTPS リバースプロキシ経由後、クライアントの url を https://your-domain/mcp に変更します。

MaxKB がホストにデプロイされている場合、MAXKB_BASE_URL を http://host.docker.internal:<端口> に設定します。

サービス停止：

docker-compose down

ログ

すべての HTTP リクエストと MCP ツール呼び出しはローカルログに書き込まれ、Authorization はマスクされます。

• ファイル：{MAXKB_LOG_DIR}/mcp.log、毎日 mcp.log.YYYY-MM-DD にローテーション

• 起動時に期限切れファイルを一度クリーンアップし、その後 6 時間ごとにクリーンアップ

• MAXKB_LOG_RETENTION_DAYS（デフォルト 7 日）を超えたログは削除されます

よくある質問

• API キーが未提供：クライアントの headers.Authorization に MaxKB ユーザーキーを渡すか、.env で MAXKB_API_KEY を設定します

• ビルドが遅い、またはタイムアウト：パッケージング時に --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple を追加

• コンテナから MaxKB にアクセスできない：MAXKB_BASE_URL、ネットワーク、host.docker.internal が必要かどうかを確認

• 証明書検証の失敗：MAXKB_VERIFY_SSL=false を設定