list_directory_contents
Explore and verify files in a Modal sandbox directory to manage content and debug file-related issues.
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
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sandbox_id | Yes | ||
| path | Yes |
Implementation Reference
- 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 ) - 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) - 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 """