MCP Excel Reader

MCP Excel Reader

Un servidor de Model Context Protocol (MCP) para leer archivos de Excel con soporte automático de fragmentación y paginación. Construido con SheetJS y TypeScript, esta herramienta te ayuda a manejar archivos de Excel grandes de manera eficiente, dividiéndolos automáticamente en fragmentos manejables.

Características

• 📊 Lee archivos de Excel (.xlsx, .xls) con límites de tamaño automáticos
• 🔄 Fragmentación automática para conjuntos de datos grandes
• 📑 Selección de hoja y paginación de filas
• 📅 Manejo adecuado de fechas
• ⚡ Optimizado para archivos grandes
• 🛡️ Manejo de errores y validación

Instalación

Instalación a través de Smithery

Para instalar Excel Reader para Claude Desktop automáticamente a través de Smithery:

npx -y @smithery/cli install @ArchimedesCrypto/excel-reader-mcp-chunked --client claude

Como servidor MCP

1. Instalar globalmente:

npm install -g @archimdescrypto/excel-reader

2. Añade a tu archivo de configuración de MCP (normalmente en ~/.config/claude/settings.json o equivalente):

{
  "mcpServers": {
    "excel-reader": {
      "command": "excel-reader",
      "env": {}
    }
  }
}

Para desarrollo

1. Clona el repositorio:

git clone https://github.com/ArchimdesCrypto/mcp-excel-reader.git
cd mcp-excel-reader

2. Instala las dependencias:

npm install

3. Compila el proyecto:

npm run build

Uso

Uso

El Excel Reader proporciona una única herramienta read_excel con los siguientes parámetros:

interface ReadExcelArgs {
  filePath: string;      // Path to Excel file
  sheetName?: string;    // Optional sheet name (defaults to first sheet)
  startRow?: number;     // Optional starting row for pagination
  maxRows?: number;      // Optional maximum rows to read
}

// Response format
interface ExcelResponse {
  fileName: string;
  totalSheets: number;
  currentSheet: {
    name: string;
    totalRows: number;
    totalColumns: number;
    chunk: {
      rowStart: number;
      rowEnd: number;
      columns: string[];
      data: Record<string, any>[];
    };
    hasMore: boolean;
    nextChunk?: {
      rowStart: number;
      columns: string[];
    };
  };
}

Uso básico

Cuando se usa con Claude u otra IA compatible con MCP:

Read the Excel file at path/to/file.xlsx

La IA usará la herramienta para leer el archivo, manejando automáticamente la fragmentación para archivos grandes.

Características

1. Fragmentación automática

   • Divide automáticamente archivos grandes en fragmentos manejables
   • Tamaño de fragmento predeterminado de 100KB
   • Proporciona metadatos para la paginación

2. Selección de hoja

   • Lee hojas específicas por nombre
   • Se usa la primera hoja si no se especifica

3. Paginación de filas

   • Controla qué filas leer con startRow y maxRows
   • Obtén información del siguiente fragmento para lectura continua

4. Manejo de errores

   • Valida la existencia y el formato del archivo
   • Proporciona mensajes de error claros
   • Maneja archivos de Excel malformados con elegancia

Extensión con características de SheetJS

El Excel Reader está construido sobre SheetJS y puede extenderse con sus potentes características:

Extensiones disponibles

1. Manejo de fórmulas

   // Enable formula parsing
   const wb = XLSX.read(data, {
     cellFormula: true,
     cellNF: true
   });
   

2. Formato de celdas

   // Access cell styles and formatting
   const styles = Object.keys(worksheet)
     .filter(key => key[0] !== '!')
     .map(key => ({
       cell: key,
       style: worksheet[key].s
     }));
   

3. Validación de datos

   // Access data validation rules
   const validation = worksheet['!dataValidation'];
   

4. Características de hoja

   • Celdas combinadas: worksheet['!merges']
   • Filas/Columnas ocultas: worksheet['!rows'], worksheet['!cols']
   • Protección de hoja: worksheet['!protect']

Para más características y documentación detallada, visita la Documentación de SheetJS.

Contribuciones

1. Haz un fork del repositorio
2. Crea tu rama de características (git checkout -b feature/amazing-feature)
3. Haz commit de tus cambios (git commit -m 'Add some amazing feature')
4. Sube a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

Licencia

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

Agradecimientos

• Construido con SheetJS
• Parte del ecosistema Model Context Protocol