Quarkus MCP Servers

Servidores MCP basados en Quarkus para interactuar con bases de datos JDBC, sistemas de archivos y contenedores Docker.

Documentación

Servidores MCP de Quarkus

Servidores MCP (Protocolo de Contexto de Modelo) universales basados en Quarkus. Soporta bases de datos JDBC, sistemas de archivos, contenedores Docker y mucho más con un único JAR.

🚀 Configuración Rápida

1. Configuración de JDK 17

El proyecto requiere JDK 17. Usa el script automático para descargarlo y configurarlo:

# Setup automatico JDK 17
./setup-jdk17.sh

El script:

Detecta automáticamente la arquitectura (x64, aarch64) y el sistema operativo (Linux, macOS)
Descarga JDK 17 desde Eclipse Temurin
Configura las variables de entorno JAVA_HOME y PATH
Crea un archivo de configuración jdk17/jdk-env.sh para usos futuros

Después de la instalación, carga el entorno JDK:

source jdk17/jdk-env.sh

2. Compilación

Una vez configurado JDK 17, compila el proyecto:

# Compila tutti i moduli (senza test per velocità)
./build-no-tests.sh

El comando creará los JAR en:

jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar - Servidor JDBC
filesystem/target/mcp-server-filesystem-999-SNAPSHOT.jar - Servidor de Sistema de Archivos
containers/target/mcp-server-containers-999-SNAPSHOT.jar - Servidor de Contenedores
jvminsight/target/mcp-server-jvminsight-999-SNAPSHOT.jar - Servidor de Información de JVM

🐳 Uso con Docker

Crear imagen Docker

# Builda l'immagine Docker con tutti i server
./docker-mcp.sh build

Servidor JDBC

# Oracle (richiede Oracle su localhost:1521)
./docker-mcp.sh oracle

# Oracle in modalità read-only (solo lettura)
./docker-mcp.sh run jdbc --jdbc.url="jdbc:oracle:thin:@localhost:1521:xe" --jdbc.user="ORACLEUSR" --jdbc.password="ORACLEUSR" --jdbc.readonly=true

# H2 in memoria
./docker-mcp.sh h2

# Server JDBC generico
./docker-mcp.sh run jdbc --jdbc.url="jdbc:postgresql://localhost:5432/mydb" --jdbc.user="user" --jdbc.password="pass"

# MySQL in modalità read-only
./docker-mcp.sh run jdbc --jdbc.url="jdbc:mysql://localhost:3306/mydb" --jdbc.user="root" --jdbc.password="toor" --jdbc.readonly=true

# PostgreSQL in modalità read-only
./docker-mcp.sh run jdbc --jdbc.url="jdbc:postgresql://localhost:5432/mydb" --jdbc.user="postgres" --jdbc.password="postgres" --jdbc.readonly=true

# Server JDBC in modalità read-only
./docker-mcp.sh run jdbc --jdbc.url="jdbc:postgresql://localhost:5432/mydb" --jdbc.user="user" --jdbc.password="pass" --jdbc.readonly=true

Servidor de Sistema de Archivos

# Monta /tmp come directory condivisa
./docker-mcp.sh filesystem /tmp

# Directory personalizzata
./docker-mcp.sh filesystem /path/to/directory

Otros servidores

# Container Docker
./docker-mcp.sh run containers

# JVM Insights
./docker-mcp.sh run jvminsight

⚙️ Configuración de MCP

Generación automática

Genera automáticamente la configuración de MCP para Claude Desktop:

./docker-mcp.sh config

Esto crea el archivo mcp-docker-config.json con configuraciones para:

Servidor JDBC Oracle
Servidor JDBC H2
Servidor de Sistema de Archivos
Servidor de Contenedores
Servidor de Información de JVM

Configuración manual para Claude Desktop

Linux/macOS

Copia el contenido del archivo generado en:

~/.config/claude/claude_desktop_config.json

Windows

%APPDATA%/Claude/claude_desktop_config.json

Configuración para Docker

Ejemplo de configuración Docker:

