@enfyra/mcp-server 0.1.8 → 0.1.9

package/README.md

@@ -265,7 +265,7 @@ The MCP server includes safety guards for LLM callers:
 - Generated code should use relation property names such as `conversation`, `sender`, and `member` instead of physical FK fields such as `conversationId`, `senderId`, or `memberId`.
 - Custom route tools reject `mainTableId` unless the route is the canonical table route.
 - `discover_enfyra_workflows` maps task intent to workflow surfaces before the agent loads detailed examples or guesses between similar tools.
-- Platform operation tools such as `api_endpoint_workflow`, `create_api_endpoint`, `enable_route`, `disable_route`, `delete_route`, `public_route_methods`, `add_route_methods`, `set_table_graphql`, `ensure_guard`, `ensure_field_permission`, `ensure_column_rule`, `ensure_websocket_event`, `choose_flow_step_tool`, fixed-type flow step tools, `ensure_menu`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension` resolve metadata ids and validate code before saving.
+- Platform operation tools such as `api_endpoint_workflow`, `extension_workflow`, `create_api_endpoint`, `enable_route`, `disable_route`, `delete_route`, `public_route_methods`, `add_route_methods`, `set_table_graphql`, `ensure_guard`, `ensure_field_permission`, `ensure_column_rule`, `ensure_websocket_event`, `choose_flow_step_tool`, fixed-type flow step tools, `ensure_menu`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension` resolve metadata ids and validate code before saving.
 - Schema changes are serialized.
 - Destructive deletes return a preview before requiring `confirm=true`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

package/src/lib/platform-operation-tools.js

@@ -873,6 +873,18 @@ function sourceMatches(existingHandler, sourceCode, scriptLanguage, timeout) {
   return true;
 }
 
+function extensionMatches(existingExtension, opts, menuId) {
+  if (!existingExtension) return false;
+  if (String(existingExtension.type || '') !== String(opts.type || 'page')) return false;
+  if (String(existingExtension.code ?? '') !== String(opts.code ?? '')) return false;
+  if (opts.description !== undefined && String(existingExtension.description || '') !== String(opts.description || '')) return false;
+  if (opts.isEnabled !== undefined && Boolean(existingExtension.isEnabled) !== Boolean(opts.isEnabled)) return false;
+  if (opts.version !== undefined && String(existingExtension.version || '') !== String(opts.version)) return false;
+  if ((opts.type || 'page') === 'page' && menuId && String(refId(existingExtension.menu)) !== String(menuId)) return false;
+  if ((opts.type || 'page') !== 'page' && refId(existingExtension.menu)) return false;
+  return true;
+}
+
 function step(status, id, title, detail = {}) {
   return { id, title, status, ...detail };
 }
@@ -1183,6 +1195,189 @@ async function runApiEndpointWorkflow(apiUrl, opts) {
   };
 }
 
