Servidor Doris MCP

El servidor Doris MCP (Panel de Control de Modelos) es un servicio backend desarrollado con Python y FastAPI. Implementa el protocolo MCP (Panel de Control de Modelos), lo que permite a los clientes interactuar con él mediante herramientas definidas. Está diseñado principalmente para conectarse a bases de datos Apache Doris, aprovechando potencialmente los Modelos de Lenguaje Grandes (LLM) para tareas como la conversión de consultas de lenguaje natural a SQL (NL2SQL), la ejecución de consultas y la gestión y el análisis de metadatos.

Características principales

Implementación del protocolo MCP : proporciona interfaces MCP estándar, admite llamadas de herramientas, gestión de recursos e interacciones rápidas.
Múltiples modos de comunicación :
- SSE (eventos enviados por el servidor) : se sirven a través de los puntos finales /sse (inicialización) y /mcp/messages (comunicación) ( src/sse_server.py ).
- HTTP transmisible : se sirve a través del punto final unificado /mcp , que admite solicitud/respuesta y transmisión ( src/streamable_server.py ).
- (Opcional) Stdio : interacción posible a través de entrada/salida estándar ( src/stdio_server.py ), requiere configuración de inicio específica.
Interfaz basada en herramientas : Las funcionalidades principales se encapsulan como herramientas MCP que los clientes pueden usar según sea necesario. Las herramientas clave disponibles actualmente se centran en la interacción directa con la base de datos:
- Ejecución de SQL ( mcp_doris_exec_query )
- Listado de bases de datos y tablas ( mcp_doris_get_db_list , mcp_doris_get_db_table_list )
- Recuperación de metadatos ( mcp_doris_get_table_schema , mcp_doris_get_table_comment , mcp_doris_get_table_column_comments , mcp_doris_get_table_indexes )
- Recuperación del registro de auditoría ( mcp_doris_get_recent_audit_logs ) Nota: Las herramientas actuales se centran principalmente en operaciones directas de la base de datos.
Interacción con la base de datos : proporciona funcionalidad para conectarse a Apache Doris (u otras bases de datos compatibles) y ejecutar consultas ( src/utils/db.py ).
Configuración flexible : se configura a través de un archivo .env , que admite configuraciones para conexiones de bases de datos, proveedores/modelos LLM, claves API, niveles de registro, etc.
Extracción de metadatos : capaz de extraer información de metadatos de la base de datos ( src/utils/schema_extractor.py ).

Requisitos del sistema

Python 3.12+
Detalles de conexión a la base de datos (por ejemplo, Doris Host, Puerto, Usuario, Contraseña, Base de datos)

Inicio rápido

1. Clonar el repositorio

# Replace with the actual repository URL if different
git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server

2. Instalar dependencias

pip install -r requirements.txt

3. Configurar variables de entorno

Copie el archivo .env.example a .env y modifique la configuración según su entorno:

cp env.example .env

Variables ambientales clave:

Conexión a la base de datos :
- DB_HOST : Nombre de host de la base de datos
- DB_PORT : Puerto de base de datos (predeterminado 9030)
- DB_USER : Nombre de usuario de la base de datos
- DB_PASSWORD : Contraseña de la base de datos
- DB_DATABASE : Nombre de la base de datos predeterminada
Configuración del servidor :
- SERVER_HOST : Dirección de host en la que escucha el servidor (valor predeterminado 0.0.0.0 )
- SERVER_PORT : Puerto en el que escucha el servidor (predeterminado 3000 )
- ALLOWED_ORIGINS : Orígenes permitidos por CORS (separados por comas, * permite todos)
- MCP_ALLOW_CREDENTIALS : Si se permiten credenciales CORS (valor predeterminado: false )
Configuración de registro :
- LOG_DIR : Directorio para archivos de registro (predeterminado ./logs )
- LOG_LEVEL : Nivel de registro (por ejemplo, INFO , DEBUG , WARNING , ERROR , predeterminado INFO )
- CONSOLE_LOGGING : Si desea enviar registros a la consola (predeterminado: false )

