Dataproc MCP Server

Un servidor MCP para gestionar operaciones de Google Cloud Dataproc y flujos de trabajo de big data, con integración fluida para VS Code.

GitHub

Documentación

Dataproc MCP Server

Un servidor Model Context Protocol (MCP) listo para producción para operaciones de Google Cloud Dataproc con inyección inteligente de parámetros, seguridad de nivel empresarial y herramientas integrales. Diseñado para una integración perfecta con Roo (VS Code).

🚀 Inicio rápido

Recomendado: Integración con Roo (VS Code)

Añade esto a la configuración de MCP en Roo:

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

Con archivo de configuración personalizado

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

Alternativa: Instalación 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

Configuración en 5 minutos

Instala el paquete:

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

Ejecuta la configuración:
```
dataproc-mcp --setup
```

Configura la autenticación:

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

Inicia el servidor:
```
dataproc-mcp
```

🌐 Compatibilidad con la aplicación web de Claude.ai

✅ LISTO PARA PRODUCCIÓN: Integración completa con Claude.ai mediante túnel HTTPS y OAuth

El Dataproc MCP Server ahora ofrece compatibilidad total con la aplicación web de Claude.ai con una solución funcional que incluye las 22 herramientas MCP.

🚀 Solución funcional (probada y verificada)

Terminal 1 - Iniciar el servidor MCP:

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

Terminal 2 - Iniciar el túnel de Cloudflare:

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

Resultado: ¡Claude.ai puede ver y usar todas las herramientas con éxito! 🎉

Características principales:

✅ Acceso completo a las herramientas - Las 22 herramientas MCP disponibles en Claude.ai
✅ Túnel HTTPS - Túnel de Cloudflare para acceso externo seguro
✅ Autenticación OAuth - OAuth de GitHub para autenticación segura
✅ Certificados de confianza - Sin advertencias del navegador ni problemas de conexión
✅ Soporte WebSocket - Compatibilidad total con WebSocket en Claude.ai
✅ Listo para producción - Solución probada y verificada

Configuración rápida:

Configura GitHub OAuth (5 minutos)
Genera certificados SSL: npm run ssl:generate
Inicia los servicios (2 terminales como se muestra arriba)
Conecta Claude.ai a la URL de tu túnel

📖 Guía completa: Consulta docs/claude-ai-integration.md para instrucciones detalladas de configuración, solución de problemas y funciones avanzadas.

📖 Configuración de certificados: Consulta docs/trusted-certificates.md para la configuración de certificados SSL.

✨ Características

🎯 Capacidades principales

22 herramientas MCP listas para producción - Suite completa de gestión de Dataproc
🧠 Búsqueda semántica en la base de conocimiento - Consultas en lenguaje natural con integración opcional de Qdrant
🚀 Optimización de respuestas - Reducción de tokens del 60-96% con almacenamiento en Qdrant
🔄 Sistema genérico de conversión de tipos - Transformaciones automáticas de datos con seguridad de tipos
Reducción de parámetros del 60-80% - Inyección inteligente de valores predeterminados
Soporte multi-entorno - Configuraciones para desarrollo, pruebas y producción
Suplantación de cuentas de servicio - Autenticación empresarial
Monitoreo de trabajos en tiempo real - Seguimiento integral del estado

🚀 Optimización de respuestas

Reducción de tokens del 96.2% - list_clusters: 7,651 → 292 tokens
Almacenamiento automático en Qdrant - Datos completos preservados y buscables
Acceso mediante URI de recursos - dataproc://responses/clusters/list/abc123
Degradación elegante - Funciona sin Qdrant, con respuestas completas como alternativa
Procesamiento en 9.95ms - Optimización ultrarrápida con uso de memoria <1MB

🔄 Sistema genérico de conversión de tipos

Reducción de código del 75% - Elimina la lógica de conversión manual en todos los servicios
Transformaciones con seguridad de tipos - Detección y mapeo automático de campos
Compresión inteligente - Compresión a nivel de campo con umbrales configurables
Tiempos de conversión de 0.50ms - Procesamiento ultrarrápido con ratios de compresión del 100%
Cero configuración - Funciona automáticamente con los tipos TypeScript existentes
Compatibilidad retroactiva - Integración perfecta con la funcionalidad existente

