download_file

Instructions

Implementation Reference

• ipybox/mcp/server.py:175-201 (handler)

  The primary MCP tool handler for 'download_file'. Performs path validation and delegates the download to the ResourceClient.download_file method.

  async def download_file(
      self,
      relpath: Annotated[
          str,
          Field(
              description="Source path relative to container's /app directory (e.g., 'output/results.csv' reads from /app/output/results.csv)"
          ),
      ],
      local_path: Annotated[str, Field(description="Absolute path on host filesystem where the file will be saved")],
  ):
      """Download a file from the container's /app directory to the host filesystem.
  
      Retrieves files created or modified during code execution from the container.
      The file at '/app/{relpath}' in the container will be saved to the specified
      location on the host.
  
      Parent directories are created automatically if they don't exist.
      """
      await self.setup_task
      assert self.resource_client is not None
  
      local_path_obj = Path(local_path)
      self.path_validator.validate(local_path_obj, "download")
      local_path_obj.parent.mkdir(parents=True, exist_ok=True)
  
      await self.resource_client.download_file(relpath, local_path_obj)

• ipybox/mcp/server.py:54-54 (registration)

  Registers the download_file method as an MCP tool using FastMCP's tool decorator.

  self.mcp.tool()(self.download_file)

• ipybox/mcp/server.py:177-183 (schema)

  Pydantic schema definitions for the tool's input parameters using Annotated and Field.

  relpath: Annotated[
      str,
      Field(
          description="Source path relative to container's /app directory (e.g., 'output/results.csv' reads from /app/output/results.csv)"
      ),
  ],
  local_path: Annotated[str, Field(description="Absolute path on host filesystem where the file will be saved")],

• ipybox/resource/client.py:148-170 (helper)

  Helper method in ResourceClient that performs the actual HTTP download from the resource server to the local filesystem.

  async def download_file(self, relpath: str, local_path: Path) -> None:
      """Download a file from the container.
  
      Args:
          relpath: Path relative to the container's `/app` directory
          local_path: Local file path to save to
  
      Raises:
          HTTPError: If the file doesn't exist or download fails
      """
      # Create parent directories if needed
      local_path.parent.mkdir(parents=True, exist_ok=True)
  
      url = f"{self._base_url}/files/{relpath}"
      async with self._session.get(url) as response:
          response.raise_for_status()
  
          # Stream content to file
          async with aiofiles.open(local_path, mode="wb") as f:
              async for chunk in response.content.iter_chunked(1024 * 1024):  # 1MB chunks
                  await f.write(chunk)
  
  async def delete_file(self, relpath: str) -> None:

• ipybox/resource/server.py:85-108 (helper)

  The resource server's HTTP endpoint handler for downloading files, serving as the backend for the client helper.

  async def download_file(self, relpath: Path):
      """Download a file from the container."""
      full_path = self._validate_path(relpath)
  
      if not full_path.exists() or not full_path.is_file():
          raise HTTPException(status_code=404, detail="File not found")
  
      # Determine MIME type
      mime_type, _ = mimetypes.guess_type(str(full_path))
      if mime_type is None:
          mime_type = "application/octet-stream"
  
      # Stream file content
      async def file_streamer():
          async with aiofiles.open(full_path, mode="rb") as f:
              while chunk := await f.read(1024 * 1024):  # 1MB chunks
                  yield chunk
  
      return StreamingResponse(
          file_streamer(),
          media_type=mime_type,
          headers={"Content-Disposition": f"attachment; filename={full_path.name}"},
      )