@enfyra/mcp-server 0.1.59 → 0.1.61

package/dist/mcp-server-entry.js

@@ -70,6 +70,7 @@ import { validateMainTableRoutePath } from './lib/route-guards.js';
 import { installColumnarToolFormatter, jsonContent } from './lib/response-format.js';
 import { startMcpUsageTelemetry } from './lib/mcp-usage-telemetry.js';
 import { startRuntimeCacheSocket } from './lib/runtime-cache-socket.js';
+import { executeSequentialBatch } from './lib/sequential-batch.js';
 import { compactSourceFields, writeSourceArtifact } from './lib/source-artifacts.js';
 import { installToolsetFilter, normalizeMcpToolset, summarizeToolsetForInstructions } from './lib/toolset-filter.js';
 import { findRoutePermission, mergeMethodNames, normalizeMethodNames, resolveRoleByNameOrId, routeAvailableMethodNames, routePublicMethodNames, summarizeRouteAccess, summarizeRoutePermission, validateMethodsForRoute, } from './lib/route-permission-tools.js';
@@ -1487,11 +1488,11 @@ server.tool('find_one_record', 'Find a single record by ID or filter. By ID uses
 // ============================================================================
 // CRUD TOOLS
 // ============================================================================
-server.tool('create_records', 'Create one or more route-backed records. Always pass records as a native JSON array; 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. create_records only writes one table at a time, so when seeding related tables, follow create_tables cleanupHints.recordCreateOrder and create parent/target records before child/source records.', {
+server.tool('create_records', 'Create one or more route-backed records. Always pass records as a native JSON array; for one record, pass a one-item array. MCP preflights every item before the first POST, then writes sequentially; this is not a backend bulk endpoint or transaction. On a failed item, it returns the completed checkpoint and remaining indexes—retry only the remaining records after resolving the error.', {
     tableName: z.string().describe('Table name to insert into'),
     records: bulkObjectArrayParam(z, 'Records').describe('Records as a native JSON array. 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.'),
+    maxRecords: z.number().int().min(1).max(100).optional().default(20).describe('Safety cap for one MCP batch. Default is 20; explicitly raise it up to 100 only when partial-write recovery is acceptable.'),
     globalRulesAckKey: globalRulesAckParam(z),
     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.'),
@@ -1509,19 +1510,35 @@ server.tool('create_records', 'Create one or more route-backed records. Always p
         extensionValidations.push(await validateExtensionCodeForGenericMutation(tableName, item.payload, item.payload?.name || item.index));
     }
     const query = parseQueryParamsArg(queryParams);
-    const created = [];
-    for (const item of prepared.records) {
+    const batch = await executeSequentialBatch(prepared.records, async (item) => {
         const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}`, query), { method: 'POST', body: JSON.stringify(item.payload) });
-        created.push({
+        return {
             index: item.index,
             ...summarizeMutationResult(result, 'created', tableName),
-        });
+        };
+    });
+    if (batch.status === 'partial_failure') {
+        return {
+            isError: true,
+            content: [{ type: 'text', text: JSON.stringify({
+                        action: 'create_records_partial_failure',
+                        tableName,
+                        requested: parsedRecords.length,
+                        createdCount: batch.completed.length,
+                        sequential: true,
+                        transactional: false,
+                        completed: batch.completed,
+                        failed: batch.failure,
+                        remainingIndexes: batch.remainingIndexes,
+                        retryHint: 'Resolve the failed item, then retry only the failed item and remaining indexes. Do not retry completed records unless the table has an idempotent unique key.',
+                    }, null, 2) }],
+        };
     }
     return { content: [{ type: 'text', text: JSON.stringify({
                     action: 'created_records',
                     tableName,
                     requested: parsedRecords.length,
-                    createdCount: created.length,
+                    createdCount: batch.completed.length,
                     sequential: true,
                     transactional: false,
                     preflight: {
@@ -1529,14 +1546,14 @@ server.tool('create_records', 'Create one or more route-backed records. Always p
                         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.`,
+                    created: batch.completed,
+                    detailHint: `Use query_table({ tableName: "${tableName}", fields: [...], limit: ${Math.min(batch.completed.length, 20)} }) to inspect created records when needed.`,
                 }, null, 2) }] };
 });
