Apresentação Detalhada do Projeto Apache Doris MCP Server

Visão Geral do Projeto

O Apache Doris MCP (Model Context Protocol) Server é um serviço de backend construído em Python e FastAPI, projetado para integrar-se perfeitamente com o banco de dados Apache Doris através do protocolo de contexto de modelo (MCP). Ele fornece interfaces padronizadas para agentes de IA e clientes, suportando funcionalidades como Natural Language to SQL (NL2SQL), execução de consultas SQL, gerenciamento de metadados e análise de dados. Este projeto é uma extensão importante da comunidade Apache Doris, especialmente adequado para cenários de negócios que exigem interação de dados eficiente e análise inteligente.

Desde o lançamento da versão 0.3.0 em 2025, o projeto passou por uma grande atualização de arquitetura, migrando da comunicação baseada em SSE (Server-Sent Events) para um protocolo HTTP Streamable unificado, e adicionou um framework de segurança de nível empresarial e funcionalidades de otimização de desempenho. O objetivo principal do projeto é conectar sistemas de IA com o banco de dados Apache Doris através do protocolo MCP, permitindo a exploração e análise de dados inteligentes.

Funcionalidades Principais

O Apache Doris MCP Server oferece as seguintes funcionalidades principais:

1. Natural Language to SQL (NL2SQL)

   • Suporta a geração de consultas SQL através de entrada em linguagem natural, combinando com modelos de linguagem grandes (LLMs) para gerar consultas inteligentes.
   • Adequado para cenários onde usuários de negócios podem consultar dados sem precisar escrever SQL complexo.

2. Execução de Consultas SQL

   • Suporta a execução direta de comandos SQL através da ferramenta exec_query, com opções para personalizar a seleção do banco de dados, limite de linhas e configurações de timeout.
   • Incorpora verificações de segurança (como proteção contra injeção de SQL) e adição automática de LIMIT, garantindo a segurança e eficiência da consulta.

3. Gerenciamento de Metadados

   • Fornece ferramentas ricas para extração de metadados, incluindo:
     • Listar todos os bancos de dados e tabelas (get_all_databases, get_database_tables).
     • Obter a estrutura da tabela, comentários e informações de índice (get_table_schema, get_table_comment, get_column_comments, get_table_indexes).
     • Suporte para descoberta de múltiplos catálogos (get_catalog_list).

4. Consulta de Logs de Auditoria

   • Obter os registros de auditoria mais recentes através de get_recent_audit_logs, com suporte para intervalos de tempo e limites de registro personalizados.

5. Framework de Segurança de Nível Empresarial

   • Suporta múltiplos métodos de autenticação (Token, Basic Auth, OAuth).
   • Controle de acesso baseado em papéis (RBAC), fornecendo quatro níveis de segurança.
   • Incorpora proteção contra injeção de SQL, validação de consultas e funcionalidades de mascaramento de dados.

6. Otimização de Desempenho

   • Otimização da execução de consultas, melhorando o desempenho através de mecanismos de cache aprimorados e gerenciamento de pool de conexões.
   • Suporte para monitoramento de desempenho e análise estatística (performance_stats).

7. Múltiplos Modos de Comunicação

   • Streamable HTTP: Suporta solicitação/resposta e transmissão em fluxo através de um endpoint /mcp unificado (src/streamable_server.py).
   • SSE (Descontinuado): Versões anteriores suportavam comunicação através dos endpoints /sse e /mcp/messages (src/sse_server.py).
   • Stdio (Opcional): Interação através de entrada/saída padrão (src/stdio_server.py).

8. Funcionalidades Experimentais

   • Análise estatística de colunas (column_analysis), fornecendo insights de dados.
   • Suporte para federação de catálogos, adequado para ambientes multi-catálogo.

Arquitetura Técnica

A arquitetura do projeto é modular e eficiente, incluindo os seguintes componentes principais:

• Framework Principal: Construído em Python 3.12 e FastAPI, fornecendo um serviço de API de alto desempenho.
• Implementação do Protocolo MCP:
  • Fornece interfaces padronizadas para chamadas de ferramentas, gerenciamento de recursos e interação de prompts.
  • Processa todas as solicitações através de um endpoint /mcp unificado, simplificando a integração.
• Interação com o Banco de Dados:
  • doris_mcp_server/utils/db.py: Fornece conexão com o banco de dados (get_db_connection) e funcionalidades de execução de consultas (execute_query, execute_query_df).
  • doris_mcp_server/utils/schema_extractor.py: A classe MetadataExtractor é responsável pela extração de metadados, incluindo mecanismos de cache.
  • doris_mcp_server/utils/sql_executor_tools.py: A função execute_sql_query encapsula a lógica de consulta, incluindo verificações de segurança e serialização de resultados.
