FlexSim MCP Server

Instructions

Args:
    steps: Number of events to step (1-1000, default: 1)

Example:
    steps=10  # Advance 10 events

Implementation Reference

• mcp_server/flexsim_mcp.py:338-363 (handler)

  Main handler function for flexsim_step tool. Steps through simulation events by executing FlexScript step() command N times. Gets the FlexSim controller, records start time, loops through the specified number of steps calling controller.evaluate('step()'), then returns formatted time progress.

  @mcp.tool()
  async def flexsim_step(params: StepInput) -> str:
      """Step through simulation events.
  
      Args:
          steps: Number of events to step (1-1000, default: 1)
  
      Example:
          steps=10  # Advance 10 events
      """
      try:
          controller = await get_controller()
          start = controller.time()
  
          # Use FlexScript step() command since Controller doesn't have native step method
          for _ in range(params.steps):
              controller.evaluate("step()")
  
          end = controller.time()
  
          return (
              f"✓ Stepped {params.steps} events\n"
              f"Time: {format_time(start)} → {format_time(end)}"
          )
      except Exception as e:
          return format_error(e)

• mcp_server/flexsim_mcp.py:104-106 (schema)

  Pydantic input schema for flexsim_step tool. Validates steps parameter as an integer between 1 and 1000, with default value of 1.

  class StepInput(BaseModel):
      """Input for stepping simulation."""
      steps: int = Field(default=1, ge=1, le=1000)

• mcp_server/flexsim_mcp.py:147-154 (helper)

  Controller management function that lazily initializes the FlexSim controller instance. Uses async lock for thread safety. Returns existing controller or launches new FlexSim instance if needed.

  async def get_controller():
      """Get or create the FlexSim controller instance."""
      global _controller
  
      async with _controller_lock:
          if _controller is None:
              _controller = await launch_flexsim()
          return _controller

• mcp_server/flexsim_mcp.py:119-126 (helper)

  Utility function that formats simulation time in seconds into human-readable format (seconds, minutes, or hours based on magnitude).

  def format_time(seconds: float) -> str:
      """Format simulation time as human-readable string."""
      if seconds < 60:
          return f"{seconds:.2f}s"
      elif seconds < 3600:
          return f"{seconds/60:.2f}m"
      else:
          return f"{seconds/3600:.2f}h"

• mcp_server/flexsim_mcp.py:129-140 (helper)

  Error formatting utility that converts exceptions into user-friendly error messages. Handles common FlexSim error types like not found, syntax, license, and permission errors.

  def format_error(e: Exception) -> str:
      """Format exception as user-friendly error message."""
      msg = str(e)
      if "not found" in msg.lower():
          return f"Not found: {msg}"
      elif "syntax" in msg.lower():
          return f"FlexScript syntax error: {msg}"
      elif "license" in msg.lower():
          return f"License error: {msg}"
      elif "permission" in msg.lower():
          return f"Permission denied: {msg}"
      return f"Error: {msg}"