Excel Finance MCP

Instructions

Implementation Reference

• src/python/financial_reporting.py:401-440 (handler)

  Core handler implementing the comparative income statement generation. It processes multiple periods, generates individual income statements, flattens key metrics into a DataFrame, and computes period-over-period variances.
  def comparative_income_statement(self, periods: List[Tuple[date, date]]) -> pd.DataFrame: """Generate comparative income statement for multiple periods""" statements = [] for start_date, end_date in periods: stmt = self.generate_income_statement(start_date, end_date) period_name = f"{start_date.strftime('%Y-%m')} to {end_date.strftime('%Y-%m')}" # Flatten the statement for comparison flattened = { 'Period': period_name, 'Total Revenue': stmt['revenue']['total'], 'Total COGS': stmt['cost_of_goods_sold']['total'], 'Gross Profit': stmt['gross_profit'], 'Gross Margin %': stmt['gross_margin_pct'], 'Operating Expenses': stmt['operating_expenses']['total'], 'Operating Income': stmt['operating_income'], 'Operating Margin %': stmt['operating_margin_pct'], 'Net Income': stmt['net_income'], 'Net Margin %': stmt['net_margin_pct'] } statements.append(flattened) df = pd.DataFrame(statements) # Add variance columns if we have multiple periods if len(statements) > 1: for i in range(1, len(statements)): period_name = df.iloc[i]['Period'] prev_period_name = df.iloc[i-1]['Period'] for col in ['Total Revenue', 'Gross Profit', 'Operating Income', 'Net Income']: current_value = df.iloc[i][col] previous_value = df.iloc[i-1][col] if previous_value != 0: variance_pct = ((current_value - previous_value) / abs(previous_value)) * 100 df.loc[i, f'{col} Variance %'] = round(variance_pct, 2) return df
• src/tools/reporting-tools.ts:141-158 (schema)

  Input schema defining the expected parameters: array of periods (each with startDate and endDate), optional outputToExcel and filePath.
  type: "object", properties: { periods: { type: "array", items: { type: "object", properties: { startDate: { type: "string", format: "date" }, endDate: { type: "string", format: "date" } }, required: ["startDate", "endDate"] } }, outputToExcel: { type: "boolean", default: false }, filePath: { type: "string" } }, required: ["periods"] },
• src/tools/reporting-tools.ts:137-177 (registration)

  MCP tool registration in the reportingTools array, including name, description, schema, and TypeScript handler that converts input periods to tuples and calls the Python FinancialReportGenerator.comparative_income_statement method via bridge.
  { name: "comparative_income_statement", description: "Generate comparative income statement for multiple periods", inputSchema: { type: "object", properties: { periods: { type: "array", items: { type: "object", properties: { startDate: { type: "string", format: "date" }, endDate: { type: "string", format: "date" } }, required: ["startDate", "endDate"] } }, outputToExcel: { type: "boolean", default: false }, filePath: { type: "string" } }, required: ["periods"] }, handler: async (args: any): Promise<ToolResult> => { try { const periodTuples = args.periods.map((p: any) => [p.startDate, p.endDate]); const result = await pythonBridge.callPythonFunction({ module: 'financial_reporting', function: 'FinancialReportGenerator.comparative_income_statement', args: [periodTuples] }); return result; } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; } } },