Excel MCP Server

Instructions

Implementation Reference

• src/handlers/ai-operations.ts:131-194 (handler)

  The primary handler function for the 'parse_natural_language' tool. Processes input arguments, loads optional file context, invokes NLPProcessor for command parsing and formula building, and returns a structured ToolResponse with results.

  async parseNaturalLanguage(args: ToolArgs): Promise<ToolResponse> {
    const { query, filePath, provider } = args;
  
    try {
      // Get file context if provided
      let context = undefined;
      if (filePath) {
        try {
          const data = await readFileContent(filePath);
          context = {
            headers: data[0],
            rowCount: data.length,
            columnCount: data[0]?.length || 0,
            dataTypes: detectDataTypes(data),
            activeCell: 'A1',
            selectedRange: 'A1:A1'
          };
        } catch (error) {
          // File context is optional, continue without it
        }
      }
  
      // Parse the natural language query
      const result = await this.nlpProcessor.parseCommand(query, context, provider);
  
      // If it's a formula, also try to build the actual formula
      let formulaResult = undefined;
      if (result.type === 'formula') {
        try {
          formulaResult = await this.nlpProcessor.buildFormula(query, context, provider);
        } catch (formulaError) {
          // Formula building failed, continue with just the command
        }
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              query,
              result: result, // Keep the command result in 'result' field for consistency
              formula: formulaResult,
              success: true,
              provider: this.nlpProcessor.getActiveProvider()?.name || 'Local'
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              query,
              error: error instanceof Error ? error.message : 'Unknown error',
              success: false
            }, null, 2),
          },
        ],
      };
    }
  }

• src/index.ts:861-882 (schema)

  Defines the tool schema including name, description, and inputSchema with properties query (required), filePath, and provider for the ListToolsRequest response.

    name: 'parse_natural_language',
    description: 'Convert natural language to Excel formula or command',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Natural language query (e.g., "sum all sales", "find duplicates", "average by category")',
        },
        filePath: {
          type: 'string',
          description: 'Path to file for context (optional)',
        },
        provider: {
          type: 'string',
          description: 'Preferred AI provider: anthropic, openai, deepseek, gemini, or local (optional)',
          enum: ['anthropic', 'openai', 'deepseek', 'gemini', 'local'],
        },
      },
      required: ['query'],
    },
  },

• src/index.ts:1260-1261 (registration)

  Registers the tool in the CallToolRequest handler by mapping the tool name to the AIOperationsHandler.parseNaturalLanguage method.

    return await this.aiOpsHandler.parseNaturalLanguage(toolArgs);
  case 'explain_formula':

• src/ai/nlp-processor.ts:49-66 (helper)

  Core helper method in NLPProcessor that parses natural language into structured NLPCommand using AI completion with context-aware prompts and fallback parsing.

  async parseCommand(text: string, context?: WorksheetContext, preferredProvider?: ProviderType): Promise<NLPCommand> {
    const prompt = this.buildCommandPrompt(text, context);
  
    try {
      const response = await this.aiManager.createCompletion([
        { role: 'user', content: prompt }
      ], {
        systemPrompt: this.getSystemPrompt(),
        maxTokens: 1000,
        temperature: 0,
        preferredProvider
      });
  
      return this.parseCommandResponse(response.content);
    } catch (error) {
      return this.fallbackParser(text);
    }
  }