• Gerenciamento de Segurança:
  • Suporta múltiplos métodos de autenticação e RBAC.
  • Fornece proteção contra injeção de SQL, validação de consultas e registro de logs de auditoria.
• Suporte à Implantação:
  • Implantação em imagem Docker, configuração de porta unificada (3000, 3001, 3002).
  • Configuração de variáveis de ambiente (como DB_HOST, DB_PORT, DB_USER, DB_PASSWORD).

Mudanças na Arquitetura: A versão 0.3.0 removeu cerca de 300 linhas de código legado do SSE, migrando para HTTP Streamable, unificou a nomenclatura das ferramentas (removendo o prefixo mcp_doris_), e aumentou o nível de modularização.

Instalação e Uso

Requisitos de Ambiente

• Python 3.12 ou superior
• Banco de dados Apache Doris (conectado via protocolo MySQL)
• Ferramenta de gerenciamento de pacotes (como uv ou pip)
• Opcional: Docker (para implantação em contêiner)

Passos de Instalação

1. Clonar o Repositório:

   git clone https://github.com/apache/doris-mcp-server.git
   cd doris-mcp-server
   

2. Instalar Dependências: Use uv (recomendado) ou pip para instalar:

   uv sync
   

   Ou

   pip install -r requirements.txt
   

3. Configurar Variáveis de Ambiente: Crie um arquivo .env ou defina as variáveis de ambiente diretamente:

   export DORIS_HOST=<doris-host>
   export DORIS_PORT=<port>
   export DORIS_USER=<doris-user>
   export DORIS_PASSWORD=<doris-pwd>
   export SERVER_PORT=3000
   

4. Iniciar o Servidor:

   uv run --with mcp-doris --python 3.13 mcp-doris
   

   Ou

   python -m mcp_doris.mcp_server
   

5. Verificar a Inicialização: Após a inicialização bem-sucedida, você pode interagir através de um cliente MCP (como Cursor) ou do navegador MCP integrado (http://localhost:5173).

Testar a Conexão

Execute o script de teste para verificar a conexão com o banco de dados:

python src/doris-mcp-server/test.py

Saída esperada:

🚀 Doris MCP Server is starting...
[DorisConnector] Connected to 127.0.0.1:9030
✅ Database connection successful.
[DorisConnector] Connection closed.

Cenários de Aplicação

1. Análise de Dados em Tempo Real

   • Combinando a funcionalidade NL2SQL, os usuários de negócios podem consultar dados em tempo real através de linguagem natural, gerando relatórios ou dashboards.
   • Adequado para suporte à decisão em tempo real em setores como varejo, finanças e telecomunicações.

2. Exploração de Metadados

   • Engenheiros de dados podem obter rapidamente o schema do banco de dados, a estrutura da tabela e informações de índice, acelerando a modelagem e otimização de dados.

3. Inteligência de Negócios Impulsionada por IA

   • Integrar agentes de IA (como Claude, Cursor), implementando fluxos de trabalho automatizados de consulta e análise de dados através do protocolo MCP.

4. Gerenciamento de Conformidade e Segurança

   • O framework de segurança de nível empresarial e as funcionalidades de log de auditoria atendem aos requisitos de segurança e conformidade de dados em setores como finanças e saúde.

5. Ambientes Multi-Catálogo

   • Suporte para federação de múltiplos catálogos, adequado para gerenciamento de metadados e consultas em ambientes complexos de data warehouse.

Vantagens e Limitações do Projeto

Vantagens

• Inteligência: A integração NL2SQL e LLM reduz a barreira para consulta de dados.
• Segurança: Múltiplos métodos de autenticação, RBAC e proteção SQL garantem segurança de nível empresarial.
• Alto Desempenho: Cache, pool de conexões e otimização de consultas aumentam a eficiência.
• Flexibilidade: Suporte para múltiplos modos de comunicação e extensão de ferramentas modulares.

Limitações

• Estabilidade em Versões Iniciais: Algumas funcionalidades (como column_analysis) são experimentais e podem conter bugs.
• Dependência do Banco de Dados Doris: Projetado principalmente para Apache Doris, a compatibilidade com outros bancos de dados de protocolo MySQL é limitada.
• Descontinuação do SSE: A versão 0.3.0 removeu o suporte para SSE, exigindo a migração para HTTP Streamable.

Conclusão

O Apache Doris MCP Server é uma ferramenta poderosa e flexível que conecta o banco de dados Apache Doris com as necessidades de análise impulsionadas por IA. Suas características como NL2SQL, gerenciamento de metadados, segurança e otimização de desempenho o tornam um projeto com amplo potencial em análise de dados em tempo real, inteligência de negócios e aplicações de nível empresarial.