terminal_launch
Initiate a new terminal session with customizable command, width, and height settings through a virtual X11 display, enabling AI agents to interact with terminal-based applications efficiently.
Instructions
Launch a new terminal session with virtual X11 display
Args: command: Command to run in terminal (default: bash) width: Terminal width in characters (default: 80) height: Terminal height in characters (default: 24)
Returns: Dictionary with session_id and status
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | No | bash | |
| height | No | ||
| width | No |
Implementation Reference
- src/terminal_control_mcp/server.py:20-54 (handler)The handler function for 'terminal_launch' tool, decorated with @mcp.tool() which also serves as registration. Creates and starts an XTermSession instance, stores it in the global sessions dictionary, and returns session details or error.@mcp.tool() async def terminal_launch( command: str = "bash", width: int = 80, height: int = 24 ) -> Dict[str, Any]: """Launch a new terminal session with virtual X11 display Args: command: Command to run in terminal (default: bash) width: Terminal width in characters (default: 80) height: Terminal height in characters (default: 24) Returns: Dictionary with session_id and status """ try: session = XTermSession(command=command, width=width, height=height) await session.start() session_id = session.session_id sessions[session_id] = session logger.info( f"Launched terminal session {session_id} with command: {command}" ) return { "session_id": session_id, "status": "launched", "command": command, "width": width, "height": height, } except Exception as e: logger.error(f"Failed to launch terminal session: {e}") return {"status": "error", "error": str(e)}
- Input schema defined by function parameters (command, width, height) and output as Dict[str, Any], with detailed docstring.async def terminal_launch( command: str = "bash", width: int = 80, height: int = 24 ) -> Dict[str, Any]: """Launch a new terminal session with virtual X11 display Args: command: Command to run in terminal (default: bash) width: Terminal width in characters (default: 80) height: Terminal height in characters (default: 24) Returns: Dictionary with session_id and status """
- Core helper method XTermSession.start() called by terminal_launch handler to launch Xvfb virtual display and xterm process.async def start(self): """Start the virtual display and xterm session""" try: await self._start_virtual_display() await self._start_xterm() self.is_running = True logger.info(f"Session {self.session_id} started successfully") except Exception as e: logger.error(f"Failed to start session {self.session_id}: {e}") await self.cleanup() raise
- Helper method to find free X11 display for the virtual terminal session.def _find_free_display(self, start: int = 100, max_attempts: int = 100) -> str: """Find a free X11 display number by checking socket files""" for display_num in range(start, start + max_attempts): socket_path = f"/tmp/.X11-unix/X{display_num}" if not os.path.exists(socket_path): logger.debug(f"Found free display: :{display_num}") return f":{display_num}" # Fallback to a high number if all checked ports are taken fallback_display = start + max_attempts logger.warning(f"All displays {start}-{start + max_attempts - 1} appear taken, using :{fallback_display}") return f":{fallback_display}"