MCP4Modal Sandbox

Instructions

Implementation Reference

• src/mcp4modal_sandbox/backend/mcp_server.py:156-167 (handler)

  The handler function that lists all sandboxes in the Modal app namespace by using modal.Sandbox.list.aio() and returns a list of SandboxListItem objects.
  async def list_sandboxes(self, ctx:Context) -> List[SandboxListItem]: await ctx.info(f"Listing sandboxes for app '{self.app_name}'...") app = modal.App.lookup(self.app_name, create_if_missing=True) sandbox_list: List[SandboxListItem] = [] async for sandbox in modal.Sandbox.list.aio(app_id=app.app_id): sandbox_status = await sandbox.poll.aio() sandbox_list.append(SandboxListItem( sandbox_id=sandbox.object_id, sandbox_status=SandboxStatus.RUNNING if sandbox_status is None else SandboxStatus.STOPPED, )) await ctx.info(f"Found {len(sandbox_list)} sandboxes") return sandbox_list
• src/mcp4modal_sandbox/backend/mcp_server.py:111-114 (registration)

  Registers the 'list_sandboxes' tool with the FastMCP server instance, associating it with the handler method.
  mcp_app.tool( name="list_sandboxes", description=ToolDescriptions.LIST_SANDBOXES, )(self.list_sandboxes)
• src/mcp4modal_sandbox/backend/response_schema.py:10-12 (schema)

  Pydantic BaseModel defining the structure of each sandbox item returned by the list_sandboxes tool.
  class SandboxListItem(BaseModel): sandbox_id: str sandbox_status: SandboxStatus
• src/mcp4modal_sandbox/backend/tool_descriptions.py:78-92 (schema)

  Tool description string providing usage information and parameters for the list_sandboxes tool, used during registration.
  LIST_SANDBOXES = """ Lists all Modal sandboxes for a specific app namespace and their current status. Parameters: - app_name: Name of the Modal app namespace to list sandboxes for Returns a list of sandboxes containing: - sandbox_id: Unique identifier for each sandbox - sandbox_status: Current state of the sandbox (running/stopped) This tool is useful for: - Monitoring active Modal sandbox environments within an app namespace - Checking which sandboxes are currently running - Getting sandbox IDs for further management operations """
• src/mcp4modal_sandbox/backend/response_schema.py:6-8 (schema)

  Enum defining possible status values for sandboxes used in SandboxListItem.
  class SandboxStatus(str, Enum): RUNNING = "running" STOPPED = "stopped"