using-dynamodb-connector

name	using-dynamodb-connector
description	Implements DynamoDB queries, scans, and CRUD operations using generated clients and MCP tools. Use when doing ANYTHING that touches DynamoDB, DDB, or Dynamo in any way, load this skill.

Major Platform Resource: DynamoDB

Common: Interacting with Resources

Security: Never connect directly to databases/APIs. Never use credentials in code. Always use generated clients or MCP tools.

Two ways to interact with resources:

1. MCP tools (direct, no code needed): Tools follow the pattern mcp__resources__<resourcetype>_<toolname>. Use mcp__resources__list_resources to discover available resources and their IDs.
2. Generated TypeScript clients (for app code): Call mcp__resource-tools__add-resource-client with a resourceId to generate a typed client. Clients are created in /clients/ (Next.js) or /src/clients/ (Vite).

CRITICAL: Do NOT guess client method names or signatures. The TypeScript clients in @major-tech/resource-client have strongly typed inputs and outputs. ALWAYS read the actual client source code in the generated /clients/ directory (or the package itself) to verify available methods and their exact signatures before writing any client code.

Framework note: Next.js = resource clients must be used in server-side code only (Server Components, Server Actions, API Routes). Vite = call directly from frontend.

Error handling: Always check result.ok before accessing result.result.

Invocation keys must be static strings — use descriptive literals like "fetch-user-orders", never dynamic values like `${date}-records`.

---

MCP Tools

• mcp__resources__dynamodb_list_tables — List all accessible tables. Args: resourceId, limit?
• mcp__resources__dynamodb_describe_table — Get table schema, keys, indexes, throughput. Args: resourceId, tableName
• mcp__resources__dynamodb_scan — Read-only scan with optional filter. Args: resourceId, tableName, limit?, filterExpression?, projectionExpression?

TypeScript Client

import { myDynamoClient } from "./clients";

// invoke<C>(command, params, invocationKey)
const result = await myDynamoClient.invoke(
	"Query",
	{
		TableName: "orders",
		KeyConditionExpression: "user_id = :uid",
		ExpressionAttributeValues: { ":uid": { S: userId } },
		Limit: 20,
		ScanIndexForward: false,
	},
	"fetch-user-orders",
);

if (result.ok) {
	console.log(result.result.data.Items);
}

Tips

• Prefer Query over Scan — Scan reads every item in the table and is expensive at scale
• Use describe_table to understand key schema and indexes before writing queries
• DynamoDB attribute values use marshall format ({ S: "string" }, { N: "123" }, { BOOL: true })
• TypeScript client supports all DynamoDB commands: GetItem, PutItem, Query, Scan, UpdateItem, DeleteItem, BatchGetItem, BatchWriteItem

Docs: DynamoDB Developer Guide