@enfyra/mcp-server 0.1.21 → 0.1.23

package/dist/lib/table-tools.js

@@ -6,7 +6,7 @@ import { fetchAPI } from './fetch.js';
 import { jsonContent } from './response-format.js';
 import { assertGlobalRulesAck, globalRulesAckParam } from './required-knowledge.js';
 function bulkObjectArrayParam(z, label) {
-    return z.union([z.array(z.record(z.any())), z.string()]).describe(`${label} as a native JSON array of objects. JSON string is accepted only for older clients.`);
+    return z.union([z.array(z.record(z.any())), z.string()]).describe(`${label} as a native JSON array of objects. Do not JSON.stringify unless your MCP client cannot send arrays.`);
 }
 let schemaQueue = Promise.resolve();
 function withSchemaQueue(operation) {
@@ -44,6 +44,7 @@ const FALLBACK_COLUMN_TYPES = [
     'richtext',
     'float',
 ];
+const AUTO_MANAGED_COLUMN_NAMES = new Set(['id', '_id', 'createdAt', 'updatedAt']);
 const COLUMN_TYPE_ALIAS_HINTS = [
     'Use varchar for short strings; text or richtext for long prose.',
     'Use float for prices, money, percentages, ratings, and decimal-like numbers unless the live instance explicitly lists decimal.',
@@ -131,6 +132,9 @@ function parseJsonArrayParam(name, value) {
     return parsed;
 }
 function parseBulkItemsParam(name, value) {
+    if (value === undefined || value === null || value === '') {
+        throw new Error(`${name} must be a native JSON array. Pass one object in the array for a single mutation.`);
+    }
     const parsed = typeof value === 'string' ? JSON.parse(value) : value;
     if (!Array.isArray(parsed)) {
         throw new Error(`${name} must be a JSON array. Pass one object in the array for a single mutation.`);
@@ -171,6 +175,97 @@ function normalizeConstraintGroupsValue(name, value) {
     }
     return normalizeConstraintGroups(name, parsed);
 }
+function stripAutoManagedColumns(columns) {
+    const skippedAutoColumns = [];
+    const filtered = columns.filter((column) => {
+        const name = String(column?.name ?? '');
+        if (!AUTO_MANAGED_COLUMN_NAMES.has(name))
+            return true;
+        skippedAutoColumns.push({
+            name,
+            reason: 'Enfyra manages id/createdAt/updatedAt automatically during table creation.',
+        });
+        return false;
+    });
+    return { columns: filtered, skippedAutoColumns };
+}
+function assertColumnNameCanBeCreated(name, context) {
+    const columnName = String(name ?? '');
+    if (AUTO_MANAGED_COLUMN_NAMES.has(columnName)) {
+        throw new Error(`${context} "${columnName}" is auto-managed by Enfyra. Do not create id, _id, createdAt, or updatedAt columns manually.`);
+    }
+}
+function assertNoDuplicateFieldNames(fieldNames, context) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const name of fieldNames.filter(Boolean)) {
+        if (seen.has(name))
+            duplicates.add(name);
+        seen.add(name);
+    }
+    if (duplicates.size > 0) {
+        throw new Error(`${context} has duplicate field name(s): ${[...duplicates].join(', ')}. Column names and relation propertyName values share one namespace.`);
+    }
+}
+function preflightCreateTableDefinitions(items) {
+    items.forEach((item, index) => {
+        const columns = Array.isArray(item.columns) ? item.columns : parseJsonArrayParam(`items[${index}].columns`, item.columns || '[]');
+        const relations = Array.isArray(item.relations) ? item.relations : parseJsonArrayParam(`items[${index}].relations`, item.relations || '[]');
+        const { columns: userColumns } = stripAutoManagedColumns(columns);
+        const columnNames = userColumns.map((column) => String(column?.name ?? '')).filter(Boolean);
+        const relationNames = relations.map((relation) => String(relation?.propertyName ?? '')).filter(Boolean);
+        assertNoDuplicateFieldNames([...columnNames, ...relationNames], `create_tables items[${index}] (${item.name || '<unnamed>'})`);
+        const logicalFields = new Set([...AUTO_MANAGED_COLUMN_NAMES, ...columnNames, ...relationNames]);
+        const indexes = normalizeConstraintGroupsValue(`items[${index}].indexes`, item.indexes ?? []);
+        const uniques = normalizeConstraintGroupsValue(`items[${index}].uniques`, item.uniques ?? []);
+        const unknownConstraintFields = [...indexes, ...uniques]
+            .flat()
+            .filter((field) => !logicalFields.has(field));
+        if (unknownConstraintFields.length > 0) {
+            throw new Error(`create_tables items[${index}] (${item.name || '<unnamed>'}) has indexes/uniques referencing undeclared field(s): ${[...new Set(unknownConstraintFields)].join(', ')}. ` +
+                'Declare each field as a column or relation propertyName in the same table item. For relation-based unique pairs added after create, first create the relations, then call update_tables with the unique group.');
+        }
+    });
+}
+function splitRelationConstraintGroups(groups, relationNames) {
+    const immediate = [];
+    const deferred = [];
+    for (const group of groups) {
+        if (group.some((field) => relationNames.has(field)))
+            deferred.push(group);
+        else
+            immediate.push(group);
+    }
+    return { immediate, deferred };
+}
+function mergeConstraintGroups(existing, additions) {
+    const seen = new Set(existing.map((group) => JSON.stringify(group)));
+    const merged = [...existing];
+    for (const group of additions) {
+        const key = JSON.stringify(group);
+        if (!seen.has(key)) {
+            seen.add(key);
+            merged.push(group);
+        }
+    }
+    return merged;
+}
+function resolveRelationConstraintGroups(table, groups, groupName) {
+    const relationByProperty = new Map((table.relations || [])
+        .filter((relation) => relation?.propertyName)
+        .map((relation) => [relation.propertyName, relation]));
+    return groups.map((group) => group.map((field) => {
+        const relation = relationByProperty.get(field);
+        if (!relation)
+            return field;
+        const physicalColumn = relation.foreignKeyColumn || relation.fkColumn || relation.fkCol;
+        if (!physicalColumn) {
+            throw new Error(`${groupName} uses relation propertyName "${field}", but the created relation did not expose a physical FK column for indexing. ` +
+                'This usually means the relation is not a direct many-to-one/one-to-one relation. Keep relation indexes/uniques only on direct owning relations.');
+        }
+        return physicalColumn;
+    }));
+}
 export function assertIndexesDoNotReferenceUniqueFields(indexes, uniques) {
     const uniqueFields = new Set(uniques.flat());
     const conflicts = indexes
@@ -261,6 +356,11 @@ function parseColumnTypeOptions(options) {
         .map((item) => item.trim().replace(/^"|"$/g, ''))
         .filter(Boolean);
 }
+function normalizeColumnOptionsValue(options) {
+    if (options === undefined)
+        return undefined;
+    return typeof options === 'string' ? JSON.parse(options) : options;
+}
 export function getSupportedColumnTypesFromMetadata(metadata) {
     const columnTable = normalizeTablesFromMetadata(metadata).find((table) => table?.name === 'enfyra_column');
     const typeColumn = columnTable?.columns?.find((column) => column?.name === 'type');
@@ -410,7 +510,7 @@ export function buildColumnDefinition({ name, type, supportedTypes, isNullable,
     if (description !== undefined)
         column.description = description;
     if (options !== undefined)
-        column.options = JSON.parse(options);
+        column.options = normalizeColumnOptionsValue(options);
     return column;
 }
 /**
@@ -430,6 +530,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
             }
             const supportedTypes = getSupportedColumnTypesFromMetadata(metadata);
             const normalized = normalizeColumnTypeForLiveMetadata(args.type, supportedTypes);
+            assertColumnNameCanBeCreated(args.name, 'create_columns');
             const existingColumns = getPatchableColumns(tableData.columns);
             const beforeIds = existingColumns.map((column) => String(getId(column)));
             const newCol = buildColumnDefinition({ ...args, supportedTypes });
@@ -452,10 +553,14 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         assertGlobalRulesAck(args.globalRulesAckKey);
         return withSchemaQueue(async () => {
             assertNoForbiddenRelationKeys(args);
-            const { sourceTableId, targetTableId, type, propertyName, inversePropertyName, mappedBy, isNullable, onDelete, description } = args;
+            const { sourceTableId, targetTableId, targetTable, type, propertyName, inversePropertyName, mappedBy, isNullable, onDelete, description } = args;
+            const targetRef = targetTableId ?? targetTable;
+            if (targetRef === undefined || targetRef === null || targetRef === '') {
+                throw new Error('create_relations requires targetTableId or targetTable. Pass an existing table id, name, or alias.');
+            }
             const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
             const resolvedSourceTableId = resolveTableIdentifierFromMetadata(metadata, sourceTableId, 'sourceTableId');
-            const resolvedTargetTableId = resolveTableIdentifierFromMetadata(metadata, targetTableId, 'targetTableId');
+            const resolvedTargetTableId = resolveTableIdentifierFromMetadata(metadata, targetRef, 'targetTableId');
             const tableData = await fetchTableWithDetails(ENFYRA_API_URL, resolvedSourceTableId);
             if (!tableData) {
                 throw new Error(`Table ${sourceTableId} not found.`);
@@ -569,7 +674,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     }
     const columnCreateSchema = {
         tableId: z.string().describe('Table definition ID (from get_all_tables or create_tables).'),
-        name: z.string().describe('Column name (e.g., "title", "webhook_secret"). Lowercase with underscores.'),
+        name: z.string().describe('Column name (e.g., "title", "webhook_secret"). Lowercase with underscores. Do not create id, _id, createdAt, or updatedAt; Enfyra manages them automatically.'),
         type: z.string().describe('Column type from the live enfyra_column.type enum. Common valid types are int, varchar, text, boolean, uuid, ObjectId, bigint, date, datetime, timestamp, enum, simple-json, code, array-select, richtext, and float. The tool normalizes common aliases before sending: decimal/numeric/money/number -> float when decimal is not live-supported, longtext -> text, json/jsonb/object/array -> simple-json when live-supported, string -> varchar. Prefer relations instead of *_id columns.'),
         isNullable: z.boolean().optional().default(true).describe('Set to false if column cannot be null.'),
         isUnique: z.boolean().optional().default(false).describe('Set to true for unique constraint.'),
@@ -581,12 +686,13 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         isSystem: z.boolean().optional().describe('Set true only for system-managed columns. Avoid for normal app fields.'),
         defaultValue: z.string().optional().describe('Default value as JSON string or backend-supported literal.'),
         description: z.string().optional().describe('Column description.'),
-        options: z.string().optional().describe('Column options as JSON string (e.g., enum values).'),
+        options: z.union([z.array(z.string()), z.string()]).optional().describe('Column options as a native array such as ["draft","published"] or a JSON string for older clients.'),
         globalRulesAckKey: globalRulesAckParam(z),
     };
     const relationCreateSchema = {
         sourceTableId: z.string().describe('Source table id, exact table name, or alias. For many-to-one, this is the table that owns the relation property.'),
-        targetTableId: z.string().describe('Target table id, exact table name, or alias. MCP resolves names/aliases to ids before mutation.'),
+        targetTableId: z.string().optional().describe('Target table id, exact table name, or alias. MCP resolves names/aliases to ids before mutation. Optional when targetTable is provided.'),
+        targetTable: z.string().optional().describe('Alias for targetTableId when naturally using a target table name/alias such as enfyra_user. Optional when targetTableId is provided.'),
         type: z.enum(['many-to-one', 'one-to-many', 'one-to-one', 'many-to-many']).describe('Relation type.'),
         propertyName: z.string().describe('Property name on source table (e.g., "customer", "items").'),
         inversePropertyName: z.string().optional().describe('Property name on target table for bidirectional relation (e.g., "orders"). Omit unless a concrete response, UI, deep query, aggregate sort/count, or parent-to-child traversal will use the reverse field. Do not add inverses merely because a parent table exists.'),
@@ -625,17 +731,26 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         const userColumns = arrayValue('columns', args.columns);
         const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
         const supportedTypes = getSupportedColumnTypesFromMetadata(metadata);
-        const { columns: normalizedUserColumns, normalizations } = normalizeColumnsForLiveMetadata(userColumns, supportedTypes);
+        const { columns: userColumnsWithoutAuto, skippedAutoColumns } = stripAutoManagedColumns(userColumns);
+        const { columns: normalizedUserColumns, normalizations } = normalizeColumnsForLiveMetadata(userColumnsWithoutAuto, supportedTypes);
+        const deferredRelations = arrayValue('relations', args.relations).map(normalizeRelationForTablePatch);
+        const relationNames = new Set(deferredRelations.map((relation) => relation.propertyName).filter(Boolean));
+        assertNoDuplicateFieldNames([
+            ...normalizedUserColumns.map((column) => String(column.name || '')).filter(Boolean),
+            ...deferredRelations.map((relation) => String(relation.propertyName || '')).filter(Boolean),
+        ], `create_tables item "${args.name}"`);
         const indexes = normalizeConstraintGroupsValue('indexes', args.indexes ?? []);
         const uniques = normalizeConstraintGroupsValue('uniques', args.uniques ?? []);
         assertIndexesDoNotReferenceUniqueFields(indexes, uniques);
+        const splitIndexes = splitRelationConstraintGroups(indexes, relationNames);
+        const splitUniques = splitRelationConstraintGroups(uniques, relationNames);
         const body = { name: args.name, description: args.description, columns: [idColumn, ...normalizedUserColumns], relations: [] };
         if (args.isSingleRecord !== undefined)
             body.isSingleRecord = args.isSingleRecord;
         if (args.indexes !== undefined)
-            body.indexes = indexes;
+            body.indexes = splitIndexes.immediate;
         if (args.uniques !== undefined)
-            body.uniques = uniques;
+            body.uniques = splitUniques.immediate;
         const result = await fetchAPI(ENFYRA_API_URL, '/enfyra_table', {
             method: 'POST',
             body: JSON.stringify(body),
@@ -648,7 +763,6 @@ export function registerTableTools(server, ENFYRA_API_URL) {
             ? null
             : liveMetadataAfterCreate?.data?.table || liveMetadataAfterCreate?.data || liveMetadataAfterCreate?.table || liveMetadataAfterCreate;
         const liveSchema = summarizeCreatedTableSchema(liveTableAfterCreate, args.name);
-        const deferredRelations = arrayValue('relations', args.relations).map(normalizeRelationForTablePatch);
         const routePath = `/${args.name}`;
         return {
             action: 'table_created',
@@ -659,8 +773,10 @@ export function registerTableTools(server, ENFYRA_API_URL) {
                 deferredRelationCount: deferredRelations.length,
                 indexGroupCount: indexes.length,
                 uniqueGroupCount: uniques.length,
+                deferredConstraintCount: splitIndexes.deferred.length + splitUniques.deferred.length,
             },
             schemaNormalization: normalizations,
+            skippedAutoColumns,
             schema: {
                 intended: {
                     tableName: args.name,
@@ -681,6 +797,39 @@ export function registerTableTools(server, ENFYRA_API_URL) {
                 noGetById: true,
             },
             deferredRelations,
+            deferredConstraints: {
+                indexes: splitIndexes.deferred,
+                uniques: splitUniques.deferred,
+            },
+            result,
+        };
+    }
+    async function applyDeferredConstraints(tableId, deferredConstraints) {
+        const deferredIndexes = deferredConstraints?.indexes || [];
+        const deferredUniques = deferredConstraints?.uniques || [];
+        if (deferredIndexes.length === 0 && deferredUniques.length === 0)
+            return null;
+        const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
+        const mappedIndexes = resolveRelationConstraintGroups(tableData, deferredIndexes, 'indexes');
+        const mappedUniques = resolveRelationConstraintGroups(tableData, deferredUniques, 'uniques');
+        const existingIndexes = normalizeConstraintGroupsValue('indexes', tableData.indexes || []);
+        const existingUniques = normalizeConstraintGroupsValue('uniques', tableData.uniques || []);
+        const indexes = mergeConstraintGroups(existingIndexes, mappedIndexes);
+        const uniques = mergeConstraintGroups(existingUniques, mappedUniques);
+        assertIndexesDoNotReferenceUniqueFields(indexes, uniques);
+        const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, { indexes, uniques });
+        return {
+            action: 'deferred_constraints_applied',
+            tableId,
+            tableName: tableData.name,
+            requested: {
+                indexes: deferredIndexes,
+                uniques: deferredUniques,
+            },
+            applied: {
+                indexes: mappedIndexes,
+                uniques: mappedUniques,
+            },
             result,
         };
     }
@@ -768,7 +917,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
                 if (description !== undefined)
                     rest.description = description;
                 if (options !== undefined)
-                    rest.options = typeof options === 'string' ? JSON.parse(options) : options;
+                    rest.options = normalizeColumnOptionsValue(options);
             }
             return rest;
         });
@@ -856,7 +1005,9 @@ export function registerTableTools(server, ENFYRA_API_URL) {
                 cascadeFields: ['columns', 'relations'],
                 constraintFields: ['indexes', 'uniques'],
                 notAcceptedAtCreate: ['alias', 'graphqlEnabled'],
+                autoManagedColumns: ['id', 'createdAt', 'updatedAt'],
                 idColumn: 'create_tables auto-includes an int id primary key; do not include your own id unless the user asks for custom primary-key behavior.',
+                reservedColumnRule: 'Do not declare id, _id, createdAt, or updatedAt in create_tables/create_columns. create_tables strips them before save and reports skippedAutoColumns; create_columns rejects them.',
             },
             columnDefinitionInput: {
                 allowedFields: ['name', 'type', 'isNullable', 'isUnique', 'isPublished', 'isUpdatable', 'isEncrypted', 'defaultValue', 'description', 'options'],
@@ -876,7 +1027,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
                 aliasNormalization: 'Schema tools normalize common aliases where possible and return schemaNormalization, but models should choose from liveTypes directly.',
             },
             relationDefinitionInput: {
-                allowedFields: ['targetTable', 'type', 'propertyName', 'inversePropertyName', 'mappedBy', 'isNullable', 'onDelete', 'description'],
+                allowedFields: ['targetTableId', 'targetTable', 'type', 'propertyName', 'inversePropertyName', 'mappedBy', 'isNullable', 'onDelete', 'description'],
                 relationTypes: relationTypes.length ? relationTypes : ['many-to-one', 'one-to-many', 'one-to-one', 'many-to-many'],
                 onDeleteOptions: onDeleteOptions.length ? onDeleteOptions : ['CASCADE', 'SET NULL', 'RESTRICT'],
                 forbiddenPhysicalFields: FORBIDDEN_RELATION_KEYS,
@@ -886,14 +1037,17 @@ export function registerTableTools(server, ENFYRA_API_URL) {
                 indexes: 'JSON array of non-unique logical field groups, e.g. [["status","createdAt"]]. Relation propertyName values are allowed.',
                 uniques: 'JSON array of unique logical field groups, e.g. [["record","actor"]].',
                 uniqueIndexRule: 'Any field in uniques must not appear in indexes because unique constraints already create indexed lookups.',
+                createTablesPreflight: 'create_tables rejects constraints that reference fields not declared as scalar columns, auto-managed columns, or relation propertyName values in that same table item before it creates anything.',
+                relationBasedUniques: 'For one-pass schema creation, put the owning relations in the same create_tables item as the relation-based unique group. If relations already exist, add relation-based uniques later with update_tables.',
             },
             recommendedSequence: [
                 '1. Name domain entities and decide which existing tables are reused, especially enfyra_user for users/owners/actors.',
                 '2. Create independent lookup/base tables first with scalar columns only.',
                 '3. Create dependent tables with scalar columns and relations whose target tables already exist.',
                 '4. Use create_relations after both tables exist when a relation could not be included during table creation.',
-                '5. Insert records using column names and relation propertyName values, never hidden FK columns.',
-                '6. Re-inspect each table with inspect_table before writing records or adding query examples.',
+                '5. Add relation-based unique groups in the same create_tables item when the relations are declared there, or via update_tables after relations exist.',
+                '6. Insert records using column names and relation propertyName values, never hidden FK columns.',
+                '7. Re-inspect each table with inspect_table before writing records or adding query examples.',
             ],
             liveMetadataAttributes: {
                 enfyra_table: tableAttributes,
@@ -907,23 +1061,37 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         'Create one or more table definitions. Always pass items as a native JSON array; for one table, pass one item. JSON string arrays are accepted only for older MCP clients.',
         'The tool creates tables sequentially, creates columns with each table, then creates all requested relations after every table in the batch exists. This avoids relation target races for weak agents.',
         'Each item supports { name, description?, isSingleRecord?, columns?, relations?, indexes?, uniques? }. columns/relations/indexes/uniques may be arrays inside the item.',
+        'Do not include id, _id, createdAt, or updatedAt in columns; Enfyra manages them and create_tables strips them before save.',
+        'Every field named in indexes/uniques must be a scalar column, auto-managed column, or relation propertyName in the same table item; otherwise the tool rejects the whole batch before creating tables.',
         'Use get_schema_design_context first for live column types and relation rules. Do not include physical FK fields.',
     ].join(' '), {
-        items: bulkObjectArrayParam(z, 'Table definitions').describe('Native JSON array of table definitions. Pass one object in the array for a single table.'),
+        items: bulkObjectArrayParam(z, 'Table definitions').optional().describe('Native JSON array of table definitions. Pass one object in the array for a single table.'),
+        tables: bulkObjectArrayParam(z, 'Table definitions').optional().describe('Alias for items when the caller naturally names the batch tables. Pass either items or tables, not both.'),
         maxItems: z.number().int().min(1).max(100).optional().default(100).describe('Safety cap for one schema batch. Default/max is 100; operations still run sequentially.'),
         globalRulesAckKey: globalRulesAckParam(z),
-    }, async ({ items, maxItems, globalRulesAckKey }) => {
+    }, async ({ items, tables, maxItems, globalRulesAckKey }) => {
         assertGlobalRulesAck(globalRulesAckKey);
-        const parsedItems = parseBulkItemsParam('items', items);
+        if (items !== undefined && tables !== undefined)
+            throw new Error('Pass either items or tables to create_tables, not both.');
+        const parsedItems = parseBulkItemsParam('items', items ?? tables);
         assertBulkLimit('create_tables', parsedItems, maxItems);
+        preflightCreateTableDefinitions(parsedItems);
         const created = [];
         const deferredRelations = [];
+        const deferredConstraints = [];
         for (const [index, item] of parsedItems.entries()) {
             const result = await withSchemaQueue(() => createOneTable(item));
             created.push({ index, ...result, deferredRelations: undefined });
             for (const relation of result.deferredRelations || []) {
                 deferredRelations.push({ index, sourceTableId: result.table.id || result.table.name, ...relation });
             }
+            if ((result.deferredConstraints?.indexes || []).length || (result.deferredConstraints?.uniques || []).length) {
+                deferredConstraints.push({
+                    index,
+                    tableId: result.table.id || result.table.name,
+                    ...result.deferredConstraints,
+                });
+            }
         }
         const createdRelations = [];
         for (const relation of deferredRelations) {
@@ -941,16 +1109,29 @@ export function registerTableTools(server, ENFYRA_API_URL) {
             });
             createdRelations.push({ index: relation.index, ...JSON.parse(relationResult.content[0].text) });
         }
+        const appliedDeferredConstraints = [];
+        for (const constraints of deferredConstraints) {
+            const constraintResult = await withSchemaQueue(() => applyDeferredConstraints(constraints.tableId, {
+                indexes: constraints.indexes,
+                uniques: constraints.uniques,
+            }));
+            if (constraintResult)
+                appliedDeferredConstraints.push({ index: constraints.index, ...constraintResult });
+        }
         return jsonContent({
             action: 'tables_created',
             requested: parsedItems.length,
             createdCount: created.length,
             deferredRelationCount: deferredRelations.length,
             createdRelationCount: createdRelations.length,
+            deferredConstraintCount: deferredConstraints.length,
+            appliedDeferredConstraintCount: appliedDeferredConstraints.length,
             sequential: true,
             relationPhaseAfterTables: true,
+            constraintPhaseAfterRelations: true,
             created,
             createdRelations,
+            appliedDeferredConstraints,
         });
     });
     server.tool('update_tables', 'Update one or more table definitions. Always pass items as a native JSON array; for one table, pass one item. Items run sequentially through the schema queue. JSON string arrays are accepted only for older MCP clients.', {
@@ -998,12 +1179,15 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     });
     // ─── COLUMN MUTATIONS ───
     server.tool('create_columns', 'Create one or more columns. Always pass items as a native JSON array; for one column, pass one item. Items run sequentially through the schema queue. JSON string arrays are accepted only for older MCP clients.', {
-        items: bulkObjectArrayParam(z, 'Column definitions').describe('Native JSON array of column definitions. Each item uses create_columns fields: { tableId, name, type, isNullable?, isUnique?, isPublished?, isUpdatable?, isEncrypted?, isPrimary?, isGenerated?, isSystem?, defaultValue?, description?, options? }.'),
+        items: bulkObjectArrayParam(z, 'Column definitions').optional().describe('Native JSON array of column definitions. Each item uses create_columns fields: { tableId, name, type, isNullable?, isUnique?, isPublished?, isUpdatable?, isEncrypted?, isPrimary?, isGenerated?, isSystem?, defaultValue?, description?, options? }.'),
+        columns: bulkObjectArrayParam(z, 'Column definitions').optional().describe('Alias for items when the caller naturally names the batch columns. Pass either items or columns, not both.'),
         maxItems: z.number().int().min(1).max(100).optional().default(100).describe('Safety cap for one schema batch. Default/max is 100.'),
         globalRulesAckKey: globalRulesAckParam(z),
-    }, async ({ items, maxItems, globalRulesAckKey }) => {
+    }, async ({ items, columns, maxItems, globalRulesAckKey }) => {
         assertGlobalRulesAck(globalRulesAckKey);
-        const parsedItems = parseBulkItemsParam('items', items);
+        if (items !== undefined && columns !== undefined)
+            throw new Error('Pass either items or columns to create_columns, not both.');
+        const parsedItems = parseBulkItemsParam('items', items ?? columns);
         assertBulkLimit('create_columns', parsedItems, maxItems);
         const created = [];
         for (const [index, item] of parsedItems.entries()) {
@@ -1061,12 +1245,15 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     });
     // ─── RELATION MUTATIONS ───
     server.tool('create_relations', 'Create one or more relations. Always pass items as a native JSON array; for one relation, pass one item. Items run sequentially through the schema queue and table names/aliases are resolved internally. JSON string arrays are accepted only for older MCP clients.', {
-        items: bulkObjectArrayParam(z, 'Relation definitions').describe('Native JSON array of relation definitions. Each item uses { sourceTableId, targetTableId, type, propertyName, inversePropertyName?, mappedBy?, isNullable?, onDelete?, description? }. Do not send physical FK fields.'),
+        items: bulkObjectArrayParam(z, 'Relation definitions').optional().describe('Native JSON array of relation definitions. Each item uses { sourceTableId, targetTableId or targetTable, type, propertyName, inversePropertyName?, mappedBy?, isNullable?, onDelete?, description? }. Do not send physical FK fields.'),
+        relations: bulkObjectArrayParam(z, 'Relation definitions').optional().describe('Alias for items when the caller naturally names the batch relations. Pass either items or relations, not both.'),
         maxItems: z.number().int().min(1).max(100).optional().default(100).describe('Safety cap for one schema batch. Default/max is 100.'),
         globalRulesAckKey: globalRulesAckParam(z),
-    }, async ({ items, maxItems, globalRulesAckKey }) => {
+    }, async ({ items, relations, maxItems, globalRulesAckKey }) => {
         assertGlobalRulesAck(globalRulesAckKey);
-        const parsedItems = parseBulkItemsParam('items', items);
+        if (items !== undefined && relations !== undefined)
+            throw new Error('Pass either items or relations to create_relations, not both.');
+        const parsedItems = parseBulkItemsParam('items', items ?? relations);
         assertBulkLimit('create_relations', parsedItems, maxItems);
         const created = [];
         for (const [index, item] of parsedItems.entries()) {