@jaypie/dynamodb 0.1.3 → 0.3.0

package/dist/esm/mcp/index.js

@@ -1,5 +1,5 @@
-import { registerMcpTool } from '@jaypie/vocabulary/mcp';
-import { serviceHandler } from '@jaypie/vocabulary';
+import { fabricMcp } from '@jaypie/fabric/mcp';
+import { getModelIndexes, populateIndexKeys, SEPARATOR, fabricService, ARCHIVED_SUFFIX, DELETED_SUFFIX, DEFAULT_INDEXES, getAllRegisteredIndexes } from '@jaypie/fabric';
 import { DynamoDBClient, DescribeTableCommand, CreateTableCommand } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient, GetCommand, PutCommand, DeleteCommand, QueryCommand } from '@aws-sdk/lib-dynamodb';
 import { ConfigurationError } from '@jaypie/errors';
@@ -75,70 +75,73 @@ function isInitialized() {
     return docClient !== null && tableName !== null;
 }
 
-// Primary markers
-const SEPARATOR = "#"; // Composite key separator
-// GSI names
+// Re-export shared constants from fabric
+// GSI names (derived from DEFAULT_INDEXES)
 const INDEX_ALIAS = "indexAlias";
 const INDEX_CLASS = "indexClass";
-const INDEX_OU = "indexOu";
+const INDEX_SCOPE = "indexScope";
 const INDEX_TYPE = "indexType";
 const INDEX_XID = "indexXid";
-// Index suffixes for soft state
-const ARCHIVED_SUFFIX = "#archived";
-const DELETED_SUFFIX = "#deleted";
 
+// =============================================================================
+// Key Builders
+// =============================================================================
 /**
- * Build the indexOu key for hierarchical queries
- * @param ou - The organizational unit (APEX or "{parent.model}#{parent.id}")
+ * Build the indexScope key for hierarchical queries
+ * @param scope - The scope (APEX or "{parent.model}#{parent.id}")
  * @param model - The entity model name
- * @returns Composite key: "{ou}#{model}"
+ * @returns Composite key: "{scope}#{model}"
  */
