Excel Finance MCP

Instructions

Implementation Reference

• src/tools/reporting-tools.ts:61-84 (handler)

  Primary MCP tool handler: calls Python backend via bridge, optionally formats and exports balance sheet to Excel file.
  handler: async (args: any): Promise<ToolResult> => { try { const result = await pythonBridge.callPythonFunction({ module: 'financial_reporting', function: 'FinancialReportGenerator.generate_balance_sheet', args: [args.asOfDate] }); if (args.outputToExcel && result.success && args.filePath) { const balanceSheet = result.data; const worksheetData = formatBalanceSheetForExcel(balanceSheet); 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:52-60 (schema)

  Input schema validation: requires asOfDate, optional Excel output parameters.
  inputSchema: { type: "object", properties: { asOfDate: { type: "string", format: "date" }, outputToExcel: { type: "boolean", default: false }, filePath: { type: "string" } }, required: ["asOfDate"] },
• src/tools/reporting-tools.ts:49-85 (registration)

  Tool registration in reportingTools export array, defining name, description, schema, and handler.
  { name: "generate_balance_sheet", description: "Generate Balance Sheet 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_balance_sheet', args: [args.asOfDate] }); if (args.outputToExcel && result.success && args.filePath) { const balanceSheet = result.data; const worksheetData = formatBalanceSheetForExcel(balanceSheet); 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:246-325 (helper)

  Backend Python implementation: computes balance sheet from cumulative journal entries up to as_of_date, organizes into assets/liabilities/equity.
  def generate_balance_sheet(self, as_of_date: date) -> Dict: """Generate Balance Sheet""" # Calculate account balances as of date account_balances = self._calculate_account_balances(as_of_date) # Organize by balance sheet sections current_assets = [] fixed_assets = [] current_liabilities = [] long_term_liabilities = [] equity_accounts = [] for account_number, balance in account_balances.items(): account = self.chart_of_accounts.get(account_number) if not account or balance == 0: continue item = { 'account_number': account_number, 'account_name': account.account_name, 'amount': round(balance, 2) } if account.account_type == AccountType.ASSET: if account.account_subtype == AccountSubtype.CURRENT_ASSET: current_assets.append(item) else: fixed_assets.append(item) elif account.account_type == AccountType.LIABILITY: if account.account_subtype == AccountSubtype.CURRENT_LIABILITY: current_liabilities.append(item) else: long_term_liabilities.append(item) elif account.account_type == AccountType.EQUITY: equity_accounts.append(item) # Calculate totals total_current_assets = sum(item['amount'] for item in current_assets) total_fixed_assets = sum(item['amount'] for item in fixed_assets) total_assets = total_current_assets + total_fixed_assets total_current_liabilities = sum(item['amount'] for item in current_liabilities) total_long_term_liabilities = sum(item['amount'] for item in long_term_liabilities) total_liabilities = total_current_liabilities + total_long_term_liabilities total_equity = sum(item['amount'] for item in equity_accounts) return { 'statement_type': 'Balance Sheet', 'as_of_date': as_of_date.isoformat(), 'assets': { 'current_assets': { 'line_items': current_assets, 'total': round(total_current_assets, 2) }, 'fixed_assets': { 'line_items': fixed_assets, 'total': round(total_fixed_assets, 2) }, 'total_assets': round(total_assets, 2) }, 'liabilities': { 'current_liabilities': { 'line_items': current_liabilities, 'total': round(total_current_liabilities, 2) }, 'long_term_liabilities': { 'line_items': long_term_liabilities, 'total': round(total_long_term_liabilities, 2) }, 'total_liabilities': round(total_liabilities, 2) }, 'equity': { 'line_items': equity_accounts, 'total': round(total_equity, 2) }, 'total_liabilities_and_equity': round(total_liabilities + total_equity, 2), 'balanced': abs(total_assets - (total_liabilities + total_equity)) < 0.01 }
• src/tools/reporting-tools.ts:403-458 (helper)

  Helper function to format balance sheet data into Excel WorksheetData structure.
  function formatBalanceSheetForExcel(balanceSheet: any): WorksheetData { const data: any[][] = [ ['BALANCE SHEET', '', ''], [`As of: ${balanceSheet.as_of_date}`, '', ''], ['', '', ''], ['ASSETS', '', ''], ['Current Assets:', '', ''], ...balanceSheet.assets.current_assets.line_items.map((item: any) => [ ` ${item.account_name}`, '', item.amount ]), ['Total Current Assets', '', balanceSheet.assets.current_assets.total], ['', '', ''], ['Fixed Assets:', '', ''], ...balanceSheet.assets.fixed_assets.line_items.map((item: any) => [ ` ${item.account_name}`, '', item.amount ]), ['Total Fixed Assets', '', balanceSheet.assets.fixed_assets.total], ['', '', ''], ['TOTAL ASSETS', '', balanceSheet.assets.total_assets], ['', '', ''], ['LIABILITIES & EQUITY', '', ''], ['Current Liabilities:', '', ''], ...balanceSheet.liabilities.current_liabilities.line_items.map((item: any) => [ ` ${item.account_name}`, '', item.amount ]), ['Total Current Liabilities', '', balanceSheet.liabilities.current_liabilities.total], ['', '', ''], ['Long-term Liabilities:', '', ''], ...balanceSheet.liabilities.long_term_liabilities.line_items.map((item: any) => [ ` ${item.account_name}`, '', item.amount ]), ['Total Long-term Liabilities', '', balanceSheet.liabilities.long_term_liabilities.total], ['', '', ''], ['Total Liabilities', '', balanceSheet.liabilities.total_liabilities], ['', '', ''], ['Equity:', '', ''], ...balanceSheet.equity.line_items.map((item: any) => [ ` ${item.account_name}`, '', item.amount ]), ['Total Equity', '', balanceSheet.equity.total], ['', '', ''], ['TOTAL LIABILITIES & EQUITY', '', balanceSheet.total_liabilities_and_equity], ['', '', ''], ['Balanced:', '', balanceSheet.balanced ? 'YES' : 'NO'] ]; return { name: 'Balance Sheet', data: data, columns: [ { header: 'Item', key: 'item', width: 30 }, { header: 'Notes', key: 'notes', width: 20 }, { header: 'Amount', key: 'amount', width: 15 } ] }; }