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'], }, },