Herramientas MCP disponibles

La siguiente tabla enumera las principales herramientas actualmente disponibles para la invocación a través de un cliente MCP:

Nombre de la herramienta	Descripción	Parámetros	Estado
`mcp_doris_get_db_list`	Obtenga una lista de todos los nombres de bases de datos en el servidor.	`random_string` (cadena, Obligatorio)	✅ Activo
`mcp_doris_get_db_table_list`	Obtenga una lista de todos los nombres de tablas en la base de datos especificada.	`random_string` (cadena, Obligatorio), `db_name` (cadena, Opcional, predeterminado a la base de datos actual)	✅ Activo
`mcp_doris_get_table_schema`	Obtenga la estructura detallada de la tabla especificada.	`random_string` (cadena, Obligatorio), `table_name` (cadena, Obligatorio), `db_name` (cadena, Opcional)	✅ Activo
`mcp_doris_get_table_comment`	Obtener el comentario para la tabla especificada.	`random_string` (cadena, Obligatorio), `table_name` (cadena, Obligatorio), `db_name` (cadena, Opcional)	✅ Activo
`mcp_doris_get_table_column_comments`	Obtener comentarios para todas las columnas de la tabla especificada.	`random_string` (cadena, Obligatorio), `table_name` (cadena, Obligatorio), `db_name` (cadena, Opcional)	✅ Activo
`mcp_doris_get_table_indexes`	Obtener información del índice para la tabla especificada.	`random_string` (cadena, Obligatorio), `table_name` (cadena, Obligatorio), `db_name` (cadena, Opcional)	✅ Activo
`mcp_doris_exec_query`	Ejecutar consulta SQL y devolver el comando de resultado.	`random_string` (cadena, Obligatorio), `sql` (cadena, Obligatorio), `db_name` (cadena, Opcional), `max_rows` (entero, Opcional, predeterminado 100), `timeout` (entero, Opcional, predeterminado 30)	✅ Activo
`mcp_doris_get_recent_audit_logs`	Obtenga registros de registro de auditoría de un período reciente.	`random_string` (cadena, Obligatorio), `days` (entero, Opcional, predeterminado 7), `limit` (entero, Opcional, predeterminado 100)	✅ Activo

Nota: Todas las herramientas requieren un parámetro random_string como identificador de llamada, que normalmente gestiona automáticamente el cliente MCP. "Opcional" y "Obligatorio" se refieren a la lógica interna de la herramienta; el cliente podría necesitar proporcionar valores para todos los parámetros según su implementación. Los nombres de las herramientas que se muestran aquí son los nombres base; los clientes podrían verlos con un prefijo (p. ej., mcp_doris_stdio3_get_db_list ) según el modo de conexión.

4. Ejecutar el servicio

Si utiliza el modo SSE, ejecute el siguiente comando:

./start_server.sh

Este comando inicia la aplicación FastAPI, que proporciona servicios SSE y Streamable HTTP MCP de forma predeterminada.

Puntos finales del servicio:

Inicialización de SSE : http://<host>:<port>/sse
Comunicación SSE : http://<host>:<port>/mcp/messages (POST)
HTTP transmisible : http://<host>:<port>/mcp (admite GET, POST, DELETE, OPCIONES)
Comprobación de estado : http://<host>:<port>/health
(Potencial) Comprobación de estado : http://<host>:<port>/status (Confirmar si está implementado en main.py )

Uso

La interacción con el servidor Doris MCP requiere un cliente MCP . El cliente se conecta a los puntos finales HTTP SSE o Streamable del servidor y envía solicitudes (como tool_call ) según la especificación MCP para invocar las herramientas del servidor.

Flujo de interacción principal:

