budget_variance_analysis
Calculate and analyze differences between budgeted and actual financial performance to identify variances and support decision-making.
Instructions
Analyze budget vs actual performance with variance calculations
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to the CSV or Excel file with budget and actual data | |
| sheet | No | Sheet name for Excel files (optional) | |
| actualColumn | Yes | Column name or index containing actual values | |
| budgetColumn | Yes | Column name or index containing budget values |
Implementation Reference
- The budgetVarianceAnalysis method implements the core logic for budget variance analysis. It reads the file content, locates the actual and budget columns, computes absolute and percentage variances for each category, determines favorable/unfavorable status, and returns a structured JSON response with summary statistics and detailed variances.
async budgetVarianceAnalysis(args: ToolArgs): Promise<ToolResponse> { const { filePath, sheet, actualColumn, budgetColumn } = args; try { const data = await readFileContent(filePath, sheet); if (data.length <= 1) { throw new Error('File has no data rows'); } const headers = data[0]; const actualIdx = isNaN(Number(actualColumn)) ? headers.indexOf(actualColumn) : Number(actualColumn); const budgetIdx = isNaN(Number(budgetColumn)) ? headers.indexOf(budgetColumn) : Number(budgetColumn); if (actualIdx === -1 || budgetIdx === -1) { throw new Error('Actual or budget column not found'); } const variances = []; let totalVariance = 0; for (let i = 1; i < data.length; i++) { const category = data[i][0] || `Row ${i}`; const actual = Number(data[i][actualIdx]) || 0; const budget = Number(data[i][budgetIdx]) || 0; const variance = actual - budget; const variancePercent = budget !== 0 ? (variance / budget) * 100 : 0; variances.push({ category, actual, budget, variance, variancePercent: Math.round(variancePercent * 100) / 100, status: variance >= 0 ? 'Favorable' : 'Unfavorable' }); totalVariance += variance; } return { content: [{ type: 'text', text: JSON.stringify({ success: true, analysis: 'Budget Variance Analysis', summary: { totalVariance, categories: variances.length, favorableCount: variances.filter(v => v.variance >= 0).length, unfavorableCount: variances.filter(v => v.variance < 0).length }, details: variances }, null, 2) }] }; } catch (error) { return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : 'Unknown error', operation: 'budget_variance_analysis' }, null, 2) }] }; } } - src/index.ts:425-449 (schema)Defines the input schema and metadata for the budget_variance_analysis tool in the MCP tools list returned by ListToolsRequestSchema.
name: 'budget_variance_analysis', description: 'Analyze budget vs actual performance with variance calculations', inputSchema: { type: 'object', properties: { filePath: { type: 'string', description: 'Path to the CSV or Excel file with budget and actual data' }, sheet: { type: 'string', description: 'Sheet name for Excel files (optional)' }, actualColumn: { type: 'string', description: 'Column name or index containing actual values' }, budgetColumn: { type: 'string', description: 'Column name or index containing budget values' } }, required: ['filePath', 'actualColumn', 'budgetColumn'] } }, - src/index.ts:1233-1234 (registration)Registers the dispatch for budget_variance_analysis tool calls to the FinancialAnalysisHandler.budgetVarianceAnalysis method in the MCP CallToolRequestSchema handler.
case 'budget_variance_analysis': return await this.financialHandler.budgetVarianceAnalysis(toolArgs);