monte_carlo_simulation

Instructions

Runs a Monte Carlo simulation using Geometric Brownian Motion (Log Returns).

Args:
    simulations: Number of paths to simulate.
    days: Number of days to project forward.
    visualize: If True, returns a histogram of final outcomes.

Implementation Reference

• tools/risk_engine.py:77-148 (handler)

  The core handler function for the 'monte_carlo_simulation' MCP tool. Performs Monte Carlo simulation of portfolio returns over specified days using geometric Brownian motion with correlated log returns via Cholesky decomposition of the covariance matrix. Supports visualization.

  def monte_carlo_simulation(simulations: int = 1000, days: int = 252, visualize: bool = False) -> str:
      """
      Runs a Monte Carlo simulation using Geometric Brownian Motion (Log Returns).
      
      Args:
          simulations: Number of paths to simulate.
          days: Number of days to project forward.
          visualize: If True, returns a histogram of final outcomes.
      """
      data, weights = _get_portfolio_data()
      if data is None:
          return "Portfolio is empty."
      
      # Use Log Returns for additivity
      log_returns = np.log(data / data.shift(1)).dropna()
      
      mean_log_returns = log_returns.mean()
      cov_matrix = log_returns.cov()
      
      # Cholesky Decomposition
      try:
          L = np.linalg.cholesky(cov_matrix)
      except np.linalg.LinAlgError:
          # Fallback for non-positive definite matrix (e.g., too few data points)
          return "Covariance matrix is not positive definite. Insufficient data history."
      
      portfolio_sims = np.zeros((days, simulations))
      initial_value = 1.0 
      
      for i in range(simulations):
          Z = np.random.normal(size=(days, len(weights)))
          # Correlated random shocks
          daily_shocks = np.dot(Z, L.T)
          
          # GBM: S_t = S_0 * exp( (mu - 0.5*sigma^2)*t + sigma*W_t )
          # Here we simulate daily steps
          daily_log_ret = mean_log_returns.values + daily_shocks
          
          # Portfolio level log return
          port_log_ret = np.dot(daily_log_ret, weights)
          
          # Accumulate log returns
          cum_log_ret = np.cumsum(port_log_ret)
          portfolio_sims[:, i] = initial_value * np.exp(cum_log_ret)
          
      final_values = portfolio_sims[-1, :]
      returns = (final_values - 1) * 100  # Convert to percentage
      expected_return = np.mean(final_values) - 1
      worst_case = np.percentile(final_values, 5) - 1
      best_case = np.percentile(final_values, 95) - 1
      
      result = (f"Monte Carlo Results ({simulations} sims, {days} days) [Log Normal]:\n"
              f"Expected Return: {expected_return:.2%}\n"
              f"5th Percentile (VaR 95%): {worst_case:.2%}\n"
              f"95th Percentile (Upside): {best_case:.2%}")
      
      if visualize:
          try:
              from tools.visualizer import plot_histogram
              chart = plot_histogram(
                  returns,
                  bins=50,
                  title=f"Monte Carlo Simulation - {simulations} Paths ({days} days)",
                  x_label="Return (%)",
                  percentiles=[5, 50, 95]
              )
              result += f"\n\n{chart}"
          except Exception as e:
              logger.error(f"Error generating visualization: {e}")
              result += f"\n(Visualization error: {str(e)})"
      
      return result

• server.py:380-383 (registration)

  Registers 'monte_carlo_simulation' as an MCP tool via the register_tools helper function, which applies @mcp.tool() decorator. Part of the Risk Engine tool group.

  register_tools(
      [portfolio_risk, var, max_drawdown, monte_carlo_simulation],
      "Risk Engine"
  )

• server.py:14-14 (registration)

  Imports the monte_carlo_simulation function from tools.risk_engine.py into the MCP server module for registration.

  from tools.risk_engine import portfolio_risk, var, max_drawdown, monte_carlo_simulation