@enfyra/mcp-server 0.1.18 → 0.1.20

package/dist/mcp-server-entry.js

@@ -26,7 +26,7 @@ import { WORKFLOW_SURFACES, discoverWorkflowRoutes } from './lib/tool-routing.js
 import { getSupportedColumnTypesFromMetadata, registerTableTools } from './lib/table-tools.js';
 import { registerPlatformOperationTools, validateExtensionCode } from './lib/platform-operation-tools.js';
 import { registerRuntimeZoneTools } from './lib/runtime-zone-tools.js';
-import { parseRecordData, prepareRecordMutation, validateScriptSourceIfPresent } from './lib/mutation-guards.js';
+import { parseRecordBatchData, parseRecordData, prepareRecordBatchMutation, prepareRecordMutation, validateScriptSourceIfPresent } from './lib/mutation-guards.js';
 import { assertDynamicCodeKnowledgeAck, assertDynamicCodeKnowledgeAckIf, assertExtensionKnowledgeAckIf, assertGlobalRulesAck, buildRequiredKnowledgePayload, dynamicCodeKnowledgeAckParam, extensionKnowledgeAckParam, globalRulesAckParam, } from './lib/required-knowledge.js';
 import { validateMainTableRoutePath } from './lib/route-guards.js';
 import { installColumnarToolFormatter, jsonContent } from './lib/response-format.js';
@@ -58,7 +58,7 @@ const CAPABILITY_AREAS = [
     {
         area: 'GraphQL',
         tables: ['enfyra_graphql'],
-        workflow: 'Enable per table through enfyra_graphql or update_table graphqlEnabled. GraphQL table data requires Bearer auth; anonymous root or schema probes may return 200 without exposing table data.',
+        workflow: 'Enable per table through enfyra_graphql or update_tables graphqlEnabled. GraphQL table data requires Bearer auth; anonymous root or schema probes may return 200 without exposing table data.',
     },
     {
         area: 'Files and storage',
@@ -558,11 +558,63 @@ async function prepareGenericMutation(tableName, data) {
         data,
     });
 }
+async function prepareGenericBatchMutation(tableName, records) {
+    const { tables } = await getMetadataTables();
+    return prepareRecordBatchMutation({
+        fetchAPI,
+        apiUrl: ENFYRA_API_URL,
+        tables,
+        tableName,
+        records,
+    });
+}
 function assertKnowledgeForGenericMutation(tableName, data, { knowledgeAckKey, extensionKnowledgeAckKey }) {
     const payload = parseRecordData(data);
     assertDynamicCodeKnowledgeAckIf(SCRIPT_BACKED_TABLE_SET.has(tableName) && typeof payload.sourceCode === 'string', knowledgeAckKey);
     assertExtensionKnowledgeAckIf(tableName === 'enfyra_extension' && typeof payload.code === 'string', extensionKnowledgeAckKey);
 }
