Excel MCP Server

Instructions

Implementation Reference

• src/handlers/data-operations.ts:660-733 (handler)

  Main handler function for the 'get_file_info' tool. Validates input, calls the utility function, adds intelligent recommendations for large files and chunking, formats response as ToolResponse.

  async getFileInfo(args: ToolArgs): Promise<ToolResponse> {
    try {
      if (!args.filePath) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                success: false,
                error: 'Missing required parameter: filePath',
              }, null, 2),
            },
          ],
        };
      }
  
      const { filePath, sheet } = args;
      const fileInfo = await getFileInfo(filePath, sheet);
  
      // Add additional recommendations based on file size
      let recommendations = [];
  
      if (fileInfo.estimatedTokens > 50000) {
        recommendations.push('Large file detected. Strongly recommend using chunked reading to avoid token limits.');
        recommendations.push(`Use read_file_chunked or read_file with offset/limit parameters.`);
      } else if (fileInfo.estimatedTokens > 20000) {
        recommendations.push('Medium-sized file. Consider chunked reading for better performance.');
      } else {
        recommendations.push('File size is manageable for direct reading.');
      }
  
      recommendations.push(`Recommended chunk size: ${fileInfo.recommendedChunkSize} rows per chunk.`);
  
      if (fileInfo.sheets && fileInfo.sheets.length > 1) {
        recommendations.push(`Excel file contains ${fileInfo.sheets.length} sheets. Specify 'sheet' parameter to read specific sheets.`);
      }
  
      const response = {
        success: true,
        fileInfo: {
          ...fileInfo,
          fileSizeMB: Math.round((fileInfo.fileSize / 1024 / 1024) * 100) / 100,
        },
        recommendations,
        chunkingAdvice: {
          useChunking: fileInfo.estimatedTokens > 20000,
          optimalChunkSize: fileInfo.recommendedChunkSize,
          estimatedChunks: Math.ceil(fileInfo.totalRows / fileInfo.recommendedChunkSize),
          maxTokensPerChunk: Math.ceil((fileInfo.recommendedChunkSize * fileInfo.totalColumns * 10) / 4),
        }
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              success: false,
              error: error instanceof Error ? error.message : 'Unknown error occurred',
            }, null, 2),
          },
        ],
      };
    }
  }

• src/index.ts:277-293 (schema)

  Input schema definition for the 'get_file_info' tool, defining parameters filePath (required) and sheet (optional).

    name: 'get_file_info',
    description: 'Analyze file size and get chunking recommendations',
    inputSchema: {
      type: 'object',
      properties: {
        filePath: {
          type: 'string',
          description: 'Path to the CSV or Excel file',
        },
        sheet: {
          type: 'string',
          description: 'Sheet name for Excel files (optional)',
        },
      },
      required: ['filePath'],
    },
  },

• src/index.ts:1217-1218 (registration)

  Tool registration in the MCP server request handler switch statement, dispatching 'get_file_info' calls to DataOperationsHandler.getFileInfo method.

  case 'get_file_info':
    return await this.dataOpsHandler.getFileInfo(toolArgs);

• src/utils/file-utils.ts:145-196 (helper)

  Core utility function that computes FileInfo including file stats, row/column counts, token estimates, chunk recommendations for CSV and Excel files.

  export async function getFileInfo(filePath: string, sheet?: string): Promise<FileInfo> {
    const absolutePath = path.resolve(filePath);
    const stats = await fs.stat(absolutePath);
    const ext = path.extname(filePath).toLowerCase();
  
    // Get basic file info
    let totalRows = 0;
    let totalColumns = 0;
    let sheets: string[] = [];
  
    if (ext === '.csv') {
      // For CSV, we need to read to count rows (but efficiently)
      const content = await fs.readFile(absolutePath, 'utf-8');
      const lines = content.split('\n').filter(line => line.trim() !== '');
      totalRows = lines.length;
  
      // Estimate columns from first line
      if (lines.length > 0) {
        const firstLine = csv.parse(lines[0])[0];
        totalColumns = firstLine.length;
      }
    } else if (ext === '.xlsx' || ext === '.xls') {
      const workbook = new ExcelJS.Workbook();
      await workbook.xlsx.readFile(absolutePath);
  
      sheets = workbook.worksheets.map(ws => ws.name);
      const worksheet = workbook.getWorksheet(sheet || sheets[0]);
  
      if (worksheet) {
        totalRows = worksheet.rowCount;
        totalColumns = worksheet.columnCount;
      }
    }
  
    // Estimate token count (rough approximation)
    const avgCellLength = 10; // characters
    const estimatedTokens = Math.ceil((totalRows * totalColumns * avgCellLength) / 4); // ~4 chars per token
  
    // Calculate recommended chunk size (target ~8000 tokens per chunk)
    const targetTokens = 8000;
    const recommendedChunkSize = Math.max(100, Math.floor(targetTokens / (totalColumns * avgCellLength / 4)));
  
    return {
      filePath: absolutePath,
      fileSize: stats.size,
      totalRows,
      totalColumns,
      estimatedTokens,
      recommendedChunkSize: Math.min(recommendedChunkSize, 5000), // Cap at 5000 rows
      sheets: sheets.length > 0 ? sheets : undefined
    };
  }