{
  "mcpServers": {
    "jdbc-oracle-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network", "host",
        "mcp-servers:latest", "jdbc",
        "--jdbc.url=jdbc:oracle:thin:@localhost:1521:xe",
        "--jdbc.user=ORACLEUSR",
        "--jdbc.password=ORACLEUSR",
        "--jdbc.readonly=false"
      ]
    },
    "jdbc-oracle-readonly": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network", "host",
        "mcp-servers:latest", "jdbc",
        "--jdbc.url=jdbc:oracle:thin:@localhost:1521:xe",
        "--jdbc.user=ORACLEUSR",
        "--jdbc.password=ORACLEUSR",
        "--jdbc.readonly=true"
      ]
    },
    "jdbc-h2-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-p", "3000:3000",
        "mcp-servers:latest", "jdbc",
        "--jdbc.url=jdbc:h2:mem:testdb",
        "--jdbc.user=sa",
        "--jdbc.password=",
        "--jdbc.readonly=false"
      ]
    },
    "jdbc-mysql-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network",
        "host",
        "mcp-servers:latest",
        "jdbc",
        "--jdbc.url=jdbc:mysql://localhost:3306/mydb",
        "--jdbc.user=root",
        "--jdbc.password=toor",
        "--jdbc.readonly=true"
      ]
    },
    "jdbc-postgres-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network",
        "host",
        "mcp-servers:latest",
        "jdbc",
        "--jdbc.url=jdbc:postgresql://localhost:5432/mydb",
        "--jdbc.user=postgres",
        "--jdbc.password=postgres",
        "--jdbc.readonly=true"
      ]
    },
    "filesystem-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-v", "/tmp:/mnt/shared",
        "mcp-servers:latest", "filesystem", "/mnt/shared"
      ]
    }
  }
}

Configuración para Ejecución Local (sin Docker)

Cuando ejecutes los servidores localmente sin Docker, usa esta configuración:

{
  "mcp": {
    "servers": {
      "jdbc-oracle": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:oracle:thin:@localhost:1521:xe",
          "--jdbc.user=ORACLEUSR",
          "--jdbc.password=ORACLEUSR",
          "--jdbc.readonly=false"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "jdbc-oracle-readonly": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:oracle:thin:@localhost:1521:xe",
          "--jdbc.user=ORACLEUSR",
          "--jdbc.password=ORACLEUSR",
          "--jdbc.readonly=true"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "jdbc-h2": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:h2:mem:testdb",
          "--jdbc.user=sa",
          "--jdbc.password=",
          "--jdbc.readonly=false"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "jdbc-mysql": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:mysql://localhost:3306/mydb",
          "--jdbc.user=root",
          "--jdbc.password=toor",
          "--jdbc.readonly=true"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "jdbc-postgres": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:postgresql://localhost:5432/mydb",
          "--jdbc.user=postgres",
          "--jdbc.password=postgres",
          "--jdbc.readonly=true"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "filesystem-local": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/filesystem/target/mcp-server-filesystem-999-SNAPSHOT.jar",
          "/tmp"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/filesystem"
      },
      "containers-local": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/containers/target/mcp-server-containers-999-SNAPSHOT.jar"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/containers"
      }
    }
  }
}

📋 Comandos Disponibles

setup-jdk17.sh

./setup-jdk17.sh              # Setup automatico JDK 17
./setup-jdk17.sh --help       # Mostra opzioni disponibili
./setup-jdk17.sh --force      # Forza reinstallazione anche se esiste

docker-mcp.sh

./docker-mcp.sh build         # Builda immagine Docker
./docker-mcp.sh oracle        # Server JDBC Oracle
./docker-mcp.sh h2            # Server JDBC H2
./docker-mcp.sh filesystem [path]  # Server Filesystem
./docker-mcp.sh config        # Genera configurazione MCP
./docker-mcp.sh help          # Mostra aiuto

🗄️ Bases de Datos Soportadas

El servidor JDBC soporta todas las bases de datos con controlador JDBC:

Oracle - jdbc:oracle:thin:@host:port:sid
PostgreSQL - jdbc:postgresql://host:port/database
MySQL - jdbc:mysql://host:port/database
H2 - jdbc:h2:mem:testdb (en memoria) o jdbc:h2:file:/path/to/db
SQLite - jdbc:sqlite:/path/to/database.db
SQL Server - jdbc:sqlserver://host:port;databaseName=db
MariaDB - jdbc:mariadb://host:port/database

🔒 Modo de Solo Lectura para Servidor JDBC

