Servidor Trino MCP

Servidor de protocolo de contexto de modelo para Trino, que proporciona modelos de IA con acceso estructurado al motor de consulta SQL distribuido de Trino.

⚠️ VERSIÓN BETA (v0.1.2) ⚠️
Este proyecto se está estabilizando y sus funciones principales funcionan y están probadas. ¡Siéntete libre de bifurcar y contribuir!

Características

• ✅ ¡Se solucionó el problema de inicialización de la API del contenedor Docker! (inicialización confiable del servidor)

• ✅ Expone recursos de Trino a través del protocolo MCP

• ✅ Permite que las herramientas de IA consulten y analicen datos en Trino

• ✅ Proporciona opciones de transporte (el transporte STDIO funciona de manera confiable; el transporte SSE tiene problemas)

• ✅ Se corrigió el manejo del catálogo para la correcta ejecución de consultas Trino

• ✅ Opciones de servidor API de Python independiente y API de contenedor Docker

Related MCP server: Trino MCP Server

Inicio rápido

# Start the server with docker-compose
docker-compose up -d

# Verify the API is working
curl -X POST "http://localhost:9097/api/query" \
     -H "Content-Type: application/json" \
     -d '{"query": "SELECT 1 AS test"}'

¿Necesita una versión sin contenedor? Ejecute la API independiente:

# Run the standalone API server on port 8008
python llm_trino_api.py

Integración de LLM

¿Quieres que un LLM tenga acceso directo para consultar tu instancia de Trino? ¡Hemos creado herramientas sencillas para ello!

Interfaz LLM de línea de comandos

La forma más sencilla de permitir que un LLM consulte a Trino es a través de nuestra herramienta de línea de comandos:

# Simple direct query (perfect for LLMs)
python llm_query_trino.py "SELECT * FROM memory.bullshit.real_bullshit_data LIMIT 5"

# Specify a different catalog or schema
python llm_query_trino.py "SELECT * FROM information_schema.tables" memory information_schema

API REST para LLM

Ofrecemos dos opciones de API para la integración con aplicaciones LLM:

1. API de contenedor Docker (Puerto 9097)

El contenedor Docker expone una API REST en el puerto 9097:

# Execute a query against the Docker container API
curl -X POST "http://localhost:9097/api/query" \
     -H "Content-Type: application/json" \
     -d '{"query": "SELECT 1 AS test"}'

2. API independiente de Python (puerto 8008)

Para implementaciones más flexibles, ejecute el servidor API independiente:

# Start the API server on port 8008
python llm_trino_api.py

Esto crea puntos finales en:

• GET http://localhost:8008/ - Información de uso de la API

• POST http://localhost:8008/query - Ejecutar consultas SQL

Luego puede hacer que su LLM realice solicitudes HTTP a este punto final:

# Example code an LLM might generate
import requests

def query_trino(sql_query):
    response = requests.post(
        "http://localhost:8008/query",
        json={"query": sql_query}
    )
    return response.json()

# LLM-generated query
results = query_trino("SELECT job_title, AVG(salary) FROM memory.bullshit.real_bullshit_data GROUP BY job_title ORDER BY AVG(salary) DESC LIMIT 5")
print(results["formatted_results"])

Este enfoque permite que los LLM se concentren en generar SQL, mientras nuestras herramientas manejan toda la complejidad del protocolo MCP.

Scripts de demostración y validación 🚀

Hemos creado algunos scripts de demostración increíbles que muestran cómo los modelos de IA pueden usar el protocolo MCP para ejecutar consultas complejas en Trino:

1. Generación y carga de datos basura

El script tools/create_bullshit_data.py genera un conjunto de datos de 10 000 empleados con cargos ridículos, salarios inflados y una calificación de "factor de estupidez" (del 1 al 10):

# Generate the bullshit data
python tools/create_bullshit_data.py

# Load the bullshit data into Trino's memory catalog
python load_bullshit_data.py

