Introducción Detallada al Proyecto Apache Doris MCP Server

Resumen del Proyecto

Apache Doris MCP (Model Context Protocol) Server es un servicio backend construido con Python y FastAPI, diseñado para integrarse sin problemas con la base de datos Apache Doris a través del protocolo de contexto de modelo (MCP). Proporciona una interfaz estandarizada para agentes de IA y clientes, admitiendo funciones como la conversión de lenguaje natural a SQL (NL2SQL), la ejecución de consultas SQL, la gestión de metadatos y el análisis de datos. Este proyecto es una extensión importante de la comunidad Apache Doris, especialmente adecuado para escenarios empresariales que requieren una interacción de datos eficiente y un análisis inteligente.

Desde el lanzamiento de la versión 0.3.0 en 2025, el proyecto ha experimentado importantes actualizaciones de arquitectura, migrando de la comunicación basada en SSE (Server-Sent Events) a un protocolo HTTP Streamable unificado, y agregando un marco de seguridad de nivel empresarial y funciones de optimización del rendimiento. El objetivo principal del proyecto es conectar sistemas de IA con la base de datos Apache Doris a través del protocolo MCP, permitiendo la exploración y el análisis de datos inteligentes.

Funciones Principales

Apache Doris MCP Server ofrece las siguientes funciones principales:

1. Conversión de Lenguaje Natural a SQL (NL2SQL)

   • Admite la generación de consultas SQL a través de la entrada de lenguaje natural, combinando modelos de lenguaje grandes (LLMs) para una generación de consultas inteligente.
   • Adecuado para escenarios en los que los usuarios empresariales pueden consultar datos sin necesidad de escribir SQL complejo.

2. Ejecución de Consultas SQL

   • Admite la ejecución directa de comandos SQL a través de la herramienta exec_query, con opciones personalizables para la selección de la base de datos, el límite de filas y la configuración de tiempo de espera.
   • Incorpora comprobaciones de seguridad (como la protección contra la inyección de SQL) y la adición automática de LIMIT para garantizar la seguridad y la eficiencia de las consultas.

3. Gestión de Metadatos

   • Proporciona una amplia gama de herramientas de extracción de metadatos, que incluyen:
     • Listar todas las bases de datos y tablas (get_all_databases, get_database_tables).
     • Obtener la estructura de la tabla, los comentarios y la información del índice (get_table_schema, get_table_comment, get_column_comments, get_table_indexes).
     • Soporte para el descubrimiento de múltiples catálogos (get_catalog_list).

4. Consulta de Registros de Auditoría

   • Obtiene los registros de auditoría más recientes a través de get_recent_audit_logs, admitiendo rangos de tiempo personalizados y límites de registro.

5. Marco de Seguridad de Nivel Empresarial

   • Admite múltiples métodos de autenticación (Token, Basic Auth, OAuth).
   • Control de acceso basado en roles (RBAC), que proporciona cuatro niveles de seguridad.
   • Incorpora protección contra la inyección de SQL, validación de consultas y funciones de desensibilización de datos.

6. Optimización del Rendimiento

   • Optimización de la ejecución de consultas, mejorando el rendimiento a través de mecanismos de caché mejorados y gestión de grupos de conexiones.
   • Soporte para la monitorización del rendimiento y el análisis estadístico (performance_stats).

7. Múltiples Modos de Comunicación

   • HTTP Streamable: Admite la solicitud/respuesta y la transmisión en flujo a través de un punto final /mcp unificado (src/streamable_server.py).
   • SSE (Obsoleto): Las versiones anteriores admitían la comunicación a través de los puntos finales /sse y /mcp/messages (src/sse_server.py).
   • Stdio (Opcional): Interacción a través de la entrada/salida estándar (src/stdio_server.py).

8. Funciones Experimentales

   • Análisis estadístico de columnas (column_analysis), que proporciona información sobre los datos.
   • Soporte para la federación de catálogos, adecuado para entornos de múltiples catálogos.

Arquitectura Técnica

El diseño de la arquitectura del proyecto es modular y eficiente, e incluye los siguientes componentes principales:

• Marco Central: Construido sobre Python 3.12 y FastAPI, que proporciona un servicio API de alto rendimiento.
• Implementación del Protocolo MCP:
  • Proporciona interfaces estandarizadas para la invocación de herramientas, la gestión de recursos y la interacción de indicaciones.
  • Maneja todas las solicitudes a través de un punto final /mcp unificado, simplificando la integración.
• Interacción con la Base de Datos:
  • doris_mcp_server/utils/db.py: Proporciona funciones de conexión a la base de datos (get_db_connection) y ejecución de consultas (execute_query, execute_query_df).
  • doris_mcp_server/utils/schema_extractor.py: La clase MetadataExtractor es responsable de la extracción de metadatos, incluyendo mecanismos de caché.
  • doris_mcp_server/utils/sql_executor_tools.py: La función execute_sql_query encapsula la lógica de la consulta, incluyendo comprobaciones de seguridad y serialización de resultados.
