DynamoDB Read-Only MCP

Instructions

Implementation Reference

• src/dynamo-helpers.ts:195-231 (handler)

  Core handler function that executes the item counting logic by performing a DynamoDB Scan operation with Select: 'COUNT' and optional filters.

  export async function countItems(
    tableName: string,
    filterExpression?: string,
    expressionAttributeValues?: Record<string, any>
  ) {
    console.error('# Starting countItems function:', {
      tableName,
      filterExpression,
      expressionAttributeValues,
    });
  
    try {
      const params: any = {
        TableName: tableName,
        Select: 'COUNT',
      };
  
      if (filterExpression) {
        params.FilterExpression = filterExpression;
      }
  
      if (expressionAttributeValues) {
        params.ExpressionAttributeValues = expressionAttributeValues;
      }
  
      console.error('# Count parameters:', params);
      const command = new ScanCommand(params);
      console.error('# Count command created successfully');
  
      const response = await dynamodb.send(command);
      console.error('# Count response received:', response);
      return response.Count || 0;
    } catch (error) {
      console.error('# Error in countItems function:', error);
      throw error;
    }
  }

• src/index.ts:294-328 (registration)

  Registers the 'count-items' tool with the MCP server, defines the input schema using Zod, and provides a thin wrapper handler that calls the core countItems function and formats the MCP response.

  server.tool(
    'count-items',
    'Count items in a DynamoDB table',
    {
      tableName: z.string().describe('Table name'),
      filterExpression: z.string().optional().describe('Filter expression (optional)'),
      expressionAttributeValues: z
        .record(z.any())
        .optional()
        .describe('Filter expression attribute values (optional)'),
    },
    async ({ tableName, filterExpression, expressionAttributeValues }) => {
      try {
        const count = await countItems(tableName, filterExpression, expressionAttributeValues);
        return {
          content: [
            {
              type: 'text',
              text: `Table "${tableName}" has ${count} items.`,
            },
          ],
        };
      } catch (error: any) {
        return {
          isError: true,
          content: [
            {
              type: 'text',
              text: `Error occurred: ${error.message}`,
            },
          ],
        };
      }
    }
  );

• src/index.ts:297-303 (schema)

  Zod schema defining the input parameters for the 'count-items' tool.

  {
    tableName: z.string().describe('Table name'),
    filterExpression: z.string().optional().describe('Filter expression (optional)'),
    expressionAttributeValues: z
      .record(z.any())
      .optional()
      .describe('Filter expression attribute values (optional)'),