Excel Finance MCP

Instructions

Implementation Reference

• src/tools/expense-tools.ts:167-181 (handler)

  MCP tool handler function that bridges to Python ExpenseTracker.expense_forecast method via PythonBridge
  handler: async (args: any): Promise<ToolResult> => { try { const result = await pythonBridge.callPythonFunction({ module: 'expense_tracking', function: 'ExpenseTracker.expense_forecast', args: [args.monthsAhead || 12] }); return result; } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; } }
• src/python/expense_tracking.py:245-301 (helper)

  Core implementation of expense forecasting using historical data, weighted moving averages of last 3/6/12 months, and seasonal adjustments
  def expense_forecast(self, months_ahead: int = 12) -> pd.DataFrame: """Forecast future expenses based on historical data""" # Get last 12 months of data end_date = date.today() start_date = end_date - timedelta(days=365) historical_expenses = [ e for e in self.expenses if start_date <= e.date <= end_date ] if not historical_expenses: return pd.DataFrame() # Create monthly aggregations df = pd.DataFrame([{ 'Date': e.date, 'Amount': e.amount, 'Category': e.category.value, 'Recurring': e.recurring } for e in historical_expenses]) df['Month'] = pd.to_datetime(df['Date']).dt.to_period('M') monthly_totals = df.groupby('Month')['Amount'].sum() # Simple moving average forecast forecast_data = [] last_3_months_avg = monthly_totals.tail(3).mean() last_6_months_avg = monthly_totals.tail(6).mean() last_12_months_avg = monthly_totals.mean() for i in range(1, months_ahead + 1): forecast_month = end_date + timedelta(days=30*i) # Weight recent data more heavily forecast_amount = ( last_3_months_avg * 0.5 + last_6_months_avg * 0.3 + last_12_months_avg * 0.2 ) # Add seasonal adjustment (simplified) month_num = forecast_month.month seasonal_factor = 1.0 if month_num in [11, 12]: # Higher expenses in Nov/Dec seasonal_factor = 1.15 elif month_num in [7, 8]: # Lower in summer seasonal_factor = 0.9 forecast_data.append({ 'Month': forecast_month.strftime('%Y-%m'), 'Forecast': round(forecast_amount * seasonal_factor, 2), 'Low Estimate': round(forecast_amount * seasonal_factor * 0.9, 2), 'High Estimate': round(forecast_amount * seasonal_factor * 1.1, 2) }) return pd.DataFrame(forecast_data)
• src/tools/expense-tools.ts:161-166 (schema)

  Input schema for the expense_forecast tool defining optional monthsAhead parameter
  inputSchema: { type: "object", properties: { monthsAhead: { type: "number", default: 12 } } },
• src/tools/expense-tools.ts:158-182 (registration)

  Tool registration in expenseTools array including name, description, schema, and handler
  { name: "expense_forecast", description: "Forecast future expenses based on historical data", inputSchema: { type: "object", properties: { monthsAhead: { type: "number", default: 12 } } }, handler: async (args: any): Promise<ToolResult> => { try { const result = await pythonBridge.callPythonFunction({ module: 'expense_tracking', function: 'ExpenseTracker.expense_forecast', args: [args.monthsAhead || 12] }); return result; } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; } } },
• src/index.ts:36-36 (registration)

  expenseTools array spread into main allTools list used by MCP server for tool listing and execution
  ...expenseTools,