@enfyra/mcp-server 0.1.11 → 0.1.13

package/README.md

@@ -258,7 +258,7 @@ The MCP server includes safety guards for LLM callers:
 - Write tools require `get_enfyra_required_knowledge` acknowledgement before mutating Enfyra state. Discovery, validation, and preview tools remain available without the acknowledgement so agents can read and plan first. If the acknowledgement is missing, the tool error tells the caller to read `get_enfyra_required_knowledge` and pass the required key.
 - Script-backed records validate `sourceCode` through `/admin/script/validate` before saving.
 - `validate_dynamic_script` checks handler, hook, flow, websocket, GraphQL, and bootstrap script source without saving.
-- `validate_extension_code` checks Enfyra admin extension code through `/enfyra_extension/preview` without saving.
+- `validate_extension_code` locally rejects common extension component-resolution mistakes, such as `resolveComponent()` or lowercase auto-injected component tags like `<ubutton>`, then checks Enfyra admin extension code through `/enfyra_extension/preview` without saving.
 - Dynamic script guidance distinguishes secure repositories (`@REPOS.main`, `@REPOS.secure.<table>`) from trusted internal repositories (`@REPOS.<table>`), and tells agents not to return raw trusted records to users.
 - `compiledCode` is generated from `sourceCode` and may differ textually because macros are expanded; the MCP server never accepts hand-written `compiledCode`.
 - Long source/code values in read responses are written to `/tmp/enfyra-mcp-sources` and returned as length/hash/preview/tmpFile metadata so LLM callers can inspect full source from the file path without truncating tool output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "packageManager": "yarn@4.17.0",

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,8 @@ 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

@@ -12,6 +12,36 @@ import {
   globalRulesAckParam,
 } from './required-knowledge.js';
 
+const AUTO_INJECTED_EXTENSION_COMPONENT_TAGS = [
+  'CommonDrawer',
+  'CommonModal',
+  'EmptyState',
+  'FormEditor',
+  'FormEditorLazy',
+  'NuxtLink',
+  'PermissionGate',
+  'UBadge',
+  'UButton',
+  'UCheckbox',
+  'UDropdownMenu',
+  'UForm',
+  'UFormField',
+  'UIcon',
+  'UInput',
+  'UModal',
+  'USelect',
+  'USelectMenu',
+  'USkeleton',
+  'USwitch',
+  'UTabs',
+  'UTextarea',
+  'UTooltip',
+  'Widget',
+];
+const AUTO_INJECTED_EXTENSION_COMPONENT_BY_LOWERCASE = new Map(
+  AUTO_INJECTED_EXTENSION_COMPONENT_TAGS.map((tag) => [tag.toLowerCase(), tag]),
+);
+
 function unwrapData(result) {
   return Array.isArray(result?.data) ? result.data : [];
 }
@@ -360,6 +390,7 @@ function getExtensionThemeContract() {
     ],
     components: [
       'Use Nuxt UI/eApp components for normal controls: UButton, UInput, UTextarea, USelectMenu/USelect, USwitch, UCheckbox, UTabs, UBadge, UModal, and CommonDrawer when available.',
+      'Use auto-injected components directly in the template with PascalCase names. Do not call resolveComponent() to manually resolve Nuxt UI/eApp components inside extension SFCs; it can compile but render unresolved lowercase DOM tags such as <ubutton>.',
       'Buttons should have stable geometry: hover may change color, border, or shadow but must not move the button or resize its content. Disabled buttons keep disabled cursor/visual state.',
       'Inputs and textareas should not add hover movement or decorative hover states; focus, invalid, disabled, and loading states must be explicit.',
       'Dynamic extensions resolve UModal to the app CommonModal. Do not pass ui.content: "eapp-surface-card" or "surface-card" to UModal/CommonModal; modal content uses the app modal surface and caller ui.content should only append z-index, width, or max-width classes.',
@@ -541,7 +572,66 @@ async function validateDynamicScript(apiUrl, sourceCode, scriptLanguage = 'javas
   };
 }
 
