Excel MCP Server

Instructions

Implementation Reference

• src/handlers/ai-operations.ts:45-129 (handler)

  Main handler function for the 'evaluate_formula' tool. Parses the input formula, constructs a WorkbookContext adapter for cell/range lookups, evaluates using FormulaEvaluator, handles circular reference detection, and returns structured JSON response with result or error.

  async evaluateFormula(args: ToolArgs): Promise<ToolResponse> {
    const { formula, context = {} } = args;
  
    try {
      // Parse the formula
      const ast = parseFormula(formula);
  
      // Create a workbook context from the provided context
      const workbookContext: WorkbookContext = {
        getCellValue: (reference: string) => {
          const value = context[reference] || 0;
  
          // If the value is a formula, detect potential circular references
          if (typeof value === 'string' && value.startsWith('=')) {
            // This is a formula reference, check for circular references
            if (value === formula) {
              throw new Error('Circular reference detected');
            }
            // For formulas that reference the same cell, also check
            if (value.includes(reference)) {
              throw new Error('Circular reference detected');
            }
          }
  
          return value;
        },
        getNamedRangeValue: (name: string) => {
          return context[name] || 0;
        },
        getRangeValues: (range: string) => {
          // Check if range is already provided in context
          if (context[range]) {
            return context[range];
          }
  
          // Try to expand the range from individual cells
          const expanded = this.expandRange(range, context);
          return expanded;
        },
        getSheetCellValue: (sheetName: string, reference: string) => {
          // For sheet references, try to get from context using proper Excel sheet!reference format
          const key = `${sheetName}!${reference}`;
          return context[key] || context[reference] || 0;
        },
        getSheetRangeValues: (sheetName: string, range: string) => {
          // For sheet range references, try to get from context using proper Excel sheet!range format
          const key = `${sheetName}!${range}`;
          return context[key] || context[range] || [];
        }
      };
  
      // Evaluate the formula
      const result = this.formulaEvaluator.evaluate(ast, workbookContext);
  
      // Check if result is an error
      const isError = typeof result === 'string' && result.startsWith('#');
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              formula,
              result,
              success: !isError,
              ...(isError && { error: result })
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              formula,
              error: error instanceof Error ? error.message : 'Unknown error',
              success: false
            }, null, 2),
          },
        ],
      };
    }
  }

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

  Tool dispatch registration in the CallToolRequestSchema handler switch statement, mapping 'evaluate_formula' to AIOperationsHandler.evaluateFormula method.

  case 'evaluate_formula':
    return await this.aiOpsHandler.evaluateFormula(toolArgs);
  case 'parse_natural_language':
    return await this.aiOpsHandler.parseNaturalLanguage(toolArgs);
  case 'explain_formula':
    return await this.aiOpsHandler.explainFormula(toolArgs);
  case 'ai_provider_status':
    return await this.aiOpsHandler.getAIProviderStatus(toolArgs);
  case 'smart_data_analysis':
    return await this.aiOpsHandler.smartDataAnalysis(toolArgs);

• src/index.ts:842-859 (schema)

  Input schema definition for the 'evaluate_formula' tool registered in ListToolsRequestSchema, defining required 'formula' string and optional 'context' object.

    name: 'evaluate_formula',
    description: 'Evaluate an Excel formula with given context',
    inputSchema: {
      type: 'object',
      properties: {
        formula: {
          type: 'string',
          description: 'Excel formula to evaluate (e.g., "=SUM(A1:A10)", "=VLOOKUP(B2,C:D,2,FALSE)")',
        },
        context: {
          type: 'object',
          description: 'Cell values and ranges for formula evaluation (optional)',
          additionalProperties: true,
        },
      },
      required: ['formula'],
    },
  },