🔒 Seguridad empresarial

Validación de entrada - Esquemas Zod para las 16 herramientas
Limitación de velocidad - Prevención configurable de abusos
Gestión de credenciales - Manejo y rotación seguros
Registro de auditoría - Seguimiento integral de eventos de seguridad
Detección de amenazas - Prevención de ataques de inyección

📊 Garantía de calidad

Cobertura de pruebas superior al 90% - Suite de pruebas integral
Monitoreo de rendimiento - Umbrales configurables
Pruebas multi-entorno - Validación multiplataforma
Controles de calidad automatizados - Integración con CI/CD
Escaneo de seguridad - Gestión de vulnerabilidades

🚀 Experiencia del desarrollador

Configuración en 5 minutos - Guía de inicio rápido
Documentación interactiva - Documentación HTML con ejemplos
Ejemplos integrales - Configuraciones multi-entorno
Guías de solución de problemas - Problemas comunes y soluciones
Integración con IDE - Soporte de TypeScript

🛠️ Suite completa de herramientas MCP (22 herramientas)

🔄 Mejorado con conversión genérica de tipos: Todas las herramientas se benefician ahora de transformaciones automáticas de datos con seguridad de tipos, compresión inteligente y mapeo de campos.

🚀 Gestión de clústeres (8 herramientas)

Herramienta	Descripción	Valores predeterminados inteligentes	Características clave
`start_dataproc_cluster`	Crear e iniciar nuevos clústeres	✅ 80% menos parámetros	Basado en perfiles, configuración automática
`create_cluster_from_yaml`	Crear desde configuración YAML	✅ Inyección de proyecto/región	Configuración basada en plantillas
`create_cluster_from_profile`	Crear usando perfiles predefinidos	✅ 85% menos parámetros	8 perfiles integrados
`list_clusters`	Listar todos los clústeres con filtrado	✅ Sin necesidad de parámetros	Consultas semánticas, paginación
`list_tracked_clusters`	Listar clústeres creados por MCP	✅ Filtrado por perfil	Seguimiento de creación
`get_cluster`	Obtener información detallada del clúster	✅ 75% menos parámetros	Extracción semántica de datos
`delete_cluster`	Eliminar clústeres existentes	✅ Valores predeterminados de proyecto/región	Eliminación segura
`get_zeppelin_url`	Obtener URL del notebook de Zeppelin	✅ Descubrimiento automático	Acceso a la interfaz web

💼 Gestión de trabajos (7 herramientas)

Herramienta	Descripción	Valores predeterminados inteligentes	Características clave
`submit_hive_query`	Enviar consultas Hive a clústeres	✅ 70% menos parámetros	Soporte asíncrono, tiempos de espera
`submit_dataproc_job`	Enviar trabajos Spark/PySpark/Presto	✅ 75% menos parámetros	Soporte multi-motor, almacenamiento de archivos locales
`cancel_dataproc_job`	Cancelar trabajos en ejecución o pendientes	✅ Solo se necesita el ID del trabajo	Cancelación de emergencia, control de costos
`get_job_status`	Obtener estado de ejecución del trabajo	✅ Solo se necesita el ID del trabajo	Monitoreo en tiempo real
`get_job_results`	Obtener salidas y resultados del trabajo	✅ Paginación automática	Formato de resultados
`get_query_status`	Obtener estado de consultas Hive	✅ Parámetros mínimos	Seguimiento de consultas
`get_query_results`	Obtener resultados de consultas Hive	✅ Paginación inteligente	Soporte asíncrono mejorado

📋 Configuración y perfiles (3 herramientas)

Herramienta	Descripción	Valores predeterminados inteligentes	Características clave
`list_profiles`	Listar perfiles de clúster disponibles	✅ Filtrado por categoría	8 perfiles de producción
`get_profile`	Obtener configuración detallada del perfil	✅ Solo se necesita el ID del perfil	Acceso a plantillas
`query_cluster_data`	Consultar datos de clúster almacenados	✅ Lenguaje natural	Búsqueda semántica