-server.tool('update_records', 'Update one or more records in one MCP call. Pass items as a native JSON array; 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.', {
+server.tool('update_records', 'Update one or more records in one MCP call. Pass items as a native JSON array; for one update, pass one item. MCP preflights every item, rejects duplicate ids, then PATCHes sequentially. On a failed item, it returns the completed checkpoint and remaining indexes so callers do not replay prior updates.', {
     tableName: z.string().describe('Table name'),
     items: bulkObjectArrayParam(z, 'Update items').describe('Native JSON array 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.'),
+    maxItems: z.number().int().min(1).max(100).optional().default(20).describe('Safety cap for one MCP batch. Default is 20; explicitly raise it up to 100 only when partial-write recovery is acceptable.'),
     globalRulesAckKey: globalRulesAckParam(z),
     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.'),
@@ -1559,21 +1576,36 @@ server.tool('update_records', 'Update one or more records in one MCP call. Pass
         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 batch = await executeSequentialBatch(preparedItems, async (item) => {
         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({
+        return {
             index: item.index,
             id: item.id,
             ...summarizeMutationResult(result, 'updated', tableName),
-        });
+        };
+    });
+    if (batch.status === 'partial_failure') {
+        return {
+            isError: true,
+            content: [{ type: 'text', text: JSON.stringify({
+                        action: 'update_records_partial_failure',
+                        tableName,
+                        requested: parsedItems.length,
+                        updatedCount: batch.completed.length,
+                        sequential: true,
+                        completed: batch.completed,
+                        failed: batch.failure,
+                        remainingIndexes: batch.remainingIndexes,
+                        retryHint: 'Resolve the failed item, then retry only the failed item and remaining indexes. Do not replay completed updates unless the new value is deliberately idempotent.',
+                    }, null, 2) }],
+        };
     }
     return { content: [{ type: 'text', text: JSON.stringify({
                     action: 'updated_records',
                     tableName,
                     requested: parsedItems.length,
-                    updatedCount: updated.length,
+                    updatedCount: batch.completed.length,
                     sequential: true,
                     duplicateIdsRejected: true,
                     preflight: {
@@ -1581,7 +1613,7 @@ server.tool('update_records', 'Update one or more records in one MCP call. Pass
                         scriptValidatedBeforeAnyPatch: preparedItems.some((item) => item.prepared.scriptValidation?.validated === true),
                         extensionValidatedBeforeAnyPatch: extensionValidations.some(Boolean),
                     },
-                    updated,
+                    updated: batch.completed,
                 }, null, 2) }] };
 });
 server.tool('get_script_source', [
@@ -2330,9 +2362,9 @@ server.tool('test_rest_endpoint', [
 ].join(' '), {
     method: z.string().optional().default('GET').describe('HTTP method name. Must exist in enfyra_method.name for Enfyra route-backed calls.'),
     path: z.string().describe('Enfyra API path, e.g. /enfyra_route?limit=1'),
-    query: z.string().optional().describe('Optional query params JSON object, merged onto path query string'),
-    body: z.string().optional().describe('Optional JSON request body string'),
-    headers: z.string().optional().describe('Optional headers JSON object'),
+    query: z.string().optional().describe('Optional JSON-encoded query object string, e.g. {"limit":1,"filter":{"status":{"_eq":"ready"}}}; merged onto the path query string.'),
+    body: z.string().optional().describe('Optional JSON request body string, e.g. {"title":"Example"}.'),
+    headers: z.string().optional().describe('Optional JSON-encoded headers object string.'),
     useAuth: z.boolean().optional().default(true).describe('Attach MCP admin Bearer token. Set false to test public access.'),
 }, async ({ method, path, query, body, headers, useAuth }) => {
     const httpMethod = normalizeMethodNameInput(method || 'GET');