Excel Finance MCP

Instructions

Implementation Reference

• src/python/financial_reporting.py:353-399 (handler)

  Core handler implementing the trial balance generation logic by calculating debit/credit balances for each account as of the given date and returning a pandas DataFrame.
  def generate_trial_balance(self, as_of_date: date) -> pd.DataFrame: """Generate trial balance""" account_balances = self._calculate_account_balances(as_of_date) trial_balance_items = [] total_debits = 0 total_credits = 0 for account_number, balance in account_balances.items(): account = self.chart_of_accounts.get(account_number) if not account or balance == 0: continue # Determine normal balance based on account type normal_debit_accounts = [AccountType.ASSET, AccountType.EXPENSE, AccountType.COGS] if account.account_type in normal_debit_accounts: debit_balance = max(0, balance) credit_balance = max(0, -balance) else: debit_balance = max(0, -balance) credit_balance = max(0, balance) trial_balance_items.append({ 'Account Number': account_number, 'Account Name': account.account_name, 'Account Type': account.account_type.value, 'Debit': round(debit_balance, 2) if debit_balance > 0 else None, 'Credit': round(credit_balance, 2) if credit_balance > 0 else None }) total_debits += debit_balance total_credits += credit_balance # Add totals row trial_balance_items.append({ 'Account Number': '', 'Account Name': 'TOTALS', 'Account Type': '', 'Debit': round(total_debits, 2), 'Credit': round(total_credits, 2) }) df = pd.DataFrame(trial_balance_items) df['Balanced'] = abs(total_debits - total_credits) < 0.01 return df
• src/tools/reporting-tools.ts:99-134 (handler)

  MCP tool handler that calls the Python FinancialReportGenerator.generate_trial_balance method and handles optional Excel export.
  handler: async (args: any): Promise<ToolResult> => { try { const result = await pythonBridge.callPythonFunction({ module: 'financial_reporting', function: 'FinancialReportGenerator.generate_trial_balance', args: [args.asOfDate] }); if (args.outputToExcel && result.success && args.filePath) { const trialBalance = result.data; const worksheetData: WorksheetData = { name: 'Trial Balance', data: [ ['Account Number', 'Account Name', 'Account Type', 'Debit', 'Credit'], ...trialBalance.map((row: any) => [ row['Account Number'], row['Account Name'], row['Account Type'], row['Debit'] || '', row['Credit'] || '' ]) ] }; await excelManager.createWorkbook([worksheetData]); await excelManager.saveWorkbook(args.filePath); } return result; } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; } }
• src/tools/reporting-tools.ts:90-98 (schema)

  Input schema validating the tool parameters: required asOfDate (date string), optional outputToExcel (boolean), and filePath (string).
  inputSchema: { type: "object", properties: { asOfDate: { type: "string", format: "date" }, outputToExcel: { type: "boolean", default: false }, filePath: { type: "string" } }, required: ["asOfDate"] },
• src/tools/reporting-tools.ts:87-135 (registration)

  Registration of the generate_trial_balance tool within the reportingTools export array.
  { name: "generate_trial_balance", description: "Generate Trial Balance as of specified date", inputSchema: { type: "object", properties: { asOfDate: { type: "string", format: "date" }, outputToExcel: { type: "boolean", default: false }, filePath: { type: "string" } }, required: ["asOfDate"] }, handler: async (args: any): Promise<ToolResult> => { try { const result = await pythonBridge.callPythonFunction({ module: 'financial_reporting', function: 'FinancialReportGenerator.generate_trial_balance', args: [args.asOfDate] }); if (args.outputToExcel && result.success && args.filePath) { const trialBalance = result.data; const worksheetData: WorksheetData = { name: 'Trial Balance', data: [ ['Account Number', 'Account Name', 'Account Type', 'Debit', 'Credit'], ...trialBalance.map((row: any) => [ row['Account Number'], row['Account Name'], row['Account Type'], row['Debit'] || '', row['Credit'] || '' ]) ] }; await excelManager.createWorkbook([worksheetData]); await excelManager.saveWorkbook(args.filePath); } return result; } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; } } },
• src/python/financial_reporting.py:326-351 (helper)

  Helper function used by generate_trial_balance to compute cumulative account balances from journal entries up to the as_of_date.
  def _calculate_account_balances(self, as_of_date: date) -> Dict[str, float]: """Calculate account balances as of a specific date""" balances = {} # Initialize all accounts with zero balance for account_number in self.chart_of_accounts.keys(): balances[account_number] = 0 # Process journal entries up to the date for entry in self.journal_entries: if not entry.posted or entry.date > as_of_date: continue if entry.debits: for account_number, amount in entry.debits: if account_number not in balances: balances[account_number] = 0 balances[account_number] += amount if entry.credits: for account_number, amount in entry.credits: if account_number not in balances: balances[account_number] = 0 balances[account_number] -= amount return balances