Dataproc MCP Server

Um servidor MCP para gerenciar operações do Google Cloud Dataproc e fluxos de trabalho de big data, com integração perfeita para o VS Code.

GitHub

Documentação

Dataproc MCP Server

Um servidor Model Context Protocol (MCP) pronto para produção para operações do Google Cloud Dataproc com injeção inteligente de parâmetros, segurança de nível empresarial e ferramentas abrangentes. Projetado para integração perfeita com Roo (VS Code).

🚀 Início Rápido

Recomendado: Integração com Roo (VS Code)

Adicione isto às suas configurações MCP do Roo:

{
  "mcpServers": {
    "dataproc": {
      "command": "npx",
      "args": ["@dipseth/dataproc-mcp-server@latest"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Com Arquivo de Configuração Personalizado

{
  "mcpServers": {
    "dataproc": {
      "command": "npx",
      "args": ["@dipseth/dataproc-mcp-server@latest"],
      "env": {
        "LOG_LEVEL": "info",
        "DATAPROC_CONFIG_PATH": "/path/to/your/config.json"
      }
    }
  }
}

Alternativa: Instalação Global

# Install globally
npm install -g @dipseth/dataproc-mcp-server

# Start the server
dataproc-mcp-server

# Or run directly
npx @dipseth/dataproc-mcp-server@latest

Configuração em 5 Minutos

Instale o pacote:

npm install -g @dipseth/dataproc-mcp-server@latest

Execute a configuração:
```
dataproc-mcp --setup
```

Configure a autenticação:

# Edit the generated config file
nano config/server.json

Inicie o servidor:
```
dataproc-mcp
```

🌐 Compatibilidade com Web App do Claude.ai

✅ PRONTO PARA PRODUÇÃO: Integração Completa com Claude.ai via Túnel HTTPS e OAuth

O Dataproc MCP Server agora oferece compatibilidade completa com o web app do Claude.ai com uma solução funcional que inclui todas as 22 ferramentas MCP!

🚀 Solução Funcional (Testada e Verificada)

Terminal 1 - Inicie o Servidor MCP:

DATAPROC_CONFIG_PATH=config/github-oauth-server.json npm start -- --http --oauth --port 8080

Terminal 2 - Inicie o Túnel Cloudflare:

cloudflared tunnel --url https://localhost:8443 --origin-server-name localhost --no-tls-verify

Resultado: O Claude.ai pode ver e usar todas as ferramentas com sucesso! 🎉

Principais Recursos:

✅ Acesso Completo às Ferramentas - Todas as 22 ferramentas MCP disponíveis no Claude.ai
✅ Túnel HTTPS - Túnel Cloudflare para acesso externo seguro
✅ Autenticação OAuth - OAuth do GitHub para autenticação segura
✅ Certificados Confiáveis - Sem avisos do navegador ou problemas de conexão
✅ Suporte a WebSocket - Compatibilidade total com WebSocket no Claude.ai
✅ Pronto para Produção - Solução testada e verificada

Configuração Rápida:

Configure o OAuth do GitHub (5 minutos)
Gere certificados SSL: npm run ssl:generate
Inicie os serviços (2 terminais como mostrado acima)
Conecte o Claude.ai à URL do seu túnel

📖 Guia Completo: Consulte docs/claude-ai-integration.md para instruções detalhadas de configuração, solução de problemas e recursos avançados.

📖 Configuração de Certificados: Consulte docs/trusted-certificates.md para configuração de certificados SSL.

✨ Recursos

🎯 Capacidades Principais

22 Ferramentas MCP Prontas para Produção - Suíte completa de gerenciamento do Dataproc
🧠 Pesquisa Semântica na Base de Conhecimento - Consultas em linguagem natural com integração opcional com Qdrant
🚀 Otimização de Respostas - Redução de 60-96% em tokens com armazenamento Qdrant
🔄 Sistema Genérico de Conversão de Tipos - Transformações automáticas de dados com segurança de tipos
Redução de 60-80% em Parâmetros - Injeção inteligente de padrões
Suporte a Múltiplos Ambientes - Configurações de dev/staging/produção
Impersonação de Conta de Serviço - Autenticação empresarial
Monitoramento de Jobs em Tempo Real - Acompanhamento abrangente de status

🚀 Otimização de Respostas

Redução de 96,2% em Tokens - list_clusters: 7,651 → 292 tokens
Armazenamento Automático no Qdrant - Dados completos preservados e pesquisáveis
Acesso via URI de Recurso - dataproc://responses/clusters/list/abc123
Fallback Gracioso - Funciona sem Qdrant, retorna a respostas completas
Processamento em 9,95ms - Otimização extremamente rápida com uso de memória <1MB

🔄 Sistema Genérico de Conversão de Tipos

Redução de 75% em Código - Elimina lógica de conversão manual em todos os serviços
Transformações com Segurança de Tipos - Detecção e mapeamento automáticos de campos
Compressão Inteligente - Compressão em nível de campo com limites configuráveis
Tempos de Conversão de 0,50ms - Processamento extremamente rápido com taxas de compressão de 100%
Zero Configuração - Funciona automaticamente com tipos TypeScript existentes
Compatível com Versões Anteriores - Integração perfeita com funcionalidades existentes

Segurança Empresarial

Validação de Entrada - Esquemas Zod para todas as 16 ferramentas
Limitação de Taxa - Prevenção de abuso configurável
Gerenciamento de Credenciais - Manuseio e rotação seguros
Registro de Auditoria - Rastreamento abrangente de eventos de segurança
Detecção de Ameaças - Prevenção de ataques de injeção

📊 Garantia de Qualidade

Cobertura de Testes de 90%+ - Suíte de testes abrangente
Monitoramento de Desempenho - Limites configuráveis
Testes em Múltiplos Ambientes - Validação entre plataformas
Portões de Qualidade Automatizados - Integração CI/CD
Varredura de Segurança - Gerenciamento de vulnerabilidades

🚀 Experiência do Desenvolvedor

Configuração em 5 Minutos - Guia de início rápido
Documentação Interativa - Documentos HTML com exemplos
Exemplos Abrangentes - Configurações de múltiplos ambientes
Guias de Solução de Problemas - Problemas comuns e soluções
Integração com IDE - Suporte a TypeScript

🛠️ Suíte Completa de Ferramentas MCP (22 Ferramentas)

🔄 Aprimorado com Conversão Genérica de Tipos: Todas as ferramentas agora se beneficiam de transformações automáticas de dados com segurança de tipos, compressão inteligente e mapeamento de campos.

🚀 Gerenciamento de Clusters (8 Ferramentas)

Ferramenta	Descrição	Padrões Inteligentes	Principais Recursos
`start_dataproc_cluster`	Criar e iniciar novos clusters	✅ 80% menos parâmetros	Baseado em perfil, configuração automática
`create_cluster_from_yaml`	Criar a partir de configuração YAML	✅ Injeção de projeto/região	Configuração orientada por modelo
`create_cluster_from_profile`	Criar usando perfis predefinidos	✅ 85% menos parâmetros	8 perfis integrados
`list_clusters`	Listar todos os clusters com filtragem	✅ Nenhum parâmetro necessário	Consultas semânticas, paginação
`list_tracked_clusters`	Listar clusters criados pelo MCP	✅ Filtragem por perfil	Rastreamento de criação
`get_cluster`	Obter informações detalhadas do cluster	✅ 75% menos parâmetros	Extração semântica de dados
`delete_cluster`	Excluir clusters existentes	✅ Padrões de projeto/região	Exclusão segura
`get_zeppelin_url`	Obter URL do notebook Zeppelin	✅ Descoberta automática	Acesso à interface web

💼 Gerenciamento de Jobs (7 Ferramentas)

Ferramenta	Descrição	Padrões Inteligentes	Principais Recursos
`submit_hive_query`	Enviar consultas Hive para clusters	✅ 70% menos parâmetros	Suporte assíncrono, timeouts
`submit_dataproc_job`	Enviar jobs Spark/PySpark/Presto	✅ 75% menos parâmetros	Suporte a múltiplos motores, Preparação de arquivos locais
`cancel_dataproc_job`	Cancelar jobs em execução ou pendentes	✅ Apenas JobID necessário	Cancelamento de emergência, controle de custos
`get_job_status`	Obter status de execução do job	✅ Apenas JobID necessário	Monitoramento em tempo real
`get_job_results`	Obter saídas e resultados do job	✅ Paginação automática	Formatação de resultados
`get_query_status`	Obter status da consulta Hive	✅ Parâmetros mínimos	Rastreamento de consultas
`get_query_results`	Obter resultados da consulta Hive	✅ Paginação inteligente	Suporte assíncrono aprimorado

📋 Configuração e Perfis (3 Ferramentas)

Ferramenta	Descrição	Padrões Inteligentes	Principais Recursos
`list_profiles`	Listar perfis de cluster disponíveis	✅ Filtragem por categoria	8 perfis de produção
`get_profile`	Obter configuração detalhada do perfil	✅ Apenas ID do perfil	Acesso a modelos
`query_cluster_data`	Consultar dados de cluster armazenados	✅ Linguagem natural	Pesquisa semântica

📊 Análises e Insights (4 Ferramentas)

Ferramenta	Descrição	Padrões Inteligentes	Principais Recursos
`check_active_jobs`	Status rápido de todos os jobs ativos	✅ Nenhum parâmetro necessário	Visão de múltiplos projetos
`get_cluster_insights`	Análises abrangentes de cluster	✅ Descoberta automática	Tipos de máquina, componentes
`get_job_analytics`	Análises de desempenho de jobs	✅ Taxas de sucesso	Padrões de erro, métricas
`query_knowledge`	Consultar base de conhecimento abrangente	✅ Linguagem natural	Clusters, jobs, erros

🎯 Principais Capacidades

🧠 Pesquisa Semântica: Consultas em linguagem natural com integração Qdrant
⚡ Padrões Inteligentes: Redução de 60-80% em parâmetros por meio de injeção inteligente
📊 Otimização de Respostas: Redução de 96% em tokens com preservação completa dos dados
🔄 Suporte Assíncrono: Envio e monitoramento de jobs sem bloqueio
🏷️ Sistema de Perfis: 8 modelos de cluster prontos para produção
📈 Análises: Insights abrangentes e acompanhamento de desempenho

📋 Configuração

Configuração Baseada em Projeto

O servidor suporta um formato de configuração baseado em projeto:

# profiles/@analytics-workloads.yaml
my-company-analytics-prod-1234:
  region: us-central1
  tags:
    - DataProc
    - analytics
    - production
  labels:
    service: analytics-service
    owner: data-team
    environment: production
  cluster_config:
    # ... cluster configuration

Métodos de Autenticação

Impersonação de Conta de Serviço (Recomendado)
Chave de Conta de Serviço Direta
Credenciais Padrão do Aplicativo
Autenticação Híbrida com fallbacks

📚 Documentação

Guia de Início Rápido - Comece em 5 minutos
Pesquisa Semântica na Base de Conhecimento - Consultas em linguagem natural e configuração
Sistema Genérico de Conversão de Tipos - Design arquitetural e implementação
Guia de Migração do Conversor Genérico - Migração de conversões manuais
Referência da API - Documentação completa das ferramentas
Exemplos de Configuração - Configurações do mundo real
Guia de Segurança - Melhores práticas e conformidade
Guia de Instalação - Instruções detalhadas de configuração

🔧 Integração com Cliente MCP

Claude Desktop

{
  "mcpServers": {
    "dataproc": {
      "command": "npx",
      "args": ["@dataproc/mcp-server"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Roo (VS Code)

{
  "mcpServers": {
    "dataproc-server": {
      "command": "npx",
      "args": ["@dataproc/mcp-server"],
      "disabled": false,
      "alwaysAllow": [
        "list_clusters",
        "get_cluster",
        "list_profiles"
      ]
    }
  }
}

🏗️ Arquitetura

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │────│  Dataproc MCP    │────│  Google Cloud   │
│  (Claude/Roo)   │    │     Server       │    │    Dataproc     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                       ┌──────┴──────┐
                       │   Features  │
                       ├─────────────┤
                       │ • Security  │
                       │ • Profiles  │
                       │ • Validation│
                       │ • Monitoring│
                       │ • Generic    │
                       │   Converter  │
                       └─────────────┘

🔄 Arquitetura do Sistema Genérico de Conversão de Tipos

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Source Types   │────│ Generic Converter │────│ Qdrant Payloads │
│ • ClusterData   │    │    System        │    │ • Compressed    │
│ • QueryResults  │    │                  │    │ • Type-Safe     │
│ • JobData       │    │ ┌──────────────┐ │    │ • Optimized     │
└─────────────────┘    │ │Field Analyzer│ │    └─────────────────┘
                       │ │Transformation│ │
                       │ │Engine        │ │
                       │ │Compression   │ │
                       │ │Service       │ │
                       │ └──────────────┘ │
                       └──────────────────┘

🚦 Desempenho

Conquistas de Tempo de Resposta

Validação de Esquema: ~2ms (alvo: <5ms) ✅
Injeção de Parâmetros: ~1ms (alvo: <2ms) ✅
Conversão Genérica de Tipos: ~0,50ms (alvo: <2ms) ✅
Validação de Credenciais: ~25ms (alvo: <50ms) ✅
Chamada de Ferramenta MCP: ~50ms (alvo: <100ms) ✅

Conquistas de Throughput

Validação de Esquema: ~2000 ops/seg ✅
Injeção de Parâmetros: ~5000 ops/seg ✅
Conversão Genérica de Tipos: ~2000 ops/seg ✅
Validação de Credenciais: ~200 ops/seg ✅
Chamada de Ferramenta MCP: ~100 ops/seg ✅

Conquistas de Compressão

Compressão em Nível de Campo: Taxas de compressão de até 100% ✅
Otimização de Memória: Redução de 30-60% no uso de memória ✅
Segurança de Tipos: Zero erros de tipo em tempo de execução com validação automática ✅

🧪 Testes

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:performance

# Run with coverage
npm run test:coverage

🤝 Contribuindo

Aceitamos contribuições! Consulte nosso Guia de Contribuição para obter detalhes.

Configuração de Desenvolvimento

# Clone the repository
git clone https://github.com/dipseth/dataproc-mcp.git
cd dataproc-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Start development server
npm run dev

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🆘 Suporte

Issues do GitHub: Relate bugs e solicite recursos
Documentação: Documentação completa
Pacote NPM: Informações do pacote

🏆 Agradecimentos

Model Context Protocol - O protocolo que torna isso possível
Google Cloud Dataproc - O serviço com o qual estamos integrando
Qdrant - Banco de dados vetorial de alto desempenho que alimenta nossa pesquisa semântica e indexação de conhecimento
TypeScript - Para segurança de tipos e experiência do desenvolvedor

Feito com ❤️ para as comunidades MCP e Google Cloud