El servidor JDBC soporta un modo de solo lectura que permite explorar y consultar bases de datos sin riesgo de modificaciones accidentales.

Funcionalidades en Modo de Solo Lectura

✅ Operaciones Permitidas:

read_query - Ejecución de consultas SELECT
list_tables - Visualización de tablas
describe_table - Descripción de estructura de tablas
database_info - Información de la base de datos (incluye estado de solo lectura)

❌ Operaciones Bloqueadas:

write_query - INSERT, UPDATE, DELETE
create_table - Creación de tablas

Cómo Activar el Modo de Solo Lectura

Docker:

./docker-mcp.sh run jdbc \
  --jdbc.url="jdbc:oracle:thin:@localhost:1521:xe" \
  --jdbc.user="ORACLEUSR" \
  --jdbc.password="ORACLEUSR" \
  --jdbc.readonly=true

Ejecución Local:

java -jar jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar \
  --jdbc.url="jdbc:h2:mem:testdb" \
  --jdbc.user="sa" \
  --jdbc.password="" \
  --jdbc.readonly=true

Verificación del Estado de Solo Lectura

Usa la herramienta database_info para verificar el estado:

{
  "database_product_name": "Oracle",
  "mcp_server_readonly_mode": "true",
  "read_only": "false",
  ...
}

Nota: mcp_server_readonly_mode indica el modo del servidor MCP, mientras que read_only indica si la base de datos en sí está en solo lectura.

🔧 Ejecución Local (sin Docker)

Servidor JDBC

source jdk17/jdk-env.sh

# Modalità standard (read/write)
java -jar jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar \
  --jdbc.url="jdbc:h2:mem:testdb" \
  --jdbc.user="sa" \
  --jdbc.password="" \
  --jdbc.readonly=false

# Modalità read-only (solo lettura)
java -jar jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar \
  --jdbc.url="jdbc:h2:mem:testdb" \
  --jdbc.user="sa" \
  --jdbc.password="" \
  --jdbc.readonly=true

Servidor de Sistema de Archivos

source jdk17/jdk-env.sh
java -jar filesystem/target/mcp-server-filesystem-999-SNAPSHOT.jar /tmp

🔍 Pruebas

Probar servidor local

# Test JDBC H2
./run-server.sh jdbc --jdbc.url="jdbc:h2:mem:testdb" --jdbc.user="sa"

# Test Filesystem
./run-server.sh filesystem /tmp

Probar Docker

# Test setup Docker
./test-docker-setup.sh

📁 Estructura del Proyecto

quarkus-mcp-servers/
├── setup-jdk17.sh          # Setup automatico JDK 17
├── docker-mcp.sh           # Script Docker per MCP
├── build-no-tests.sh       # Build senza test
├── run-server.sh           # Esecuzione server locale
├── jdbc/                   # Server JDBC
├── filesystem/             # Server Filesystem  
├── containers/             # Server Container Docker
├── jvminsight/            # Server JVM Insights
├── jdk17/                 # JDK 17 (creato da setup)
├── mcp-configs/           # Configurazioni MCP
└── mcp-docker-config.json # Config generata per Docker

🚨 Solución de Problemas

JDK 17 no encontrado

# Reinstalla JDK 17
./setup-jdk17.sh --force

# Carica ambiente
source jdk17/jdk-env.sh

# Verifica versione
java -version

Imagen Docker no encontrada

# Rebuilda immagine
./docker-mcp.sh build

Errores de conexión a la base de datos

Verifica que la base de datos esté en ejecución
Comprueba URL, nombre de usuario y contraseña
Para Oracle, asegúrate de que esté en localhost:1521

Problemas con Docker Desktop

# Su Linux, assicurati che Docker sia in esecuzione
sudo systemctl start docker

# Aggiungi utente al gruppo docker
sudo usermod -aG docker $USER
# Poi fai logout/login

📚 Documentación Adicional

README Docker - Guía completa de Docker
README Italiano - Documentación en italiano
Configuración Java Independiente - Configuración Java independiente

🤝 Contribuciones

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/amazing-feature)
Haz commit de los cambios (git commit -m 'Add amazing feature')
Haz push a la rama (git push origin feature/amazing-feature)
Abre una Solicitud de Extracción

📝 Licencia

Este proyecto está bajo licencia MIT. Consulta el archivo LICENCIA para más detalles.