MCP CSV Analysis with Gemini AI

MCP CSV Analysis with Gemini AI

Un potente servidor de Protocolo de Contexto de Modelo (MCP) que proporciona capacidades avanzadas de análisis de CSV y generación de pensamiento utilizando la IA Gemini de Google. Esta herramienta se integra perfectamente con Claude Desktop y ofrece funciones sofisticadas de análisis de datos, visualización y procesamiento de lenguaje natural.

🌟 Características

1. Herramienta de Análisis CSV (analyze-csv)

• Análisis de Datos Integral: Realiza un Análisis Exploratorio de Datos (EDA) detallado en archivos CSV
• Dos Modos de Análisis:
  • basic: Resumen rápido y estadísticas esenciales
  • detailed: Análisis en profundidad con información avanzada
• Componentes del Análisis:
  • Análisis estadístico de todas las columnas
  • Evaluación de la calidad de los datos
  • Reconocimiento de patrones
  • Análisis de correlación
  • Evaluación de importancia de características
  • Recomendaciones de preprocesamiento
  • Perspectivas de negocio
  • Sugerencias de visualización

2. Herramienta de Visualización de Datos (visualize-data)

• Visualizaciones Interactivas: Crea gráficos hermosos e informativos usando Plotly
• Tipos de Visualización:
  • basic: Selección automática de visualización según los tipos de datos
  • advanced: Visualizaciones complejas de múltiples variables
  • custom: Configuraciones de gráficos definidas por el usuario
• Tipos de Gráficos:
  • Histogramas para análisis de distribución
  • Mapas de calor de correlación
  • Gráficos de dispersión
  • Gráficos de líneas
  • Gráficos de barras
  • Diagramas de caja
• Características:
  • Detección automática de tipos de datos
  • Selección inteligente de gráficos
  • Gráficos interactivos
  • Exportaciones de alta resolución
  • Diseños personalizables

3. Herramienta de Generación de Pensamiento (generate-thinking)

• Genera texto detallado del proceso de pensamiento utilizando el modelo experimental de Gemini
• Admite razonamiento y análisis complejos
• Guarda las respuestas con marcas de tiempo
• Directorio de salida personalizable

🚀 Inicio Rápido

Requisitos Previos

• Node.js (v16 o superior)
• TypeScript
• Claude Desktop
• Clave de API de Google Gemini
• Cuenta de Plotly (para visualizaciones)

Instalación

1. Clona y configura:

git clone [your-repo-url]
cd mcp-csv-analysis-gemini
npm install

2. Crea el archivo .env:

GEMINI_API_KEY=your_api_key_here

3. Compila el proyecto:

npm run build

Configuración de Claude Desktop

1. Crea/Edita %AppData%/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "CSV Analysis": {
      "command": "node",
      "args": ["path/to/mcp-csv-analysis-gemini/dist/index.js"],
      "cwd": "path/to/mcp-csv-analysis-gemini",
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "PLOTLY_USERNAME": "your_plotly_username",
        "PLOTLY_API_KEY": "your_plotly_api_key"
      }
    }
  }
}

2. Reinicia Claude Desktop

📊 Uso de las Herramientas

Análisis CSV

{
  "name": "analyze-csv",
  "arguments": {
    "csvPath": "./data/your_file.csv",
    "analysisType": "detailed",
    "outputDir": "./custom_output"
  }
}

Visualización de Datos

{
  "name": "visualize-data",
  "arguments": {
    "csvPath": "./data/your_file.csv",
    "visualizationType": "basic",
    "columns": ["column1", "column2"],
    "chartTypes": ["histogram", "scatter"],
    "outputDir": "./custom_output"
  }
}

Generación de Pensamiento

{
  "name": "generate-thinking",
  "arguments": {
    "prompt": "Your complex analysis prompt here",
    "outputDir": "./custom_output"
  }
}

📁 Estructura de Salida

output/
├── analysis/
│   ├── csv_analysis_[timestamp]_part1.txt
│   ├── csv_analysis_[timestamp]_part2.txt
│   └── csv_analysis_[timestamp]_summary.txt
├── visualizations/
│   ├── histogram_[column]_[timestamp].png
│   ├── scatter_[columns]_[timestamp].png
│   └── correlation_heatmap_[timestamp].png
└── thinking/
    └── gemini_thinking_[timestamp].txt

📊 Tipos de Visualización