+async function resolveExtensionWorkflowState(apiUrl, opts) {
+  const type = opts.type || 'page';
+  if (type === 'page' && opts.menuId && (opts.menuLabel || opts.menuPath)) {
+    throw new Error('Provide menuId or menuLabel/menuPath for page extension workflow, not both.');
+  }
+  if (type !== 'page' && (opts.menuId || opts.menuLabel || opts.menuPath)) {
+    throw new Error('Menu fields are only valid for page extensions.');
+  }
+  const validation = await validateExtensionCode(apiUrl, opts.code, opts.name);
+  const existingExtension = await findRecord(apiUrl, 'enfyra_extension', { name: { _eq: opts.name } }, 'id,_id,name,type,menu.id,description,isEnabled,version,code');
+  let menu = null;
+  if (type === 'page' && opts.menuId) {
+    menu = await findRecord(apiUrl, 'enfyra_menu', { id: { _eq: opts.menuId } }, 'id,_id,label,path,type,order,isEnabled');
+    if (!menu) throw new Error(`Menu not found: ${opts.menuId}`);
+  } else if (type === 'page' && (opts.menuPath || opts.menuLabel)) {
+    const normalizedPath = opts.menuPath ? normalizeRestPath(opts.menuPath) : undefined;
+    menu = normalizedPath
+      ? await findRecord(apiUrl, 'enfyra_menu', { path: { _eq: normalizedPath } }, 'id,_id,label,path,type,order,isEnabled')
+      : await findRecord(apiUrl, 'enfyra_menu', { label: { _eq: opts.menuLabel } }, 'id,_id,label,path,type,order,isEnabled');
+  }
+
+  const menuId = opts.menuId || getId(menu);
+  const steps = [];
+  steps.push(step('completed', 'validate_extension', 'Validate extension code', { validation }));
+  if (type === 'page') {
+    if (menuId) {
+      const menuNeedsUpdate = Boolean(menu && (
+        (opts.menuLabel !== undefined && menu.label !== opts.menuLabel)
+        || (opts.menuPath !== undefined && menu.path !== normalizeRestPath(opts.menuPath))
+        || (opts.menuType !== undefined && menu.type !== opts.menuType)
+        || (opts.menuOrder !== undefined && Number(menu.order || 0) !== Number(opts.menuOrder))
+        || (opts.menuIsEnabled !== undefined && Boolean(menu.isEnabled) !== Boolean(opts.menuIsEnabled))
+      ));
+      steps.push(step(menuNeedsUpdate ? 'pending' : 'completed', 'ensure_menu', 'Ensure page menu', {
+        menuId,
+        menu: menu ? { id: getId(menu), label: menu.label, path: menu.path } : { id: menuId },
+      }));
+    } else if (opts.menuLabel) {
+      steps.push(step('pending', 'ensure_menu', 'Create page menu', {
+        reason: 'No existing menu matched; ensure_menu will create it.',
+      }));
+    } else {
+      steps.push(step('blocked', 'ensure_menu', 'Create or select page menu', {
+        reason: 'Page extensions require menuId or menuLabel. Provide menuId for an existing menu or menuLabel/menuPath to create/update one.',
+      }));
+    }
+  }
+
+  const effectiveMenuId = type === 'page' ? menuId : undefined;
+  const saveStatus = steps.some((item) => ['blocked', 'waiting'].includes(item.status))
+    ? 'waiting'
+    : extensionMatches(existingExtension, { ...opts, type }, effectiveMenuId)
+      ? 'completed'
+      : 'pending';
+  steps.push(step(saveStatus, 'save_extension', `Ensure ${type} extension`, {
+    extensionId: getId(existingExtension),
+    currentType: existingExtension?.type || null,
+    desiredType: type,
+    menuId: effectiveMenuId || null,
+    reason: saveStatus === 'waiting' ? 'Menu must exist before saving page extension.' : undefined,
+  }));
+
+  const firstRunnable = steps.find((item) => item.status === 'pending') || null;
+  const blocked = steps.find((item) => item.status === 'blocked') || null;
+  return {
+    extension: {
+      name: opts.name,
+      type,
+      id: getId(existingExtension),
+      menuId: effectiveMenuId || null,
+    },
+    validation,
+    existingExtension: existingExtension ? {
+      id: getId(existingExtension),
+      name: existingExtension.name,
+      type: existingExtension.type,
+      menuId: refId(existingExtension.menu) || null,
+    } : null,
+    menu: menu ? { id: getId(menu), label: menu.label, path: menu.path } : null,
+    steps,
+    firstRunnable,
+    blocked,
+    nextSteps: blocked
+      ? [{ tool: 'extension_workflow', input: { name: opts.name, type }, reason: blocked.reason }]
+      : firstRunnable
+        ? [{
+          tool: 'extension_workflow',
+          input: { name: opts.name, type, apply: true, stepId: firstRunnable.id },
+          stepId: firstRunnable.id,
+          requiresKnowledgeAck: 'globalRulesAckKey and extensionAckKey from get_enfyra_required_knowledge',
+        }]
+        : [],
+  };
+}
+
+async function applyExtensionWorkflowStep(apiUrl, state, opts, stepId) {
+  const selectedStep = stepId
+    ? state.steps.find((item) => item.id === stepId)
+    : state.firstRunnable;
+  if (!selectedStep) return { action: 'noop', reason: 'No runnable step remains.' };
+  if (selectedStep.status !== 'pending') {
+    throw new Error(`Step "${selectedStep.id}" is ${selectedStep.status}, not pending.`);
+  }
+
+  const type = opts.type || 'page';
+  if (selectedStep.id === 'ensure_menu') {
+    if (type !== 'page') throw new Error('ensure_menu step is only valid for page extensions.');
+    if (!opts.menuLabel && !opts.menuId) throw new Error('menuLabel or menuId is required for ensure_menu.');
+    return {
+      action: 'menu_ensured',
+      menu: await ensureMenu(apiUrl, {
+        label: opts.menuLabel || state.menu?.label || opts.name,
+        path: opts.menuPath || state.menu?.path,
+        icon: opts.menuIcon,
+        type: opts.menuType,
+        order: opts.menuOrder,
+        permission: opts.menuPermission,
+        description: opts.menuDescription,
+        isEnabled: opts.menuIsEnabled,
+        globalRulesAckKey: opts.globalRulesAckKey,
+      }),
+    };
+  }
+
+  if (selectedStep.id === 'save_extension') {
+    let menuId = opts.menuId || state.extension.menuId;
+    if (type === 'page' && !menuId) {
+      const freshState = await resolveExtensionWorkflowState(apiUrl, opts);
+      menuId = freshState.extension.menuId;
+    }
+    if (type === 'page' && !menuId) throw new Error('Page extension menu is missing. Apply ensure_menu first.');
+    return {
+      action: `${type}_extension_ensured`,
+      extension: await ensureExtension(apiUrl, {
+        name: opts.name,
+        type,
+        code: opts.code,
+        menuId,
+        description: opts.description,
+        isEnabled: opts.isEnabled,
+        version: opts.version,
+        globalRulesAckKey: opts.globalRulesAckKey,
+        extensionKnowledgeAckKey: opts.extensionKnowledgeAckKey,
+      }),
+    };
+  }
+
+  throw new Error(`Unsupported extension workflow step: ${selectedStep.id}`);
+}
+
+async function runExtensionWorkflow(apiUrl, opts) {
+  let state = await resolveExtensionWorkflowState(apiUrl, opts);
+  const operations = [];
+  if (opts.apply || opts.applyAll) {
+    assertGlobalRulesAck(opts.globalRulesAckKey);
+    assertExtensionKnowledgeAck(opts.extensionKnowledgeAckKey);
+    const maxSteps = opts.applyAll ? 5 : 1;
+    for (let i = 0; i < maxSteps; i += 1) {
+      if (state.blocked || !state.firstRunnable) break;
+      operations.push(await applyExtensionWorkflowStep(apiUrl, state, opts, opts.stepId));
+      if (!opts.applyAll) break;
+      state = await resolveExtensionWorkflowState(apiUrl, opts);
+    }
+  }
+  const latestState = operations.length ? await resolveExtensionWorkflowState(apiUrl, opts) : state;
+  return {
+    action: operations.length ? 'extension_workflow_advanced' : 'extension_workflow_planned',
+    extension: latestState.extension,
+    validation: latestState.validation,
+    menu: latestState.menu,
+    existingExtension: latestState.existingExtension,
+    steps: latestState.steps,
+    operations,
+    complete: latestState.steps.every((item) => ['completed', 'skipped'].includes(item.status)),
+    nextSteps: latestState.nextSteps,
+    guidance: [
+      'Call get_extension_theme_contract before generating or reviewing extension UI.',
+      'For menu/account-panel notifications, use counts only when the signal source already owns an exact count; otherwise use a dot/chip for new attention.',
+      'Do not fetch destination domain lists solely to decorate the shell; destination pages own domain fetching after click.',
+    ],
+  };
+}
+
 export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
   server.tool(
     'validate_dynamic_script',
@@ -1236,6 +1431,40 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     async () => jsonText(getThemeClassReference()),
   );
 
