scan-table
Scan items from a DynamoDB table by specifying filters, limits, or projections. Use this tool to retrieve and analyze data efficiently in a read-only environment.
Instructions
Scan items from a DynamoDB table
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| expressionAttributeValues | No | Filter expression attribute values (JSON format) | |
| filterExpression | No | Filter expression (e.g: 'age > :minAge') | |
| limit | No | Maximum number of items to return (default: 20) | |
| projectionExpression | No | Projection expression (e.g: "id") | |
| tableName | Yes | Name of the table to scan |
Implementation Reference
- src/index.ts:78-126 (registration)Registers the MCP tool 'scan-table' with input schema, description, and a handler function that calls the scanTable helper.server.tool( 'scan-table', 'Scan items from a DynamoDB table', { tableName: z.string().describe('Name of the table to scan'), limit: z.number().optional().describe('Maximum number of items to return (default: 20)'), filterExpression: z.string().optional().describe("Filter expression (e.g: 'age > :minAge')"), expressionAttributeValues: z .record(z.any()) .optional() .describe('Filter expression attribute values (JSON format)'), projectionExpression: z.string().optional().describe('Projection expression (e.g: "id")'), }, async ({ tableName, limit, filterExpression, expressionAttributeValues, projectionExpression, }) => { try { const items = await scanTable( tableName, limit, filterExpression, expressionAttributeValues, projectionExpression ); return { content: [ { type: 'text', text: JSON.stringify(items, null, 2), }, ], }; } catch (error: any) { return { isError: true, content: [ { type: 'text', text: `Error occurred: ${error.message}`, }, ], }; } } );
- src/index.ts:81-90 (schema)Zod schema defining input parameters for the scan-table tool.{ tableName: z.string().describe('Name of the table to scan'), limit: z.number().optional().describe('Maximum number of items to return (default: 20)'), filterExpression: z.string().optional().describe("Filter expression (e.g: 'age > :minAge')"), expressionAttributeValues: z .record(z.any()) .optional() .describe('Filter expression attribute values (JSON format)'), projectionExpression: z.string().optional().describe('Projection expression (e.g: "id")'), },
- src/index.ts:91-125 (handler)Handler function for the scan-table tool that performs the scan via helper and returns formatted response.async ({ tableName, limit, filterExpression, expressionAttributeValues, projectionExpression, }) => { try { const items = await scanTable( tableName, limit, filterExpression, expressionAttributeValues, projectionExpression ); return { content: [ { type: 'text', text: JSON.stringify(items, null, 2), }, ], }; } catch (error: any) { return { isError: true, content: [ { type: 'text', text: `Error occurred: ${error.message}`, }, ], }; } }
- src/dynamo-helpers.ts:37-81 (helper)Core helper function implementing DynamoDB ScanCommand with parameters for the scan-table tool.export async function scanTable( tableName: string, limit: number = 100, filterExpression?: string, expressionAttributeValues?: Record<string, any>, projectionExpression?: string ) { console.error('# Starting scanTable function:', { tableName, limit, filterExpression, expressionAttributeValues, projectionExpression, }); try { const params: any = { TableName: tableName, Limit: limit, }; if (filterExpression) { params.FilterExpression = filterExpression; } if (expressionAttributeValues) { params.ExpressionAttributeValues = expressionAttributeValues; } if (projectionExpression) { params.ProjectionExpression = projectionExpression; } console.error('# Scan parameters:', params); const command = new ScanCommand(params); console.error('# Scan command created successfully'); const response = await dynamodb.send(command); console.error('# Scan response received:', response); return response?.Items || []; } catch (error) { console.error('# Error in scanTable function:', error); throw error; } }