2. Ejecución de consultas complejas a través de MCP

El script test_bullshit_query.py demuestra la interacción MCP de extremo a extremo:

• Se conecta al servidor MCP mediante el transporte STDIO

• Inicializa el protocolo siguiendo la especificación MCP

• Ejecuta una consulta SQL compleja con WHERE, GROUP BY, HAVING, ORDER BY

• Procesa y formatea los resultados

# Run a complex query against the bullshit data through MCP
python test_bullshit_query.py

Ejemplo de salida que muestra los mejores trabajos de BS con salarios altos:

🏆 TOP 10 BULLSHIT JOBS (high salary, high BS factor):
----------------------------------------------------------------------------------------------------
JOB_TITLE             | COUNT                | AVG_SALARY           | MAX_SALARY           | AVG_BS_FACTOR        
----------------------------------------------------------------------------------------------------
Advanced Innovation Jedi | 2                    |            241178.50 |            243458.00 |                 7.50
VP of Digital Officer | 1                    |            235384.00 |            235384.00 |                 7.00
Innovation Technical Architect | 1                    |            235210.00 |            235210.00 |                 9.00
...and more!

3. Pruebas de API

El script test_llm_api.py valida la funcionalidad de la API:

# Test the Docker container API 
python test_llm_api.py

Esto realiza una verificación exhaustiva de:

• Descubrimiento de puntos finales de API

• Disponibilidad de la documentación

• Ejecución de consulta válida

• Manejo de errores para consultas no válidas

Uso

# Start the server with docker-compose
docker-compose up -d

El servidor estará disponible en:

• Trino: http://localhost:9095

• Servidor MCP: http://localhost:9096

• Servidor API: http://localhost:9097

Conexión del cliente

✅ IMPORTANTE : Los scripts del cliente se ejecutan en tu equipo local (FUERA de Docker) y se conectan a los contenedores Docker. Los scripts gestionan esto automáticamente mediante comandos docker exec. ¡No necesitas estar dentro del contenedor para usar MCP!

Ejecutar pruebas desde su máquina local:

# Generate and load data into Trino
python tools/create_bullshit_data.py  # Generates data locally
python load_bullshit_data.py          # Loads data to Trino in Docker

# Run MCP query through Docker
python test_bullshit_query.py         # Queries using MCP in Docker

Opciones de transporte

Este servidor admite dos métodos de transporte, pero actualmente solo STDIO es confiable:

Transporte STDIO (recomendado y funcional)

El transporte STDIO funciona de manera confiable y actualmente es el único método recomendado para pruebas y desarrollo:

# Run with STDIO transport inside the container
docker exec -i trino_mcp_trino-mcp_1 python -m trino_mcp.server --transport stdio --debug --trino-host trino --trino-port 8080 --trino-user trino --trino-catalog memory

Transporte SSE (NO RECOMENDADO - Presenta problemas críticos)

SSE es el transporte predeterminado en MCP, pero presenta graves problemas con la versión actual de MCP 1.3.0, que provocan fallos del servidor al desconectarse el cliente. No se recomienda su uso hasta que se resuelvan estos problemas :

# NOT RECOMMENDED: Run with SSE transport (crashes on disconnection)
docker exec trino_mcp_trino-mcp_1 python -m trino_mcp.server --transport sse --host 0.0.0.0 --port 8000 --debug

Problemas conocidos y soluciones

Corregido: Inicialización de la API del contenedor Docker

SOLUCIONADO : Se solucionó un problema por el cual la API del contenedor Docker devolvía respuestas 503 "Servicio no disponible". El problema se debía a que la función app_lifespan no inicializaba correctamente app_context_global ni la conexión del cliente Trino. La solución garantiza que:

1. El cliente Trino se conecta explícitamente durante el inicio

2. La variable global AppContext se inicializa correctamente

3. Los controles de salud ahora funcionan correctamente

Si encuentra errores 503, verifique que su contenedor se haya reconstruido con el código más reciente:

