fabianaguero/polenta

Polenta - Presto Datalake MCP Server

Un servidor MCP (Model Context Protocol) completo desarrollado en Java con Spring Boot para acceder a un datalake de PrestoDB de manera amigable para usuarios no técnicos.

Características Principales

• MCP Compliant: Totalmente compatible con el protocolo MCP 2024-11-05 con endpoint JSON-RPC estándar
• Consultas en Lenguaje Natural: Los usuarios pueden hacer preguntas sin conocer SQL
• Acceso a PrestoDB: Integración nativa con PrestoDB para consultas de datalake
• Abstracción de Esquemas: Los usuarios no necesitan conocer estructuras de tablas
• Compatible con Múltiples Clientes: VSCode, Ollama Desktop, y cualquier cliente MCP
• Endpoints Helper: Endpoints REST adicionales para desarrollo y depuración

Inicio Rápido

Prerrequisitos

• Java 17+
• Maven 3.6+
• PrestoDB server ejecutándose
• Acceso a las tablas del datalake

Configuración

1. Clonar el repositorio

git clone <repository-url>
cd polenta

2. Configurar PrestoDB Editar src/main/resources/application.yml:

presto:
  url: jdbc:presto://tu-servidor-presto:8080/hive/default
  user: tu-usuario
  password: tu-password
  catalog: hive
  schema: default
  connection-timeout: 5000 # Tiempo de espera para establecer la conexión (ms)
  query-timeout: 10000     # Tiempo máximo para ejecutar consultas (ms)

# Configuración MCP
mcp:
  helpers:
    enabled: true  # Habilitar endpoints helper (desactivar en producción)

El parámetro presto.query-timeout define el tiempo máximo permitido para la ejecución de consultas (en milisegundos).

3. Compilar y ejecutar

mvn clean install
mvn spring-boot:run

El servidor estará disponible en http://localhost:8090

Uso del Protocolo MCP (Recomendado)

Endpoint JSON-RPC Principal

POST /mcp - Endpoint estándar MCP JSON-RPC 2.0

Este es el endpoint recomendado que cumple completamente con la especificación MCP.

Ejemplos con curl:

1. Inicializar sesión:

curl -X POST http://localhost:8090/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initialize",
    "params": {}
  }'

2. Ping (requiere inicialización previa):

curl -X POST http://localhost:8090/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2", 
    "method": "ping",
    "params": {}
  }'

3. Listar herramientas disponibles:

curl -X POST http://localhost:8090/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/list",
    "params": {}
  }'

4. Ejecutar consulta:

curl -X POST http://localhost:8090/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "4",
    "method": "tools/call",
    "params": {
      "name": "query_data",
      "arguments": {
        "query": "Muestra todas las tablas disponibles"
      }
    }
  }'

Prueba Rápida

Ejecuta el script de prueba incluido:

./mcp_smoke.sh

Ejecutar con Docker

Para probar rápidamente el servidor con un PrestoDB de ejemplo se puede utilizar el docker-compose.yml incluido. Este levanta un contenedor de Presto con el conector tpch que genera datos sintéticos y el servidor Polenta conectado a él.

docker-compose up --build

El servidor MCP quedará disponible en http://localhost:8090 y el Presto de prueba en http://localhost:8082.

Endpoints Helper (Desarrollo)

Estos endpoints están disponibles cuando mcp.helpers.enabled=true y proporcionan wrappers REST para facilitar el desarrollo. En producción se recomienda usar únicamente el endpoint /mcp.

Inicialización

• POST /mcp/initialize - Establece conexión con cliente MCP
• POST /mcp/ping - Verificación de actividad
• POST /mcp/notifications/cancelled - Notifica cancelación de operaciones
• POST /mcp/notifications/progress - Reporta progreso de operaciones

Prompts

• POST /mcp/prompts/list - Lista prompts disponibles
• POST /mcp/prompts/get - Obtiene detalles de un prompt específico

Recursos

• POST /mcp/resources/list - Lista recursos disponibles
• POST /mcp/resources/read - Lee contenido de un recurso
• POST /mcp/resources/templates/list - Lista plantillas de recursos
• POST /mcp/resources/subscribe - Suscribe a actualizaciones de recursos

Herramientas Disponibles

• POST /mcp/tools/list - Lista todas las herramientas disponibles
• POST /mcp/tools/call - Ejecuta herramientas específicas

Utilidades

• POST /mcp/logging/setLevel - Ajusta nivel de logs del servidor
• POST /mcp/completion/complete - Devuelve sugerencias de autocompletado

