Apache Doris

Servidor MCP de Apache Doris

English | 简体中文

El servidor MCP de Apache Doris expone capacidades de solo lectura de Apache Doris a los hosts MCP y agentes de IA a través de MCP 2026-07-28. La versión 1.0 reemplaza una gran superficie plana de herramientas con ocho dominios estables y cincuenta y cinco capacidades secundarias reveladas progresivamente, manteniendo explícitos la disponibilidad en tiempo de ejecución, la autorización, los esquemas de entrada, los esquemas de salida y el comportamiento ante fallos.

Estado del lanzamiento

La versión del paquete es 1.0.0. La compatibilidad del protocolo MCP 2026-07-28 en master está Generalmente Disponible (GA) en Streamable HTTP y stdio. Esta declaración de GA se limita a la compatibilidad del protocolo; el clasificador del paquete Python sigue siendo Beta, y los límites de implementación documentados siguen aplicándose.

Antes de actualizar, lea las notas del lanzamiento 1.0, la guía de migración a 1.0 y el registro generado de 8 dominios/55 capacidades secundarias. El registro detallado del lanzamiento está en Issue #189.

Arquitectura de un vistazo

MCP Host
  -> stdio or Streamable HTTP
  -> transport security and authentication
  -> MCP protocol validation and authorization
  -> stable domain discovery
  -> route-aware Doris capability detection
  -> exact child dispatch and read-only runtime
  -> request-specific Doris route and RBAC
  -> bounded, schema-validated result

El modo hierarchical predeterminado expone estos dominios:

Dominio	Capacidades secundarias	Responsabilidad
doris_catalog	5	catálogos, bases de datos, tablas, contexto de tablas, tamaño
doris_query	7	consulta, explain, perfil, diagnóstico, consultas lentas, ADBC explícito
doris_cluster	11	nodos, tareas, métricas, memoria, caché, compactación, cargas de trabajo
doris_pipeline	5	ingesta, vistas materializadas, frescura, dependencias
doris_search	4	búsqueda de texto/vectorial/híbrida, analizadores, índices, diagnóstico
doris_governance	8	calidad, almacenamiento, linaje, auditoría, UDF, mapeo de autenticación
doris_lakehouse	3	catálogos externos, tablas lakehouse, Variant
doris_semantic	12	fundamentación opcional de Apache Ossie y consumo de MetricFlow

Llame a un dominio con {} para descubrir sus capacidades secundarias autorizadas y esquemas exactos. Vuelva a llamar al mismo dominio con child_tool, arguments y el manifest_version devuelto. Los hosts que no puedan usar la revelación progresiva pueden configurar MCP_TOOL_EXPOSURE_MODE=flat antes del inicio; esto expone las mismas 55 capacidades secundarias bajo nombres formales sin colisiones y no restaura los alias anteriores a 1.0.

Consulte Arquitectura, Ciclo de vida de las solicitudes y Dominios de herramientas.

Inicio rápido

Requisitos:

• Python 3.12 o posterior;
• Apache Doris 2.0.0 o posterior;
• acceso de red al endpoint MySQL de Doris FE, normalmente el puerto 9030.

Instale el lanzamiento fijado:

pip install doris-mcp-server==1.0.0

doris-mcp-server inicia el servidor. doris-mcp-client es un cliente independiente; los dos comandos no son intercambiables.

Configure una ruta de Doris:

export DORIS_HOST=127.0.0.1
export DORIS_PORT=9030
export DORIS_USER=mcp_reader
export DORIS_PASSWORD='replace-me'
export DORIS_DATABASE=information_schema

Inicie Streamable HTTP en loopback:

doris-mcp-server \
  --transport http \
  --host 127.0.0.1 \
  --port 3000

Endpoints:

• MCP: POST http://127.0.0.1:3000/mcp
• MCP heredado (opt-in): POST http://127.0.0.1:3000/mcp/legacy
• liveness: GET http://127.0.0.1:3000/live
• readiness respaldado por Doris: GET http://127.0.0.1:3000/ready

Los hosts limitados a Streamable HTTP de la era del handshake, incluido Dify 1.16.1 con MCP 2025-06-18, deben configurar ENABLE_LEGACY_HTTP_ADAPTER=true y conectarse a /mcp/legacy. El adaptador solo cambia el límite del protocolo; conserva las mismas herramientas 1.0, autorización, compuertas de capacidad y ejecución de solo lectura.

O ejecute stdio para un host local:

doris-mcp-server --transport stdio

Consulte el Inicio rápido completo y la Guía de integración de hosts.

Límite de seguridad

• El catálogo 1.0 integrado es de solo lectura; doris_admin está reservado y no está registrado.
• Se admiten tokens estáticos, JWT, OAuth/OIDC externos y OAuth respaldado por Doris bajo límites de configuración validados mutuamente.
• El descubrimiento de dominios y la ejecución de capacidades secundarias usan identificadores de autorización exactos.
• El RBAC de Doris sigue siendo la autoridad final para los objetos y datos visibles.
• La forma de las consultas SQL, los identificadores, los parámetros, el tiempo de espera, las filas, los bytes y los esquemas de resultados están acotados antes de que los datos salgan del servidor.
• Los secretos y los errores de backend se redactan de los resultados públicos y los registros.
• HTTP fuera de loopback requiere autenticación a menos que se habilite una anulación de desarrollo peligrosa explícita.

Lea el Modelo de seguridad y permisos y la Guía de acceso de grano fino de Doris.

Límite de fiabilidad

El servidor utiliza manifiestos y errores deterministas, cursores firmados con caducidad, instantáneas de capacidades conscientes de la ruta, respaldo obsoleto acotado, enrutamiento de conexiones específico de la solicitud, conmutación por error multi-FE, separación de liveness/readiness, validación de esquema de salida y propagación de trazas saneadas. Las capacidades no compatibles o mal configuradas siguen siendo descubribles con callable=false y fallan de forma cerrada cuando se las llama.

Los límites actuales incluyen OAuth respaldado por Doris local al proceso, ADBC solo explícito deshabilitado por defecto y con fallo cerrado en rutas con token, fundamentación opcional de solo lectura de Ossie, un compilador MetricFlow opcional como sidecar cuyo SQL debe ejecutarse a través del tiempo de ejecución de consultas MCP acotado, y entrega de linaje nativo de mejor esfuerzo. Consulte Fiabilidad y límites.

Documentación

El README raíz es intencionalmente un punto de entrada. El sistema de documentación bilingüe está indexado en:

• Documentación en inglés
• 简体中文文档

Guías principales:

• Arquitectura
• Flujo de solicitudes y datos
• Dominios de herramientas
• Disponibilidad de capacidades
• Matriz de capacidades por versión de Doris
• Integración de MetricFlow
• Contrato MCP 2026-07-28
• Modelo de seguridad
• Implementación
• Fiabilidad y límites
• Solución de problemas
• Referencia de configuración
• Integraciones de hosts
• Proveedores de herramientas personalizados
• Contribuciones

Desarrollo

git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server
uv sync --group dev
uv run pytest

Los artefactos generados deben permanecer sincronizados:

uv run python generate_tool_catalog.py --check
uv lock --check

Consulte Contribuciones y verificación.

Licencia

Apache License 2.0. Consulte LICENSE.txt y NOTICE.