Trino MCP Server

Uma implementação em Go de um servidor Model Context Protocol (MCP) para Trino, permitindo que modelos LLM consultem bancos de dados SQL distribuídos por meio de ferramentas padronizadas.

GitHub

121

Experimente este MCPPatrocinado

Documentação

Servidor MCP Trino em Go

Um servidor de Model Context Protocol (MCP) de alto desempenho para Trino implementado em Go. Este projeto permite que assistentes de IA interajam perfeitamente com o mecanismo de consulta SQL distribuído do Trino por meio de ferramentas MCP padronizadas.

Visão Geral

Este projeto implementa um servidor de Model Context Protocol (MCP) para Trino em Go. Ele permite que assistentes de IA acessem o mecanismo de consulta SQL distribuído do Trino por meio de ferramentas MCP padronizadas.

Trino (anteriormente PrestoSQL) é um poderoso mecanismo de consulta SQL distribuído projetado para análises rápidas em grandes conjuntos de dados.

Arquitetura

graph TB
    subgraph "AI Clients"
        CC[Claude Code]
        CD[Claude Desktop]
        CR[Cursor]
        WS[Windsurf]
        CW[ChatWise]
    end
    
    subgraph "Authentication (Optional)"
        OP[OAuth Provider<br/>Okta/Google/Azure AD]
        JWT[JWT Tokens]
    end
    
    subgraph "MCP Server (mcp-trino)"
        HTTP[HTTP Transport<br/>/mcp endpoint]
        STDIO[STDIO Transport]
        AUTH[OAuth Middleware]
        TOOLS[MCP Tools<br/>• execute_query<br/>• list_catalogs<br/>• list_schemas<br/>• list_tables<br/>• get_table_schema<br/>• explain_query]
    end
    
    subgraph "Data Layer"
        TRINO[Trino Cluster<br/>Distributed SQL Engine]
        CATALOGS[Data Sources<br/>• PostgreSQL<br/>• MySQL<br/>• S3/Hive<br/>• BigQuery<br/>• MongoDB]
    end
    
    %% Connections
    CC -.->|OAuth Flow| OP
    OP -.->|JWT Token| JWT
    
    CC -->|HTTP + JWT| HTTP
    CD -->|STDIO| STDIO
    CR -->|HTTP + JWT| HTTP
    WS -->|STDIO| STDIO
    CW -->|HTTP + JWT| HTTP
    
    HTTP --> AUTH
    AUTH -->|Validated| TOOLS
    STDIO --> TOOLS
    
    TOOLS -->|SQL Queries| TRINO
    TRINO --> CATALOGS
    
    %% Styling
    classDef client fill:#e1f5fe
    classDef auth fill:#f3e5f5
    classDef server fill:#e8f5e8
    classDef data fill:#fff3e0
    
    class CC,CD,CR,WS,CW client
    class OP,JWT auth
    class HTTP,STDIO,AUTH,TOOLS server
    class TRINO,CATALOGS data

Componentes Principais:

Clientes de IA: Vários aplicativos compatíveis com MCP
Autenticação: OAuth 2.0 opcional com provedores OIDC
Servidor MCP: Servidor baseado em Go com suporte a transporte duplo
Modo CLI: Shell SQL interativo para acesso direto ao Trino (semelhante ao psql)
Camada de Dados: Cluster Trino conectando-se a múltiplas fontes de dados

Recursos

✅ Modo Duplo: Funciona tanto como servidor MCP QUANTO como CLI interativo
- Modo CLI: Shell SQL interativo semelhante ao psql para acesso direto ao Trino
- Modo MCP: Servidor MCP completo para integração com assistentes de IA
✅ Implementação de servidor MCP em Go
✅ Execução de consultas SQL do Trino por meio de ferramentas MCP
✅ Descoberta de catálogos, schemas e tabelas
✅ Suporte a contêineres Docker
✅ Suporte aos transportes STDIO e HTTP
✅ Autenticação OAuth 2.1 via biblioteca oauth-mcp-proxy
- 4 Provedores: HMAC, Okta, Google, Azure AD
- Modo nativo: O cliente lida com OAuth diretamente (zero segredos no lado do servidor)
- Modo proxy: O servidor faz proxy do fluxo OAuth para clientes simples
- Pronto para produção: Cache de tokens, PKCE, segurança em profundidade
- Reutilizável: Biblioteca OAuth disponível para qualquer servidor MCP em Go
✅ Suporte a StreamableHTTP com autenticação JWT (atualizado de SSE)
✅ Compatibilidade retroativa com endpoints SSE
✅ Compatível com Cursor, Claude Desktop, Windsurf, ChatWise e qualquer cliente compatível com MCP.
✅ Rastreamento de Identidade do Usuário:
- Atribuição de Consultas (automática): Marca consultas com o usuário OAuth via cabeçalhos X-Trino-Client-Tags/Info
- Personificação de Usuário (opt-in): Executa consultas como usuário OAuth via cabeçalho X-Trino-User

Instalação e Início Rápido

Instalação:

# Homebrew
brew install tuannvm/mcp/mcp-trino

