Excel Finance MCP

Instructions

Implementation Reference

• src/tools/cash-flow-tools.ts:132-146 (handler)

  MCP tool handler that invokes the Python cash_flow_at_risk function via the Python bridge, handling args and errors.
  handler: async (args: any): Promise<ToolResult> => { try { const result = await pythonBridge.callPythonFunction({ module: 'cash_flow_tools', function: 'cash_flow_at_risk', args: [args.confidenceLevel || 0.95] }); return result; } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; } }
• src/tools/cash-flow-tools.ts:126-131 (schema)

  Input schema defining the confidenceLevel parameter for the cash_flow_at_risk tool.
  inputSchema: { type: "object", properties: { confidenceLevel: { type: "number", default: 0.95, minimum: 0.01, maximum: 0.99 } } },
• src/tools/cash-flow-tools.ts:123-147 (registration)

  Tool registration object in the cashFlowTools array, defining name, description, schema, and handler for cash_flow_at_risk.
  { name: "cash_flow_at_risk", description: "Calculate Cash Flow at Risk (CFaR) metric", inputSchema: { type: "object", properties: { confidenceLevel: { type: "number", default: 0.95, minimum: 0.01, maximum: 0.99 } } }, handler: async (args: any): Promise<ToolResult> => { try { const result = await pythonBridge.callPythonFunction({ module: 'cash_flow_tools', function: 'cash_flow_at_risk', args: [args.confidenceLevel || 0.95] }); return result; } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; } } },
• src/python/cash_flow_analysis.py:420-448 (helper)

  Core helper function in CashFlowAnalyzer class that computes Cash Flow at Risk using historical daily cash flows and numpy percentile for VaR calculation.
  def cash_flow_at_risk(self, confidence_level: float = 0.95) -> Dict: """Calculate Cash Flow at Risk (CFaR) - similar to VaR for investments""" if len(self.cash_flows) < 30: # Need sufficient data return {'error': 'Insufficient historical data for CFaR calculation'} # Calculate daily cash flows daily_flows = {} for cf in self.cash_flows: date_key = cf.date.isoformat() if date_key not in daily_flows: daily_flows[date_key] = 0 flow_amount = cf.amount * (1 if cf.direction == CashFlowDirection.INFLOW else -1) daily_flows[date_key] += flow_amount # Calculate percentiles flow_values = list(daily_flows.values()) var_percentile = (1 - confidence_level) * 100 cash_flow_at_risk = np.percentile(flow_values, var_percentile) expected_shortfall = np.mean([f for f in flow_values if f <= cash_flow_at_risk]) return { 'confidence_level': f"{confidence_level * 100}%", 'cash_flow_at_risk': round(cash_flow_at_risk, 2), 'expected_shortfall': round(expected_shortfall, 2), 'volatility': round(np.std(flow_values), 2), 'interpretation': f"With {confidence_level * 100}% confidence, daily cash flow will not be worse than ${abs(cash_flow_at_risk):,.2f}" }
• src/python/cash_flow_tools.py:46-51 (helper)

  Thin wrapper function exposed to the Python bridge that creates a CashFlowAnalyzer instance and delegates to its cash_flow_at_risk method.
  def cash_flow_at_risk(confidence_level: float = 0.95) -> Dict[str, Any]: """Calculate Cash Flow at Risk (CFaR)""" from cash_flow_analysis import CashFlowAnalyzer analyzer = CashFlowAnalyzer() return analyzer.cash_flow_at_risk(confidence_level)