MCP de recuperación de MaxKB Knowledge Base

Servicio MCP basado en la API de administración de MaxKB, que recupera fragmentos de la base de conocimiento según la pregunta del usuario. Admite recuperación vectorial, recuperación mixta y recuperación completa. El Top K predeterminado es 10 y el modo de recuperación es vectorial.

De forma predeterminada, se sirve mediante HTTP Streamable:

• Dirección MCP: http://<host>:8000/mcp

• Verificación de estado: http://<host>:8000/health

Capacidades

search_mode (si la herramienta no lo especifica, se usa la variable de entorno; el valor predeterminado es recuperación vectorial):

• 向量 / 向量检索 / embedding

• 混合 / 混合检索 / blend

• 全量 / 全量检索 / keywords

• auto: recuperación mixta → recuperación vectorial → recuperación de texto completo, hasta que haya coincidencias

Si no se especifica knowledge_ids, se buscará en todas las bases de conocimiento del espacio de trabajo actual que tengan modelos vectoriales configurados.

Related MCP server: mcp-rag-bridge

Variables de entorno

Después de copiar el archivo de ejemplo, modifíquelo según el entorno real:

cp .env.example .env

Si al llamar a search_knowledge se pasa top_n o search_mode, se sobrescribirán los valores predeterminados del servidor.

Inicio local

Se requiere Python 3.10+ y uv.

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

Después de iniciar:

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

• Verificación de salud: http://127.0.0.1:8000/health

• Archivo de registro: logs/mcp.log (rotación diaria, retención predeterminada de 7 días)

Ejemplo de conexión del cliente:

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

Authorization puede ser la clave original o Bearer <key>.

Si se necesita el modo stdio:

MCP_TRANSPORT=stdio uv run maxkb-mcp

Empaquetado de imagen Docker

Se requiere Docker 20.10+.

docker build -t maxkb-mcp:latest .

Para redes nacionales, se recomienda especificar el espejo PyPI:

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

Enviar al repositorio de imágenes (opcional):

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

Implementación con Docker

docker-compose.yml no construye la imagen, solo inicia con una imagen existente. Antes de la implementación, complete la construcción local o extraiga la imagen del repositorio.

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

Al usar una imagen remota:

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

Después de iniciar:

• MCP: http://<host>:8000/mcp

• Verificación de salud: http://<host>:8000/health

• Directorio de registros: ./logs del host (dentro del contenedor /app/logs)

Después de un proxy inverso HTTPS, la url del cliente cambia a https://your-domain/mcp.

Si MaxKB está implementado en el host, escriba MAXKB_BASE_URL como http://host.docker.internal:<puerto>.

Detener el servicio:

docker-compose down

Registros

Todas las solicitudes HTTP y las llamadas a herramientas MCP se escriben en el registro local; la autorización se enmascara.

• Archivo: {MAXKB_LOG_DIR}/mcp.log, se rota diariamente a mcp.log.YYYY-MM-DD

• Se limpian los archivos vencidos una vez al inicio y luego cada 6 horas

• Los registros que superen MAXKB_LOG_RETENTION_DAYS (predeterminado 7 días) se eliminarán

Preguntas frecuentes

• Clave API no proporcionada: Pase la clave de usuario de MaxKB en headers.Authorization del cliente, o configure MAXKB_API_KEY en .env

• Construcción lenta o tiempo de espera: agregue --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple al empaquetar

• El contenedor no puede acceder a MaxKB: verifique MAXKB_BASE_URL, la red y si se necesita host.docker.internal

• Error de verificación de certificado: establezca MAXKB_VERIFY_SSL=false