-async function validateExtensionCode(apiUrl, code, name) {
+function readTemplateBlocks(code) {
+  const blocks = [];
+  const lower = String(code || '').toLowerCase();
+  let index = 0;
+  while (index < lower.length) {
+    const openStart = lower.indexOf('<template', index);
+    if (openStart === -1) break;
+    const boundary = lower[openStart + '<template'.length];
+    if (boundary && !/\s|>/.test(boundary)) {
+      index = openStart + 1;
+      continue;
+    }
+    const openEnd = lower.indexOf('>', openStart + '<template'.length);
+    if (openEnd === -1) break;
+    const closeStart = lower.indexOf('</template', openEnd + 1);
+    if (closeStart === -1) break;
+    blocks.push(String(code).slice(openEnd + 1, closeStart));
+    index = closeStart + '</template'.length;
+  }
+  return blocks;
+}
+
+function readTemplateTagName(template, start) {
+  const next = template[start + 1];
+  if (!next || next === '!' || next === '?') return null;
+  let index = start + (next === '/' ? 2 : 1);
+  while (/\s/.test(template[index] || '')) index += 1;
+  const nameStart = index;
+  while (/[\w.-]/.test(template[index] || '')) index += 1;
+  return index > nameStart ? template.slice(nameStart, index) : null;
+}
+
+export function validateExtensionCodeLocally(code) {
+  if (/\bresolveComponent\s*\(/.test(String(code || ''))) {
+    throw new Error('Invalid extension component resolution: do not call resolveComponent() in Enfyra extensions. Use auto-injected components such as <UButton> directly in the template so the app/compiler resolves them correctly.');
+  }
+
+  const violations = [];
+  for (const template of readTemplateBlocks(code)) {
+    let index = 0;
+    while (index < template.length) {
+      const tagStart = template.indexOf('<', index);
+      if (tagStart === -1) break;
+      const tagName = readTemplateTagName(template, tagStart);
+      if (tagName && tagName === tagName.toLowerCase() && !tagName.includes('-')) {
+        const expected = AUTO_INJECTED_EXTENSION_COMPONENT_BY_LOWERCASE.get(tagName);
+        if (expected) violations.push({ tag: tagName, expected });
+      }
+      index = tagStart + 1;
+    }
+  }
+  if (violations.length) {
+    const first = violations[0];
+    throw new Error(`Invalid extension component casing: use <${first.expected}> instead of <${first.tag}>. Enfyra/Nuxt UI auto-injected components must keep PascalCase in extension templates; lowercase tags render as unresolved DOM elements.`);
+  }
+  return { componentCasing: 'passed' };
+}
+
+export async function validateExtensionCode(apiUrl, code, name) {
+  const localChecks = validateExtensionCodeLocally(code);
   const result = await fetchAPI(apiUrl, '/enfyra_extension/preview', {
     method: 'POST',
     body: JSON.stringify({ code, name }),
@@ -551,11 +641,51 @@ async function validateExtensionCode(apiUrl, code, name) {
   }
   return {
     valid: true,
+    localChecks,
     extensionId: result?.extensionId || name || null,
     compiledLength: typeof result?.compiledCode === 'string' ? result.compiledCode.length : undefined,
   };
 }
 
+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 || {});
@@ -1436,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(' '),
     {
@@ -1449,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/required-knowledge.js

@@ -175,6 +175,7 @@ export function buildRequiredKnowledgePayload() {
         id: 'extension-runtime-contract',
         rules: [
           'Save extensions as enfyra_extension Vue SFC records; no static import statements in extension code.',
+          'Do not call resolveComponent() in extension SFCs. Use auto-injected components such as <UButton>, <UBadge>, <PermissionGate>, and <Widget> directly in the template so the app/compiler resolves them correctly.',
           'Load app packages with getPackages(["package-name"]) inside extension runtime code.',
           'Prefer FormEditor/FormEditorLazy for direct table-backed forms when the form maps to metadata fields.',
           'For long admin setup workflows, open CommonDrawer immediately and show loading/error/content inside it.',

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) }] };
 });