Salud del Sistema

• GET /mcp/health - Estado del servidor y conexión a base de datos

Herramientas Disponibles

1. query_data

Ejecuta consultas en lenguaje natural o SQL directo.

Ejemplos de uso:

• "Muestra todas las tablas"
• "¿Qué columnas tiene la tabla usuarios?"
• "Dame datos de ejemplo de la tabla ventas"
• "SELECT * FROM productos LIMIT 10"

2. metadata

Navega los metadatos del catálogo. Sin parámetros devuelve los esquemas disponibles. Con schema lista las tablas del esquema. Con schema y table describe las columnas de la tabla.

3. sample_data

Obtiene datos de muestra de una tabla (limitado a 10 filas).

4. search_tables

Busca tablas que contengan palabras clave específicas.

5. get_suggestions

Proporciona sugerencias útiles de consultas para usuarios.

Ejemplos de Consultas en Lenguaje Natural

"Muestra todas las tablas disponibles"
"Describe la tabla clientes"
"Dame datos de ejemplo de productos"
"Busca tablas que contengan 'ventas'"
"¿Qué columnas tiene la tabla pedidos?"
"Muestra los primeros 10 registros de usuarios"
"¿Qué tablas puedo consultar?"

Integración con Clientes MCP

VSCode

1. Instalar extensión MCP
2. Configurar servidor: http://localhost:8090/mcp

Ollama Desktop

1. Agregar servidor MCP en configuración
2. URL: http://localhost:8090/mcp

Cliente Personalizado

Usar cualquier cliente compatible con MCP 2024-11-05 apuntando al endpoint /mcp con JSON-RPC 2.0.

Códigos de Error JSON-RPC

El servidor implementa los códigos de error estándar JSON-RPC:

• -32600: Solicitud inválida (JSON-RPC malformado)
• -32601: Método no encontrado
• -32602: Parámetros inválidos
• -32603: Error interno del servidor
• -32000: Errores de estado (ej: ping sin inicializar)

Arquitectura

Componentes Principales

• McpJsonRpcController: Endpoint JSON-RPC estándar /mcp
• McpDispatcherService: Enrutamiento y manejo de métodos JSON-RPC
• McpController: Endpoints helper REST (opcional, solo desarrollo)
• QueryIntelligenceService: Procesamiento de lenguaje natural
• PrestoService: Integración con PrestoDB
• Modelos MCP: Request/Response según especificación JSON-RPC 2.0

Configuración de Seguridad

Para producción, configurar:

presto:
  user: ${PRESTO_USER}
  password: ${PRESTO_PASSWORD}

Y establecer variables de entorno:

export PRESTO_USER=tu-usuario
export PRESTO_PASSWORD=tu-password-seguro

Monitoreo

Endpoints de salud disponibles:

• /mcp/health - Estado general
• /actuator/health - Spring Boot Actuator
• /actuator/metrics - Métricas del sistema

Cambios de Diseño y Documentación PlantUML

Nuevo Diseño de Paquetes de Servicio

El paquete service ha sido reorganizado en subpaquetes para mejorar la modularidad y el mantenimiento del código. Ahora la estructura es la siguiente:

• service.dispatcher: Lógica de despacho de métodos MCP (McpDispatcherService)
• service.metadata: Manejo y cacheo de metadatos (MetadataCacheService, MetadataCacheTool)
• service.presto: Integración directa con PrestoDB (PrestoService)
• service.query: Procesamiento de lenguaje natural y consultas (QueryIntelligenceService, QueryParser, QueryResultFormatter)
• service.session: Gestión de sesiones (SessionManager)
• service.token: Tokenización y procesamiento de texto (TokenizerService)
• service.tools: Registro y gestión de herramientas MCP (ToolRegistry)

Esto permite una separación clara de responsabilidades y facilita la extensión y el testing de cada módulo.

Arquitectura General

Descripción:

• Actores: El "Cliente MCP" representa cualquier cliente compatible (VSCode, Ollama, etc.) que interactúa con el servidor Polenta mediante JSON-RPC 2.0.
• Componentes: El "Polenta Server" (Spring Boot) es el núcleo de la solución, recibiendo solicitudes y despachando operaciones a los servicios internos.
• Servicios: El componente central es McpDispatcherService, que enruta las operaciones principales (initialize, ping, tools/list, tools/call).
• Backend: El servidor se conecta a PrestoDB (Data Lake) para ejecutar consultas y obtener datos.
• Flujo: El diagrama muestra el flujo de solicitudes desde el cliente, pasando por el servidor y llegando a PrestoDB, con especial énfasis en el despacho de métodos MCP.