Visualizaciones Básicas

• Generadas automáticamente según los tipos de datos
• Incluye:
  • Histogramas para columnas numéricas
  • Mapas de calor de correlación
  • Gráficos de dispersión básicos

Visualizaciones Avanzadas

• Gráficos más sofisticados
• Múltiples variables
• Diseños mejorados
• Esquemas de color personalizados

Visualizaciones Personalizadas

• Tipos de gráficos definidos por el usuario
• Parámetros configurables
• Opciones de estilo personalizadas
• Diseños de gráficos avanzados

🛠️ Desarrollo

Scripts Disponibles

• npm run build: Compila TypeScript a JavaScript
• npm run start: Inicia el servidor MCP
• npm run dev: Ejecuta en modo desarrollo con ts-node

Variables de Entorno

• GEMINI_API_KEY: Tu clave de API de Google Gemini
• PLOTLY_USERNAME: Tu nombre de usuario de Plotly
• PLOTLY_API_KEY: Tu clave de API de Plotly

📝 Detalles del Análisis

El Análisis Básico Incluye

1. Resumen estadístico básico para cada columna
2. Evaluación de la calidad de los datos
3. Información clave y patrones
4. Correlaciones potenciales
5. Recomendaciones para análisis adicionales

El Análisis Detallado Incluye

1. Análisis estadístico integral
   • Análisis de distribución
   • Medidas de tendencia central
   • Medidas de dispersión
   • Detección de valores atípicos
2. Evaluación avanzada de la calidad de los datos
3. Reconocimiento de patrones
4. Análisis de correlación
5. Análisis de importancia de características
6. Recomendaciones de preprocesamiento
7. Sugerencias de visualización
8. Perspectivas de negocio

⚠️ Limitaciones

• Tamaño máximo de archivo: Depende de la memoria del sistema
• Límites de velocidad: Basados en las cuotas de la API de Gemini y Plotly
• Límite de tokens de salida: 65,536 tokens por respuesta
• Formato CSV: Solo archivos CSV estándar
• Tiempo de análisis: Varía según el tamaño y la complejidad de los datos
• Límites de visualización: Basados en las restricciones del plan gratuito de Plotly

🔒 Notas de Seguridad

• Almacena tus claves de API de forma segura
• No compartas tu archivo .env
• Revisa los datos CSV para detectar información sensible
• Usa directorios de salida personalizados para análisis sensibles
• Asegura tus credenciales de Plotly

🐛 Solución de Problemas

Problemas Comunes

1. Error de Clave de API

   • Verifica que el archivo .env exista
   • Comprueba la validez de la clave de API
   • Asegura una carga adecuada del entorno

2. Error de Análisis CSV

   • Verifica el formato del archivo CSV
   • Comprueba los permisos del archivo
   • Asegura que el archivo no esté vacío

3. Conexión con Claude Desktop

   • Verifica la sintaxis de config.json
   • Comprueba las rutas de archivo en la configuración
   • Reinicia Claude Desktop

Modo de Depuración

Agrega DEBUG=true a tu archivo .env para registro detallado:

GEMINI_API_KEY=your_key_here
DEBUG=true

📚 Referencia de la API

Herramienta de Análisis CSV

interface AnalyzeCSVParams {
  csvPath: string;          // Path to CSV file
  outputDir?: string;       // Optional output directory
  analysisType?: 'basic' | 'detailed';  // Analysis type
}

Herramienta de Visualización de Datos

interface VisualizeDataParams {
  csvPath: string;          // Path to CSV file
  outputDir?: string;       // Optional output directory
  visualizationType?: 'basic' | 'advanced' | 'custom';  // Visualization type
  columns?: string[];       // Columns to visualize
  chartTypes?: ('scatter' | 'line' | 'bar' | 'histogram' | 'box' | 'heatmap')[];  // Chart types
  customConfig?: Record<string, any>;  // Custom configuration
}

Herramienta de Generación de Pensamiento

interface GenerateThinkingParams {
  prompt: string;           // Analysis prompt
  outputDir?: string;       // Optional output directory
}

🤝 Contribuciones

1. Haz un fork del repositorio
2. Crea tu rama de características
3. Haz commit de tus cambios
4. Sube los cambios a la rama
5. Crea una Solicitud de Extracción (Pull Request)

📄 Licencia

Licencia MIT - Consulta el archivo LICENSE para más detalles