# Rebuild and restart the container with the fix
docker-compose stop trino-mcp
docker-compose rm -f trino-mcp
docker-compose up -d trino-mcp

Fallos del transporte SSE de MCP 1.3.0

Hay un problema crítico con el transporte SSE de MCP 1.3.0 que provoca fallos del servidor cuando los clientes se desconectan. Hasta que se integre una versión más reciente de MCP, utilice exclusivamente el transporte STDIO. El error se manifiesta como:

RuntimeError: generator didn't stop after athrow()
anyio.BrokenResourceError

Manejo del catálogo Trino

Se solucionó un problema con la gestión del catálogo en el cliente Trino. La implementación original intentaba usar sentencias USE catalog , lo cual no funcionaba correctamente. La solución establece el catálogo directamente en los parámetros de conexión.

Estructura del proyecto

Este proyecto está organizado de la siguiente manera:

• src/ - Código fuente principal del servidor Trino MCP

• examples/ - Ejemplos sencillos que muestran cómo utilizar el servidor

• scripts/ - Scripts útiles de diagnóstico y prueba

• tools/ - Scripts de utilidad para la creación y configuración de datos

• tests/ - Pruebas automatizadas

Archivos clave:

• llm_trino_api.py : servidor API independiente para la integración de LLM

• test_llm_api.py - Script de prueba para el servidor API

• test_mcp_stdio.py - Script de prueba principal que utiliza el transporte STDIO (recomendado)

• test_bullshit_query.py - Ejemplo de consulta compleja con datos falsos

• load_bullshit_data.py - Script para cargar datos generados en Trino

• tools/create_bullshit_data.py - Script para generar datos de prueba divertidos

• run_tests.sh - Script para ejecutar pruebas automatizadas

• examples/simple_mcp_query.py - Ejemplo simple para consultar datos usando MCP

Desarrollo

IMPORTANTE : Todos los scripts se pueden ejecutar desde su máquina local: se comunicarán automáticamente con los contenedores Docker a través de comandos docker exec.

# Install development dependencies
pip install -e ".[dev]"

# Run automated tests 
./run_tests.sh

# Test MCP with STDIO transport (recommended)
python test_mcp_stdio.py

# Simple example query
python examples/simple_mcp_query.py "SELECT 'Hello World' AS message"

Pruebas

Para probar que las consultas Trino funcionan correctamente, utilice el script de prueba de transporte STDIO:

# Recommended test method (STDIO transport)
python test_mcp_stdio.py

Para realizar pruebas más complejas con datos falsos:

# Load and query the bullshit data (shows the full power of Trino MCP!)
python load_bullshit_data.py
python test_bullshit_query.py

Para probar el punto final de la API de LLM:

# Test the Docker container API
python test_llm_api.py 

# Test the standalone API (make sure it's running first)
python llm_trino_api.py
curl -X POST "http://localhost:8008/query" \
     -H "Content-Type: application/json" \
     -d '{"query": "SELECT 1 AS test"}'

Cómo los LLM pueden usar esto

Los LLM pueden utilizar el servidor Trino MCP para:

1. Obtener información del esquema de la base de datos :

   # Example prompt to LLM: "What schemas are available in the memory catalog?"
   # LLM can generate code to query:
   query = "SHOW SCHEMAS FROM memory"

2. Ejecutar consultas analíticas complejas :

   # Example prompt: "Find the top 5 job titles with highest average salaries"
   # LLM can generate complex SQL:
   query = """
   SELECT 
     job_title, 
     AVG(salary) as avg_salary
   FROM 
     memory.bullshit.real_bullshit_data
   GROUP BY 
     job_title
   ORDER BY 
     avg_salary DESC
   LIMIT 5
   """

3. Realizar análisis de datos y presentar resultados :

   # LLM can parse the response, extract insights and present to user:
   "The highest paying job title is 'Advanced Innovation Jedi' with an average salary of $241,178.50"

