MCP Iceberg Catalog

MCP Iceberg Catalog

Uma implementação de servidor MCP (Model Context Protocol) para interagir com Apache Iceberg. Este servidor fornece uma interface SQL para consultar e gerenciar tabelas Iceberg através do Claude desktop.

Claude Desktop como seu Catálogo de Data Lake Iceberg

Como Instalar no Claude Desktop

Instalando via Smithery

Para instalar o MCP Iceberg Catalog para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @ahodroj/mcp-iceberg-service --client claude

1. Pré-requisitos

   • Python 3.10 ou superior
   • Instalador de pacotes UV (recomendado) ou pip
   • Acesso a um catálogo REST Iceberg e armazenamento compatível com S3

2. Como instalar no Claude Desktop Adicione a seguinte configuração ao claude_desktop_config.json:

{
  "mcpServers": {
    "iceberg": {
      "command": "uv",
      "args": [
        "--directory",
        "PATH_TO_/mcp-iceberg-service",
        "run",
        "mcp-server-iceberg"
      ],
      "env": {
        "ICEBERG_CATALOG_URI" : "http://localhost:8181",
        "ICEBERG_WAREHOUSE" : "YOUR ICEBERG WAREHOUSE NAME",
        "S3_ENDPOINT" : "OPTIONAL IF USING S3",
        "AWS_ACCESS_KEY_ID" : "YOUR S3 ACCESS KEY",
        "AWS_SECRET_ACCESS_KEY" : "YOUR S3 SECRET KEY"
      }
    }
  }
}

Projeto

Arquitetura

O servidor MCP é construído sobre três componentes principais:

1. Manipulador de Protocolo MCP

   • Implementa o Model Context Protocol para comunicação com Claude
   • Lida com ciclos de requisição/resposta via stdio
   • Gerencia o ciclo de vida e a inicialização do servidor

2. Processador de Consultas

   • Analisa consultas SQL usando sqlparse
   • Suporta operações:
     • LIST TABLES
     • DESCRIBE TABLE
     • SELECT
     • INSERT

3. Integração Iceberg

   • Usa pyiceberg para operações de tabela
   • Integra-se com PyArrow para manipulação eficiente de dados
   • Gerencia conexões de catálogo e operações de tabela

Integração PyIceberg

O servidor utiliza PyIceberg de várias maneiras:

1. Gerenciamento de Catálogo

   • Conecta-se a catálogos REST
   • Gerencia metadados de tabela
   • Lida com operações de namespace

2. Operações de Dados

   • Converte entre tipos PyIceberg e PyArrow
   • Lida com inserção de dados através de tabelas PyArrow
   • Gerencia esquemas de tabela e tipos de campo

3. Execução de Consultas

   • Traduz SQL para operações PyIceberg
   • Lida com varredura e filtragem de dados
   • Gerencia a conversão do conjunto de resultados

Implementação Adicional Necessária

1. Operações de Consulta

   • Implementar operações UPDATE
   • Adicionar suporte a DELETE
   • Suporte para CREATE TABLE com definição de esquema
   • Adicionar operações ALTER TABLE
   • Implementar suporte a particionamento de tabelas

2. Tipos de Dados

   • Suporte para tipos complexos (arrays, maps, structs)
   • Adicionar tratamento de timestamp com fuso horário
   • Suporte para tipos decimais
   • Adicionar suporte a campos aninhados

3. Melhorias de Desempenho

   • Implementar inserções em lote
   • Adicionar otimização de consultas
   • Suporte para varreduras paralelas
   • Adicionar camada de cache para dados acessados com frequência

4. Recursos de Segurança

   • Adicionar mecanismos de autenticação
   • Implementar controle de acesso baseado em funções
   • Adicionar segurança em nível de linha
   • Suporte para conexões criptografadas

5. Monitoramento e Gerenciamento

   • Adicionar coleta de métricas
   • Implementar registro de consultas
   • Adicionar monitoramento de desempenho
   • Suporte para operações de manutenção de tabelas

6. Tratamento de Erros

   • Melhorar mensagens de erro
   • Adicionar mecanismos de repetição para falhas transitórias
   • Implementar suporte a transações
   • Adicionar validação de dados