Inicialización del cliente : Conéctese a /sse (SSE) o envíe una llamada al método initialize a /mcp (transmisible).
(Opcional) Descubrir herramientas : el cliente puede llamar a mcp/listTools o mcp/listOfferings para obtener la lista de herramientas compatibles, sus descripciones y esquemas de parámetros.
Herramienta de llamada : el cliente envía un mensaje/solicitud tool_call , especificando el tool_name y arguments .
- Ejemplo: Obtener el esquema de la tabla
  - tool_name : mcp_doris_get_table_schema (o el nombre específico del modo)
  - arguments : incluye random_string , table_name , db_name .
Respuesta del manejador :
- Sin transmisión : el cliente recibe una respuesta que contiene result o error .
- Transmisión : el cliente recibe una serie de tools/progress , seguidas de una respuesta final que contiene el result o error .

Los nombres y parámetros de herramientas específicos deben referenciarse desde el código src/tools/ u obtenerse mediante mecanismos de descubrimiento de MCP.

Conectando con el cursor

Puede conectar Cursor a este servidor MCP usando el modo Stdio o SSE.

Modo estudio

El modo Stdio permite a Cursor gestionar directamente el proceso del servidor. La configuración se realiza en el archivo de configuración del servidor MCP de Cursor (normalmente ~/.cursor/mcp.json o similar).

Si usa el modo stdio, ejecute el siguiente comando para descargar y compilar el paquete de dependencia del entorno, pero tenga en cuenta que debe cambiar la ruta del proyecto a la dirección de ruta correcta :

uv --project /your/path/doris-mcp-server run doris-mcp

