list-objects
Retrieve and filter objects from an S3 bucket using a prefix or limit results with maxKeys, enabling efficient management of stored files within AWS S3.
Instructions
List objects in an S3 bucket
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bucket | Yes | Name of the S3 bucket | |
| maxKeys | No | Maximum number of objects to return | |
| prefix | No | Prefix to filter objects (like a folder) |
Implementation Reference
- src/tools/listObjects.ts:50-73 (handler)The `execute` method implements the core handler logic for the 'list-objects' tool. It validates parameters, calls the S3 resource to list objects, formats the response as JSON text, and handles errors.async execute(args: InferZodParams<typeof this.parameters>) { const { bucket, prefix, maxKeys } = args; try { // Handle both undefined and null values for optional parameters const validPrefix = prefix === null || prefix === undefined ? "" : prefix; const validMaxKeys = maxKeys === null || maxKeys === undefined ? 1000 : maxKeys; const objects = await this.s3Resource.listObjects(bucket, validPrefix, validMaxKeys); return { content: [ { type: "text" as const, text: JSON.stringify(objects, null, 2), }, ], }; } catch (error) { return createErrorResponse( error, `Error listing objects in bucket ${bucket}: ${error instanceof Error ? error.message : String(error)}`, ); } }
- src/tools/listObjects.ts:23-33 (schema)Zod schema defining the input parameters for the tool: required 'bucket' string, optional 'prefix' (string or null), optional 'maxKeys' (number or null).readonly parameters = { bucket: z.string().describe("Name of the S3 bucket"), prefix: z .union([z.string(), z.null()]) .optional() .describe("Prefix to filter objects (like a folder)"), maxKeys: z .union([z.number(), z.null()]) .optional() .describe("Maximum number of objects to return"), } as const;
- src/tools/index.ts:12-18 (registration)The `createTools` function registers the 'list-objects' tool by instantiating `ListObjectsTool` and including it in the array of MCP tools.export function createTools(s3Resource: S3Resource): IMCPTool[] { return [ new ListBucketsTool(s3Resource), new ListObjectsTool(s3Resource), new GetObjectTool(s3Resource), ]; }
- src/resources/s3.ts:92-116 (helper)The `listObjects` method in `S3Resource` class is the supporting utility called by the tool handler to interact with the AWS S3 API and retrieve the list of objects.async listObjects(bucketName: string, prefix = "", maxKeys = 1000): Promise<_Object[]> { try { // Use pattern matching to check bucket accessibility await match({ hasConfiguredBuckets: this.configuredBuckets.length > 0, isAllowed: this.configuredBuckets.includes(bucketName), }) .with({ hasConfiguredBuckets: true, isAllowed: false }, () => { throw new Error(`Bucket ${bucketName} is not in the allowed buckets list`); }) .otherwise(() => Promise.resolve()); const command = new ListObjectsV2Command({ Bucket: bucketName, Prefix: prefix, MaxKeys: maxKeys, }); const response = await this.client.send(command); return response.Contents || []; } catch (error) { this.logError(`Error listing objects in bucket ${bucketName}:`, error); throw error; } }