Diagrama de Componentes

Descripción:

• Muestra la organización interna del backend, con los subpaquetes de servicio y sus relaciones.
• Los controladores (McpJsonRpcController, McpController) interactúan con los servicios, que a su vez se comunican entre sí según su responsabilidad.
• Se visualizan dependencias clave como el acceso a PrestoDB, la gestión de metadatos, la tokenización y el registro de herramientas.
• Permite entender la modularidad y la separación de responsabilidades en la arquitectura.

Diagrama de Despliegue

Descripción:

• Representa la arquitectura física: usuarios, clientes, el servidor MCP desplegado como artefacto Spring Boot, y el clúster PrestoDB en contenedores.
• Muestra los canales de comunicación (HTTP, JDBC/REST) y los nodos involucrados en la solución.
• Útil para comprender cómo se despliega y conecta cada parte del sistema en un entorno real.

Secuencia de Uso de Herramientas MCP

Descripción:

• Ilustra el flujo de una operación típica de herramientas MCP desde el usuario hasta la obtención del resultado.
• Detalla la interacción entre el cliente, los controladores, el registro de herramientas, el despachador y los servicios de consulta.
• Permite ver cómo se resuelve una solicitud de herramienta, desde la identificación hasta la respuesta final.

Secuencia Detallada de Listado de Tablas

Descripción:

• Muestra paso a paso cómo se procesa una solicitud de listado de tablas.
• Incluye la identificación del tipo de consulta, la obtención de esquemas y tablas desde Presto, y la construcción de la respuesta.
• Participan los servicios de consulta, metadatos y Presto, reflejando la colaboración entre los subpaquetes.

Todos los diagramas reflejan la nueva organización modular y pueden ser visualizados con cualquier visor PlantUML o directamente como imágenes en este README.

Uso y Extensión de Tools MCP

¿Qué es una Tool MCP?

Una "tool" es una herramienta o función expuesta por el servidor Polenta a través del protocolo MCP. Permite a los clientes (VSCode, Ollama, etc.) descubrir y ejecutar operaciones complejas (consultas, obtención de metadatos, etc.) de forma estructurada y autodescriptiva, sin necesidad de conocer detalles internos del backend.

Descubrimiento de Tools (tools/list)

El método tools/list devuelve todas las herramientas disponibles, junto con su descripción, parámetros esperados y ejemplos de uso. Esto permite a los clientes construir interfaces dinámicas y mostrar ayuda contextual.

Ejemplo de request:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list",
  "params": {}
}

Ejemplo de respuesta:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": [
    {
      "name": "query_data",
      "description": "Ejecuta una consulta en lenguaje natural sobre el datalake.",
      "parameters": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "Consulta en lenguaje natural o SQL" }
        },
        "required": ["query"]
      },
      "examples": [
        { "query": "¿Cuántos usuarios hay en la tabla clientes?" }
      ]
    },
    // ...otras tools...
  ]
}

Ejecución de una Tool (tools/call)

Para ejecutar una tool, se usa el método tools/call indicando el nombre y los argumentos requeridos.

Ejemplo de request:

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "query_data",
    "arguments": {
      "query": "Muestra todas las tablas disponibles"
    }
  }
}

Ejemplo de respuesta:

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "columns": ["table_name"],
    "rows": [["clientes"], ["ventas"], ["productos"]],
    "summary": "Se encontraron 3 tablas."
  }
}

Estructura de una Tool

Cada tool tiene:

• name: Nombre único.
• description: Descripción clara de su función.
• parameters: Esquema JSON de los argumentos esperados (tipo, descripción, requeridos).
• examples: Ejemplos de uso para facilitar la integración y la UX.

Cómo agregar una nueva Tool (para desarrolladores)

1. Implementar la interfaz Tool en Java (ver paquete service.tools).
2. Registrar la nueva tool en el ToolRegistry.
3. Documentar bien los parámetros y ejemplos para que los clientes puedan autodescubrirla.
4. (Opcional) Agregar tests en test/service/tools/.

Consejos para clientes MCP

• Usar siempre tools/list para descubrir y mostrar las herramientas disponibles.
• Mostrar la descripción y ejemplos al usuario final para mejorar la experiencia.
• Validar los parámetros antes de llamar a tools/call (el esquema JSON ayuda a construir formularios dinámicos).
• Aprovechar la autodescripción para ofrecer ayuda contextual y autocompletado.