MaxKB Wissensdatenbank-Suche-MCP

Ein MCP-Dienst auf Basis der MaxKB-Admin-API, der anhand von Benutzerfragen passende Wissensdatenbank-Segmente abruft. Unterstützt Vektorsuche, Hybride Suche und Volltextsuche. Standardmäßig ist Top K = 10, der Suchmodus ist die Vektorsuche.

Standardmäßig wird der Dienst über Streamable HTTP bereitgestellt:

• MCP-Adresse: http://<主机>:8000/mcp

• Health-Check: http://<主机>:8000/health

Funktionen

search_mode (falls nicht vom Tool angegeben, wird die Umgebungsvariable verwendet; Standard ist die Vektorsuche):

• 向量 / 向量检索 / embedding

• 混合 / 混合检索 / blend

• 全量 / 全量检索 / keywords

• auto: Hybride Suche → Vektorsuche → Volltextnavigation, bis ein Treffer erzielt wird

Wenn knowledge_ids nicht angegeben ist, wird in allen Wissensdatenbanken des aktuellen Arbeitsbereich gesucht, die ein Vektormodell konfiguriert haben.

Related MCP server: mcp-rag-bridge

Umgebungsvariablen

Kopieren Sie die Beispieldatei und passen Sie die Werte an Ihre Umgebung an:

cp .env.example .env

Wenn bei einem einzelnen Aufruf von search_knowledge top_n oder search_mode übergeben wird, werden die serverseitigen Standardwerte überschrieben.

Lokaler Start

Erfordert Python 3.10+ und uv.

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

Nach dem Start:

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

• Health-Check: http://127.0.0.1:8000/health

• Protokolldatei: logs/mcp.log (tägliche Rotation, standardmäßig 7 Tage vorgehalten)

Beispiel für die Client-Anbindung:

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

Authorization kann der rohe Key oder Bearer <key> sein.

Falls der stdio-Modus benötigt wird:

MCP_TRANSPORT=stdio uv run maxkb-mcp

Docker-Image erstellen

Erfordert Docker 20.10+.

docker build -t maxkb-mcp:latest .

Für Netzwerke innerhalb Chinas wird empfohlen, einen PyPI-Armor anzugeben:

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

Push in die Image-Registry (optional):

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

Docker-Bereitstellung

docker-compose.yml erstellt kein Image, sondern startet nur mit einem bereits vorhandenen Image. Stellen Sie sicherdass Sie das Image vorher lokal gebaut oder aus der Registry gezogen haben.

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

Bei Verwendung eines Remote-Images:

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

Nach dem Start:

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

• Health-Check: http://<主机>:8000/health

• Protokollverzeichnis: Host ./logs (im Container /app/logs)

Nach einem HTTPS-Reverse-Proxy ändern Sie die Client-url auf https://your-domain/mcp.

Falls MaxKB auf dem Host-Host bereitgestellt ist, setzen Sie MAXKB_BASE_URL auf http://host.docker.internal:<端口>.

Dienst stoppen:

docker-compose down

Protokollierung

Alle HTTP-Anfragen und MCP-Tool-Aufrufe werden in lokalen Protokollen gespeichert; Authorization wird maskiert.

• Datei: {MAXKB_LOG_DIR}/mcp.log, täglich rotiert zu mcp.log.YYYY-MM-DD

• Beim Start werden abgelaufene Dateien einmal bereinigt, danach alle 6 Stunden

• Protokolle, die MAXKB_LOG_RETENTION_DAYS (Standard 7 Tage) überschreiten, werden gelöscht

Häufige Fragen

• Kein API-Key angegeben: Den MaxKB-Benutzer-Key über headers.Authorization des Clients übergeben oder MAXKB_API_KEY in .env konfigurieren

• Build langsam oder Zeitüberschreitung: Beim Packen --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple angeben

• Container kann MaxKB nicht erreichen: Prüfen Sie MAXKB_BASE_URL, das Netzwerk und ob host.docker.internal erforderlich ist

• Zertifikatsprüfung fehlgeschlagen: MAXKB_VERIFY_SSL=false setzen