upload_file
Upload local files to the Gemini Files API to handle large images (over 20MB) or reuse files across multiple prompts, returning the file URI and metadata for integration.
Instructions
Upload a local file through the Gemini Files API and return its URI & metadata. Useful when the image is larger than 20MB or reused across prompts.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Server-accessible file path to upload to Gemini Files API. | |
| display_name | No | Optional display name for the uploaded file. |
Implementation Reference
- Core handler function for the 'upload_file' tool. Handles input parameters, performs file upload using file_service, manages errors, and returns a ToolResult with file metadata or error details.def upload_file( path: Annotated[ str, Field( description="Server-accessible file path to upload to Gemini Files API.", min_length=1, max_length=512, ), ], display_name: Annotated[ Optional[str], Field(description="Optional display name for the uploaded file.", max_length=256), ] = None, ctx: Context = None, ) -> ToolResult: """ Upload a local file through the Gemini Files API and return its URI & metadata. Useful when the image is larger than 20MB or reused across prompts. """ logger = logging.getLogger(__name__) try: logger.info(f"Upload file request: path='{path}', display_name='{display_name}'") # Get service (would be injected in real implementation) file_service = _get_file_service() # Upload file metadata = file_service.upload_file(path, display_name) # Create response summary = f"Successfully uploaded file: {metadata['name']}" # Return as structured content (not image blocks) logger.info(f"Successfully uploaded file: {metadata['name']}") return ToolResult( content=[summary], structured_content={"success": True, "file": metadata} ) except ValidationError as e: logger.error(f"Validation error in upload_file: {e}") return ToolResult( content=[f"Validation error: {e}"], structured_content={"error": "validation_error", "message": str(e)}, ) except FileOperationError as e: logger.error(f"File operation error in upload_file: {e}") return ToolResult( content=[f"File upload failed: {e}"], structured_content={"error": "file_operation_error", "message": str(e)}, ) except Exception as e: logger.error(f"Unexpected error in upload_file: {e}") raise
- Input schema for the upload_file tool defined using Annotated and Pydantic Field for path (required str, 1-512 chars) and optional display_name (str, max 256 chars).def upload_file( path: Annotated[ str, Field( description="Server-accessible file path to upload to Gemini Files API.", min_length=1, max_length=512, ), ], display_name: Annotated[ Optional[str], Field(description="Optional display name for the uploaded file.", max_length=256), ] = None, ctx: Context = None, ) -> ToolResult:
- nanobanana_mcp_server/tools/upload_file.py:9-18 (registration)Registration function that decorates the upload_file handler with @server.tool, providing tool metadata like title.def register_upload_file_tool(server: FastMCP): """Register the upload_file tool with the FastMCP server.""" @server.tool( annotations={ "title": "Upload file to Gemini Files API", "readOnlyHint": False, "openWorldHint": True, } )
- nanobanana_mcp_server/core/server.py:37-42 (registration)Top-level registration: imports register_upload_file_tool and calls it in _register_tools method to add the tool to the MCP server.from ..tools.upload_file import register_upload_file_tool from ..tools.output_stats import register_output_stats_tool from ..tools.maintenance import register_maintenance_tool register_generate_image_tool(self.server) register_upload_file_tool(self.server)
- Helper function to retrieve the file_service instance used for uploading files.def _get_file_service(): """Get the file service instance.""" from ..services import get_file_service return get_file_service()