@enfyra/mcp-server 0.1.5 → 0.1.7

package/src/mcp-server-entry.mjs

@@ -27,9 +27,11 @@ 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';
@@ -329,7 +331,7 @@ function summarizeRoutes(routesResult) {
   }));
 }
 
-function summarizeMetadata(metadata, { search, limit } = {}) {
+function summarizeMetadata(metadata, { search, limit, all = false } = {}) {
   const tables = normalizeTables(metadata);
   const q = search ? search.toLowerCase() : null;
   const summarized = tables.map((table) => ({
@@ -344,11 +346,13 @@ function summarizeMetadata(metadata, { search, limit } = {}) {
   const matched = q
     ? summarized.filter((table) => JSON.stringify(table).toLowerCase().includes(q))
     : summarized;
-  const outputLimit = limit || 30;
+  const outputLimit = all ? matched.length : (limit || 30);
   return {
     tableCount: tables.length,
     matchedTableCount: matched.length,
     returnedTableCount: Math.min(matched.length, outputLimit),
+    complete: all || outputLimit >= matched.length,
+    hardCap: all ? null : outputLimit,
     search: search || null,
     tables: matched.slice(0, outputLimit),
   };
@@ -805,15 +809,21 @@ server.tool('get_all_metadata', 'Get concise metadata summary for all tables. Us
   includeFull: z.boolean().optional().default(false).describe('Return full raw metadata. Default false to keep MCP context small.'),
   search: z.string().optional().describe('Optional table-name/alias substring filter.'),
   limit: z.number().optional().describe('Maximum tables returned after search. Default 30.'),
-}, async ({ includeFull, search, limit }) => {
+  all: z.boolean().optional().default(false).describe('Return every matched table summary. Use when a complete table list is required.'),
+}, async ({ includeFull, search, limit, all }) => {
+  if (all && limit !== undefined) {
+    throw new Error('get_all_metadata accepts either all=true or limit, not both.');
+  }
   const result = await fetchAPI(ENFYRA_API_URL, '/metadata');
   const payload = includeFull
     ? result
     : {
         statusCode: result?.statusCode,
         success: result?.success,
-        ...summarizeMetadata(result, { search, limit }),
-        detailHint: 'Default response is capped and minimal. Call get_table_metadata({ tableName }) or inspect_table({ tableName }) for columns, relations, and route context.',
+        ...summarizeMetadata(result, { search, limit, all }),
+        detailHint: all
+          ? 'Complete summary returned. Call get_table_metadata({ tableName }) or inspect_table({ tableName }) for columns, relations, and route context.'
+          : 'Default response is capped and minimal. Pass all=true for a complete summary, or call get_table_metadata({ tableName }) / inspect_table({ tableName }) for detail.',
       };
   return jsonContent(payload);
 });
@@ -1471,9 +1481,11 @@ server.tool('create_record', 'Create a new record in any route-backed table. The
   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.'),
+  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, knowledgeAckKey, extensionKnowledgeAckKey }) => {
+}, async ({ tableName, data, queryParams, globalRulesAckKey, knowledgeAckKey, extensionKnowledgeAckKey }) => {
+  assertGlobalRulesAck(globalRulesAckKey);
   validateTableName(tableName);
   assertKnowledgeForGenericMutation(tableName, data, { knowledgeAckKey, extensionKnowledgeAckKey });
   const prepared = await prepareGenericMutation(tableName, data);
@@ -1490,9 +1502,11 @@ server.tool('update_record', 'Update an existing record by ID using PATCH. The t
   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.'),
+  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, knowledgeAckKey, extensionKnowledgeAckKey }) => {
+}, async ({ tableName, id, data, queryParams, globalRulesAckKey, knowledgeAckKey, extensionKnowledgeAckKey }) => {
+  assertGlobalRulesAck(globalRulesAckKey);
   validateTableName(tableName);
   assertKnowledgeForGenericMutation(tableName, data, { knowledgeAckKey, extensionKnowledgeAckKey });
   const prepared = await prepareGenericMutation(tableName, data);
@@ -1548,9 +1562,10 @@ server.tool(
     expectedSourceSha256: z.string().optional().describe('Optional SHA-256 from get_script_source; fails if source changed.'),
     scriptLanguage: z.string().optional().describe('Script language to save. Defaults to existing scriptLanguage or javascript.'),
     apply: z.boolean().optional().default(false).describe('false returns preview only; true validates and saves.'),
+    globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when apply=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
     knowledgeAckKey: dynamicCodeKnowledgeAckParam(z).optional().describe('Required when apply=true. Use dynamicCodeAckKey from get_enfyra_required_knowledge.'),
   },
-  async ({ tableName, id, oldText, newText, occurrence, expectedSourceSha256, scriptLanguage, apply, knowledgeAckKey }) => {
+  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.`);
@@ -1581,6 +1596,7 @@ server.tool(
     if (!apply) {
       return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
     }
+    assertGlobalRulesAck(globalRulesAckKey);
     assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     const language = scriptLanguage || record.scriptLanguage || 'javascript';
     const prepared = await prepareGenericMutation(
@@ -1623,9 +1639,11 @@ server.tool(
     id: z.string().describe('Record ID to update'),
     sourceCode: z.string().describe('Editable script sourceCode. Pass the raw code string; do not JSON-escape it yourself.'),
     scriptLanguage: z.string().optional().default('javascript').describe('Script language, usually javascript or typescript'),
+    globalRulesAckKey: globalRulesAckParam(z),
     knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
   },
-  async ({ tableName, id, sourceCode, scriptLanguage, knowledgeAckKey }) => {
+  async ({ tableName, id, sourceCode, scriptLanguage, globalRulesAckKey, knowledgeAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     validateTableName(tableName);
     const prepared = await prepareGenericMutation(
@@ -1652,7 +1670,8 @@ server.tool('delete_record', 'Delete a record by ID', {
   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.'),
-}, async ({ tableName, id, queryParams, confirm }) => {
+  globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when confirm=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
+}, async ({ tableName, id, queryParams, confirm, globalRulesAckKey }) => {
   validateTableName(tableName);
   const primaryKey = await getPrimaryFieldName(tableName);
   if (!confirm) {
@@ -1673,6 +1692,7 @@ server.tool('delete_record', 'Delete a record by ID', {
       next: 'Call delete_record again with confirm=true to delete this route-backed record.',
     }, null, 2) }] };
   }
+  assertGlobalRulesAck(globalRulesAckKey);
   const query = parseQueryParamsArg(queryParams);
   const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}/${id}`, query), { method: 'DELETE' });
   return { content: [{ type: 'text', text: JSON.stringify({
@@ -1713,8 +1733,10 @@ server.tool(
     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.'),
     isSystem: z.boolean().optional().default(false).describe('Set true only for built-in/runtime-owned methods. Normal app methods should leave this false.'),
+    globalRulesAckKey: globalRulesAckParam(z),
   },
-  async ({ method, buttonColor, textColor, isSystem }) => {
+  async ({ method, buttonColor, textColor, isSystem, globalRulesAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     const normalizedMethod = normalizeMethodNameInput(method);
     const existing = await findMethodRecordByName(normalizedMethod);
     if (existing) {
@@ -1747,8 +1769,10 @@ server.tool(
     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.'),
     textColor: z.string().optional().describe('Badge text color as full hex, e.g. #1d4ed8.'),
+    globalRulesAckKey: globalRulesAckParam(z),
   },
-  async ({ id, method, buttonColor, textColor }) => {
+  async ({ id, method, buttonColor, textColor, globalRulesAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     let targetId = id;
     let existing = null;
     if (!targetId) {
@@ -1793,8 +1817,9 @@ server.tool(
     id: z.string().optional().describe('Method record id. If omitted, method is used to find the record.'),
     method: z.string().optional().describe('Method name to find when id is omitted.'),
     confirm: z.boolean().optional().default(false).describe('Required true to apply the destructive delete. Omit/false returns a preview only.'),
+    globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when confirm=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
   },
-  async ({ id, method, confirm }) => {
+  async ({ id, method, confirm, globalRulesAckKey }) => {
     let targetId = id;
     let target = null;
     if (!targetId) {
@@ -1820,6 +1845,7 @@ server.tool(
         next: 'Call delete_method again with confirm=true to delete.',
       }, null, 2) }] };
     }
+    assertGlobalRulesAck(globalRulesAckKey);
     const result = await fetchAPI(ENFYRA_API_URL, `/enfyra_method/${encodeURIComponent(String(targetId))}`, { method: 'DELETE' });
     _methodMap = null;
     return { content: [{ type: 'text', text: JSON.stringify({
@@ -2091,16 +2117,11 @@ server.tool(
     tableName: z.string().describe('Table name or alias to inspect'),
   },
   async ({ tableName }) => {
-    let state = await collectRestDefinitionState();
-    let table = state.tables.find((item) => item?.name === tableName || item?.alias === tableName);
+    const state = await collectRestDefinitionState();
+    const table = state.tables.find((item) => item?.name === tableName || item?.alias === tableName);
     if (!table) {
-      await fetchAPI(ENFYRA_API_URL, '/admin/reload/metadata', { method: 'POST' }).catch(() => {});
-      await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
-      await new Promise((resolve) => setTimeout(resolve, 150));
-      state = await collectRestDefinitionState();
-      table = state.tables.find((item) => item?.name === tableName || item?.alias === tableName);
+      throw new Error(`Unknown table "${tableName}". Use get_all_tables({ search, limit }) or get_all_metadata({ search, all: true }) to confirm the table name. If a just-created table is missing, verify the create response/reload event before calling manual reload tools.`);
     }
-    if (!table) throw new Error(`Unknown table "${tableName}"`);
     const tableId = getId(table);
     const columnIds = new Set((table.columns || []).map((column) => String(getId(column))));
     const relationIds = new Set((table.relations || []).map((relation) => String(getId(relation))));
@@ -2402,7 +2423,7 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Every
   const queryParams = new URLSearchParams({
     filter: JSON.stringify(filter),
     fields: 'id,path,mainTable.name,availableMethods.*,publicMethods.*,isEnabled',
-    limit: '1000',
+    limit: all ? '0' : '1000',
   });
   const result = await fetchAPI(ENFYRA_API_URL, `/enfyra_route?${queryParams.toString()}`);
   const q = search ? search.toLowerCase() : null;
@@ -2421,6 +2442,8 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Every
     matchedRouteCount: matchedRoutes.length,
     returnedRouteCount: Math.min(matchedRoutes.length, routeLimit),
     all: !!all,
+    complete: all || routeLimit >= matchedRoutes.length,
+    hardCap: all ? null : routeLimit,
     search: search || null,
     routes: matchedRoutes.slice(0, routeLimit),
     detailHint: matchedRoutes.length > routeLimit
@@ -2449,8 +2472,10 @@ server.tool(
       .describe('Methods accessible WITHOUT auth token. Omit = all methods require auth.'),
     isEnabled: z.boolean().optional().default(true).describe('Enable route immediately'),
     description: z.string().optional().describe('Route description'),
+    globalRulesAckKey: globalRulesAckParam(z),
   },
-  async ({ path: routePath, mainTableId, methods, publicMethods, isEnabled, description }) => {
+  async ({ path: routePath, mainTableId, methods, publicMethods, isEnabled, description, globalRulesAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     const methodMap = await getMethodMap();
     const normalizedPath = normalizeRestPath(routePath);
 
@@ -2513,9 +2538,11 @@ server.tool(
     sourceCode: z.string().describe('Handler JavaScript sourceCode. Do not use logic; backend CRUD rejects logic.'),
     scriptLanguage: z.enum(['javascript', 'typescript']).optional().default('javascript').describe('Script language for compiler. Default javascript.'),
     timeout: z.number().optional().describe('Timeout in ms (default: system DEFAULT_HANDLER_TIMEOUT, usually 30000)'),
+    globalRulesAckKey: globalRulesAckParam(z),
     knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
   },
-  async ({ routeId, method, methods, sourceCode, scriptLanguage, timeout, knowledgeAckKey }) => {
+  async ({ routeId, method, methods, sourceCode, scriptLanguage, timeout, globalRulesAckKey, knowledgeAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     const methodNames = methods && methods.length > 0 ? methods : method ? [method] : [];
     if (methodNames.length === 0) throw new Error('Provide method or methods');
@@ -2576,9 +2603,11 @@ server.tool(
       .describe('Method names this hook applies to. Default: built-in REST methods GET, POST, PATCH, DELETE.'),
     priority: z.number().optional().default(0).describe('Execution order (lower = first)'),
     isEnabled: z.boolean().optional().default(true).describe('Enable hook immediately'),
+    globalRulesAckKey: globalRulesAckParam(z),
     knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
   },
-  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled, knowledgeAckKey }) => {
+  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled, globalRulesAckKey, knowledgeAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     const methodMap = await getMethodMap();
     const methodNames = methods || ['GET', 'POST', 'PATCH', 'DELETE'];
@@ -2632,9 +2661,11 @@ server.tool(
       .describe('Method names this hook applies to. Default: built-in REST methods GET, POST, PATCH, DELETE.'),
     priority: z.number().optional().default(0).describe('Execution order (lower = first)'),
     isEnabled: z.boolean().optional().default(true).describe('Enable hook immediately'),
+    globalRulesAckKey: globalRulesAckParam(z),
     knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
   },
-  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled, knowledgeAckKey }) => {
+  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled, globalRulesAckKey, knowledgeAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     assertDynamicCodeKnowledgeAck(knowledgeAckKey);
     const methodMap = await getMethodMap();
     const methodNames = methods || ['GET', 'POST', 'PATCH', 'DELETE'];
@@ -2751,8 +2782,10 @@ server.tool(
     mode: z.enum(['merge', 'replace']).optional().default('merge').describe('merge adds methods to an existing permission; replace overwrites methods on the matched permission.'),
     description: z.string().optional().describe('Admin note'),
     isEnabled: z.boolean().optional().default(true).describe('Enable the permission'),
+    globalRulesAckKey: globalRulesAckParam(z),
   },
-  async ({ path, routeId, methods, roleId, roleName, allowedUserIds, mode, description, isEnabled }) => {
+  async ({ path, routeId, methods, roleId, roleName, allowedUserIds, mode, description, isEnabled, globalRulesAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     if (!path && !routeId) throw new Error('Provide path or routeId.');
     if (path && routeId) throw new Error('Provide path or routeId, not both.');
     if (roleId && roleName) throw new Error('Provide roleId or roleName, not both.');
@@ -2852,24 +2885,36 @@ registerPlatformOperationTools(server, ENFYRA_API_URL);
 // CACHE & SYSTEM TOOLS
 // ============================================================================
 
-server.tool('reload_all', 'Reload all caches (metadata, routes, GraphQL)', {}, async () => {
+server.tool('reload_all', 'Reload all caches (metadata, routes, GraphQL)', {
+  globalRulesAckKey: globalRulesAckParam(z),
+}, async ({ globalRulesAckKey }) => {
+  assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload', { method: 'POST' });
-  return { content: [{ type: 'text', text: `System reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+  return jsonContent({ action: 'reloaded_all', result });
 });
 
-server.tool('reload_metadata', 'Reload metadata cache only', {}, async () => {
+server.tool('reload_metadata', 'Reload metadata cache only', {
+  globalRulesAckKey: globalRulesAckParam(z),
+}, async ({ globalRulesAckKey }) => {
+  assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/metadata', { method: 'POST' });
-  return { content: [{ type: 'text', text: `Metadata reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+  return jsonContent({ action: 'reloaded_metadata', result });
 });
 
-server.tool('reload_routes', 'Reload routes cache only', {}, async () => {
+server.tool('reload_routes', 'Reload routes cache only', {
+  globalRulesAckKey: globalRulesAckParam(z),
+}, async ({ globalRulesAckKey }) => {
+  assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' });
-  return { content: [{ type: 'text', text: `Routes reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+  return jsonContent({ action: 'reloaded_routes', result });
 });
 
-server.tool('reload_graphql', 'Reload GraphQL schema', {}, async () => {
+server.tool('reload_graphql', 'Reload GraphQL schema', {
+  globalRulesAckKey: globalRulesAckParam(z),
+}, async ({ globalRulesAckKey }) => {
+  assertGlobalRulesAck(globalRulesAckKey);
   const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/graphql', { method: 'POST' });
-  return { content: [{ type: 'text', text: `GraphQL reloaded:\n${JSON.stringify(result, null, 2)}` }] };
+  return jsonContent({ action: 'reloaded_graphql', result });
 });
 
 // ============================================================================
@@ -3015,8 +3060,10 @@ server.tool(
     name: z.string().describe('Exact NPM package name (e.g., "node-ssh", "axios")'),
     type: z.enum(['Server', 'App']).default('Server').describe('Where to install: Server (handlers/hooks) or App (extensions)'),
     version: z.string().optional().describe('Specific version. If omitted, fetches latest from NPM.'),
+    globalRulesAckKey: globalRulesAckParam(z),
   },
-  async ({ name, type, version }) => {
+  async ({ name, type, version, globalRulesAckKey }) => {
+    assertGlobalRulesAck(globalRulesAckKey);
     // Step 1: Get package info from NPM if version not specified
     let pkgVersion = version;
     let pkgDescription = '';
@@ -3038,12 +3085,15 @@ server.tool(
     const checkFilter = JSON.stringify({ name: { _eq: name }, type: { _eq: type } });
     const existing = await fetchAPI(ENFYRA_API_URL, `/enfyra_package?filter=${encodeURIComponent(checkFilter)}&limit=1`);
     if (existing.data && existing.data.length > 0) {
-      return {
-        content: [{
-          type: 'text',
-          text: `Package "${name}" is already installed (version: ${existing.data[0].version}, type: ${existing.data[0].type}).\n${JSON.stringify(existing.data[0], null, 2)}`,
-        }],
-      };
+      return jsonContent({
+        action: 'package_already_installed',
+        package: {
+          name,
+          version: existing.data[0].version,
+          type: existing.data[0].type,
+        },
+        record: existing.data[0],
+      });
     }
 
     // Step 3: Get current user for installedBy
@@ -3065,12 +3115,11 @@ server.tool(
       body: JSON.stringify(body),
     });
 
-    return {
-      content: [{
-        type: 'text',
-        text: `Package "${name}@${pkgVersion}" installed successfully (type: ${type}).\n${JSON.stringify(result, null, 2)}`,
-      }],
-    };
+    return jsonContent({
+      action: 'package_installed',
+      package: { name, version: pkgVersion, type },
+      result,
+    });
   },
 );