parse_natural_language
Convert natural language queries into Excel formulas or commands to analyze spreadsheet data without manual formula writing.
Instructions
Convert natural language to Excel formula or command
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language query (e.g., "sum all sales", "find duplicates", "average by category") | |
| filePath | No | Path to file for context (optional) | |
| provider | No | Preferred AI provider: anthropic, openai, deepseek, gemini, or local (optional) |
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); } }