Terminal Control MCP

Instructions

Implementation Reference

• src/terminal_control_mcp/server.py:20-55 (handler)

  The handler function for the 'terminal_launch' tool. It is registered via the @mcp.tool() decorator. Creates and starts a new XTermSession with the specified command, dimensions, stores it in the sessions dict, 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)}

• src/terminal_control_mcp/server.py:20-20 (registration)

  The @mcp.tool() decorator registers the terminal_launch function as an MCP tool.

  @mcp.tool()

• src/terminal_control_mcp/server.py:21-32 (schema)

  Type hints and docstring define the input schema (command, width, height) and output (dict with session_id, status).

  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