Ejemplo de análisis real de LLM: trabajos basura por empresa

He aquí un ejemplo real de lo que un LLM podría producir cuando se le pide "Identificar las empresas con la mayor cantidad de empleados en trabajos de mierda y crear un gráfico de sirena":

Paso 1: LLM genera y ejecuta la consulta

SELECT 
  company, 
  COUNT(*) as employee_count, 
  AVG(bullshit_factor) as avg_bs_factor 
FROM 
  memory.bullshit.real_bullshit_data 
WHERE 
  bullshit_factor > 7 
GROUP BY 
  company 
ORDER BY 
  employee_count DESC, 
  avg_bs_factor DESC 
LIMIT 10

Paso 2: LLM obtiene y analiza los resultados

COMPANY | EMPLOYEE_COUNT | AVG_BS_FACTOR
----------------------------------------
Unknown Co | 2 | 9.0
BitEdge | 1 | 10.0
CyberWare | 1 | 10.0
BitLink | 1 | 10.0
AlgoMatrix | 1 | 10.0
CryptoHub | 1 | 10.0
BitGrid | 1 | 10.0
MLStream | 1 | 10.0
CloudCube | 1 | 10.0
UltraEdge | 1 | 10.0

Paso 3: LLM genera una visualización del gráfico de sirena

%%{init: {'theme': 'forest'}}%%
graph LR
    title[Companies with Most Bullshit Jobs]
    style title fill:#333,stroke:#333,stroke-width:1px,color:white,font-weight:bold,font-size:18px

    Companies --> UnknownCo[Unknown Co]
    Companies --> BitEdge[BitEdge]
    Companies --> CyberWare[CyberWare]
    Companies --> BitLink[BitLink]
    Companies --> AlgoMatrix[AlgoMatrix]
    Companies --> CryptoHub[CryptoHub]
    Companies --> BitGrid[BitGrid]
    Companies --> MLStream[MLStream]
    Companies --> CloudCube[CloudCube]
    Companies --> UltraEdge[UltraEdge]
    
    UnknownCo --- Count2[2 employees]
    BitEdge --- Count1a[1 employee]
    CyberWare --- Count1b[1 employee]
    BitLink --- Count1c[1 employee]
    AlgoMatrix --- Count1d[1 employee]
    CryptoHub --- Count1e[1 employee]
    BitGrid --- Count1f[1 employee]
    MLStream --- Count1g[1 employee]
    CloudCube --- Count1h[1 employee]
    UltraEdge --- Count1i[1 employee]
    
    classDef company fill:#ff5733,stroke:#333,stroke-width:1px,color:white,font-weight:bold;
    classDef count fill:#006100,stroke:#333,stroke-width:1px,color:white,font-weight:bold;
    
    class UnknownCo,BitEdge,CyberWare,BitLink,AlgoMatrix,CryptoHub,BitGrid,MLStream,CloudCube,UltraEdge company;
    class Count2,Count1a,Count1b,Count1c,Count1d,Count1e,Count1f,Count1g,Count1h,Count1i count;

Gráfico de barras alternativo:

%%{init: {'theme': 'default'}}%%
pie showData
    title Companies with Bullshit Jobs
    "Unknown Co (BS: 9.0)" : 2
    "BitEdge (BS: 10.0)" : 1
    "CyberWare (BS: 10.0)" : 1
    "BitLink (BS: 10.0)" : 1
    "AlgoMatrix (BS: 10.0)" : 1
    "CryptoHub (BS: 10.0)" : 1
    "BitGrid (BS: 10.0)" : 1
    "MLStream (BS: 10.0)" : 1
    "CloudCube (BS: 10.0)" : 1
    "UltraEdge (BS: 10.0)" : 1

Paso 4: LLM proporciona información clave

El LLM puede analizar los datos y proporcionar información:

• "Unknown Co" tiene la mayor cantidad de empleados en roles de mierda (2), mientras que todos los demás tienen solo uno