+function assertKnowledgeForGenericBatchMutation(tableName, records, { knowledgeAckKey, extensionKnowledgeAckKey }) {
+    const payloads = parseRecordBatchData(records);
+    for (const payload of payloads) {
+        assertDynamicCodeKnowledgeAckIf(SCRIPT_BACKED_TABLE_SET.has(tableName) && typeof payload.sourceCode === 'string', knowledgeAckKey);
+        assertExtensionKnowledgeAckIf(tableName === 'enfyra_extension' && typeof payload.code === 'string', extensionKnowledgeAckKey);
+    }
+}
+function parseBulkItemsArg(name, value) {
+    const parsed = typeof value === 'string' ? JSON.parse(value) : value;
+    if (!Array.isArray(parsed)) {
+        throw new Error(`${name} must be a JSON array string. Pass one item in the array for a single mutation.`);
+    }
+    if (parsed.length === 0) {
+        throw new Error(`${name} must include at least one item.`);
+    }
+    parsed.forEach((item, index) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            throw new Error(`${name}[${index}] must be a JSON object.`);
+        }
+    });
+    return parsed;
+}
+function assertMaxBulkItems(name, items, maxItems) {
+    if (items.length > maxItems) {
+        throw new Error(`${name} received ${items.length} items, above maxItems=${maxItems}. Split the batch deliberately.`);
+    }
+}
+function assertNoDuplicateBulkIds(name, items) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const item of items) {
+        const id = String(item.id ?? '');
+        if (!id)
+            continue;
+        if (seen.has(id))
+            duplicates.add(id);
+        seen.add(id);
+    }
+    if (duplicates.size > 0) {
+        throw new Error(`${name} contains duplicate id(s): ${[...duplicates].join(', ')}. Split or merge duplicate writes so the sequential batch has one clear final mutation per record.`);
+    }
+}
 async function validateExtensionCodeForGenericMutation(tableName, payload, fallbackName) {
     if (tableName !== 'enfyra_extension' || typeof payload?.code !== 'string')
         return null;
@@ -844,20 +896,20 @@ server.tool('discover_enfyra_system', [
             publicAccess: 'publicMethods controls anonymous REST access per route/method; otherwise Bearer JWT + routePermissions apply.',
             routeTables: sample(routeTableList),
             noRouteTables: sample(noRouteTableList),
-            canonicalCrudTools: 'query_table/create_record/update_record/delete_record use dynamic REST routes and only work for route-backed tables.',
+            canonicalCrudTools: 'query_table reads route-backed tables. create_records/update_records/delete_records are the only generic write tools; pass arrays even for one item. They preflight arrays and run sequentially.',
             customRouteWorkflow: 'For a new endpoint use create_route without mainTableId, then create_handler/create_pre_hook/create_post_hook. Do not create a table just to get a path.',
             routeSamples: sample(routes, 25),
             detailHint: 'Use get_all_routes({ search, limit }) or inspect_route({ path }) for route details. Use inspect_table({ tableName }) for table detail.',
         },
         schemaManagement: {
-            createTable: 'POST /enfyra_table supports isSingleRecord at create time and supports columns and relations arrays in the same cascade call. MCP create_table exposes isSingleRecord, columns, and relations directly. It does not accept alias at create time; table name drives the default route/schema behavior.',
+            createTable: 'POST /enfyra_table supports isSingleRecord at create time. MCP create_tables accepts an array, creates tables/columns sequentially, then creates requested relations after all tables in the batch exist. It does not accept alias at create time; table name drives the default route/schema behavior.',
             updateTable: 'PATCH /enfyra_table/:id is the canonical path for table property changes and column/relation schema changes.',
-            columns: 'enfyra_column has no REST route; use create_table/create_column/update_column/delete_column. Use liveColumnTypes below; do not invent SQL dialect names.',
+            columns: 'enfyra_column has no REST route; use create_tables/create_columns/update_columns/delete_columns. Use liveColumnTypes below; do not invent SQL dialect names.',
             liveColumnTypes: getSupportedColumnTypesFromMetadata(metadata),
             columnTypeGuidance: 'Use varchar for short strings, text/richtext for long prose, float for price/amount/rating/decimal-like values unless decimal is listed, simple-json for structured objects/arrays only when listed, and relations instead of *_id columns for links.',
             relations: routeTables.has('enfyra_relation')
-                ? 'enfyra_relation has a REST route for reads/metadata, but canonical schema migration is create_relation/delete_relation or enfyra_table PATCH with the full relations array. Relation onDelete accepts CASCADE, SET NULL, or RESTRICT.'
-                : 'Use create_relation/delete_relation or enfyra_table PATCH with the full relations array. Relation onDelete accepts CASCADE, SET NULL, or RESTRICT.',
+                ? 'enfyra_relation has a REST route for reads/metadata, but canonical schema migration is create_relations/delete_relations or enfyra_table PATCH with the full relations array. Relation onDelete accepts CASCADE, SET NULL, or RESTRICT.'
+                : 'Use create_relations/delete_relations or enfyra_table PATCH with the full relations array. Relation onDelete accepts CASCADE, SET NULL, or RESTRICT.',
             relationCascadeFkContract: 'Do not ask for or send physical FK/junction column names in relation create/update payloads. Enfyra derives fk/junction columns from relation propertyName/table metadata and hides FK columns from app schema/forms. Use targetTable, type, propertyName, inversePropertyName or mappedBy, isNullable, onDelete. Add inversePropertyName only when a concrete response, UI, deep query, aggregate sort/count, or parent-to-child traversal will use the reverse field.',
             tableDefinitionRelations: (tableDefinition?.relations || []).map((rel) => rel.propertyName),
             relationDefinitionRelations: (relationTable?.relations || []).map((rel) => rel.propertyName),
@@ -873,8 +925,8 @@ server.tool('discover_enfyra_system', [
             enablement: 'A table appears in GraphQL when enfyra_graphql has an enabled row for that table. REST route availableMethods does not enable GraphQL.',
             auth: 'GraphQL table data requires Authorization: Bearer <accessToken>; REST publicMethods do not make GraphQL table data anonymous. Anonymous root/schema probes may still return 200.',
             management: routeTables.has('enfyra_graphql')
-                ? 'Use update_table graphqlEnabled or create/update records on enfyra_graphql, then reload_graphql if needed.'
-                : 'Use update_table graphqlEnabled, then reload_graphql if needed.',
+                ? 'Use update_tables graphqlEnabled or create_records/update_records on enfyra_graphql, then reload_graphql if needed.'
+                : 'Use update_tables graphqlEnabled, then reload_graphql if needed.',
             gqlDefinitionColumns: (gqlDefinition?.columns || []).map((column) => column.name),
         },
         tableSamples: sample(tableNames, 40),
@@ -1023,7 +1075,7 @@ server.tool('discover_query_capabilities', [
                 ? 'Use this table metadata primary column when available.'
                 : 'SQL commonly uses id; Mongo uses _id. Use table metadata primary column when available.',
             relationNames: 'API relation operations use relation propertyName, not physical FK column names.',
-            relationCascadeFkContract: 'When creating relations through create_table/create_relation/enfyra_table PATCH, never provide fkCol/fkColumn/foreignKeyColumn/sourceColumn/targetColumn/junction*Column. These are physical implementation details derived by Enfyra and hidden from app schema/forms. Add inversePropertyName only for a concrete reverse traversal such as parent deep child lists, response fields, UI sections, or aggregate sort/count.',
+            relationCascadeFkContract: 'When creating relations through create_tables/create_relations/enfyra_table PATCH, never provide fkCol/fkColumn/foreignKeyColumn/sourceColumn/targetColumn/junction*Column. These are physical implementation details derived by Enfyra and hidden from app schema/forms. Add inversePropertyName only for a concrete reverse traversal such as parent deep child lists, response fields, UI sections, or aggregate sort/count.',
             graphql: 'GraphQL query args also accept filter/sort/page/limit. Table data requires Bearer auth and table enablement via enfyra_graphql; anonymous root/schema probes may still return 200.',
         },
         table: tableName
@@ -1175,7 +1227,7 @@ server.tool('discover_script_contexts', [
             },
             socketInHttpOrFlow: 'HTTP/flow context can emitToUser/emitToRoom/emitToGateway/broadcast and roomSize, but cannot reply/join/leave/disconnect/emitToCurrentRoom/broadcastToRoom because there is no bound socket. emitToRoom requires an explicit gateway path: emitToRoom(path, room, event, data). roomSize(room) counts sockets in that room across registered gateways.',
             packages: 'Server packages installed through install_package are exposed as $ctx.$pkgs.packageName in server scripts.',
-            files: 'Upload helpers are on $storage; raw create_record on enfyra_file is not equivalent to multipart upload/storage rollback. For multipart request files, pass file: @UPLOADED_FILE to @STORAGE.$upload/@STORAGE.$update so Enfyra streams from disk-backed temp storage. Use @STORAGE.$registerFile only when the object already exists in storage and the script should create the enfyra_file record without uploading bytes. Use buffer only for small generated files.',
+            files: 'Upload helpers are on $storage; raw create_records on enfyra_file is not equivalent to multipart upload/storage rollback. For multipart request files, pass file: @UPLOADED_FILE to @STORAGE.$upload/@STORAGE.$update so Enfyra streams from disk-backed temp storage. Use @STORAGE.$registerFile only when the object already exists in storage and the script should create the enfyra_file record without uploading bytes. Use buffer only for small generated files.',
         },
         adminTesting: {
             flowStep: 'Use test_flow_step or run_admin_test(kind=flow_step).',
@@ -1193,8 +1245,8 @@ server.tool('get_enfyra_api_context', [
     'Use when the user asks which HTTP endpoint or full URL applies: combine enfyraApiUrl with paths from server instructions (GET/POST /{table}, PATCH/DELETE /{table}/{id}, no GET /{table}/{id}).',
     'Auth: publicMethods on a route can allow a method without Bearer; otherwise JWT + routePermissions — see server instructions.',
     'If path might differ from table name, use get_all_routes before asserting a URL.',
-    'Same mapping as MCP tool → HTTP: query_table=GET /table?..., create_record=POST /table, update_record=PATCH /table/id, delete_record=DELETE /table/id.',
-    'GraphQL: see graphqlHttpUrl / graphqlSchemaUrl in response; enable per table via enfyra_graphql/update_table graphqlEnabled and send Bearer auth for table data queries. Anonymous root/schema probes may still return 200.',
+    'Same mapping as MCP tool → HTTP: query_table=GET /table?..., create_records=sequential POST /table, update_records=sequential PATCH /table/id, delete_records=sequential DELETE /table/id.',
+    'GraphQL: see graphqlHttpUrl / graphqlSchemaUrl in response; enable per table via enfyra_graphql/update_tables graphqlEnabled and send Bearer auth for table data queries. Anonymous root/schema probes may still return 200.',
 ].join(' '), {}, async () => {
     const base = ENFYRA_API_URL.replace(/\/$/, '');
     const gql = buildGraphqlUrls(ENFYRA_API_URL);
@@ -1362,47 +1414,101 @@ server.tool('find_one_record', 'Find a single record by ID or filter. By ID uses
 // ============================================================================
 // CRUD TOOLS
 // ============================================================================
-server.tool('create_record', 'Create a new record in any route-backed table. The tool validates body keys against live metadata, validates sourceCode before saving script-backed records, and validates enfyra_extension.code before saving extension records.', {
+server.tool('create_records', 'Create one or more route-backed records. Always pass a JSON array string; for one record, pass a one-item array. MCP preflights every item against live metadata first, then sends one POST per record sequentially; this is not a backend bulk endpoint or transaction.', {
     tableName: z.string().describe('Table name to insert into'),
-    data: z.string().describe('Record data as JSON string'),
-    queryParams: z.string().optional().describe('Optional query params as JSON object string, e.g. {"expired_at":"2026-09-20"}. Use for route contracts that intentionally keep workflow fields out of the validated body.'),
+    records: z.string().describe('Records as a JSON array string. Each item must be a JSON object using metadata-backed column names and relation propertyName values.'),
+    queryParams: z.string().optional().describe('Optional query params as JSON object string applied to every POST, for route contracts that intentionally keep workflow fields out of the validated body.'),
+    maxRecords: z.number().int().min(1).max(100).optional().default(100).describe('Safety cap for one MCP batch. Default/max is 100. For larger imports, split intentionally.'),
     globalRulesAckKey: globalRulesAckParam(z),
-    knowledgeAckKey: dynamicCodeKnowledgeAckParam(z).optional().describe('Required only when data contains sourceCode. Use dynamicCodeAckKey from get_enfyra_required_knowledge.'),
-    extensionKnowledgeAckKey: extensionKnowledgeAckParam(z).optional().describe('Required only when tableName is enfyra_extension and data contains code. Use extensionAckKey from get_enfyra_required_knowledge.'),
-}, async ({ tableName, data, queryParams, globalRulesAckKey, knowledgeAckKey, extensionKnowledgeAckKey }) => {
+    knowledgeAckKey: dynamicCodeKnowledgeAckParam(z).optional().describe('Required only when any item contains sourceCode. Use dynamicCodeAckKey from get_enfyra_required_knowledge.'),
+    extensionKnowledgeAckKey: extensionKnowledgeAckParam(z).optional().describe('Required only when tableName is enfyra_extension and any item contains code. Use extensionAckKey from get_enfyra_required_knowledge.'),
+}, async ({ tableName, records, queryParams, maxRecords, globalRulesAckKey, knowledgeAckKey, extensionKnowledgeAckKey }) => {
     assertGlobalRulesAck(globalRulesAckKey);
     validateTableName(tableName);
-    assertKnowledgeForGenericMutation(tableName, data, { knowledgeAckKey, extensionKnowledgeAckKey });
-    const prepared = await prepareGenericMutation(tableName, data);
-    const extensionValidation = await validateExtensionCodeForGenericMutation(tableName, prepared.payload, prepared.payload?.name);
+    const parsedRecords = parseRecordBatchData(records);
+    if (parsedRecords.length > maxRecords) {
+        throw new Error(`create_records received ${parsedRecords.length} records, above maxRecords=${maxRecords}. Split the batch deliberately.`);
+    }
+    assertKnowledgeForGenericBatchMutation(tableName, parsedRecords, { knowledgeAckKey, extensionKnowledgeAckKey });
+    const prepared = await prepareGenericBatchMutation(tableName, parsedRecords);
+    const extensionValidations = [];
+    for (const item of prepared.records) {
+        extensionValidations.push(await validateExtensionCodeForGenericMutation(tableName, item.payload, item.payload?.name || item.index));
+    }
     const query = parseQueryParamsArg(queryParams);
-    const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}`, query), { method: 'POST', body: JSON.stringify(prepared.payload) });
+    const created = [];
+    for (const item of prepared.records) {
+        const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}`, query), { method: 'POST', body: JSON.stringify(item.payload) });
+        created.push({
+            index: item.index,
+            ...summarizeMutationResult(result, 'created', tableName),
+        });
+    }
     return { content: [{ type: 'text', text: JSON.stringify({
-                    ...summarizeMutationResult(result, 'created', tableName),
-                    scriptValidation: prepared.scriptValidation,
-                    extensionValidation,
+                    action: 'created_records',
+                    tableName,
+                    requested: parsedRecords.length,
+                    createdCount: created.length,
+                    sequential: true,
+                    transactional: false,
+                    preflight: {
+                        liveMetadataFieldsValidated: true,
+                        scriptValidatedBeforeAnyPost: prepared.records.some((item) => item.scriptValidation?.validated === true),
+                        extensionValidatedBeforeAnyPost: extensionValidations.some(Boolean),
+                    },
+                    created,
+                    detailHint: `Use query_table({ tableName: "${tableName}", fields: [...], limit: ${Math.min(created.length, 20)} }) to inspect created records when needed.`,
                 }, null, 2) }] };
 });
-server.tool('update_record', 'Update an existing record by ID using PATCH. The tool validates body keys against live metadata, validates sourceCode before saving script-backed records, and validates enfyra_extension.code before saving extension records. Prefer update_extension_code for normal extension edits.', {
+server.tool('update_records', 'Update one or more records in one MCP call. Pass items as a JSON array string; for one update, pass one item. MCP preflights every item against live metadata and extension/script validators first, rejects duplicate ids, then PATCHes sequentially to avoid races and server overload.', {
     tableName: z.string().describe('Table name'),
-    id: z.string().describe('Record ID to update'),
-    data: z.string().describe('Fields to update as JSON string'),
-    queryParams: z.string().optional().describe('Optional query params as JSON object string for route contracts that intentionally keep workflow fields out of the validated body.'),
+    items: z.string().describe('JSON array string of update items: [{ "id": "...", "data": { ... }, "queryParams": { ... }? }]. data must use metadata-backed column names and relation propertyName values.'),
+    maxItems: z.number().int().min(1).max(100).optional().default(100).describe('Safety cap for one MCP batch. Default/max is 100.'),
     globalRulesAckKey: globalRulesAckParam(z),
-    knowledgeAckKey: dynamicCodeKnowledgeAckParam(z).optional().describe('Required only when data contains sourceCode. Use dynamicCodeAckKey from get_enfyra_required_knowledge.'),
-    extensionKnowledgeAckKey: extensionKnowledgeAckParam(z).optional().describe('Required only when tableName is enfyra_extension and data contains code. Use extensionAckKey from get_enfyra_required_knowledge.'),
-}, async ({ tableName, id, data, queryParams, globalRulesAckKey, knowledgeAckKey, extensionKnowledgeAckKey }) => {
+    knowledgeAckKey: dynamicCodeKnowledgeAckParam(z).optional().describe('Required only when any item.data contains sourceCode. Use dynamicCodeAckKey from get_enfyra_required_knowledge.'),
+    extensionKnowledgeAckKey: extensionKnowledgeAckParam(z).optional().describe('Required only when tableName is enfyra_extension and any item.data contains code. Use extensionAckKey from get_enfyra_required_knowledge.'),
+}, async ({ tableName, items, maxItems, globalRulesAckKey, knowledgeAckKey, extensionKnowledgeAckKey }) => {
     assertGlobalRulesAck(globalRulesAckKey);
     validateTableName(tableName);
-    assertKnowledgeForGenericMutation(tableName, data, { knowledgeAckKey, extensionKnowledgeAckKey });
-    const prepared = await prepareGenericMutation(tableName, data);
-    const extensionValidation = await validateExtensionCodeForGenericMutation(tableName, prepared.payload, id);
-    const query = parseQueryParamsArg(queryParams);
-    const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}/${id}`, query), { method: 'PATCH', body: JSON.stringify(prepared.payload) });
+    const parsedItems = parseBulkItemsArg('items', items);
+    assertMaxBulkItems('update_records', parsedItems, maxItems);
+    assertNoDuplicateBulkIds('update_records', parsedItems);
+    const preparedItems = [];
+    const extensionValidations = [];
+    for (const [index, item] of parsedItems.entries()) {
+        if (!item.id)
+            throw new Error(`items[${index}].id is required.`);
+        if (!item.data || typeof item.data !== 'object' || Array.isArray(item.data)) {
+            throw new Error(`items[${index}].data must be a JSON object.`);
+        }
+        assertKnowledgeForGenericMutation(tableName, JSON.stringify(item.data), { knowledgeAckKey, extensionKnowledgeAckKey });
+        const prepared = await prepareGenericMutation(tableName, JSON.stringify(item.data));
+        preparedItems.push({ index, id: item.id, queryParams: item.queryParams, prepared });
+        extensionValidations.push(await validateExtensionCodeForGenericMutation(tableName, prepared.payload, item.id));
+    }
+    const updated = [];
+    for (const item of preparedItems) {
+        const query = parseQueryParamsArg(JSON.stringify(item.queryParams || {}));
+        const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}/${encodeURIComponent(String(item.id))}`, query), { method: 'PATCH', body: JSON.stringify(item.prepared.payload) });
+        updated.push({
+            index: item.index,
+            id: item.id,
+            ...summarizeMutationResult(result, 'updated', tableName),
+        });
+    }
     return { content: [{ type: 'text', text: JSON.stringify({
-                    ...summarizeMutationResult(result, 'updated', tableName),
-                    scriptValidation: prepared.scriptValidation,
-                    extensionValidation,
+                    action: 'updated_records',
+                    tableName,
+                    requested: parsedItems.length,
+                    updatedCount: updated.length,
+                    sequential: true,
+                    duplicateIdsRejected: true,
+                    preflight: {
+                        liveMetadataFieldsValidated: true,
+                        scriptValidatedBeforeAnyPatch: preparedItems.some((item) => item.prepared.scriptValidation?.validated === true),
+                        extensionValidatedBeforeAnyPatch: extensionValidations.some(Boolean),
+                    },
+                    updated,
                 }, null, 2) }] };
 });
 server.tool('get_script_source', [
@@ -1445,7 +1551,7 @@ server.tool('patch_script_source', [
 }, async ({ tableName, id, oldText, newText, occurrence, expectedSourceSha256, scriptLanguage, apply, globalRulesAckKey, knowledgeAckKey }) => {
     const { record, sourceField, sourceCode } = await fetchScriptRecord(tableName, id);
     if (sourceField !== 'sourceCode') {
-        throw new Error(`patch_script_source only saves sourceCode records. Record uses "${sourceField}"; use update_record intentionally for this legacy field.`);
+        throw new Error(`patch_script_source only saves sourceCode records. Record uses "${sourceField}"; use update_records intentionally for this legacy field.`);
     }
     const beforeHash = sha256(sourceCode);
     if (expectedSourceSha256 && expectedSourceSha256 !== beforeHash) {
@@ -1520,42 +1626,69 @@ server.tool('update_script_source', [
                     scriptValidation: prepared.scriptValidation,
                 }, null, 2) }] };
 });
-server.tool('delete_record', 'Delete a record by ID', {
+server.tool('delete_records', 'Delete one or more route-backed records in one MCP call. Pass items as a JSON array string; for one delete, pass one item. The tool previews every target when confirm=false, rejects duplicate ids, and deletes sequentially when confirm=true.', {
     tableName: z.string().describe('Table name'),
-    id: z.string().describe('Record ID to delete'),
-    queryParams: z.string().optional().describe('Optional query params as JSON object string for route-specific confirmation contracts.'),
-    confirm: z.boolean().optional().default(false).describe('Required true to apply the destructive delete. Omit/false returns a preview only.'),
+    items: z.string().describe('JSON array string of delete items: [{ "id": "...", "queryParams": { ... }? }].'),
+    maxItems: z.number().int().min(1).max(100).optional().default(100).describe('Safety cap for one MCP batch. Default/max is 100.'),
+    confirm: z.boolean().optional().default(false).describe('Required true to apply destructive deletes. Omit/false returns previews only.'),
     globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when confirm=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
-}, async ({ tableName, id, queryParams, confirm, globalRulesAckKey }) => {
+}, async ({ tableName, items, maxItems, confirm, globalRulesAckKey }) => {
     validateTableName(tableName);
+    const parsedItems = parseBulkItemsArg('items', items);
+    assertMaxBulkItems('delete_records', parsedItems, maxItems);
+    assertNoDuplicateBulkIds('delete_records', parsedItems);
+    for (const [index, item] of parsedItems.entries()) {
+        if (!item.id)
+            throw new Error(`items[${index}].id is required.`);
+    }
     const primaryKey = await getPrimaryFieldName(tableName);
     if (!confirm) {
-        const query = new URLSearchParams({
-            filter: JSON.stringify({ [primaryKey]: { _eq: id } }),
-            limit: '1',
-            fields: primaryKey,
-        });
-        const preview = await fetchAPI(ENFYRA_API_URL, `/${tableName}?${query.toString()}`).catch((error) => ({ error: String(error?.message || error) }));
+        const previews = [];
+        for (const [index, item] of parsedItems.entries()) {
+            const query = new URLSearchParams({
+                filter: JSON.stringify({ [primaryKey]: { _eq: item.id } }),
+                limit: '1',
+                fields: primaryKey,
+            });
+            const preview = await fetchAPI(ENFYRA_API_URL, `/${tableName}?${query.toString()}`).catch((error) => ({ error: String(error?.message || error) }));
+            previews.push({
+                index,
+                id: item.id,
+                preview: preview?.data?.[0] || null,
+                previewError: preview?.error,
+            });
+        }
         return { content: [{ type: 'text', text: JSON.stringify({
-                        action: 'delete_record_preview',
+                        action: 'delete_records_preview',
                         tableName,
-                        id,
                         primaryKey,
-                        preview: preview?.data?.[0] || null,
-                        previewError: preview?.error,
+                        requested: parsedItems.length,
+                        duplicateIdsRejected: true,
                         destructive: true,
-                        next: 'Call delete_record again with confirm=true to delete this route-backed record.',
+                        previews,
+                        next: 'Call delete_records again with the same items and confirm=true to delete these route-backed records sequentially.',
                     }, null, 2) }] };
     }
     assertGlobalRulesAck(globalRulesAckKey);
-    const query = parseQueryParamsArg(queryParams);
-    const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}/${id}`, query), { method: 'DELETE' });
+    const deleted = [];
+    for (const [index, item] of parsedItems.entries()) {
+        const query = parseQueryParamsArg(JSON.stringify(item.queryParams || {}));
+        const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}/${encodeURIComponent(String(item.id))}`, query), { method: 'DELETE' });
+        deleted.push({
+            index,
+            id: item.id,
+            statusCode: result?.statusCode,
+            success: result?.success,
+        });
+    }
     return { content: [{ type: 'text', text: JSON.stringify({
-                    action: 'deleted',
+                    action: 'deleted_records',
                     tableName,
-                    id,
-                    statusCode: result?.statusCode,
-                    success: result?.success,
+                    requested: parsedItems.length,
+                    deletedCount: deleted.length,
+                    sequential: true,
+                    duplicateIdsRejected: true,
+                    deleted,
                 }, null, 2) }] };
 });
 server.tool('list_methods', 'List enfyra_method records with their UI colors. Use this before creating route methods or method-colored UI.', {}, async () => {
@@ -1573,7 +1706,7 @@ server.tool('list_methods', 'List enfyra_method records with their UI colors. Us
                     appUi: '/settings/methods',
                 }, null, 2) }] };
 });