Configurar cursor: agregue una entrada como la siguiente a su configuración de Cursor MCP:
{ "mcpServers": { "doris-stdio": { "command": "uv", "args": ["--project", "/path/to/your/doris-mcp-server", "run", "doris-mcp"], "env": { "DB_HOST": "127.0.0.1", "DB_PORT": "9030", "DB_USER": "root", "DB_PASSWORD": "your_db_password", "DB_DATABASE": "your_default_db" } }, // ... other server configurations ... } }
Puntos clave:
- Reemplace /path/to/your/doris-mcp con la ruta absoluta al directorio raíz del proyecto en su sistema. El argumento --project es crucial para que uv encuentre el pyproject.toml y ejecute el comando correcto.
- El command se establece en uv (suponiendo que se usa uv para la gestión de paquetes, como se indica en uv.lock ). Los args incluyen --project , la ruta, run y mcp-doris (que debería corresponder a un script definido en pyproject.toml ).
- Los detalles de conexión a la base de datos ( DB_HOST , DB_PORT , DB_USER , DB_PASSWORD , DB_DATABASE ) se configuran directamente en el bloque env del archivo de configuración. Cursor los pasará al proceso del servidor. No se necesita el archivo .env para este modo cuando se configura mediante Cursor.

Modo SSE

El modo SSE requiere que primero ejecutes el servidor MCP de forma independiente y luego le digas a Cursor cómo conectarse a él.

Configurar .env : asegúrese de que las credenciales de su base de datos y cualquier otra configuración necesaria (como SERVER_PORT si no usa el valor predeterminado 3000) estén configuradas correctamente en el archivo .env dentro del directorio del proyecto.
Iniciar el servidor: Ejecute el servidor desde su terminal en el directorio raíz del proyecto:
./start_server.sh
Este script suele leer el archivo .env e iniciar el servidor FastAPI en modo SSE (consulte el script y sse_server.py para obtener más información). Anote main.py host y el puerto en los que escucha el servidor (el valor predeterminado es 0.0.0.0:3000 ).
Configurar cursor: agregue una entrada como la siguiente a su configuración de MCP de Cursor, que apunte al punto final SSE del servidor en ejecución:
{ "mcpServers": { "doris-sse": { "url": "http://127.0.0.1:3000/sse" // Adjust host/port if your server runs elsewhere }, // ... other server configurations ... } }
Nota: El ejemplo utiliza el puerto predeterminado 3000 Si su servidor está configurado para ejecutarse en un puerto diferente (como 3010 en el ejemplo del usuario), ajuste la URL según corresponda.

Después de configurar cualquiera de los modos en Cursor, debería poder seleccionar el servidor (por ejemplo, doris-stdio o doris-sse ) y utilizar sus herramientas.

Estructura del directorio

doris-mcp-server/
├── doris_mcp_server/    # Source code for the MCP server
│   ├── main.py          # Main entry point, FastAPI app definition
│   ├── mcp_core.py      # Core MCP tool registration and Stdio handling
│   ├── sse_server.py    # SSE server implementation
│   ├── streamable_server.py # Streamable HTTP server implementation
│   ├── config.py        # Configuration loading
│   ├── tools/           # MCP tool definitions
│   │   ├── mcp_doris_tools.py # Main Doris-related MCP tools
│   │   ├── tool_initializer.py # Tool registration helper (used by mcp_core.py)
│   │   └── __init__.py
│   ├── utils/           # Utility classes and helper functions
│   │   ├── db.py              # Database connection and operations
│   │   ├── logger.py          # Logging configuration
│   │   ├── schema_extractor.py # Doris metadata/schema extraction logic
│   │   ├── sql_executor_tools.py # SQL execution helper (might be legacy)
│   │   └── __init__.py
│   └── __init__.py
├── logs/                # Log file directory (if file logging enabled)
├── README.md            # This file
├── .env.example         # Example environment variable file
├── requirements.txt     # Python dependencies for pip
├── pyproject.toml       # Project metadata and build system configuration (PEP 518)
├── uv.lock              # Lock file for 'uv' package manager (alternative to pip)
├── start_server.sh      # Script to start the server
└── restart_server.sh    # Script to restart the server

Desarrollo de nuevas herramientas

Esta sección describe el proceso para agregar nuevas herramientas MCP al servidor Doris MCP, considerando la estructura actual del proyecto.

1. Aproveche los módulos de utilidad

Antes de escribir una nueva lógica de interacción con la base de datos desde cero, verifique los módulos de utilidad existentes:

doris_mcp_server/utils/db.py : proporciona funciones básicas para obtener conexiones de base de datos ( get_db_connection ) y ejecutar consultas sin procesar ( execute_query , execute_query_df ).
doris_mcp_server/utils/schema_extractor.py (clase MetadataExtractor ) : Ofrece métodos avanzados para recuperar metadatos de bases de datos, como listar bases de datos/tablas ( get_all_databases , get_database_tables ), obtener esquemas/comentarios/índices de tablas ( get_table_schema , get_table_comment , get_column_comments , get_table_indexes ) y acceder a registros de auditoría ( get_recent_audit_logs ). Incluye mecanismos de almacenamiento en caché.
doris_mcp_server/utils/sql_executor_tools.py (función execute_sql_query ) : Proporciona un contenedor para db.execute_query que incluye comprobaciones de seguridad (opcionales, controladas por la variable de entorno ENABLE_SQL_SECURITY_CHECK ), añade LIMIT automático a las consultas SELECT, gestiona la serialización de resultados (fechas, decimales) y formatea la salida según la estructura estándar de éxito/error de MCP. Se recomienda su uso para ejecutar SQL proporcionado o generado por el usuario.

Puede importar y combinar funcionalidades de estos módulos para crear su nueva herramienta.

2. Implementar la lógica de la herramienta

Implemente la lógica principal de su nueva herramienta como una función async dentro de doris_mcp_server/tools/mcp_doris_tools.py . Esto mantiene centralizadas las implementaciones principales de la herramienta. Asegúrese de que su función devuelva datos en un formato que se pueda integrar fácilmente en la estructura de respuesta estándar de MCP (consulte _format_response en el mismo archivo como referencia).

Ejemplo: Creemos una herramienta simple get_server_time .

# In doris_mcp_server/tools/mcp_doris_tools.py
import datetime
# ... other imports ...
from doris_mcp_server.tools.mcp_doris_tools import _format_response # Reuse formatter

# ... existing tools ...

async def mcp_doris_get_server_time() -> Dict[str, Any]:
    """Gets the current server time."""
    logger.info(f"MCP Tool Call: mcp_doris_get_server_time")
    try:
        current_time = datetime.datetime.now().isoformat()
        # Use the existing formatter for consistency
        return _format_response(success=True, result={"server_time": current_time})
    except Exception as e:
        logger.error(f"MCP tool execution failed mcp_doris_get_server_time: {str(e)}", exc_info=True)
        return _format_response(success=False, error=str(e), message="Error getting server time")

3. Registrar la herramienta (registro dual)

Debido al manejo separado de los modos SSE/Streamable y Stdio, debe registrar la herramienta en dos lugares:

A. Registro SSE/Transmitible ( tool_initializer.py )

Importe su nueva función de herramienta desde mcp_doris_tools.py .
Dentro de la función register_mcp_tools , agregue una nueva función contenedora decorada con @mcp.tool() .
La función envolvente debe llamar a la función de su herramienta principal.
Define el nombre de la herramienta y proporciona una descripción detallada (incluyendo los parámetros, si los hay) en el decorador. Recuerda incluir la descripción obligatoria del parámetro random_string para compatibilidad con el cliente, incluso si tu wrapper no la usa explícitamente.

Ejemplo ( tool_initializer.py ):

# In doris_mcp_server/tools/tool_initializer.py
# ... other imports ...
from doris_mcp_server.tools.mcp_doris_tools import (
    # ... existing tool imports ...
    mcp_doris_get_server_time # <-- Import the new tool
)

async def register_mcp_tools(mcp):
    # ... existing tool registrations ...

    # Register Tool: Get Server Time
    @mcp.tool("get_server_time", description="""[Function Description]: Get the current time of the MCP server.\n
[Parameter Content]:\n
- random_string (string) [Required] - Unique identifier for the tool call\n""")
    async def get_server_time_tool() -> Dict[str, Any]:
        """Wrapper: Get server time"""
        # Note: No parameters needed for the core function call here
        return await mcp_doris_get_server_time()

    # ... logging registration count ...

B. Registro de Stdio ( mcp_core.py )

De manera similar a SSE, agregue una nueva función contenedora decorada con @stdio_mcp.tool() .
Importante: Importe la función de su herramienta principal ( mcp_doris_get_server_time ) dentro de la función contenedora (patrón de importación retrasada utilizado en este archivo).
El contenedor llama a la función principal de la herramienta. El contenedor podría necesitar una async def según cómo FastMCP gestione las herramientas en modo Stdio, incluso si la función subyacente es simple (como se observa en la estructura del archivo actual). Asegúrese de que la llamada coincida (por ejemplo, use await si se llama a una función asíncrona).

Ejemplo ( mcp_core.py ):

# In doris_mcp_server/mcp_core.py
# ... other imports and setup ...

# ... existing Stdio tool registrations ...

# Register Tool: Get Server Time (for Stdio)
@stdio_mcp.tool("get_server_time", description="""[Function Description]: Get the current time of the MCP server.\n
[Parameter Content]:\n
- random_string (string) [Required] - Unique identifier for the tool call\n""")
async def get_server_time_tool_stdio() -> Dict[str, Any]: # Using a slightly different wrapper name for clarity if needed
    """Wrapper: Get server time (Stdio)"""
    from doris_mcp_server.tools.mcp_doris_tools import mcp_doris_get_server_time # <-- Delayed import
    # Assuming the Stdio runner handles async wrappers correctly
    return await mcp_doris_get_server_time()

# --- Register Tools --- (Or wherever the registrations are finalized)

4. Reiniciar y probar

Después de implementar y registrar la herramienta en ambos archivos, reinicie el servidor MCP (ambos modos SSE a través de ./start_server.sh y asegúrese de que el comando Stdio utilizado por Cursor se actualice si es necesario) y pruebe la nueva herramienta usando su cliente MCP (como Cursor) en ambos modos de conexión.

Contribuyendo

Las contribuciones son bienvenidas a través de problemas o solicitudes de extracción.

Licencia

Este proyecto está licenciado bajo la licencia Apache 2.0. Consulte el archivo de licencia (si existe) para obtener más información.

Doris MCP Server

Integrations