Excel MCP Server

Instructions

Implementation Reference

• src/handlers/ai-operations.ts:265-323 (handler)

  Core implementation of the smart_data_analysis tool handler. Reads file content, builds worksheet context, detects data types, generates AI formula suggestions via NLPProcessor.suggestFormulas, and returns structured response.

  async smartDataAnalysis(args: ToolArgs): Promise<ToolResponse> {
    const { filePath, sheet, provider } = args;
  
    try {
      // Read the file
      const data = await readFileContent(filePath, sheet);
  
      if (data.length === 0) {
        throw new Error('File is empty');
      }
  
      // Create context for AI analysis
      const context = {
        headers: data[0],
        rowCount: data.length,
        columnCount: data[0]?.length || 0,
        dataTypes: detectDataTypes(data),
        sampleData: data.slice(0, 6), // First 5 data rows + header
        activeCell: 'A1',
        selectedRange: 'A1:A1'
      };
  
      // Generate AI suggestions
      const suggestions = await this.nlpProcessor.suggestFormulas(context);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              filePath,
              context: {
                headers: context.headers,
                rowCount: context.rowCount,
                columnCount: context.columnCount,
                dataTypes: context.dataTypes
              },
              aiSuggestions: suggestions,
              success: true,
              provider: this.nlpProcessor.getActiveProvider()?.name || 'Local'
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              filePath,
              error: error instanceof Error ? error.message : 'Unknown error',
              success: false
            }, null, 2),
          },
        ],
      };
    }
  }

• src/index.ts:911-932 (schema)

  Tool schema definition in ListToolsRequestSchema, specifying input parameters: filePath (required), sheet, and provider.

    name: 'smart_data_analysis',
    description: 'AI-powered analysis suggestions for your data',
    inputSchema: {
      type: 'object',
      properties: {
        filePath: {
          type: 'string',
          description: 'Path to the CSV or Excel file to analyze',
        },
        sheet: {
          type: 'string',
          description: 'Sheet name for Excel files (optional)',
        },
        provider: {
          type: 'string',
          description: 'Preferred AI provider: anthropic, openai, deepseek, gemini, or local (optional)',
          enum: ['anthropic', 'openai', 'deepseek', 'gemini', 'local'],
        },
      },
      required: ['filePath'],
    },
  },

• src/index.ts:1265-1266 (registration)

  Tool registration in CallToolRequestSchema switch statement, dispatching calls to AIOperationsHandler.smartDataAnalysis method.

  case 'smart_data_analysis':
    return await this.aiOpsHandler.smartDataAnalysis(toolArgs);

• src/ai/nlp-processor.ts:116-146 (helper)

  Supporting helper method in NLPProcessor that generates formula suggestions based on data patterns (numeric columns, dates), used by the handler for AI analysis.

  async suggestFormulas(context: WorksheetContext): Promise<FormulaIntent[]> {
    const suggestions: FormulaIntent[] = [];
    
    // Analyze data patterns
    const patterns = this.analyzeDataPatterns(context);
    
    // Generate suggestions based on patterns
    if (patterns.hasNumbers) {
      suggestions.push({
        formula: `=SUM(${patterns.numericColumns[0]}:${patterns.numericColumns[0]})`,
        explanation: 'Sum all values in the column',
        references: patterns.numericColumns
      });
      
      suggestions.push({
        formula: `=AVERAGE(${patterns.numericColumns[0]}:${patterns.numericColumns[0]})`,
        explanation: 'Calculate the average of all values',
        references: patterns.numericColumns
      });
    }
    
    if (patterns.hasDates && patterns.hasNumbers) {
      suggestions.push({
        formula: `=SUMIFS(${patterns.numericColumns[0]}:${patterns.numericColumns[0]}, ${patterns.dateColumns[0]}:${patterns.dateColumns[0]}, ">="&TODAY()-30)`,
        explanation: 'Sum values from the last 30 days',
        references: [...patterns.numericColumns, ...patterns.dateColumns]
      });
    }
    
    return suggestions;
  }