MCP Terminal

Instructions

Implementation Reference

• src/mcp_terminal/tools/terminal.py:160-229 (handler)

  The main handler function for the 'get_terminal_info' tool. It fetches terminal type via controller, platform info, current directory (preferring terminal pwd), user, shell, and terminal size, returning a TerminalInfoResponse.

  @mcp.tool(name="get_terminal_info", description="Gets terminal information")
  async def get_terminal_info() -> TerminalInfoResponse:
      try:
          # Ensure we have a controller
          if not self.controller:
              self._init_controller()
  
          # Get terminal type
          terminal_type = await self.controller.get_terminal_type()
  
          # Get platform
          import getpass
          import os
          import platform
          import shutil
  
          platform_name = platform.system()
  
          # Get current directory directly
          current_dir = None
          try:
              pwd_result = await self.controller.execute_command(
                  "pwd", wait_for_output=True, timeout=5
              )
              if pwd_result.get("success") and pwd_result.get("output"):
                  # Clean the output by splitting lines and finding a valid path
                  lines = pwd_result.get("output").splitlines()
                  for line in lines:
                      line = line.strip()
                      # On macOS/Linux, a valid path should start with /
                      if line.startswith("/"):
                          current_dir = line
                          break
          except Exception as e:
              logger.debug(f"Error getting current directory from terminal: {e}")
  
          # Fallback to Python's os.getcwd()
          if not current_dir:
              current_dir = os.getcwd()
  
          # Get user
          user = getpass.getuser()
  
          # Get shell
          shell = os.environ.get("SHELL", None)
  
          # Get terminal size if possible
          terminal_size = None
          try:
              cols, rows = shutil.get_terminal_size(fallback=(80, 24))
              terminal_size = {"rows": rows, "columns": cols}
          except Exception:
              pass
  
          return TerminalInfoResponse(
              terminal_type=terminal_type,
              platform=platform_name,
              current_directory=current_dir,
              user=user,
              shell=shell,
              terminal_size=terminal_size,
          )
      except Exception as e:
          logger.error(f"Error getting terminal info: {e}")
          return TerminalInfoResponse(
              terminal_type="unknown",
              platform="unknown",
              current_directory="unknown",
              user="unknown",
          )

• src/mcp_terminal/tools/terminal.py:52-65 (schema)

  Pydantic model defining the output schema (TerminalInfoResponse) for the get_terminal_info tool.

  class TerminalInfoResponse(BaseModel):
      """Response model for terminal information."""
  
      terminal_type: str = Field(..., description="The type of terminal being used")
      platform: str = Field(..., description="The platform the terminal is running on")
      current_directory: str = Field(
          ..., description="Current working directory of the terminal"
      )
      user: str = Field(..., description="Current user name")
      shell: Optional[str] = Field(None, description="Shell being used")
      terminal_size: Optional[dict] = Field(
          None, description="Terminal dimensions (rows, columns)"
      )

• src/mcp_terminal/server.py:94-103 (registration)

  Code that instantiates the TerminalTool and calls its register_mcp method, which defines and registers the get_terminal_info tool with the FastMCP instance.

  terminal_tool = TerminalTool(
      self.controller_type,
      whitelist_file=self.whitelist_file,
      blacklist_file=self.blacklist_file,
      whitelist_mode=self.whitelist_mode,
  )
  file_tool = FileTool()
  terminal_tool.register_mcp(self.mcp)
  file_tool.register_mcp(self.mcp)
  self.tools["terminal"] = terminal_tool