@jaypie/dynamodb 0.0.1 → 0.1.1

package/dist/cjs/mcp/index.cjs

@@ -0,0 +1,1090 @@
+'use strict';
+
+var mcp = require('@jaypie/vocabulary/mcp');
+var vocabulary = require('@jaypie/vocabulary');
+var clientDynamodb = require('@aws-sdk/client-dynamodb');
+var libDynamodb = require('@aws-sdk/lib-dynamodb');
+var errors = require('@jaypie/errors');
+
+const DEFAULT_REGION$2 = "us-east-1";
+const LOCAL_CREDENTIALS = {
+    accessKeyId: "local",
+    secretAccessKey: "local",
+};
+// Module-level state
+let docClient = null;
+let tableName = null;
+/**
+ * Check if endpoint indicates local development mode
+ */
+function isLocalEndpoint(endpoint) {
+    if (!endpoint)
+        return false;
+    return endpoint.includes("127.0.0.1") || endpoint.includes("localhost");
+}
+/**
+ * Initialize the DynamoDB client
+ * Must be called once at application startup before using query functions
+ *
+ * @param config - Client configuration
+ */
+function initClient(config) {
+    const { endpoint, region = DEFAULT_REGION$2 } = config;
+    // Auto-detect local mode and use dummy credentials
+    const credentials = config.credentials ??
+        (isLocalEndpoint(endpoint) ? LOCAL_CREDENTIALS : undefined);
+    const dynamoClient = new clientDynamodb.DynamoDBClient({
+        ...(credentials && { credentials }),
+        ...(endpoint && { endpoint }),
+        region,
+    });
+    docClient = libDynamodb.DynamoDBDocumentClient.from(dynamoClient, {
+        marshallOptions: {
+            removeUndefinedValues: true,
+        },
+    });
+    tableName = config.tableName;
+}
+/**
+ * Get the initialized DynamoDB Document Client
+ * @throws ConfigurationError if client has not been initialized
+ */
+function getDocClient() {
+    if (!docClient) {
+        throw new errors.ConfigurationError("DynamoDB client not initialized. Call initClient() first.");
+    }
+    return docClient;
+}
+/**
+ * Get the configured table name
+ * @throws ConfigurationError if client has not been initialized
+ */
+function getTableName() {
+    if (!tableName) {
+        throw new errors.ConfigurationError("DynamoDB client not initialized. Call initClient() first.");
+    }
+    return tableName;
+}
+/**
+ * Check if the client has been initialized
+ */
+function isInitialized() {
+    return docClient !== null && tableName !== null;
+}
+
+// Primary markers
+const SEPARATOR = "#"; // Composite key separator
+// GSI names
+const INDEX_ALIAS = "indexAlias";
+const INDEX_CLASS = "indexClass";
+const INDEX_OU = "indexOu";
+const INDEX_TYPE = "indexType";
+const INDEX_XID = "indexXid";
+// Index suffixes for soft state
+const ARCHIVED_SUFFIX = "#archived";
+const DELETED_SUFFIX = "#deleted";
+
+/**
+ * Build the indexOu key for hierarchical queries
+ * @param ou - The organizational unit (APEX or "{parent.model}#{parent.id}")
+ * @param model - The entity model name
+ * @returns Composite key: "{ou}#{model}"
+ */
+function buildIndexOu(ou, model) {
+    return `${ou}${SEPARATOR}${model}`;
+}
+/**
+ * Build the indexAlias key for human-friendly lookups
+ * @param ou - The organizational unit
+ * @param model - The entity model name
+ * @param alias - The human-friendly alias
+ * @returns Composite key: "{ou}#{model}#{alias}"
+ */
+function buildIndexAlias(ou, model, alias) {
+    return `${ou}${SEPARATOR}${model}${SEPARATOR}${alias}`;
+}
+/**
+ * Build the indexClass key for category filtering
+ * @param ou - The organizational unit
+ * @param model - The entity model name
+ * @param recordClass - The category classification
+ * @returns Composite key: "{ou}#{model}#{class}"
+ */
+function buildIndexClass(ou, model, recordClass) {
+    return `${ou}${SEPARATOR}${model}${SEPARATOR}${recordClass}`;
+}
+/**
+ * Build the indexType key for type filtering
+ * @param ou - The organizational unit
+ * @param model - The entity model name
+ * @param type - The type classification
+ * @returns Composite key: "{ou}#{model}#{type}"
+ */
+function buildIndexType(ou, model, type) {
+    return `${ou}${SEPARATOR}${model}${SEPARATOR}${type}`;
+}
+/**
+ * Build the indexXid key for external ID lookups
+ * @param ou - The organizational unit
+ * @param model - The entity model name
+ * @param xid - The external ID
+ * @returns Composite key: "{ou}#{model}#{xid}"
+ */
+function buildIndexXid(ou, model, xid) {
+    return `${ou}${SEPARATOR}${model}${SEPARATOR}${xid}`;
+}
+/**
+ * Auto-populate GSI index keys on an entity
+ * - indexOu is always populated from ou + model
+ * - indexAlias is populated only when alias is present
+ * - indexClass is populated only when class is present
+ * - indexType is populated only when type is present
+ * - indexXid is populated only when xid is present
+ *
+ * @param entity - The entity to populate index keys for
+ * @param suffix - Optional suffix to append to all index keys (e.g., "#deleted", "#archived")
+ * @returns The entity with populated index keys
+ */
+function indexEntity(entity, suffix = "") {
+    const result = { ...entity };
+    // indexOu is always set (from ou + model)
+    result.indexOu = buildIndexOu(entity.ou, entity.model) + suffix;
+    // Optional indexes - only set when the source field is present
+    if (entity.alias !== undefined) {
+        result.indexAlias =
+            buildIndexAlias(entity.ou, entity.model, entity.alias) + suffix;
+    }
+    if (entity.class !== undefined) {
+        result.indexClass =
+            buildIndexClass(entity.ou, entity.model, entity.class) + suffix;
+    }
+    if (entity.type !== undefined) {
+        result.indexType =
+            buildIndexType(entity.ou, entity.model, entity.type) + suffix;
+    }
+    if (entity.xid !== undefined) {
+        result.indexXid =
+            buildIndexXid(entity.ou, entity.model, entity.xid) + suffix;
+    }
+    return result;
+}
+
+/**
+ * Calculate suffix based on entity's archived/deleted state
+ */
+function calculateEntitySuffix(entity) {
+    const hasArchived = Boolean(entity.archivedAt);
+    const hasDeleted = Boolean(entity.deletedAt);
+    if (hasArchived && hasDeleted) {
+        return ARCHIVED_SUFFIX + DELETED_SUFFIX;
+    }
+    if (hasArchived) {
+        return ARCHIVED_SUFFIX;
+    }
+    if (hasDeleted) {
+        return DELETED_SUFFIX;
+    }
+    return "";
+}
+/**
+ * Get a single entity by primary key
+ */
+const getEntity = vocabulary.serviceHandler({
+    alias: "getEntity",
+    description: "Get a single entity by primary key",
+    input: {
+        id: { type: String, description: "Entity ID (sort key)" },
+        model: { type: String, description: "Entity model (partition key)" },
+    },
+    service: async ({ id, model }) => {
+        const docClient = getDocClient();
+        const tableName = getTableName();
+        const command = new libDynamodb.GetCommand({
+            Key: { id, model },
+            TableName: tableName,
+        });
+        const response = await docClient.send(command);
+        return response.Item ?? null;
+    },
+});
+/**
+ * Put (create or replace) an entity
+ * Auto-populates GSI index keys via indexEntity
+ *
+ * Note: This is a regular async function (not serviceHandler) because it accepts
+ * complex FabricEntity objects that can't be coerced by vocabulary's type system.
+ */
+async function putEntity({ entity, }) {
+    const docClient = getDocClient();
+    const tableName = getTableName();
+    // Auto-populate index keys
+    const indexedEntity = indexEntity(entity);
+    const command = new libDynamodb.PutCommand({
+        Item: indexedEntity,
+        TableName: tableName,
+    });
+    await docClient.send(command);
+    return indexedEntity;
+}
+/**
+ * Update an existing entity
+ * Auto-populates GSI index keys and sets updatedAt
+ *
+ * Note: This is a regular async function (not serviceHandler) because it accepts
+ * complex FabricEntity objects that can't be coerced by vocabulary's type system.
+ */
+async function updateEntity({ entity, }) {
+    const docClient = getDocClient();
+    const tableName = getTableName();
+    // Update timestamp and re-index
+    const updatedEntity = indexEntity({
+        ...entity,
+        updatedAt: new Date().toISOString(),
+    });
+    const command = new libDynamodb.PutCommand({
+        Item: updatedEntity,
+        TableName: tableName,
+    });
+    await docClient.send(command);
+    return updatedEntity;
+}
+/**
+ * Soft delete an entity by setting deletedAt timestamp
+ * Re-indexes with appropriate suffix based on archived/deleted state
+ */
+const deleteEntity = vocabulary.serviceHandler({
+    alias: "deleteEntity",
+    description: "Soft delete an entity (sets deletedAt timestamp)",
+    input: {
+        id: { type: String, description: "Entity ID (sort key)" },
+        model: { type: String, description: "Entity model (partition key)" },
+    },
+    service: async ({ id, model }) => {
+        const docClient = getDocClient();
+        const tableName = getTableName();
+        // Fetch the current entity
+        const existing = await getEntity({ id, model });
+        if (!existing) {
+            return false;
+        }
+        const now = new Date().toISOString();
+        // Build updated entity with deletedAt
+        const updatedEntity = {
+            ...existing,
+            deletedAt: now,
+            updatedAt: now,
+        };
+        // Calculate suffix based on combined state (may already be archived)
+        const suffix = calculateEntitySuffix(updatedEntity);
+        const deletedEntity = indexEntity(updatedEntity, suffix);
+        const command = new libDynamodb.PutCommand({
+            Item: deletedEntity,
+            TableName: tableName,
+        });
+        await docClient.send(command);
+        return true;
+    },
+});
+/**
+ * Archive an entity by setting archivedAt timestamp
+ * Re-indexes with appropriate suffix based on archived/deleted state
+ */
+const archiveEntity = vocabulary.serviceHandler({
+    alias: "archiveEntity",
+    description: "Archive an entity (sets archivedAt timestamp)",
+    input: {
+        id: { type: String, description: "Entity ID (sort key)" },
+        model: { type: String, description: "Entity model (partition key)" },
+    },
+    service: async ({ id, model }) => {
+        const docClient = getDocClient();
+        const tableName = getTableName();
+        // Fetch the current entity
+        const existing = await getEntity({ id, model });
+        if (!existing) {
+            return false;
+        }
+        const now = new Date().toISOString();
+        // Build updated entity with archivedAt
+        const updatedEntity = {
+            ...existing,
+            archivedAt: now,
+            updatedAt: now,
+        };
+        // Calculate suffix based on combined state (may already be deleted)
+        const suffix = calculateEntitySuffix(updatedEntity);
+        const archivedEntity = indexEntity(updatedEntity, suffix);
+        const command = new libDynamodb.PutCommand({
+            Item: archivedEntity,
+            TableName: tableName,
+        });
+        await docClient.send(command);
+        return true;
+    },
+});
+/**
+ * Hard delete an entity (permanently removes from table)
+ * Use with caution - prefer deleteEntity for soft delete
+ */
+const destroyEntity = vocabulary.serviceHandler({
+    alias: "destroyEntity",
+    description: "Hard delete an entity (permanently removes from table)",
+    input: {
+        id: { type: String, description: "Entity ID (sort key)" },
+        model: { type: String, description: "Entity model (partition key)" },
+    },
+    service: async ({ id, model }) => {
+        const docClient = getDocClient();
+        const tableName = getTableName();
+        const command = new libDynamodb.DeleteCommand({
+            Key: { id, model },
+            TableName: tableName,
+        });
+        await docClient.send(command);
+        return true;
+    },
+});
+
+/**
+ * Calculate the suffix based on archived/deleted flags
+ * When both are true, returns combined suffix (archived first, alphabetically)
+ */
+function calculateSuffix({ archived, deleted, }) {
+    if (archived && deleted) {
+        return ARCHIVED_SUFFIX + DELETED_SUFFIX;
+    }
+    if (archived) {
+        return ARCHIVED_SUFFIX;
+    }
+    if (deleted) {
+        return DELETED_SUFFIX;
+    }
+    return "";
+}
+/**
+ * Execute a GSI query with common options
+ */
+async function executeQuery(indexName, keyValue, options = {}) {
+    const { ascending = false, limit, startKey } = options;
+    const docClient = getDocClient();
+    const tableName = getTableName();
+    const command = new libDynamodb.QueryCommand({
+        ExclusiveStartKey: startKey,
+        ExpressionAttributeNames: {
+            "#pk": indexName,
+        },
+        ExpressionAttributeValues: {
+            ":pkValue": keyValue,
+        },
+        IndexName: indexName,
+        KeyConditionExpression: "#pk = :pkValue",
+        ...(limit && { Limit: limit }),
+        ScanIndexForward: ascending,
+        TableName: tableName,
+    });
+    const response = await docClient.send(command);
+    return {
+        items: (response.Items ?? []),
+        lastEvaluatedKey: response.LastEvaluatedKey,
+    };
+}
+/**
+ * Query entities by organizational unit (parent hierarchy)
+ * Uses indexOu GSI
+ *
+ * Note: This is a regular async function (not serviceHandler) because it accepts
+ * complex startKey objects that can't be coerced by vocabulary's type system.
+ */
+async function queryByOu({ archived = false, ascending = false, deleted = false, limit, model, ou, startKey, }) {
+    const suffix = calculateSuffix({ archived, deleted });
+    const keyValue = buildIndexOu(ou, model) + suffix;
+    return executeQuery(INDEX_OU, keyValue, {
+        ascending,
+        limit,
+        startKey,
+    });
+}
+/**
+ * Query a single entity by human-friendly alias
+ * Uses indexAlias GSI
+ */
+const queryByAlias = vocabulary.serviceHandler({
+    alias: "queryByAlias",
+    description: "Query a single entity by human-friendly alias",
+    input: {
+        alias: { type: String, description: "Human-friendly alias" },
+        archived: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query archived entities instead of active ones",
+        },
+        deleted: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query deleted entities instead of active ones",
+        },
+        model: { type: String, description: "Entity model name" },
+        ou: { type: String, description: "Organizational unit (@ for root)" },
+    },
+    service: async ({ alias, archived, deleted, model, ou, }) => {
+        const aliasStr = alias;
+        const archivedBool = archived;
+        const deletedBool = deleted;
+        const modelStr = model;
+        const ouStr = ou;
+        const suffix = calculateSuffix({ archived: archivedBool, deleted: deletedBool });
+        const keyValue = buildIndexAlias(ouStr, modelStr, aliasStr) + suffix;
+        const result = await executeQuery(INDEX_ALIAS, keyValue, {
+            limit: 1,
+        });
+        return result.items[0] ?? null;
+    },
+});
+/**
+ * Query entities by category classification
+ * Uses indexClass GSI
+ *
+ * Note: This is a regular async function (not serviceHandler) because it accepts
+ * complex startKey objects that can't be coerced by vocabulary's type system.
+ */
+async function queryByClass({ archived = false, ascending = false, deleted = false, limit, model, ou, recordClass, startKey, }) {
+    const suffix = calculateSuffix({ archived, deleted });
+    const keyValue = buildIndexClass(ou, model, recordClass) + suffix;
+    return executeQuery(INDEX_CLASS, keyValue, {
+        ascending,
+        limit,
+        startKey,
+    });
+}
+/**
+ * Query entities by type classification
+ * Uses indexType GSI
+ *
+ * Note: This is a regular async function (not serviceHandler) because it accepts
+ * complex startKey objects that can't be coerced by vocabulary's type system.
+ */
+async function queryByType({ archived = false, ascending = false, deleted = false, limit, model, ou, startKey, type, }) {
+    const suffix = calculateSuffix({ archived, deleted });
+    const keyValue = buildIndexType(ou, model, type) + suffix;
+    return executeQuery(INDEX_TYPE, keyValue, {
+        ascending,
+        limit,
+        startKey,
+    });
+}
+/**
+ * Query a single entity by external ID
+ * Uses indexXid GSI
+ */
+const queryByXid = vocabulary.serviceHandler({
+    alias: "queryByXid",
+    description: "Query a single entity by external ID",
+    input: {
+        archived: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query archived entities instead of active ones",
+        },
+        deleted: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query deleted entities instead of active ones",
+        },
+        model: { type: String, description: "Entity model name" },
+        ou: { type: String, description: "Organizational unit (@ for root)" },
+        xid: { type: String, description: "External ID" },
+    },
+    service: async ({ archived, deleted, model, ou, xid, }) => {
+        const archivedBool = archived;
+        const deletedBool = deleted;
+        const modelStr = model;
+        const ouStr = ou;
+        const xidStr = xid;
+        const suffix = calculateSuffix({ archived: archivedBool, deleted: deletedBool });
+        const keyValue = buildIndexXid(ouStr, modelStr, xidStr) + suffix;
+        const result = await executeQuery(INDEX_XID, keyValue, {
+            limit: 1,
+        });
+        return result.items[0] ?? null;
+    },
+});
+
+const DEFAULT_ENDPOINT = "http://127.0.0.1:8000";
+const DEFAULT_REGION$1 = "us-east-1";
+const DEFAULT_TABLE_NAME$1 = "jaypie-local";
+/**
+ * DynamoDB table schema with Jaypie GSI pattern
+ */
+function createTableParams(tableName, billingMode) {
+    const gsiProjection = { ProjectionType: "ALL" };
+    return {
+        AttributeDefinitions: [
+            { AttributeName: "id", AttributeType: "S" },
+            { AttributeName: "indexAlias", AttributeType: "S" },
+            { AttributeName: "indexClass", AttributeType: "S" },
+            { AttributeName: "indexOu", AttributeType: "S" },
+            { AttributeName: "indexType", AttributeType: "S" },
+            { AttributeName: "indexXid", AttributeType: "S" },
+            { AttributeName: "model", AttributeType: "S" },
+            { AttributeName: "sequence", AttributeType: "N" },
+        ],
+        BillingMode: billingMode,
+        GlobalSecondaryIndexes: [
+            {
+                IndexName: "indexOu",
+                KeySchema: [
+                    { AttributeName: "indexOu", KeyType: "HASH" },
+                    { AttributeName: "sequence", KeyType: "RANGE" },
+                ],
+                Projection: gsiProjection,
+            },
+            {
+                IndexName: "indexAlias",
+                KeySchema: [
+                    { AttributeName: "indexAlias", KeyType: "HASH" },
+                    { AttributeName: "sequence", KeyType: "RANGE" },
+                ],
+                Projection: gsiProjection,
+            },
+            {
+                IndexName: "indexClass",
+                KeySchema: [
+                    { AttributeName: "indexClass", KeyType: "HASH" },
+                    { AttributeName: "sequence", KeyType: "RANGE" },
+                ],
+                Projection: gsiProjection,
+            },
+            {
+                IndexName: "indexType",
+                KeySchema: [
+                    { AttributeName: "indexType", KeyType: "HASH" },
+                    { AttributeName: "sequence", KeyType: "RANGE" },
+                ],
+                Projection: gsiProjection,
+            },
+            {
+                IndexName: "indexXid",
+                KeySchema: [
+                    { AttributeName: "indexXid", KeyType: "HASH" },
+                    { AttributeName: "sequence", KeyType: "RANGE" },
+                ],
+                Projection: gsiProjection,
+            },
+        ],
+        KeySchema: [
+            { AttributeName: "model", KeyType: "HASH" },
+            { AttributeName: "id", KeyType: "RANGE" },
+        ],
+        TableName: tableName,
+    };
+}
+/**
+ * Create DynamoDB table with Jaypie GSI schema
+ */
+const createTableHandler = vocabulary.serviceHandler({
+    alias: "dynamodb_create_table",
+    description: "Create DynamoDB table with Jaypie GSI schema",
+    input: {
+        billingMode: {
+            type: ["PAY_PER_REQUEST", "PROVISIONED"],
+            default: "PAY_PER_REQUEST",
+            description: "DynamoDB billing mode",
+        },
+        endpoint: {
+            type: String,
+            default: DEFAULT_ENDPOINT,
+            description: "DynamoDB endpoint URL",
+        },
+        tableName: {
+            type: String,
+            default: DEFAULT_TABLE_NAME$1,
+            description: "Table name to create",
+        },
+    },
+    service: async ({ billingMode, endpoint, tableName }) => {
+        const endpointStr = endpoint;
+        const tableNameStr = tableName;
+        const billingModeStr = billingMode;
+        const client = new clientDynamodb.DynamoDBClient({
+            credentials: {
+                accessKeyId: "local",
+                secretAccessKey: "local",
+            },
+            endpoint: endpointStr,
+            region: DEFAULT_REGION$1,
+        });
+        try {
+            // Check if table already exists
+            await client.send(new clientDynamodb.DescribeTableCommand({ TableName: tableNameStr }));
+            return {
+                message: `Table "${tableNameStr}" already exists`,
+                success: false,
+                tableName: tableNameStr,
+            };
+        }
+        catch (error) {
+            if (error.name !== "ResourceNotFoundException") {
+                throw error;
+            }
+        }
+        // Create the table
+        const tableParams = createTableParams(tableNameStr, billingModeStr);
+        await client.send(new clientDynamodb.CreateTableCommand(tableParams));
+        return {
+            message: "Table created successfully",
+            success: true,
+            tableName: tableNameStr,
+        };
+    },
+});
+
+const DEFAULT_ADMIN_PORT = 8001;
+const DEFAULT_DYNAMODB_PORT = 8000;
+const DEFAULT_PROJECT_NAME = "jaypie";
+const DEFAULT_TABLE_NAME = "jaypie-local";
+/**
+ * Generate docker-compose.yml for local DynamoDB development
+ */
+const dockerComposeHandler = vocabulary.serviceHandler({
+    alias: "dynamodb_generate_docker_compose",
+    description: "Generate docker-compose.yml for local DynamoDB development",
+    input: {
+        adminPort: {
+            type: Number,
+            default: DEFAULT_ADMIN_PORT,
+            description: "Port for DynamoDB Admin UI",
+        },
+        dynamodbPort: {
+            type: Number,
+            default: DEFAULT_DYNAMODB_PORT,
+            description: "Port for DynamoDB Local",
+        },
+        projectName: {
+            type: String,
+            default: DEFAULT_PROJECT_NAME,
+            description: "Project name for container naming",
+        },
+        tableName: {
+            type: String,
+            default: DEFAULT_TABLE_NAME,
+            description: "Default table name",
+        },
+    },
+    service: async ({ adminPort, dynamodbPort, projectName, tableName }) => {
+        const dockerCompose = `name: ${projectName}-dynamodb-stack
+
+services:
+  dynamodb:
+    image: amazon/dynamodb-local:latest
+    container_name: ${projectName}-dynamodb
+    command: "-jar DynamoDBLocal.jar -sharedDb -dbPath /data"
+    ports:
+      - "${dynamodbPort}:8000"
+    working_dir: /home/dynamodblocal
+    volumes:
+      - dynamodb_data:/data
+    user: "0:0"
+
+  dynamodb-admin:
+    image: aaronshaf/dynamodb-admin:latest
+    container_name: ${projectName}-dynamodb-admin
+    ports:
+      - "${adminPort}:8001"
+    environment:
+      - DYNAMO_ENDPOINT=http://dynamodb:8000
+      - AWS_REGION=us-east-1
+      - AWS_ACCESS_KEY_ID=local
+      - AWS_SECRET_ACCESS_KEY=local
+    depends_on:
+      - dynamodb
+
+volumes:
+  dynamodb_data:
+    driver: local
+`;
+        const envVars = {
+            AWS_REGION: "us-east-1",
+            DYNAMODB_ENDPOINT: `http://127.0.0.1:${dynamodbPort}`,
+            DYNAMODB_TABLE_NAME: tableName,
+        };
+        const envFile = `# DynamoDB Local Configuration
+DYNAMODB_TABLE_NAME=${tableName}
+DYNAMODB_ENDPOINT=http://127.0.0.1:${dynamodbPort}
+AWS_REGION=us-east-1
+`;
+        return {
+            dockerCompose,
+            envFile,
+            envVars,
+        };
+    },
+});
+
+const DEFAULT_REGION = "us-east-1";
+/**
+ * Ensure DynamoDB client is initialized from environment variables
+ * Called automatically before each MCP tool execution
+ */
+function ensureInitialized() {
+    if (isInitialized()) {
+        return;
+    }
+    const tableName = process.env.DYNAMODB_TABLE_NAME;
+    if (!tableName) {
+        throw new errors.ConfigurationError("DYNAMODB_TABLE_NAME environment variable is required");
+    }
+    initClient({
+        endpoint: process.env.DYNAMODB_ENDPOINT,
+        region: process.env.AWS_REGION || DEFAULT_REGION,
+        tableName,
+    });
+}
+
+/**
+ * Check DynamoDB connection status and configuration
+ */
+const statusHandler = vocabulary.serviceHandler({
+    alias: "dynamodb_status",
+    description: "Check DynamoDB connection status and configuration",
+    service: async () => {
+        ensureInitialized();
+        return {
+            endpoint: process.env.DYNAMODB_ENDPOINT || "AWS Default",
+            initialized: isInitialized(),
+            region: process.env.AWS_REGION || "us-east-1",
+            tableName: getTableName(),
+        };
+    },
+});
+
+/**
+ * Wrap a handler to auto-initialize before execution
+ */
+function wrapWithInit(handler) {
+    const wrapped = async (input) => {
+        ensureInitialized();
+        return handler(input);
+    };
+    // Preserve handler properties for MCP registration
+    Object.assign(wrapped, {
+        alias: handler.alias,
+        description: handler.description,
+        input: handler.input,
+    });
+    return wrapped;
+}
+// MCP-specific serviceHandler wrappers for functions with complex inputs
+// Note: These wrap the regular async functions to make them work with registerMcpTool
+/**
+ * MCP wrapper for putEntity
+ * Accepts entity JSON directly from LLM
+ */
+const mcpPutEntity = vocabulary.serviceHandler({
+    alias: "dynamodb_put",
+    description: "Create or replace an entity in DynamoDB (auto-indexes GSI keys)",
+    input: {
+        // Required entity fields
+        id: { type: String, description: "Entity ID (sort key)" },
+        model: { type: String, description: "Entity model name (partition key)" },
+        name: { type: String, description: "Entity name" },
+        ou: { type: String, description: "Organizational unit (@ for root)" },
+        // Optional fields
+        alias: { type: String, required: false, description: "Human-friendly alias" },
+        class: { type: String, required: false, description: "Category classification" },
+        type: { type: String, required: false, description: "Type classification" },
+        xid: { type: String, required: false, description: "External ID" },
+    },
+    service: async (input) => {
+        const now = new Date().toISOString();
+        const entity = {
+            alias: input.alias,
+            class: input.class,
+            createdAt: now,
+            id: input.id,
+            model: input.model,
+            name: input.name,
+            ou: input.ou,
+            sequence: Date.now(),
+            type: input.type,
+            updatedAt: now,
+            xid: input.xid,
+        };
+        return putEntity({ entity });
+    },
+});
+/**
+ * MCP wrapper for updateEntity
+ * Accepts entity JSON directly from LLM
+ */
+const mcpUpdateEntity = vocabulary.serviceHandler({
+    alias: "dynamodb_update",
+    description: "Update an entity in DynamoDB (sets updatedAt, re-indexes GSI keys)",
+    input: {
+        // Required fields to identify the entity
+        id: { type: String, description: "Entity ID (sort key)" },
+        model: { type: String, description: "Entity model name (partition key)" },
+        // Fields that can be updated
+        name: { type: String, required: false, description: "Entity name" },
+        ou: { type: String, required: false, description: "Organizational unit" },
+        alias: { type: String, required: false, description: "Human-friendly alias" },
+        class: { type: String, required: false, description: "Category classification" },
+        type: { type: String, required: false, description: "Type classification" },
+        xid: { type: String, required: false, description: "External ID" },
+    },
+    service: async (input) => {
+        // First get the existing entity
+        const existing = await getEntity({
+            id: input.id,
+            model: input.model,
+        });
+        if (!existing) {
+            return { error: "Entity not found", id: input.id, model: input.model };
+        }
+        // Merge updates
+        const entity = {
+            ...existing,
+            ...(input.alias !== undefined && { alias: input.alias }),
+            ...(input.class !== undefined && { class: input.class }),
+            ...(input.name !== undefined && { name: input.name }),
+            ...(input.ou !== undefined && { ou: input.ou }),
+            ...(input.type !== undefined && { type: input.type }),
+            ...(input.xid !== undefined && { xid: input.xid }),
+        };
+        return updateEntity({ entity });
+    },
+});
+/**
+ * MCP wrapper for queryByOu
+ * Note: Pagination via startKey is not exposed to MCP; use limit instead
+ */
+const mcpQueryByOu = vocabulary.serviceHandler({
+    alias: "dynamodb_query_ou",
+    description: "Query entities by organizational unit (parent hierarchy)",
+    input: {
+        model: { type: String, description: "Entity model name" },
+        ou: { type: String, description: "Organizational unit (@ for root)" },
+        archived: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query archived entities instead of active ones",
+        },
+        ascending: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Sort ascending (oldest first)",
+        },
+        deleted: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query deleted entities instead of active ones",
+        },
+        limit: {
+            type: Number,
+            required: false,
+            description: "Maximum number of items to return",
+        },
+    },
+    service: async (input) => {
+        return queryByOu({
+            archived: input.archived,
+            ascending: input.ascending,
+            deleted: input.deleted,
+            limit: input.limit,
+            model: input.model,
+            ou: input.ou,
+        });
+    },
+});
+/**
+ * MCP wrapper for queryByClass
+ * Note: Pagination via startKey is not exposed to MCP; use limit instead
+ */
+const mcpQueryByClass = vocabulary.serviceHandler({
+    alias: "dynamodb_query_class",
+    description: "Query entities by category classification",
+    input: {
+        model: { type: String, description: "Entity model name" },
+        ou: { type: String, description: "Organizational unit (@ for root)" },
+        recordClass: { type: String, description: "Category classification" },
+        archived: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query archived entities instead of active ones",
+        },
+        ascending: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Sort ascending (oldest first)",
+        },
+        deleted: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query deleted entities instead of active ones",
+        },
+        limit: {
+            type: Number,
+            required: false,
+            description: "Maximum number of items to return",
+        },
+    },
+    service: async (input) => {
+        return queryByClass({
+            archived: input.archived,
+            ascending: input.ascending,
+            deleted: input.deleted,
+            limit: input.limit,
+            model: input.model,
+            ou: input.ou,
+            recordClass: input.recordClass,
+        });
+    },
+});
+/**
+ * MCP wrapper for queryByType
+ * Note: Pagination via startKey is not exposed to MCP; use limit instead
+ */
+const mcpQueryByType = vocabulary.serviceHandler({
+    alias: "dynamodb_query_type",
+    description: "Query entities by type classification",
+    input: {
+        model: { type: String, description: "Entity model name" },
+        ou: { type: String, description: "Organizational unit (@ for root)" },
+        type: { type: String, description: "Type classification" },
+        archived: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query archived entities instead of active ones",
+        },
+        ascending: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Sort ascending (oldest first)",
+        },
+        deleted: {
+            type: Boolean,
+            default: false,
+            required: false,
+            description: "Query deleted entities instead of active ones",
+        },
+        limit: {
+            type: Number,
+            required: false,
+            description: "Maximum number of items to return",
+        },
+    },
+    service: async (input) => {
+        return queryByType({
+            archived: input.archived,
+            ascending: input.ascending,
+            deleted: input.deleted,
+            limit: input.limit,
+            model: input.model,
+            ou: input.ou,
+            type: input.type,
+        });
+    },
+});
+/**
+ * Register all DynamoDB MCP tools with a server
+ */
+function registerDynamoDbTools(config) {
+    const { includeAdmin = true, server } = config;
+    const tools = [];
+    // Entity operations
+    mcp.registerMcpTool({
+        handler: wrapWithInit(getEntity),
+        name: "dynamodb_get",
+        server,
+    });
+    tools.push("dynamodb_get");
+    mcp.registerMcpTool({
+        handler: wrapWithInit(mcpPutEntity),
+        name: "dynamodb_put",
+        server,
+    });
+    tools.push("dynamodb_put");
+    mcp.registerMcpTool({
+        handler: wrapWithInit(mcpUpdateEntity),
+        name: "dynamodb_update",
+        server,
+    });
+    tools.push("dynamodb_update");
+    mcp.registerMcpTool({
+        handler: wrapWithInit(deleteEntity),
+        name: "dynamodb_delete",
+        server,
+    });
+    tools.push("dynamodb_delete");
+    mcp.registerMcpTool({
+        handler: wrapWithInit(archiveEntity),
+        name: "dynamodb_archive",
+        server,
+    });
+    tools.push("dynamodb_archive");
+    mcp.registerMcpTool({
+        handler: wrapWithInit(destroyEntity),
+        name: "dynamodb_destroy",
+        server,
+    });
+    tools.push("dynamodb_destroy");
+    // Query operations
+    mcp.registerMcpTool({
+        handler: wrapWithInit(mcpQueryByOu),
+        name: "dynamodb_query_ou",
+        server,
+    });
+    tools.push("dynamodb_query_ou");
+    mcp.registerMcpTool({
+        handler: wrapWithInit(queryByAlias),
+        name: "dynamodb_query_alias",
+        server,
+    });
+    tools.push("dynamodb_query_alias");
+    mcp.registerMcpTool({
+        handler: wrapWithInit(mcpQueryByClass),
+        name: "dynamodb_query_class",
+        server,
+    });
+    tools.push("dynamodb_query_class");
+    mcp.registerMcpTool({
+        handler: wrapWithInit(mcpQueryByType),
+        name: "dynamodb_query_type",
+        server,
+    });
+    tools.push("dynamodb_query_type");
+    mcp.registerMcpTool({
+        handler: wrapWithInit(queryByXid),
+        name: "dynamodb_query_xid",
+        server,
+    });
+    tools.push("dynamodb_query_xid");
+    // Admin tools (MCP-only)
+    if (includeAdmin) {
+        mcp.registerMcpTool({ handler: statusHandler, server });
+        tools.push("dynamodb_status");
+        mcp.registerMcpTool({ handler: createTableHandler, server });
+        tools.push("dynamodb_create_table");
+        mcp.registerMcpTool({ handler: dockerComposeHandler, server });
+        tools.push("dynamodb_generate_docker_compose");
+    }
+    return { tools };
+}
+
+exports.createTableHandler = createTableHandler;
+exports.dockerComposeHandler = dockerComposeHandler;
+exports.ensureInitialized = ensureInitialized;
+exports.registerDynamoDbTools = registerDynamoDbTools;
+exports.statusHandler = statusHandler;
+//# sourceMappingURL=index.cjs.map