• La mayoría de las empresas han conseguido una puntuación perfecta de 10,0 en el factor de estupidez.

• Las empresas centradas en la tecnología (BitEdge, CyberWare, etc.) parecen crear roles particularmente insignificantes

• Los roles de mierda aparecen concentrados en niveles ejecutivos o de puestos especializados

Este ejemplo demuestra cómo un LLM puede:

1. Generar consultas SQL apropiadas basadas en preguntas en lenguaje natural

2. Procesar e interpretar los resultados de Trino

3. Crear representaciones visuales de los datos

4. Proporcionar información y análisis significativos

Accediendo a la API

El servidor Trino MCP ahora incluye dos opciones de API para acceder a los datos:

1. API de contenedor Docker (Puerto 9097)

import requests
import json

# API endpoint (default port 9097 in Docker setup)
api_url = "http://localhost:9097/api/query"

# Define your SQL query
query_data = {
    "query": "SELECT * FROM memory.bullshit.real_bullshit_data LIMIT 5",
    "catalog": "memory",
    "schema": "bullshit"
}

# Send the request
response = requests.post(api_url, json=query_data)
results = response.json()

# Process the results
if results["success"]:
    print(f"Query returned {results['results']['row_count']} rows")
    for row in results['results']['rows']:
        print(row)
else:
    print(f"Query failed: {results['message']}")

2. API independiente de Python (puerto 8008)

# Same code as above, but with different port
api_url = "http://localhost:8008/query"

Ambas API ofrecen los siguientes puntos finales:

• GET /api - Documentación de la API y ejemplos de uso

• POST /api/query - Ejecutar consultas SQL contra Trino

Estas API eliminan la necesidad de scripts envolventes y permiten que los LLM consulten a Trino directamente mediante llamadas REST, lo que hace que sea mucho más sencilla la integración con servicios como Claude, GPT y otros sistemas de IA.

Solución de problemas

La API devuelve el error 503: Servicio no disponible

Si la API del contenedor Docker devuelve errores 503:

1. Asegúrese de haber reconstruido el contenedor con el código más reciente:

   docker-compose stop trino-mcp
   docker-compose rm -f trino-mcp
   docker-compose up -d trino-mcp

2. Verifique los registros del contenedor para detectar errores:

   docker logs trino_mcp_trino-mcp_1

3. Verifique que Trino esté funcionando correctamente:

   curl -s http://localhost:9095/v1/info | jq

Conflictos de puertos con API independientes

La API independiente usa el puerto 8008 por defecto para evitar conflictos. Si ve el error "Dirección ya en uso":

1. Edite llm_trino_api.py y cambie el número de puerto en la última línea:

   uvicorn.run(app, host="127.0.0.1", port=8008) 

2. Ejecutar con un puerto personalizado a través de la línea de comando:

   python -c "import llm_trino_api; import uvicorn; uvicorn.run(llm_trino_api.app, host='127.0.0.1', port=8009)"

Trabajo futuro

Esta versión ahora está en versión beta con las siguientes mejoras planificadas:

• [ ] Integrar con versiones más nuevas de MCP cuando estén disponibles para solucionar problemas de transporte de SSE

• [ ] Agregar/Validar soporte para Hive, JDBC y otros conectores

• [ ] Agregue una validación de consultas más completa en diferentes tipos y complejidades

• [ ] Implementar soporte para más tipos de datos y funciones avanzadas de Trino

• [ ] Mejorar los mecanismos de gestión y recuperación de errores

• [ ] Agregar controles de permisos y autenticación de usuarios

• [ ] Crear ejemplos y documentación más completos

• [ ] Desarrollar interfaces de gestión y monitoreo administrativo

• [ ] Agregar métricas de rendimiento y sugerencias de optimización de consultas

• [ ] Implementar soporte para consultas de larga duración y transmisión de resultados

Desarrollado por Stink Labs, 2025