Quarkus MCP Servers

Servidores MCP baseados em Quarkus para interagir com bancos de dados JDBC, sistemas de arquivos e contêineres Docker.

Documentação

Quarkus MCP Servers

Servidores MCP (Model Context Protocol) universais baseados em Quarkus. Suporta bancos de dados JDBC, filesystem, contêineres Docker e muito mais com um único JAR.

🚀 Configuração Rápida

1. Configuração do JDK 17

O projeto requer JDK 17. Use o script automático para baixá-lo e configurá-lo:

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

O script:

Detecta automaticamente a arquitetura (x64, aarch64) e SO (Linux, macOS)
Baixa o JDK 17 do Eclipse Temurin
Configura as variáveis de ambiente JAVA_HOME e PATH
Cria um arquivo de configuração jdk17/jdk-env.sh para reutilizações futuras

Após a instalação, carregue o ambiente JDK:

source jdk17/jdk-env.sh

2. Compilação

Uma vez configurado o JDK 17, compile o projeto:

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

O comando criará os JARs em:

jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar - Servidor JDBC
filesystem/target/mcp-server-filesystem-999-SNAPSHOT.jar - Servidor Filesystem
containers/target/mcp-server-containers-999-SNAPSHOT.jar - Servidor Container
jvminsight/target/mcp-server-jvminsight-999-SNAPSHOT.jar - Servidor JVM Insights

🐳 Uso com Docker

Build da imagem 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 Filesystem

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

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

Outros servidores

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

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

⚙️ Configuração MCP

Geração automática

Gere automaticamente a configuração MCP para Claude Desktop:

./docker-mcp.sh config

Isso cria o arquivo mcp-docker-config.json com configurações para:

Servidor JDBC Oracle
Servidor JDBC H2
Servidor Filesystem
Servidor Container
Servidor JVM Insights

Configuração manual para Claude Desktop

Linux/macOS

Copie o conteúdo do arquivo gerado em:

~/.config/claude/claude_desktop_config.json

Windows

%APPDATA%/Claude/claude_desktop_config.json

Configuração para Docker

Exemplo de configuração 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"
      ]
    }
  }
}

Configuração para Execução Local (sem Docker)

Quando você executa os servidores localmente sem Docker, use esta configuração:

{
  "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 Disponíveis

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

🗄️ Bancos de Dados Suportados

O servidor JDBC suporta todos os bancos de dados com driver 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 (em memória) ou 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 Somente Leitura para Servidor JDBC

O servidor JDBC suporta um modo somente leitura que permite explorar e consultar bancos de dados sem risco de alterações acidentais.

Funcionalidades no Modo Somente Leitura

✅ Operações Permitidas:

read_query - Execução de consultas SELECT
list_tables - Visualização de tabelas
describe_table - Descrição da estrutura das tabelas
database_info - Informações do banco de dados (inclui estado somente leitura)

❌ Operações Bloqueadas:

write_query - INSERT, UPDATE, DELETE
create_table - Criação de tabelas

Como Ativar o Modo Somente Leitura

Docker:

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

Execução 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

Verificação do Estado Somente Leitura

Use a ferramenta database_info para verificar o estado:

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

Nota: mcp_server_readonly_mode indica o modo do servidor MCP, enquanto read_only indica se o próprio banco de dados está em somente leitura.

🔧 Execução Local (sem 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 Filesystem

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

🔍 Testes

Teste do 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

Teste Docker

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

📁 Estrutura do Projeto

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

🚨 Solução de Problemas

JDK 17 não encontrado

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

# Carica ambiente
source jdk17/jdk-env.sh

# Verifica versione
java -version

Imagem Docker não encontrada

# Rebuilda immagine
./docker-mcp.sh build

Erros de conexão com o banco de dados

Verifique se o banco de dados está em execução
Verifique URL, usuário e senha
Para Oracle, certifique-se de que esteja em localhost:1521

Problemas com 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

📚 Documentação Adicional

README Docker - Guia completo do Docker
README Italiano - Documentação em italiano
Standalone Java Setup - Configuração Java standalone

🤝 Contribuições

Fork do repositório
Crie um branch de feature (git checkout -b feature/amazing-feature)
Faça commit das alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

📝 Licença

Este projeto está sob licença MIT. Veja o arquivo LICENSE para detalhes.