FlexSim MCP Server

Instructions

Args:
    target_time: Target simulation time in seconds
    fast_mode: Run at maximum speed (default: True). Set to False for real-time GUI updates.

Example:
    target_time=3600  # Run for 1 hour

Implementation Reference

• mcp_server/flexsim_mcp.py:268-312 (handler)

  Main implementation of flexsim_run_to_time tool. Handles both fast mode (blocking, no GUI) and real-time mode (with GUI updates) simulation running until a target time is reached.

  @mcp.tool()
  async def flexsim_run_to_time(params: RunToTimeInput) -> str:
      """Run simulation until reaching target time.
  
      Args:
          target_time: Target simulation time in seconds
          fast_mode: Run at maximum speed (default: True). Set to False for real-time GUI updates.
  
      Example:
          target_time=3600  # Run for 1 hour
      """
      try:
          controller = await get_controller()
          start = controller.time()
  
          if start >= params.target_time:
              return f"Already at time {format_time(start)}"
  
          if params.fast_mode:
              # Fast mode: blocking call at max speed (no GUI updates)
              controller.runToTime(params.target_time)
          else:
              # Real-time mode: set stop time and run with GUI animation
              controller.evaluate(f"setstoptime({params.target_time})")
              controller.run()
              
              # Poll until target time reached or simulation stops
              while True:
                  current = controller.time()
                  if current >= params.target_time:
                      controller.stop()
                      break
                  await asyncio.sleep(0.1)
  
          end = controller.time()
  
          mode_str = "fast" if params.fast_mode else "real-time"
          return (
              f"✓ Simulation complete ({mode_str})\n"
              f"Start: {format_time(start)}\n"
              f"End: {format_time(end)}\n"
              f"Duration: {format_time(end - start)}"
          )
      except Exception as e:
          return format_error(e)

• mcp_server/flexsim_mcp.py:82-86 (schema)

  Pydantic BaseModel schema defining input parameters for flexsim_run_to_time tool. Validates target_time (must be positive) and fast_mode (optional, defaults to False).

  class RunToTimeInput(BaseModel):
      """Input for running to a specific time."""
      target_time: float = Field(..., gt=0)
      fast_mode: bool = Field(default=False)

• mcp_server/flexsim_mcp.py:268-268 (registration)

  Tool registration using FastMCP's @mcp.tool() decorator, which automatically registers flexsim_run_to_time with the MCP server and generates the tool schema from the RunToTimeInput type hint.

  @mcp.tool()

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

  Helper function used by flexsim_run_to_time to format simulation time values (seconds) into human-readable strings (s/m/h).

  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:147-154 (helper)

  Helper function that lazily initializes and returns the FlexSim controller instance. Used by flexsim_run_to_time to access the FlexSim API.

  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