-server.tool('create_method', 'Create a enfyra_method record with app badge colors. Prefer this over generic create_record for enfyra_method.', {
+server.tool('create_method', 'Create a enfyra_method record with app badge colors. Prefer this over generic create_records for enfyra_method.', {
     method: z.string().describe('Uppercase method name, e.g. GET, POST, PUT, CUSTOM_METHOD. Must start with A-Z and contain only A-Z, 0-9, or underscore.'),
     buttonColor: z.string().describe('Badge background color as full hex, e.g. #dbeafe.'),
     textColor: z.string().describe('Badge text color as full hex, e.g. #1d4ed8.'),
@@ -1603,7 +1736,7 @@ server.tool('create_method', 'Create a enfyra_method record with app badge color
                     appUi: '/settings/methods',
                 }, null, 2) }] };
 });
-server.tool('update_method', 'Update a enfyra_method record color pair, and optionally rename non-system methods. Prefer this over generic update_record for enfyra_method.', {
+server.tool('update_method', 'Update a enfyra_method record color pair, and optionally rename non-system methods. Prefer this over generic update_records for enfyra_method.', {
     id: z.string().optional().describe('Method record id. If omitted, method is used to find the record.'),
     method: z.string().optional().describe('Existing method name to find, or new name when id is provided.'),
     buttonColor: z.string().optional().describe('Badge background color as full hex, e.g. #dbeafe.'),
@@ -2187,10 +2320,10 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Every
     return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 });
 server.tool('create_route', [
-    '**Use this when the user wants a new REST API route or path** — not `create_table`. Custom routes must omit `mainTableId`.',
+    '**Use this when the user wants a new REST API route or path** — not `create_tables`. Custom routes must omit `mainTableId`.',
     '`mainTableId` is only a marker for canonical table routes such as `/orders`; do not set it for `/orders/stats`, `/reports/summary`, `/auth/login`, or any custom path.',
     'Do NOT create a new enfyra_table only to expose an endpoint; create a route without `mainTableId`, then have the handler/hook query explicit repos such as `$ctx.$repos.orders`.',
-    'availableMethods = which REST verbs the route responds to. publicMethods = which REST verbs are public (no auth). GraphQL is enabled separately through enfyra_graphql/update_table graphqlEnabled.',
+    'availableMethods = which REST verbs the route responds to. publicMethods = which REST verbs are public (no auth). GraphQL is enabled separately through enfyra_graphql/update_tables graphqlEnabled.',
     'After creation the tool auto-reloads routes. Then create handlers for specific methods via create_handler on this route id.',
     'Flow: create_route → create_handler (per method) → optionally create_pre_hook / create_post_hook → test via HTTP or admin test APIs (see server instructions).',
 ].join(' '), {