upload_file

Instructions

Implementation Reference

• src/tools/implementations/upload-file-tool.ts:62-108 (handler)

  The execute method contains the core handler logic for the 'upload_file' tool: ensures the store exists, determines display name and MIME type, prepares upload arguments including metadata conversion, calls geminiClient.uploadFile, and returns the result.

  async execute(args: UploadFileArgs): Promise<MCPToolResponse<UploadFileResult>> {
    const { geminiClient, storeDisplayName } = this.context;
  
    // Ensure store exists
    const store = await geminiClient.ensureStore(storeDisplayName);
  
    // Determine display name
    const displayName = args.displayName ?? basename(args.filePath);
  
    // Auto-detect MIME type if not provided
    let mimeType = args.mimeType;
    if (!mimeType) {
      const ext = args.filePath.split(".").pop()?.toLowerCase();
      mimeType = this.getMimeTypeFromExtension(ext ?? "");
    }
  
    // Upload file
    const uploadArgs: {
      storeName: string;
      filePath: string;
      mimeType: string;
      displayName: string;
      metadata?: CustomMetadata[];
    } = {
      storeName: store.name,
      filePath: args.filePath,
      mimeType,
      displayName,
    };
  
    if (args.metadata) {
      uploadArgs.metadata = convertMetadataInput(args.metadata);
    }
  
    const result = await geminiClient.uploadFile(uploadArgs);
  
    return {
      success: true,
      message: `File uploaded successfully: ${displayName}`,
      data: {
        documentName: result.documentName,
        filePath: args.filePath,
        displayName,
        storeName: store.name,
      },
    };
  }

• src/tools/implementations/upload-file-tool.ts:15-60 (schema)

  Defines the UploadFileArgs and UploadFileResult types, the tool name and description, and the Zod input schema via getInputSchema() for the 'upload_file' tool.

  type UploadFileArgs = {
    filePath: string;
    mimeType?: string;
    displayName?: string;
    metadata?: MetadataInput;
  };
  
  type UploadFileResult = {
    documentName: string;
    filePath: string;
    displayName: string;
    storeName: string;
  };
  
  export class UploadFileTool extends BaseTool<UploadFileArgs> {
    readonly name = "upload_file";
    readonly description =
      "Upload a file to the FileSearchStore for RAG indexing. The file will be processed and made searchable.";
  
    getInputSchema() {
      return z.object({
        filePath: z
          .string()
          .describe(
            "Absolute path to the file to upload (e.g., /path/to/document.pdf)",
          ),
        mimeType: z
          .string()
          .optional()
          .describe(
            "MIME type of the file (e.g., application/pdf, text/markdown). Auto-detected if not provided.",
          ),
        displayName: z
          .string()
          .optional()
          .describe(
            "Display name for the file in the store. Uses filename if not provided.",
          ),
        metadata: z
          .record(z.union([z.string(), z.number()]))
          .optional()
          .describe(
            "Custom metadata as key-value pairs. Values can be strings or numbers. Maximum 20 entries per document. Example: {\"category\": \"guide\", \"year\": 2025}",
          ),
      });
    }

• src/server/tool-registry.ts:24-37 (registration)

  Instantiates the UploadFileTool with context and stores it in the tool instances map during registry initialization.

  initialize(context: ToolContext): void {
    // Manual tool registration for safety and explicit review
    const tools: Tool[] = [
      new UploadFileTool(context),
      new UploadContentTool(context),
      new QueryTool(context),
    ];
  
    for (const tool of tools) {
      this.toolInstances.set(tool.name, tool);
    }
  
    console.log(`✅ ToolRegistry initialized with ${String(this.toolInstances.size)} tools`);
  }

• src/server/tool-registry.ts:43-57 (registration)

  Registers all tools, including 'upload_file', with the MCP server using the tool's name, description, input schema, and bound handler method.

  setupToolHandlers(): void {
    for (const tool of this.toolInstances.values()) {
      // Pass Zod schema directly to MCP SDK
      // SDK handles JSON Schema conversion internally for both stdio and HTTP transports
      this.server.registerTool(
        tool.name,
        {
          description: tool.description,
          inputSchema: tool.getInputSchema().shape,
        },
        tool.handler.bind(tool) as never,
      );
      this.registeredTools.push(tool.name);
    }
  }