# Or one-liner (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/tuannvm/mcp-trino/main/install.sh | bash

Execução (Desenvolvimento Local):

export TRINO_HOST=localhost TRINO_USER=trino
mcp-trino

Para implantação em produção com OAuth, consulte Guia de Implantação e Arquitetura OAuth.

Modo CLI

mcp-trino pode ser usado como um CLI interativo semelhante ao psql ou ao CLI do Trino:

# Interactive REPL mode
mcp-trino --interactive

# Execute a query directly
mcp-trino query "SELECT * FROM my_table LIMIT 10"

# List catalogs, schemas, tables
mcp-trino catalogs
mcp-trino schemas my_catalog
mcp-trino tables my_catalog my_schema

# Describe a table
mcp-trino describe my_catalog.my_schema.my_table

# Explain a query
mcp-trino explain "SELECT COUNT(*) FROM my_table"

# Output formats
mcp-trino --format json query "SELECT 1"
mcp-trino --format csv query "SELECT 1"
mcp-trino --format table query "SELECT 1"  # default

Ajuda Integrada

Todo comando possui saída de ajuda estruturada e amigável para LLM:

# Main help with all commands, flags, examples, and environment variables
mcp-trino --help

# Per-subcommand help
mcp-trino query --help
mcp-trino describe --help

A saída de ajuda segue as convenções de páginas de manual do Unix com seções: NAME, SYNOPSIS, DESCRIPTION, COMMANDS, FLAGS, EXAMPLES, ENVIRONMENT e CONFIGURATION.

Códigos de Saída

Código	Significado
0	Sucesso
1	Erro de execução (falha de conexão, erro de consulta, etc.)
2	Erro de uso (comando desconhecido, flags inválidas, argumentos ausentes)

Perfis Nomeados

mcp-trino suporta perfis de conexão nomeados para facilitar a alternância entre ambientes Trino.

Arquivo de Configuração — suporta tanto YAML (~/.config/trino/config.yaml) quanto JSON (~/.config/trino/config.json):

# ~/.config/trino/config.yaml
current: prod

profiles:
  prod:
    host: trino.example.com
    port: 443
    user: prod_user
    password: prod_password
    catalog: hive
    schema: analytics
    ssl:
      enabled: true
      insecure: false

  dev:
    host: localhost
    port: 8080
    user: trino
    catalog: memory
    schema: default

  staging:
    host: staging-trino.example.com
    port: 443
    user: staging_user

output:
  format: table

Ou equivalentemente em JSON:

{
  "current": "prod",
  "profiles": {
    "prod": {
      "host": "trino.example.com",
      "port": 443,
      "user": "prod_user",
      "catalog": "hive",
      "ssl": { "enabled": true }
    },
    "dev": {
      "host": "localhost",
      "port": 8080,
      "user": "trino"
    }
  },
  "output": { "format": "table" }
}

Quando ambos os arquivos existem, config.json tem precedência. Novas configurações usam JSON por padrão.

Comandos de Gerenciamento de Perfis:

# List all profiles
mcp-trino config profile list

# Set default profile
mcp-trino config profile use prod

# Show profile details
mcp-trino config profile show staging

# Use a specific profile (overrides config file)
mcp-trino --profile dev catalogs

Precedência de Configuração (da maior para a menor):

Flags de CLI (--host, --port, etc.)
Flag --profile
Variável de ambiente TRINO_PROFILE
Campo current no arquivo de configuração
Fallback do perfil default
Variáveis de ambiente (TRINO_HOST, etc.)

Variáveis de Ambiente (prioridade mais baixa — sobrescritas por perfis e flags):

export TRINO_HOST=trino.example.com
export TRINO_PORT=443
export TRINO_USER=myuser
export TRINO_PASSWORD=mypass
export TRINO_CATALOG=hive
export TRINO_SCHEMA=analytics
export TRINO_SSL=true

Gerenciamento de Segredos (recomendado):

Os segredos são carregados puramente de variáveis de ambiente. Use um CLI de segredos para injetá-los via pipe Unix no momento da inicialização — o aplicativo nunca toca no seu cofre:

# 1Password CLI — resolves op:// references in an env file
op run --env-file=.env -- mcp-trino

# Or inline per-variable
TRINO_PASSWORD=$(op read 'op://Engineering/Trino/password') mcp-trino

Consulte docs/secrets.md para padrões com 1Password, Vault e Kubernetes, e para nuances de segurança (histórico de shell, lista de processos e vazamento de variáveis de ambiente).

Meta-Comandos do REPL (no modo interativo):

\help - Mostrar ajuda
\quit, \exit, \q - Sair do REPL
\history - Mostrar histórico de comandos
\catalogs - Listar todos os catálogos
\schemas [catalog] - Listar schemas
\tables [catalog schema] - Listar tabelas
\describe <table> - Descrever tabela
\format <table|json|csv> - Alterar formato de saída

Uso

Clientes Suportados: Claude Desktop, Claude Code, Cursor, Windsurf, ChatWise

Ferramentas Disponíveis: execute_query, list_catalogs, list_schemas, list_tables, get_table_schema, explain_query

