Gemini MCP Server for Claude Desktop

Instructions

Implementation Reference

• src/tools/file-upload.js:60-80 (handler)

  Main handler function that validates the operation and dispatches to specific file management methods (upload, list, get, delete).

  async execute(args) {
    const operation = validateString(args.operation, 'operation', ['upload', 'list', 'get', 'delete']);
    
    try {
      switch (operation) {
        case 'upload':
          return await this.handleUpload(args);
        case 'list':
          return await this.handleList(args);
        case 'get':
          return await this.handleGet(args);
        case 'delete':
          return await this.handleDelete(args);
        default:
          throw new Error(`Unknown operation: ${operation}`);
      }
    } catch (error) {
      log(`Error in file upload tool: ${error.message}`, this.name);
      throw error;
    }
  }

• src/tools/file-upload.js:82-181 (handler)

  Core upload handler: validates file path and size, performs upload using FileUploadService, builds detailed success response with file metadata.

  async handleUpload(args) {
    const filePath = validateNonEmptyString(args.file_path, 'file_path');
    const displayName = args.display_name || null;
    
    // Check if file exists
    if (!fs.existsSync(filePath)) {
      throw new Error(`File not found: ${filePath}`);
    }
    
    // Check file size
    const stats = fs.statSync(filePath);
    const fileSizeMB = stats.size / (1024 * 1024);
    
    if (fileSizeMB > 2048) { // 2GB limit
      throw new Error(`File too large: ${fileSizeMB.toFixed(2)}MB. Maximum size is 2GB.`);
    }
    
    log(`Uploading file: ${filePath} (${fileSizeMB.toFixed(2)}MB)`, this.name);
    
    try {
      const fileInfo = await this.fileUploadService.uploadFile(filePath, displayName);
      
      // Build response with available fields
      let response = `✓ File uploaded successfully to Gemini File API:\n\n`;
      
      if (fileInfo.display_name) {
        response += `**Name:** ${fileInfo.display_name}\n`;
      }
      
      if (fileInfo.uri) {
        response += `**URI:** ${fileInfo.uri}\n`;
      }
      
      if (fileInfo.name) {
        response += `**File ID:** ${fileInfo.name}\n`;
      }
      
      if (fileInfo.size_bytes && fileInfo.size_bytes > 0) {
        response += `**Size:** ${(fileInfo.size_bytes / (1024 * 1024)).toFixed(2)}MB\n`;
      } else {
        response += `**Size:** ${fileSizeMB.toFixed(2)}MB (estimated)\n`;
      }
      
      if (fileInfo.mime_type) {
        response += `**MIME Type:** ${fileInfo.mime_type}\n`;
      }
      
      if (fileInfo.create_time) {
        try {
          response += `**Created:** ${new Date(fileInfo.create_time).toLocaleString()}\n`;
        } catch (e) {
          response += `**Created:** ${fileInfo.create_time}\n`;
        }
      }
      
      if (fileInfo.expiration_time) {
        try {
          response += `**Expires:** ${new Date(fileInfo.expiration_time).toLocaleString()}\n`;
        } catch (e) {
          response += `**Expires:** ${fileInfo.expiration_time}\n`;
        }
      }
      
      response += `\n`;
      
      if (fileInfo.uri) {
        response += `This file can now be used in other Gemini operations by referencing its URI.\n`;
        response += `The file will be automatically deleted after 48 hours.`;
      } else {
        response += `File uploaded but URI not returned. Check logs for details.`;
        log(`Warning: File uploaded but no URI returned. Response: ${JSON.stringify(fileInfo)}`, this.name);
      }
      
      // Learn from the interaction if intelligence is enabled
      if (this.intelligenceSystem.initialized) {
        try {
          await this.intelligenceSystem.learnFromInteraction(
            `Upload file ${filePath}`,
            `Upload file ${filePath} with display name ${displayName || path.basename(filePath)}`,
            `Successfully uploaded ${fileSizeMB.toFixed(2)}MB file`,
            'file-upload',
            this.name
          );
        } catch (err) {
          log(`Tool Intelligence learning failed: ${err.message}`, this.name);
        }
      }
      
      return {
        content: [
          {
            type: 'text',
            text: response,
          },
        ],
      };
    } catch (error) {
      throw new Error(`Failed to upload file: ${error.message}`);
    }
  }

• src/tools/file-upload.js:21-46 (schema)

  JSON schema defining the input parameters for the gemini-upload-file tool, including operations and file details.

  {
    type: 'object',
    properties: {
      file_path: {
        type: 'string',
        description: 'Path to the file to upload',
      },
      display_name: {
        type: 'string',
        description: 'Optional display name for the file (defaults to filename)',
      },
      operation: {
        type: 'string',
        description: 'Operation to perform: "upload", "list", "get", or "delete"',
        enum: ['upload', 'list', 'get', 'delete'],
      },
      file_name: {
        type: 'string',
        description: 'File name (for get/delete operations)',
      },
      page_size: {
        type: 'number',
        description: 'Number of files to list (for list operation, max 100)',
      },
    },
    required: ['operation'],

• src/tools/index.js:87-87 (registration)

  Registers the FileUploadTool instance (named 'gemini-upload-file') with the tool dispatcher/registry.

  registerTool(new FileUploadTool(intelligenceSystem, geminiService));

• src/gemini/file-api/file-upload-service.js:27-46 (helper)

  Helper service method that implements the resumable file upload protocol to Gemini File API, called by the tool handler.

  async uploadFile(filePath, displayName = null, options = {}) {
    const stats = fs.statSync(filePath);
    const fileSize = stats.size;
    const mimeType = this.getMimeType(filePath);
    
    if (!displayName) {
      displayName = path.basename(filePath);
    }
  
    log(`Starting resumable upload for file: ${filePath} (${(fileSize / (1024 * 1024)).toFixed(2)}MB)`, 'file-upload');
  
    // Step 1: Initialize resumable upload
    const uploadUrl = await this.initializeResumableUpload(displayName, mimeType, fileSize);
    
    // Step 2: Upload the file data
    const fileInfo = await this.uploadFileData(uploadUrl, filePath, fileSize);
    
    log(`File uploaded successfully: ${fileInfo.name}, URI: ${fileInfo.uri}`, 'file-upload');
    return fileInfo;
  }