MCP4Modal Sandbox

Instructions

        Lists contents of a directory in the sandbox.
        
        Parameters:
        - sandbox_id: The unique identifier of the sandbox
        - path: Directory path to list in the sandbox
        
        Returns a SandboxListDirectoryResponse containing:
        - contents: List of filenames/directories at the specified path
        
        This tool is useful for:
        - Exploring sandbox filesystem structure
        - Verifying file operations
        - Debugging file-related issues
        - Managing sandbox content
        
        The tool will:
        1. Verify sandbox and directory exist
        2. List all contents at specified path
        3. Return directory listing
        

Implementation Reference

• src/mcp4modal_sandbox/backend/mcp_server.py:357-372 (handler)

  The handler function that implements the list_directory_contents tool. It retrieves the Modal sandbox, checks if it's running, lists the directory contents using modal_sandbox.ls.aio(path), logs the action, and returns a SandboxListDirectoryContentsResponse.

  async def list_directory_contents(self, sandbox_id: str, path: str) -> SandboxListDirectoryContentsResponse:
      # Get sandbox from Modal using from_id
      modal_sandbox = await modal.Sandbox.from_id.aio(sandbox_id)
      
      # Check if sandbox is running before listing directory
      sandbox_status = await modal_sandbox.poll.aio()
      if sandbox_status is not None:
          raise ToolError(f"Sandbox {sandbox_id} is not running")
      
      contents = await modal_sandbox.ls.aio(path)
      logger.info(f"Listed directory {path} in sandbox {sandbox_id}")
      
      return SandboxListDirectoryContentsResponse(
          contents=contents
      )

• src/mcp4modal_sandbox/backend/response_schema.py:36-37 (schema)

  Pydantic BaseModel defining the response schema for the tool, which includes a list of strings representing the directory contents.

  class SandboxListDirectoryContentsResponse(BaseModel):
      contents: List[str]

• src/mcp4modal_sandbox/backend/mcp_server.py:131-134 (registration)

  Tool registration in the FastMCP application within the register_tools method, binding the name, description, and handler function.

  mcp_app.tool(
      name="list_directory_contents",
      description=ToolDescriptions.LIST_DIRECTORY_CONTENTS,
  )(self.list_directory_contents)

• src/mcp4modal_sandbox/backend/tool_descriptions.py:183-203 (helper)

  The descriptive docstring for the list_directory_contents tool used during registration.

  LIST_DIRECTORY_CONTENTS = """
          Lists contents of a directory in the sandbox.
          
          Parameters:
          - sandbox_id: The unique identifier of the sandbox
          - path: Directory path to list in the sandbox
          
          Returns a SandboxListDirectoryResponse containing:
          - contents: List of filenames/directories at the specified path
          
          This tool is useful for:
          - Exploring sandbox filesystem structure
          - Verifying file operations
          - Debugging file-related issues
          - Managing sandbox content
          
          The tool will:
          1. Verify sandbox and directory exist
          2. List all contents at specified path
          3. Return directory listing
          """