@enfyra/mcp-server 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "packageManager": "yarn@4.17.0",
@@ -27,4 +27,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/lib/mcp-examples.js

@@ -1597,6 +1597,7 @@ ensure_page_extension({
           'Use enfyra_menu.label, not title.',
           'Sensitive admin menus should include a permission condition at creation time.',
           'For page extensions, create the menu first with ensure_menu and pass its id to ensure_page_extension.',
+          'When editing an existing extension by id or name, use update_extension_code so local guards plus /enfyra_extension/preview and the save happen in one atomic call. Do not spend a second LLM step on validate_extension_code followed by update_record unless the user requested validation-only output.',
           'Call get_extension_theme_contract before writing or reviewing page/widget/global extension UI; that tool is the authority for theme, color, layout, modal, drawer, and shell registry details.',
           'Call get_enfyra_required_knowledge before saving extension code, pass globalRulesAckKey as globalRulesAckKey, and pass extensionAckKey as extensionKnowledgeAckKey.',
           'Page extensions must register the app-shell PageHeader with usePageHeaderRegistry instead of rendering a custom top header.',

package/src/lib/mcp-instructions.js

@@ -33,7 +33,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Before mutating metadata, schema, routes, permissions, menus, packages, cache state, dynamic code, or extension UI, call `get_enfyra_required_knowledge`, read the global rules, and pass `globalRulesAckKey` into write tools. Dynamic server code also requires `dynamicCodeAckKey`; extension code also requires `extensionAckKey`.',
     '- With non-root API tokens, call `get_permission_profile` before relying on admin helper tools or when debugging 403s. MCP admin helpers require ordinary route permissions for static admin routes such as `/admin/script/validate`, `/admin/test/run`, `/admin/flow/trigger/:id`, and `/admin/reload/*`.',
     '- Prefer the most specific business operation tool over raw metadata CRUD. `discover_enfyra_workflows` provides the current operation-tool map and negative-routing avoidTools.',
-    '- Before saving standalone dynamic script or extension code, call `validate_dynamic_script` or `validate_extension_code` unless the chosen ensure/update tool already validates the code.',
+    '- Before saving standalone dynamic script code, call `validate_dynamic_script` unless the chosen write tool already validates the code. For extension edits, prefer `update_extension_code`, `extension_workflow`, or `ensure_*_extension`; these validate and save atomically. Use `validate_extension_code` only for validation-only checks.',
     '- Extension SFCs must use auto-injected components directly in templates, such as `<UButton>`, and must not call `resolveComponent()` for Nuxt UI/eApp components.',
     '- For existing script-backed records, use `trace_metadata_usage` then `get_script_source`; edit with `patch_script_source` or `update_script_source` so source is hash-checked and validated.',
     '- Validate behavior with `test_rest_endpoint`, `run_admin_test`, `test_flow_step`, or the route-specific tool before claiming a dynamic feature works.',

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

@@ -630,7 +630,7 @@ export function validateExtensionCodeLocally(code) {
   return { componentCasing: 'passed' };
 }
 
-async function validateExtensionCode(apiUrl, code, name) {
+export async function validateExtensionCode(apiUrl, code, name) {
   const localChecks = validateExtensionCodeLocally(code);
   const result = await fetchAPI(apiUrl, '/enfyra_extension/preview', {
     method: 'POST',
@@ -647,6 +647,45 @@ async function validateExtensionCode(apiUrl, code, name) {
   };
 }
 
+async function updateExtensionCode(apiUrl, {
+  id,
+  name,
+  code,
+  description,
+  isEnabled,
+  version,
+  globalRulesAckKey,
+  extensionKnowledgeAckKey,
+}) {
+  assertGlobalRulesAck(globalRulesAckKey);
+  assertExtensionKnowledgeAck(extensionKnowledgeAckKey);
+  if (!id && !name) throw new Error('Provide id or name to update an existing extension.');
+  const existing = id
+    ? await findRecord(apiUrl, 'enfyra_extension', { id: { _eq: id } }, 'id,_id,name,type,menu.id')
+    : await findRecord(apiUrl, 'enfyra_extension', { name: { _eq: name } }, 'id,_id,name,type,menu.id');
+  if (!existing) throw new Error(`Extension not found: ${id || name}`);
+  const extensionId = getId(existing);
+  const validation = await validateExtensionCode(apiUrl, code, name || existing.name || extensionId);
+  const body = {
+    code,
+    ...(description !== undefined ? { description } : {}),
+    ...(isEnabled !== undefined ? { isEnabled } : {}),
+    ...(version !== undefined ? { version } : {}),
+  };
+  const result = await fetchAPI(apiUrl, `/enfyra_extension/${encodeURIComponent(String(extensionId))}`, {
+    method: 'PATCH',
+    body: JSON.stringify(body),
+  });
+  return {
+    action: 'extension_code_updated',
+    id: extensionId,
+    name: existing.name || name || null,
+    type: existing.type || null,
+    result,
+    validation,
+  };
+}
+
 function normalizeMetadataTables(metadata) {
   const tables = metadata?.data?.tables || metadata?.tables || metadata?.data || [];
   return Array.isArray(tables) ? tables : Object.values(tables || {});
@@ -1527,7 +1566,8 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     'validate_extension_code',
     [
       'Validate Enfyra admin extension code before saving it to enfyra_extension.',
-      'Use this for Vue SFC page/widget/global extension code. It calls /enfyra_extension/preview and does not save anything.',
+      'Use this only when the user explicitly wants a validation-only check. For normal edits, use update_extension_code or ensure_*_extension so successful validation saves in the same tool call.',
+      'This calls /enfyra_extension/preview and does not save anything.',
       'Call get_extension_theme_contract first when generating or reviewing UI.',
     ].join(' '),
     {
@@ -1540,6 +1580,27 @@ export function registerPlatformOperationTools(server, ENFYRA_API_URL) {
     }),
   );
 
+  server.tool(
+    'update_extension_code',
+    [
+      'Business operation: update an existing Enfyra admin extension code by id or name.',
+      'It runs local extension guards and /enfyra_extension/preview first, then saves the code in the same call only when validation succeeds.',
+      'Use this instead of validate_extension_code followed by update_record when editing an existing page/widget/global extension.',
+      'Call get_extension_theme_contract first when generating or reviewing UI.',
+    ].join(' '),
+    {
+      id: z.union([z.string(), z.number()]).optional().describe('Existing extension id. Provide id or name.'),
+      name: z.string().optional().describe('Existing extension unique name. Provide id or name.'),
+      code: z.string().describe('Vue SFC extension code.'),
+      description: z.string().optional().describe('Optional replacement extension description. Omit to preserve.'),
+      isEnabled: z.boolean().optional().describe('Optional enabled state. Omit to preserve.'),
+      version: z.string().optional().describe('Optional extension version. Omit to preserve.'),
+      globalRulesAckKey: globalRulesAckParam(z),
+      extensionKnowledgeAckKey: extensionKnowledgeAckParam(z),
+    },
+    async (input) => jsonText(await updateExtensionCode(ENFYRA_API_URL, input)),
+  );
+
   server.tool(
     'get_extension_theme_contract',
     'Return the concise Enfyra admin extension UI/theme/security contract. Call before writing or reviewing extension UI.',

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: ['extension_workflow', 'ensure_menu', 'reorder_menus', 'ensure_page_extension', 'ensure_global_extension', 'ensure_widget_extension'],
+    writeTools: ['extension_workflow', 'ensure_menu', 'reorder_menus', 'update_extension_code', '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: '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.',
+        useInstead: 'update_extension_code for an existing extension id/name, or extension_workflow/ensure_*_extension for create/wire flows',
+        reason: 'Extension operation tools validate local guards plus /enfyra_extension/preview and save only after validation succeeds.',
       },
       {
         tool: 'query_table on destination domain lists',

package/src/mcp-server-entry.mjs

@@ -22,7 +22,7 @@ import { buildMcpServerInstructions, buildGraphqlUrls } from './lib/mcp-instruct
 import { getExamples, listExampleCategories } from './lib/mcp-examples.js';
 import { WORKFLOW_SURFACES, discoverWorkflowRoutes } from './lib/tool-routing.js';
 import { registerTableTools } from './lib/table-tools.js';
-import { registerPlatformOperationTools } from './lib/platform-operation-tools.js';
+import { registerPlatformOperationTools, validateExtensionCode } from './lib/platform-operation-tools.js';
 import { parseRecordData, prepareRecordMutation, validateScriptSourceIfPresent } from './lib/mutation-guards.js';
 import {
   assertDynamicCodeKnowledgeAck,
@@ -623,6 +623,11 @@ function assertKnowledgeForGenericMutation(tableName, data, { knowledgeAckKey, e
   assertExtensionKnowledgeAckIf(tableName === 'enfyra_extension' && typeof payload.code === 'string', extensionKnowledgeAckKey);
 }
 
+async function validateExtensionCodeForGenericMutation(tableName, payload, fallbackName) {
+  if (tableName !== 'enfyra_extension' || typeof payload?.code !== 'string') return null;
+  return validateExtensionCode(ENFYRA_API_URL, payload.code, payload.name || fallbackName);
+}
+
 function parseQueryParamsArg(queryParams) {
   const parsed = parseJsonArg(queryParams, {});
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
@@ -1501,7 +1506,7 @@ server.tool(
 // CRUD TOOLS
 // ============================================================================
 
-server.tool('create_record', 'Create a new record in any route-backed table. The tool validates body keys against live metadata and validates sourceCode before saving script-backed records.', {
+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.', {
   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.'),
@@ -1513,15 +1518,17 @@ server.tool('create_record', 'Create a new record in any route-backed table. The
   validateTableName(tableName);
   assertKnowledgeForGenericMutation(tableName, data, { knowledgeAckKey, extensionKnowledgeAckKey });
   const prepared = await prepareGenericMutation(tableName, data);
+  const extensionValidation = await validateExtensionCodeForGenericMutation(tableName, prepared.payload, prepared.payload?.name);
   const query = parseQueryParamsArg(queryParams);
   const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}`, query), { method: 'POST', body: JSON.stringify(prepared.payload) });
   return { content: [{ type: 'text', text: JSON.stringify({
     ...summarizeMutationResult(result, 'created', tableName),
     scriptValidation: prepared.scriptValidation,
+    extensionValidation,
   }, null, 2) }] };
 });
 
-server.tool('update_record', 'Update an existing record by ID using PATCH. The tool validates body keys against live metadata and validates sourceCode before saving script-backed records.', {
+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.', {
   tableName: z.string().describe('Table name'),
   id: z.string().describe('Record ID to update'),
   data: z.string().describe('Fields to update as JSON string'),
@@ -1534,11 +1541,13 @@ server.tool('update_record', 'Update an existing record by ID using PATCH. The t
   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) });
   return { content: [{ type: 'text', text: JSON.stringify({
     ...summarizeMutationResult(result, 'updated', tableName),
     scriptValidation: prepared.scriptValidation,
+    extensionValidation,
   }, null, 2) }] };
 });