📊 Analítica e información (4 herramientas)

Herramienta	Descripción	Valores predeterminados inteligentes	Características clave
`check_active_jobs`	Estado rápido de todos los trabajos activos	✅ Sin necesidad de parámetros	Vista multi-proyecto
`get_cluster_insights`	Analítica integral de clústeres	✅ Descubrimiento automático	Tipos de máquina, componentes
`get_job_analytics`	Analítica de rendimiento de trabajos	✅ Tasas de éxito	Patrones de error, métricas
`query_knowledge`	Consultar base de conocimiento integral	✅ Lenguaje natural	Clústeres, trabajos, errores

🎯 Capacidades clave

🧠 Búsqueda semántica: Consultas en lenguaje natural con integración de Qdrant
⚡ Valores predeterminados inteligentes: Reducción de parámetros del 60-80% mediante inyección inteligente
📊 Optimización de respuestas: Reducción de tokens del 96% con preservación completa de datos
🔄 Soporte asíncrono: Envío y monitoreo de trabajos sin bloqueo
🏷️ Sistema de perfiles: 8 plantillas de clúster listas para producción
📈 Analítica: Información integral y seguimiento de rendimiento

📋 Configuración

Configuración basada en proyectos

El servidor admite un formato de configuración basado en proyectos:

# 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 autenticación

Suplantación de cuenta de servicio (recomendado)
Clave directa de cuenta de servicio
Credenciales predeterminadas de la aplicación
Autenticación híbrida con alternativas

📚 Documentación

Guía de inicio rápido - Comienza en 5 minutos
Búsqueda semántica en la base de conocimiento - Consultas en lenguaje natural y configuración
Sistema genérico de conversión de tipos - Diseño arquitectónico e implementación
Guía de migración del convertidor genérico - Migración desde conversiones manuales
Referencia de API - Documentación completa de herramientas
Ejemplos de configuración - Configuraciones del mundo real
Guía de seguridad - Mejores prácticas y cumplimiento
Guía de instalación - Instrucciones detalladas de configuración

🔧 Integración con clientes 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"
      ]
    }
  }
}

🏗️ Arquitectura

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

🔄 Arquitectura del sistema genérico de conversión de tipos

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

🚦 Rendimiento

Logros en tiempo de respuesta

Validación de esquemas: ~2ms (objetivo: <5ms) ✅
Inyección de parámetros: ~1ms (objetivo: <2ms) ✅
Conversión genérica de tipos: ~0.50ms (objetivo: <2ms) ✅
Validación de credenciales: ~25ms (objetivo: <50ms) ✅
Llamada a herramienta MCP: ~50ms (objetivo: <100ms) ✅

Logros de rendimiento

Validación de esquemas: ~2000 operaciones/seg ✅
Inyección de parámetros: ~5000 operaciones/seg ✅
Conversión genérica de tipos: ~2000 operaciones/seg ✅
Validación de credenciales: ~200 operaciones/seg ✅
Llamada a herramienta MCP: ~100 operaciones/seg ✅

Logros de compresión

Compresión a nivel de campo: Hasta ratios de compresión del 100% ✅
Optimización de memoria: Reducción del 30-60% en el uso de memoria ✅
Seguridad de tipos: Cero errores de tipo en tiempo de ejecución con validación automática ✅

🧪 Pruebas

# 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

🤝 Contribuciones

¡Agradecemos las contribuciones! Consulta nuestra Guía de contribuciones para más detalles.

Configuración de desarrollo

# 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

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

🆘 Soporte

Problemas en GitHub: Reporta errores y solicita funciones
Documentación: Documentación completa
Paquete NPM: Información del paquete

🏆 Agradecimientos

Model Context Protocol - El protocolo que hace esto posible
Google Cloud Dataproc - El servicio con el que nos integramos
Qdrant - Base de datos vectorial de alto rendimiento que impulsa nuestra búsqueda semántica e indexación de conocimiento
TypeScript - Por la seguridad de tipos y la experiencia del desarrollador

Hecho con ❤️ para las comunidades de MCP y Google Cloud