Para integração com clientes e documentação de ferramentas, consulte Guia de Integração e Referência de Ferramentas.

Configuração

Variáveis Principais: TRINO_HOST, TRINO_USER, TRINO_SCHEME, MCP_TRANSPORT, OAUTH_PROVIDER

Gerenciamento de Segredos: Injete segredos por meio do ambiente do processo — mcp-trino os lê diretamente. Consulte docs/secrets.md para receitas com 1Password, Vault e Kubernetes.

# 1Password (biometric-gated, zero disk writes)
op run --env-file=.env -- mcp-trino

# Vault (via vault-agent or CLI)
TRINO_PASSWORD=$(vault kv get -field=password secret/mcp-trino) mcp-trino

# Kubernetes: use standard Secret → envFrom in the Helm chart values

Configuração OAuth:

# Native mode (most secure - zero server-side secrets)
export OAUTH_ENABLED=true OAUTH_MODE=native OAUTH_PROVIDER=okta
export OIDC_ISSUER=https://company.okta.com OIDC_AUDIENCE=https://mcp-server.com

# Proxy mode (centralized credential management)
export OAUTH_MODE=proxy OIDC_CLIENT_ID=app-id OIDC_CLIENT_SECRET=secret
export OAUTH_REDIRECT_URI=https://mcp-server.com/oauth/callback  # Fixed mode (localhost-only)
export OAUTH_REDIRECT_URI=https://app1.com/cb,https://app2.com/cb  # Allowlist mode
export JWT_SECRET=$(openssl rand -hex 32)  # Required for multi-pod deployments

Otimização de Desempenho:

# Focus AI on specific schemas only (10-20x performance improvement)
export TRINO_ALLOWED_SCHEMAS="hive.analytics,hive.marts,hive.reporting"

Rastreamento de Identidade do Usuário:

# Query Attribution is AUTOMATIC when OAuth is enabled
# Queries are tagged with X-Trino-Client-Tags and X-Trino-Client-Info headers

# For full impersonation (Trino enforces user permissions):
export TRINO_ENABLE_IMPERSONATION=true
export TRINO_IMPERSONATION_FIELD=email  # Options: username, email, subject

Para configuração completa, consulte Guia de Implantação, Guia OAuth, Guia de Listas de Permissão e Guia de Identidade do Usuário.

Implementação OAuth

mcp-trino usa oauth-mcp-proxy — uma biblioteca OAuth 2.1 independente para servidores MCP em Go.

Por que uma biblioteca separada?

✅ Reutilizável em qualquer servidor MCP em Go
✅ Testes e versionamento independentes
✅ Documentação e exemplos dedicados
✅ Implementação OAuth mantida pela comunidade

Para detalhes sobre OAuth:

Documentação do oauth-mcp-proxy - Guia OAuth completo
Guias de Configuração de Provedores - Okta, Google, Azure AD
Melhores Práticas de Segurança - Segurança em produção

Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Este projeto é licenciado sob a Licença MIT — consulte o arquivo LICENSE para detalhes.

Projetos Relacionados

oauth-mcp-proxy — Biblioteca de autenticação OAuth 2.1 usada pelo mcp-trino (reutilizável para qualquer servidor MCP em Go)

CI/CD e Lançamentos

Este projeto usa GitHub Actions para integração contínua e GoReleaser para lançamentos automatizados.

Verificações de Integração Contínua

Nosso pipeline de CI executa as seguintes verificações em todos os PRs e commits para o branch principal:

Qualidade de Código

Linting: Usando golangci-lint para verificar problemas comuns de código e violações de estilo
Verificação de Módulos Go: Garantindo que go.mod e go.sum sejam mantidos adequadamente
Formatação: Verificando se o código está formatado corretamente com gofmt

Segurança

Varredura de Vulnerabilidades: Usando govulncheck para verificar vulnerabilidades conhecidas em dependências
Varredura de Dependências: Usando Trivy para verificar vulnerabilidades em dependências (CRITICAL, HIGH e MEDIUM)
Geração de SBOM: Criando uma Lista de Materiais de Software para rastreamento de dependências
Proveniência SLSA: Criando proveniência de build verificável para segurança da cadeia de suprimentos

Testes

Testes Unitários: Executando testes com detecção de corrida e relatório de cobertura de código
Verificação de Build: Garantindo que o código seja compilado com sucesso

Segurança de CI/CD

Menor Privilégio: Workflows executam com as permissões mínimas necessárias
Versões Fixadas: Todas as GitHub Actions usam versões específicas para prevenir ataques à cadeia de suprimentos
Atualizações de Dependências: Atualizações automatizadas de dependências via Dependabot

Processo de Lançamento

Quando alterações são mescladas ao branch principal:

As verificações de CI são executadas para validar qualidade e segurança do código
Se bem-sucedidas, um novo lançamento é criado automaticamente com:
- Versionamento semântico baseado em mensagens de commit
- Builds binários para múltiplas plataformas
- Publicação de imagem Docker no GitHub Container Registry
- Atestado de SBOM e proveniência