nanobanana-mcp-server

Instructions

Implementation Reference

• nanobanana_mcp_server/tools/upload_file.py:19-74 (handler)

  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

• nanobanana_mcp_server/tools/upload_file.py:19-33 (schema)

  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)

• nanobanana_mcp_server/tools/upload_file.py:76-80 (helper)

  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()