Terminal Controller for MCP

Instructions

List files and subdirectories in the specified directory

Args:
    path: Directory path to list contents, default is current directory

Returns:
    List of directory contents

Implementation Reference

• terminal_controller.py:201-252 (handler)

  The handler function for the 'list_directory' tool. It lists contents of a directory (current if path=None) using os.listdir, separates directories and files with emojis, sorts them, formats output nicely, and handles common exceptions.

  @mcp.tool()
  async def list_directory(path: Optional[str] = None) -> str:
      """
      List files and subdirectories in the specified directory
      
      Args:
          path: Directory path to list contents, default is current directory
      
      Returns:
          List of directory contents
      """
      if path is None:
          path = os.getcwd()
      
      try:
          items = os.listdir(path)
          
          dirs = []
          files = []
          
          for item in items:
              full_path = os.path.join(path, item)
              if os.path.isdir(full_path):
                  dirs.append(f"📁 {item}/")
              else:
                  files.append(f"📄 {item}")
          
          # Sort directories and files
          dirs.sort()
          files.sort()
          
          if not dirs and not files:
              return f"Directory '{path}' is empty"
          
          output = f"Contents of directory '{path}':\n\n"
          
          if dirs:
              output += "Directories:\n"
              output += "\n".join(dirs) + "\n\n"
          
          if files:
              output += "Files:\n"
              output += "\n".join(files)
          
          return output
      
      except FileNotFoundError:
          return f"Error: Directory '{path}' does not exist"
      except PermissionError:
          return f"Error: No permission to access directory '{path}'"
      except Exception as e:
          return f"Error listing directory contents: {str(e)}"

• terminal_controller.py:201-201 (registration)

  The @mcp.tool() decorator registers the list_directory function as an MCP tool with the FastMCP server.

  @mcp.tool()