-function buildIndexOu(ou, model) {
-    return `${ou}${SEPARATOR}${model}`;
+function buildIndexScope(scope, model) {
+    return `${scope}${SEPARATOR}${model}`;
 }
 /**
  * Build the indexAlias key for human-friendly lookups
- * @param ou - The organizational unit
+ * @param scope - The scope
  * @param model - The entity model name
  * @param alias - The human-friendly alias
- * @returns Composite key: "{ou}#{model}#{alias}"
+ * @returns Composite key: "{scope}#{model}#{alias}"
  */
-function buildIndexAlias(ou, model, alias) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${alias}`;
+function buildIndexAlias(scope, model, alias) {
+    return `${scope}${SEPARATOR}${model}${SEPARATOR}${alias}`;
 }
 /**
  * Build the indexClass key for category filtering
- * @param ou - The organizational unit
+ * @param scope - The scope
  * @param model - The entity model name
  * @param recordClass - The category classification
- * @returns Composite key: "{ou}#{model}#{class}"
+ * @returns Composite key: "{scope}#{model}#{class}"
  */
-function buildIndexClass(ou, model, recordClass) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${recordClass}`;
+function buildIndexClass(scope, model, recordClass) {
+    return `${scope}${SEPARATOR}${model}${SEPARATOR}${recordClass}`;
 }
 /**
  * Build the indexType key for type filtering
- * @param ou - The organizational unit
+ * @param scope - The scope
  * @param model - The entity model name
  * @param type - The type classification
- * @returns Composite key: "{ou}#{model}#{type}"
+ * @returns Composite key: "{scope}#{model}#{type}"
  */
-function buildIndexType(ou, model, type) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${type}`;
+function buildIndexType(scope, model, type) {
+    return `${scope}${SEPARATOR}${model}${SEPARATOR}${type}`;
 }
 /**
  * Build the indexXid key for external ID lookups
- * @param ou - The organizational unit
+ * @param scope - The scope
  * @param model - The entity model name
  * @param xid - The external ID
- * @returns Composite key: "{ou}#{model}#{xid}"
+ * @returns Composite key: "{scope}#{model}#{xid}"
  */
-function buildIndexXid(ou, model, xid) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${xid}`;
+function buildIndexXid(scope, model, xid) {
+    return `${scope}${SEPARATOR}${model}${SEPARATOR}${xid}`;
 }
 /**
  * Auto-populate GSI index keys on an entity
- * - indexOu is always populated from ou + model
+ *
+ * Uses the model's registered indexes (from vocabulary registry) or
+ * DEFAULT_INDEXES if no custom indexes are registered.
+ *
+ * - indexScope is always populated from scope + 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
@@ -149,27 +152,9 @@ function buildIndexXid(ou, model, xid) {
  * @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;
+    const indexes = getModelIndexes(entity.model);
+    // Cast through unknown to bridge the type gap between StorableEntity and IndexableModel
+    return populateIndexKeys(entity, indexes, suffix);
 }
 
 /**
@@ -192,7 +177,7 @@ function calculateEntitySuffix(entity) {
 /**
  * Get a single entity by primary key
  */
-const getEntity = serviceHandler({
+const getEntity = fabricService({
     alias: "getEntity",
     description: "Get a single entity by primary key",
     input: {
@@ -214,8 +199,8 @@ const getEntity = serviceHandler({
  * 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.
+ * Note: This is a regular async function (not fabricService) because it accepts
+ * complex StorableEntity objects that can't be coerced by vocabulary's type system.
  */
 async function putEntity({ entity, }) {
     const docClient = getDocClient();
@@ -233,8 +218,8 @@ async function putEntity({ entity, }) {
  * 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.
+ * Note: This is a regular async function (not fabricService) because it accepts
+ * complex StorableEntity objects that can't be coerced by vocabulary's type system.
  */
 async function updateEntity({ entity, }) {
     const docClient = getDocClient();
@@ -255,7 +240,7 @@ async function updateEntity({ entity, }) {
  * Soft delete an entity by setting deletedAt timestamp
  * Re-indexes with appropriate suffix based on archived/deleted state
  */
-const deleteEntity = serviceHandler({
+const deleteEntity = fabricService({
     alias: "deleteEntity",
     description: "Soft delete an entity (sets deletedAt timestamp)",
     input: {
@@ -292,7 +277,7 @@ const deleteEntity = serviceHandler({
  * Archive an entity by setting archivedAt timestamp
  * Re-indexes with appropriate suffix based on archived/deleted state
  */
-const archiveEntity = serviceHandler({
+const archiveEntity = fabricService({
     alias: "archiveEntity",
     description: "Archive an entity (sets archivedAt timestamp)",
     input: {
@@ -329,7 +314,7 @@ const archiveEntity = serviceHandler({
  * Hard delete an entity (permanently removes from table)
  * Use with caution - prefer deleteEntity for soft delete
  */
-const destroyEntity = serviceHandler({
+const destroyEntity = fabricService({
     alias: "destroyEntity",
     description: "Hard delete an entity (permanently removes from table)",
     input: {
@@ -392,16 +377,16 @@ async function executeQuery(indexName, keyValue, options = {}) {
     };
 }
 /**
- * Query entities by organizational unit (parent hierarchy)
- * Uses indexOu GSI
+ * Query entities by scope (parent hierarchy)
+ * Uses indexScope GSI
  *
- * Note: This is a regular async function (not serviceHandler) because it accepts
+ * Note: This is a regular async function (not fabricService) 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, }) {
+async function queryByScope({ archived = false, ascending = false, deleted = false, limit, model, scope, startKey, }) {
     const suffix = calculateSuffix({ archived, deleted });
-    const keyValue = buildIndexOu(ou, model) + suffix;
-    return executeQuery(INDEX_OU, keyValue, {
+    const keyValue = buildIndexScope(scope, model) + suffix;
+    return executeQuery(INDEX_SCOPE, keyValue, {
         ascending,
         limit,
         startKey,
@@ -411,7 +396,7 @@ async function queryByOu({ archived = false, ascending = false, deleted = false,
  * Query a single entity by human-friendly alias
  * Uses indexAlias GSI
  */
-const queryByAlias = serviceHandler({
+const queryByAlias = fabricService({
     alias: "queryByAlias",
     description: "Query a single entity by human-friendly alias",
     input: {
@@ -429,16 +414,19 @@ const queryByAlias = serviceHandler({
             description: "Query deleted entities instead of active ones",
         },
         model: { type: String, description: "Entity model name" },
-        ou: { type: String, description: "Organizational unit (@ for root)" },
+        scope: { type: String, description: "Scope (@ for root)" },
     },
-    service: async ({ alias, archived, deleted, model, ou, }) => {
+    service: async ({ alias, archived, deleted, model, scope, }) => {
         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 scopeStr = scope;
+        const suffix = calculateSuffix({
+            archived: archivedBool,
+            deleted: deletedBool,
+        });
+        const keyValue = buildIndexAlias(scopeStr, modelStr, aliasStr) + suffix;
         const result = await executeQuery(INDEX_ALIAS, keyValue, {
             limit: 1,
         });
@@ -449,12 +437,12 @@ const queryByAlias = serviceHandler({
  * Query entities by category classification
  * Uses indexClass GSI
  *
- * Note: This is a regular async function (not serviceHandler) because it accepts
+ * Note: This is a regular async function (not fabricService) 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, }) {
+async function queryByClass({ archived = false, ascending = false, deleted = false, limit, model, scope, recordClass, startKey, }) {
     const suffix = calculateSuffix({ archived, deleted });
-    const keyValue = buildIndexClass(ou, model, recordClass) + suffix;
+    const keyValue = buildIndexClass(scope, model, recordClass) + suffix;
     return executeQuery(INDEX_CLASS, keyValue, {
         ascending,
         limit,
@@ -465,12 +453,12 @@ async function queryByClass({ archived = false, ascending = false, deleted = fal
  * Query entities by type classification
  * Uses indexType GSI
  *
- * Note: This is a regular async function (not serviceHandler) because it accepts
+ * Note: This is a regular async function (not fabricService) 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, }) {
+async function queryByType({ archived = false, ascending = false, deleted = false, limit, model, scope, startKey, type, }) {
     const suffix = calculateSuffix({ archived, deleted });
-    const keyValue = buildIndexType(ou, model, type) + suffix;
+    const keyValue = buildIndexType(scope, model, type) + suffix;
     return executeQuery(INDEX_TYPE, keyValue, {
         ascending,
         limit,
@@ -481,7 +469,7 @@ async function queryByType({ archived = false, ascending = false, deleted = fals
  * Query a single entity by external ID
  * Uses indexXid GSI
  */
-const queryByXid = serviceHandler({
+const queryByXid = fabricService({
     alias: "queryByXid",
     description: "Query a single entity by external ID",
     input: {
@@ -498,17 +486,20 @@ const queryByXid = serviceHandler({
             description: "Query deleted entities instead of active ones",
         },
         model: { type: String, description: "Entity model name" },
-        ou: { type: String, description: "Organizational unit (@ for root)" },
+        scope: { type: String, description: "Scope (@ for root)" },
         xid: { type: String, description: "External ID" },
     },
-    service: async ({ archived, deleted, model, ou, xid, }) => {
+    service: async ({ archived, deleted, model, scope, xid, }) => {
         const archivedBool = archived;
         const deletedBool = deleted;
         const modelStr = model;
-        const ouStr = ou;
+        const scopeStr = scope;
         const xidStr = xid;
-        const suffix = calculateSuffix({ archived: archivedBool, deleted: deletedBool });
-        const keyValue = buildIndexXid(ouStr, modelStr, xidStr) + suffix;
+        const suffix = calculateSuffix({
+            archived: archivedBool,
+            deleted: deletedBool,
+        });
+        const keyValue = buildIndexXid(scopeStr, modelStr, xidStr) + suffix;
         const result = await executeQuery(INDEX_XID, keyValue, {
             limit: 1,
         });
@@ -519,65 +510,106 @@ const queryByXid = serviceHandler({
 const DEFAULT_ENDPOINT = "http://127.0.0.1:8000";
 const DEFAULT_REGION$1 = "us-east-1";
 const DEFAULT_TABLE_NAME$1 = "jaypie-local";
+// =============================================================================
+// Index to GSI Conversion
+// =============================================================================
+/**
+ * Generate an index name from pk fields (if not provided)
+ */
+function generateIndexName(pk) {
+    const suffix = pk
+        .map((field) => field.charAt(0).toUpperCase() + field.slice(1))
+        .join("");
+    return `index${suffix}`;
+}
+/**
+ * Collect all unique indexes from DEFAULT_INDEXES and registered models
+ */
+function collectAllIndexes() {
+    const indexMap = new Map();
+    // Add DEFAULT_INDEXES first
+    for (const index of DEFAULT_INDEXES) {
+        const name = index.name ?? generateIndexName(index.pk);
+        indexMap.set(name, { ...index, name });
+    }
+    // Add registered model indexes (will not overwrite if name already exists)
+    for (const index of getAllRegisteredIndexes()) {
+        const name = index.name ?? generateIndexName(index.pk);
+        if (!indexMap.has(name)) {
+            indexMap.set(name, { ...index, name });
+        }
+    }
+    return Array.from(indexMap.values());
+}
+/**
+ * Build attribute definitions from indexes
+ */
+function buildAttributeDefinitions(indexes) {
+    const attrs = new Map();
+    // Primary key attributes
+    attrs.set("model", "S");
+    attrs.set("id", "S");
+    attrs.set("sequence", "N");
+    // GSI attributes (partition keys are always strings)
+    for (const index of indexes) {
+        const indexName = index.name ?? generateIndexName(index.pk);
+        attrs.set(indexName, "S");
+    }
+    // Sort keys (sequence is always a number, others would be strings)
+    // Note: Currently all indexes use sequence as SK, so this is mostly future-proofing
+    for (const index of indexes) {
+        const sk = index.sk ?? ["sequence"];
+        for (const skField of sk) {
+            if (!attrs.has(skField)) {
+                // Assume string unless it's sequence
+                attrs.set(skField, skField === "sequence" ? "N" : "S");
+            }
+        }
+    }
+    return Array.from(attrs.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, type]) => ({
+        AttributeName: name,
+        AttributeType: type,
+    }));
+}
+/**
+ * Build GSI definitions from indexes
+ */
+function buildGSIs(indexes) {
+    const gsiProjection = { ProjectionType: "ALL" };
+    return indexes.map((index) => {
+        const indexName = index.name ?? generateIndexName(index.pk);
+        const sk = index.sk ?? ["sequence"];
+        // For GSIs, the partition key attribute name IS the index name
+        // (e.g., indexOu stores the composite key value "@#record")
+        return {
+            IndexName: indexName,
+            KeySchema: [
+                { AttributeName: indexName, KeyType: "HASH" },
+                // Use first SK field as the range key attribute
+                { AttributeName: sk[0], KeyType: "RANGE" },
+            ],
+            Projection: gsiProjection,
+        };
+    });
+}
+// =============================================================================
+// Table Creation
+// =============================================================================
 /**
  * DynamoDB table schema with Jaypie GSI pattern
+ *
+ * Collects indexes from:
+ * 1. DEFAULT_INDEXES (5 standard GSIs)
+ * 2. Any custom indexes registered via registerModel()
  */
 function createTableParams(tableName, billingMode) {
-    const gsiProjection = { ProjectionType: "ALL" };
+    const allIndexes = collectAllIndexes();
     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" },
-        ],
+        AttributeDefinitions: buildAttributeDefinitions(allIndexes),
         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,
-            },
-        ],
+        GlobalSecondaryIndexes: buildGSIs(allIndexes),
         KeySchema: [
             { AttributeName: "model", KeyType: "HASH" },
             { AttributeName: "id", KeyType: "RANGE" },
@@ -588,7 +620,7 @@ function createTableParams(tableName, billingMode) {
 /**
  * Create DynamoDB table with Jaypie GSI schema
  */
-const createTableHandler = serviceHandler({
+const createTableHandler = fabricService({
     alias: "dynamodb_create_table",
     description: "Create DynamoDB table with Jaypie GSI schema",
     input: {
@@ -652,7 +684,7 @@ const DEFAULT_TABLE_NAME = "jaypie-local";
 /**
  * Generate docker-compose.yml for local DynamoDB development
  */
-const dockerComposeHandler = serviceHandler({
+const dockerComposeHandler = fabricService({
     alias: "dynamodb_generate_docker_compose",
     description: "Generate docker-compose.yml for local DynamoDB development",
     input: {
@@ -750,7 +782,7 @@ function ensureInitialized() {
 /**
  * Check DynamoDB connection status and configuration
  */
-const statusHandler = serviceHandler({
+const statusHandler = fabricService({
     alias: "dynamodb_status",
     description: "Check DynamoDB connection status and configuration",
     service: async () => {
@@ -781,12 +813,12 @@ function wrapWithInit(handler) {
     return wrapped;
 }
 // MCP-specific serviceHandler wrappers for functions with complex inputs
-// Note: These wrap the regular async functions to make them work with registerMcpTool
+// Note: These wrap the regular async functions to make them work with fabricMcp
 /**
  * MCP wrapper for putEntity
  * Accepts entity JSON directly from LLM
  */
-const mcpPutEntity = serviceHandler({
+const mcpPutEntity = fabricService({
     alias: "dynamodb_put",
     description: "Create or replace an entity in DynamoDB (auto-indexes GSI keys)",
     input: {
@@ -794,10 +826,18 @@ const mcpPutEntity = serviceHandler({
         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)" },
+        scope: { type: String, description: "Scope (@ for root)" },
         // Optional fields
-        alias: { type: String, required: false, description: "Human-friendly alias" },
-        class: { type: String, required: false, description: "Category classification" },
+        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" },
     },
@@ -810,7 +850,7 @@ const mcpPutEntity = serviceHandler({
             id: input.id,
             model: input.model,
             name: input.name,
-            ou: input.ou,
+            scope: input.scope,
             sequence: Date.now(),
             type: input.type,
             updatedAt: now,
@@ -823,7 +863,7 @@ const mcpPutEntity = serviceHandler({
  * MCP wrapper for updateEntity
  * Accepts entity JSON directly from LLM
  */
-const mcpUpdateEntity = serviceHandler({
+const mcpUpdateEntity = fabricService({
     alias: "dynamodb_update",
     description: "Update an entity in DynamoDB (sets updatedAt, re-indexes GSI keys)",
     input: {
@@ -832,9 +872,17 @@ const mcpUpdateEntity = serviceHandler({
         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" },
+        scope: { type: String, required: false, description: "Scope" },
+        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" },
     },
@@ -853,7 +901,7 @@ const mcpUpdateEntity = serviceHandler({
             ...(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.scope !== undefined && { scope: input.scope }),
             ...(input.type !== undefined && { type: input.type }),
             ...(input.xid !== undefined && { xid: input.xid }),
         };
@@ -861,15 +909,15 @@ const mcpUpdateEntity = serviceHandler({
     },
 });
 /**
- * MCP wrapper for queryByOu
+ * MCP wrapper for queryByScope
  * Note: Pagination via startKey is not exposed to MCP; use limit instead
  */
-const mcpQueryByOu = serviceHandler({
-    alias: "dynamodb_query_ou",
-    description: "Query entities by organizational unit (parent hierarchy)",
+const mcpQueryByScope = fabricService({
+    alias: "dynamodb_query_scope",
+    description: "Query entities by scope (parent hierarchy)",
     input: {
         model: { type: String, description: "Entity model name" },
-        ou: { type: String, description: "Organizational unit (@ for root)" },
+        scope: { type: String, description: "Scope (@ for root)" },
         archived: {
             type: Boolean,
             default: false,
@@ -895,13 +943,13 @@ const mcpQueryByOu = serviceHandler({
         },
     },
     service: async (input) => {
-        return queryByOu({
+        return queryByScope({
             archived: input.archived,
             ascending: input.ascending,
             deleted: input.deleted,
             limit: input.limit,
             model: input.model,
-            ou: input.ou,
+            scope: input.scope,
         });
     },
 });
@@ -909,12 +957,12 @@ const mcpQueryByOu = serviceHandler({
  * MCP wrapper for queryByClass
  * Note: Pagination via startKey is not exposed to MCP; use limit instead
  */
-const mcpQueryByClass = serviceHandler({
+const mcpQueryByClass = fabricService({
     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)" },
+        scope: { type: String, description: "Scope (@ for root)" },
         recordClass: { type: String, description: "Category classification" },
         archived: {
             type: Boolean,
@@ -947,7 +995,7 @@ const mcpQueryByClass = serviceHandler({
             deleted: input.deleted,
             limit: input.limit,
             model: input.model,
-            ou: input.ou,
+            scope: input.scope,
             recordClass: input.recordClass,
         });
     },
@@ -956,12 +1004,12 @@ const mcpQueryByClass = serviceHandler({
  * MCP wrapper for queryByType
  * Note: Pagination via startKey is not exposed to MCP; use limit instead
  */
-const mcpQueryByType = serviceHandler({
+const mcpQueryByType = fabricService({
     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)" },
+        scope: { type: String, description: "Scope (@ for root)" },
         type: { type: String, description: "Type classification" },
         archived: {
             type: Boolean,
@@ -994,7 +1042,7 @@ const mcpQueryByType = serviceHandler({
             deleted: input.deleted,
             limit: input.limit,
             model: input.model,
-            ou: input.ou,
+            scope: input.scope,
             type: input.type,
         });
     },
@@ -1006,80 +1054,80 @@ function registerDynamoDbTools(config) {
     const { includeAdmin = true, server } = config;
     const tools = [];
     // Entity operations
-    registerMcpTool({
-        handler: wrapWithInit(getEntity),
+    fabricMcp({
+        service: wrapWithInit(getEntity),
         name: "dynamodb_get",
         server,
     });
     tools.push("dynamodb_get");
-    registerMcpTool({
-        handler: wrapWithInit(mcpPutEntity),
+    fabricMcp({
+        service: wrapWithInit(mcpPutEntity),
         name: "dynamodb_put",
         server,
     });
     tools.push("dynamodb_put");
-    registerMcpTool({
-        handler: wrapWithInit(mcpUpdateEntity),
+    fabricMcp({
+        service: wrapWithInit(mcpUpdateEntity),
         name: "dynamodb_update",
         server,
     });
     tools.push("dynamodb_update");
-    registerMcpTool({
-        handler: wrapWithInit(deleteEntity),
+    fabricMcp({
+        service: wrapWithInit(deleteEntity),
         name: "dynamodb_delete",
         server,
     });
     tools.push("dynamodb_delete");
-    registerMcpTool({
-        handler: wrapWithInit(archiveEntity),
+    fabricMcp({
+        service: wrapWithInit(archiveEntity),
         name: "dynamodb_archive",
         server,
     });
     tools.push("dynamodb_archive");
-    registerMcpTool({
-        handler: wrapWithInit(destroyEntity),
+    fabricMcp({
+        service: wrapWithInit(destroyEntity),
         name: "dynamodb_destroy",
         server,
     });
     tools.push("dynamodb_destroy");
     // Query operations
-    registerMcpTool({
-        handler: wrapWithInit(mcpQueryByOu),
-        name: "dynamodb_query_ou",
+    fabricMcp({
+        service: wrapWithInit(mcpQueryByScope),
+        name: "dynamodb_query_scope",
         server,
     });
-    tools.push("dynamodb_query_ou");
-    registerMcpTool({
-        handler: wrapWithInit(queryByAlias),
+    tools.push("dynamodb_query_scope");
+    fabricMcp({
+        service: wrapWithInit(queryByAlias),
         name: "dynamodb_query_alias",
         server,
     });
     tools.push("dynamodb_query_alias");
-    registerMcpTool({
-        handler: wrapWithInit(mcpQueryByClass),
+    fabricMcp({
+        service: wrapWithInit(mcpQueryByClass),
         name: "dynamodb_query_class",
         server,
     });
     tools.push("dynamodb_query_class");
-    registerMcpTool({
-        handler: wrapWithInit(mcpQueryByType),
+    fabricMcp({
+        service: wrapWithInit(mcpQueryByType),
         name: "dynamodb_query_type",
         server,
     });
     tools.push("dynamodb_query_type");
-    registerMcpTool({
-        handler: wrapWithInit(queryByXid),
+    fabricMcp({
+        service: wrapWithInit(queryByXid),
         name: "dynamodb_query_xid",
         server,
     });
     tools.push("dynamodb_query_xid");
     // Admin tools (MCP-only)
     if (includeAdmin) {
-        registerMcpTool({ handler: statusHandler, server });
+        fabricMcp({ service: statusHandler, server });
         tools.push("dynamodb_status");
-        registerMcpTool({ handler: createTableHandler, server });
+        fabricMcp({ service: createTableHandler, server });
         tools.push("dynamodb_create_table");
-        registerMcpTool({ handler: dockerComposeHandler, server });
+        fabricMcp({ service: dockerComposeHandler, server });
         tools.push("dynamodb_generate_docker_compose");
     }
     return { tools };