DynamoDB Read-Only MCP

Instructions

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;
    }
  }