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 async handler function that implements the list_directory_contents tool by listing the contents of a directory in a Modal sandbox using modal_sandbox.ls.aio(path) and returning 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/mcp_server.py:131-134 (registration)Registers the list_directory_contents tool on the MCP app using mcp_app.tool() with the name and description from ToolDescriptions.mcp_app.tool( name="list_directory_contents", description=ToolDescriptions.LIST_DIRECTORY_CONTENTS, )(self.list_directory_contents)
- Pydantic BaseModel defining the output schema for the tool response, containing a list of directory contents.class SandboxListDirectoryContentsResponse(BaseModel): contents: List[str]
- Multiline tool description string defining expected parameters (sandbox_id, path) and response format for the list_directory_contents tool.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 """