• Gestión de la Seguridad:
  • Soporte para múltiples métodos de autenticación y RBAC.
  • Proporciona protección contra la inyección de SQL, validación de consultas y registro de auditoría.
• Soporte para el Despliegue:
  • Despliegue en contenedores Docker, configuración unificada de puertos (3000, 3001, 3002).
  • Configuración de variables de entorno (como DB_HOST, DB_PORT, DB_USER, DB_PASSWORD).

Cambios en la Arquitectura: La versión 0.3.0 eliminó aproximadamente 300 líneas de código heredado de SSE, migrando a HTTP Streamable, unificando los nombres de las herramientas (eliminando el prefijo mcp_doris_), y mejorando el grado de modularización.

Instalación y Uso

Requisitos del Entorno

• Python 3.12 o superior
• Base de datos Apache Doris (conectada a través del protocolo MySQL)
• Herramienta de gestión de paquetes (como uv o pip)
• Opcional: Docker (para el despliegue en contenedores)

Pasos de Instalación

1. Clonar el Repositorio:

   git clone https://github.com/apache/doris-mcp-server.git
   cd doris-mcp-server
   

2. Instalar Dependencias: Utilice uv (recomendado) o pip para instalar:

   uv sync
   

   O

   pip install -r requirements.txt
   

3. Configurar Variables de Entorno: Cree un archivo .env o establezca las variables de entorno directamente:

   export DORIS_HOST=<doris-host>
   export DORIS_PORT=<port>
   export DORIS_USER=<doris-user>
   export DORIS_PASSWORD=<doris-pwd>
   export SERVER_PORT=3000
   

4. Iniciar el Servidor:

   uv run --with mcp-doris --python 3.13 mcp-doris
   

   O

   python -m mcp_doris.mcp_server
   

5. Verificar el Inicio: Después de un inicio exitoso, puede interactuar a través de un cliente MCP (como Cursor) o un navegador MCP incorporado (http://localhost:5173).

Probar la Conexión

Ejecute un script de prueba para verificar la conexión a la base de datos:

python src/doris-mcp-server/test.py

Salida esperada:

🚀 Doris MCP Server is starting...
[DorisConnector] Connected to 127.0.0.1:9030
✅ Database connection successful.
[DorisConnector] Connection closed.

Escenarios de Aplicación

1. Análisis de Datos en Tiempo Real

   • Combinando la función NL2SQL, los usuarios empresariales pueden consultar datos en tiempo real a través del lenguaje natural, generando informes o paneles.
   • Adecuado para el soporte de decisiones en tiempo real en industrias como el comercio minorista, las finanzas y las telecomunicaciones.

2. Exploración de Metadatos

   • Los ingenieros de datos pueden obtener rápidamente el esquema de la base de datos, la estructura de la tabla y la información del índice, acelerando el modelado y la optimización de los datos.

3. Inteligencia Empresarial Impulsada por IA

   • Integrar agentes de IA (como Claude, Cursor), implementando flujos de trabajo automatizados de consulta y análisis de datos a través del protocolo MCP.

4. Gestión de la Seguridad y el Cumplimiento

   • El marco de seguridad de nivel empresarial y las funciones de registro de auditoría cumplen con los requisitos de seguridad y cumplimiento de datos en industrias como las finanzas y la atención médica.

5. Entornos de Múltiples Catálogos

   • Soporta la federación de múltiples catálogos, adecuado para la gestión de metadatos y la consulta en entornos complejos de almacenamiento de datos.

Ventajas y Limitaciones del Proyecto

Ventajas

• Inteligencia: La integración de NL2SQL y LLM reduce la barrera de entrada a la consulta de datos.
• Seguridad: La autenticación múltiple, RBAC y la protección SQL garantizan la seguridad de nivel empresarial.
• Alto Rendimiento: El almacenamiento en caché, los grupos de conexiones y la optimización de consultas mejoran la eficiencia.
• Flexibilidad: Soporta múltiples modos de comunicación y la expansión de herramientas modulares.

Limitaciones

• Estabilidad de las Primeras Versiones: Algunas funciones (como column_analysis) son experimentales y pueden contener errores.
• Dependencia de la Base de Datos Doris: Diseñado principalmente para Apache Doris, la compatibilidad con otras bases de datos de protocolo MySQL es limitada.
• SSE Obsoleto: La versión 0.3.0 eliminó el soporte de SSE, requiriendo la migración a HTTP Streamable.

Resumen

Apache Doris MCP Server es una herramienta potente y flexible que conecta la base de datos Apache Doris con las necesidades de análisis impulsadas por la IA. Sus características de NL2SQL, gestión de metadatos, seguridad y optimización del rendimiento le dan un amplio potencial en el análisis de datos en tiempo real, la inteligencia empresarial y las aplicaciones de nivel empresarial.