+  server.tool(
+    'extension_workflow',
+    [
+      'Step-by-step workflow for creating or updating Enfyra admin page, global, or widget extensions.',
+      'Use this when an LLM is building extension UI, menu shell notifications, account panel entries, or page/menu wiring and should follow live nextSteps instead of guessing raw enfyra_extension mutations.',
+      'With apply=false it validates code, reads live menu/extension state, and returns pending steps.',
+      'With apply=true it applies exactly the next pending step. With applyAll=true it advances all currently safe pending steps.',
+      'Call get_extension_theme_contract before generating or reviewing UI.',
+    ].join(' '),
+    {
+      name: z.string().describe('Extension unique name.'),
+      type: z.enum(['page', 'global', 'widget']).optional().default('page').describe('Extension type. Page extensions need a menu. Global extensions are for shell-wide registration.'),
+      code: z.string().describe('Vue SFC extension code.'),
+      menuId: z.union([z.string(), z.number()]).optional().describe('Existing menu id for a page extension. Provide this or menuLabel/menuPath.'),
+      menuLabel: z.string().optional().describe('Menu label to create or update for a page extension when menuId is not provided.'),
+      menuPath: z.string().optional().describe('Admin app route path for the page menu, e.g. /cloud/support.'),
+      menuIcon: z.string().optional().describe('Optional menu icon name.'),
+      menuType: z.enum(['Menu', 'Dropdown Menu']).optional().describe('Menu type. Omit to preserve an existing menu value or use the platform default for a new menu.'),
+      menuOrder: z.number().optional().describe('Menu display order. Omit to preserve an existing menu value or use the platform default for a new menu.'),
+      menuPermission: z.string().optional().describe('Optional menu permission JSON object.'),
+      menuDescription: z.string().optional().describe('Optional menu admin note.'),
+      menuIsEnabled: z.boolean().optional().describe('Enable the menu. Omit to preserve an existing menu value or use the platform default for a new menu.'),
+      description: z.string().optional().describe('Extension description.'),
+      isEnabled: z.boolean().optional().default(true).describe('Enable extension.'),
+      version: z.string().optional().default('1.0.0').describe('Extension version.'),
+      apply: z.boolean().optional().default(false).describe('false returns plan only; true applies exactly the next pending step.'),
+      applyAll: z.boolean().optional().default(false).describe('true applies all safe pending steps in order. Prefer apply=true for production changes.'),
+      stepId: z.string().optional().describe('Optional pending step id to apply. Omit to apply the next pending step.'),
+      globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when apply/applyAll mutates metadata. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
+      extensionKnowledgeAckKey: extensionKnowledgeAckParam(z).optional().describe('Required when apply/applyAll saves extension code. Use extensionAckKey from get_enfyra_required_knowledge.'),
+    },
+    async (input) => jsonText(await runExtensionWorkflow(ENFYRA_API_URL, input)),
+  );
+
   server.tool(
     'set_table_graphql',
     'Business operation: enable or disable GraphQL for one table through enfyra_graphql, then reload GraphQL. REST route methods do not control GraphQL.',

package/src/lib/tool-routing.js

@@ -67,14 +67,14 @@ export const TOOL_WORKFLOWS = [
     firstTools: ['get_enfyra_required_knowledge', 'get_extension_theme_contract', 'inspect_feature'],
     inspectTools: ['inspect_feature', 'trace_metadata_usage', 'get_script_source'],
     knowledgeTools: ['get_enfyra_required_knowledge', 'get_extension_theme_contract', 'get_theme_class_reference'],
-    writeTools: ['ensure_menu', 'ensure_page_extension', 'ensure_global_extension', 'ensure_widget_extension'],
+    writeTools: ['extension_workflow', 'ensure_menu', 'ensure_page_extension', 'ensure_global_extension', 'ensure_widget_extension'],
     verifyTools: ['validate_extension_code', 'inspect_feature'],
     avoidTools: [
       {
         tool: 'create_record/update_record on enfyra_extension',
         when: 'creating or changing extension code',
-        useInstead: 'ensure_page_extension, ensure_global_extension, or ensure_widget_extension',
-        reason: 'Ensure tools validate extension code and preserve extension/menu contracts before saving.',
+        useInstead: 'extension_workflow, ensure_page_extension, ensure_global_extension, or ensure_widget_extension',
+        reason: 'Workflow and ensure tools validate extension code and preserve extension/menu contracts before saving.',
       },
       {
         tool: 'query_table on destination domain lists',
@@ -88,6 +88,7 @@ export const TOOL_WORKFLOWS = [
     nextStepTemplate: [
       'Call get_extension_theme_contract before writing or reviewing UI.',
       'Inspect the existing menu/extension/global shell registration.',
+      'Use extension_workflow with apply=false when page/menu wiring or shell notification behavior needs multiple steps.',
       'Choose count only when the source already owns an exact count; choose dot/chip for new-attention signals.',
       'Validate extension code or use an ensure_*_extension tool that validates before saving.',
     ],