@enfyra/mcp-server 0.0.50 → 0.0.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-examples.js

@@ -184,6 +184,32 @@ window.location.href = url.toString()`,
           'For chat-list UX, default to a boolean unread dot instead of exact counts.',
         ],
       },
+      {
+        name: 'Add server-owned user verification fields',
+        code: `create_column({
+  tableId: "<user_definition_table_id>",
+  name: "emailVerifiedAt",
+  type: "datetime",
+  isNullable: true,
+  isPublished: true,
+  description: "When the user's email address was verified."
+})
+
+create_column({
+  tableId: "<user_definition_table_id>",
+  name: "emailVerificationStatus",
+  type: "varchar",
+  isNullable: false,
+  defaultValue: "pending",
+  isPublished: true,
+  description: "Email verification state controlled by server hooks."
+})`,
+        notes: [
+          'Run schema-changing calls sequentially. Do not parallelize create_column calls.',
+          'create_column fetches table_definition and patches only real persisted columns with id/_id; generated metadata projections such as createdAt, updatedAt, or relation FK display fields are skipped.',
+          'Use hooks or field permissions to prevent clients from updating server-owned fields.',
+        ],
+      },
     ],
   },
   'queries-deep': {
@@ -289,19 +315,49 @@ const scope = {
       },
       {
         name: 'Pre-hook encrypted field normalization',
-        code: `const value = @BODY.api_token_encrypted
+        code: `create_pre_hook({
+  routeId: "<route_id>",
+  name: "encrypt_api_token",
+  methods: ["POST", "PATCH"],
+  priority: 0,
+  code: \`const value = @BODY.api_token_encrypted
 if (value && value.slice(0, 7) !== "enc:v1:") {
   @BODY.api_token_encrypted = @HELPERS.$encrypt.encrypt(value)
-}`,
+}\`
+})`,
         notes: [
+          'MCP create_pre_hook accepts code as the tool argument, then persists it to Enfyra as sourceCode with scriptLanguage.',
+          'Do not call raw create_record with a code field for pre_hook_definition or post_hook_definition; backend CRUD rejects code.',
           'Use Enfyra pre-hooks for request-body normalization before canonical CRUD persists the record.',
           'Do not implement encrypted field normalization as a Knex/database hook.',
           'Use $encrypt for encryption and $ssh.generateKeyPair for SSH key generation; do not use $secrets.',
         ],
       },
+      {
+        name: 'Pre-hook strips protected body fields silently',
+        code: `create_pre_hook({
+  routeId: "<user_definition_patch_route_id>",
+  name: "strip_email_verification_fields",
+  methods: ["PATCH"],
+  priority: -10,
+  code: \`delete @BODY.emailVerifiedAt
+delete @BODY.emailVerificationStatus
+delete @BODY.emailVerificationSentAt\`
+})`,
+        notes: [
+          'Use this pattern when clients may send protected user fields through /me or user_definition PATCH.',
+          'Strip fields instead of throwing when the product wants a permissive client contract with server-owned fields.',
+          'Use native macros such as @BODY instead of raw $ctx when a macro exists.',
+        ],
+      },
       {
         name: 'Post-hook response shaping',
-        code: `if (@ERROR) {
+        code: `create_post_hook({
+  routeId: "<route_id>",
+  name: "shape_display_title",
+  methods: ["GET"],
+  priority: 0,
+  code: \`if (@ERROR) {
   @LOGS("Request failed", @ERROR.message)
   return
 }
@@ -311,8 +367,10 @@ if (row) {
   row.displayTitle = row.title || row.email || String(row.id)
 }
 
-return @DATA`,
+return @DATA\`
+})`,
         notes: [
+          'MCP create_post_hook accepts code as the tool argument, then persists sourceCode/scriptLanguage to Enfyra.',
           'Post-hooks run after success and error paths.',
           'Return non-undefined only when replacing the response body.',
         ],
@@ -650,6 +708,58 @@ create_extension({
           'After saving, open eApp tabs should update through the server/eApp realtime reload contract; do not tell the user to refresh unless that contract is proven broken.',
         ],
       },
+      {
+        name: 'Page header and action button variants',
+        code: `<script setup>
+const { registerPageHeader } = usePageHeaderRegistry()
+
+registerPageHeader({
+  title: 'Host detail',
+  description: 'Provider state, capacity, projects, and reconciliation status.',
+  leadingIcon: 'lucide:server',
+  gradient: 'cyan',
+  variant: 'minimal'
+})
+
+useHeaderActionRegistry([
+  {
+    id: 'back-to-hosts',
+    label: 'Hosts',
+    icon: 'lucide:arrow-left',
+    color: 'neutral',
+    variant: 'ghost',
+    order: 0,
+    onClick: () => navigateTo('/cloud/hosts')
+  },
+  {
+    id: 'run-host-check',
+    label: 'Run check',
+    icon: 'lucide:scan-search',
+    color: 'neutral',
+    variant: 'outline',
+    order: 1,
+    permission: { or: [{ route: '/cloud/admin/hosts/reconcile', methods: ['POST'] }] },
+    onClick: runCheck
+  },
+  {
+    id: 'refresh-host',
+    label: 'Refresh',
+    icon: 'lucide:refresh-cw',
+    color: 'primary',
+    variant: 'solid',
+    order: 2,
+    onClick: refresh
+  }
+])
+</script>`,
+        notes: [
+          'Use PageHeader for the title strip; do not render a duplicate header inside extension body.',
+          'Back/navigation actions should be neutral ghost so they read as navigation, not a primary operation.',
+          'Visible secondary operations should be neutral outline; soft is only for low-emphasis chrome actions.',
+          'The main page action should be primary solid.',
+          'Do not choose soft only because it looks acceptable in dark mode; light mode must remain clear too.',
+        ],
+      },
       {
         name: 'Debug menu or extension changes that do not appear in open eApp tabs',
         code: `// Server side: menu_definition and extension_definition are runtime UI definitions.

package/src/lib/mcp-instructions.js

@@ -134,6 +134,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- For encrypted persisted fields such as `*_encrypted`, use an Enfyra route pre-hook, not a Knex/database hook. Mutate the body before persistence: `const value = @BODY.field_encrypted; if (value && value.slice(0, 7) !== "enc:v1:") @BODY.field_encrypted = @HELPERS.$encrypt.encrypt(value);`.',
     '- ASV exposes `$helpers.$encrypt.encrypt/decrypt` for encrypted strings and `$helpers.$ssh.generateKeyPair` for SSH keys. Do not generate `$helpers.$secrets` usage.',
     '- Script-backed records use one shared persistence contract: `sourceCode` is the editable source, `scriptLanguage` controls compilation, and `compiledCode` is generated by the server from `sourceCode`. Do not hand-edit or send stale `compiledCode` from generated tools; save `sourceCode`/`scriptLanguage` through `PATCH /<script_table>/<id>` and let the server persist generated `compiledCode` internally. Public metadata may mark `compiledCode` non-updatable, but the server engine must still preserve the generated value after normalization.',
+    '- MCP `create_pre_hook` and `create_post_hook` accept a user-facing `code` argument but persist it as `sourceCode` with `scriptLanguage`. Do not call raw `create_record` with a `code` field for hook tables; backend request validation rejects `code` on REST CRUD.',
     '- Enfyra Cloud host provisioning with PgBouncer must preserve tenant database isolation. PgBouncer should use per-tenant `DATABASE_URLS` entries with each tenant `db_user`, `db_password`, and `db_name`, and PostgreSQL 16/SCRAM hosts need `AUTH_TYPE=plain`. Do not route all tenants through PostgreSQL `postgres` just to make PgBouncer connect; that bypasses tenant DB permissions.',
     '- Enfyra Cloud Docker health checks must compare exact healthy states. `true healthy` passes, `true starting` keeps waiting, and `true unhealthy` fails. Do not use broad substring logic where `unhealthy` accidentally counts as healthy.',
     '- Before saving generated script code, validate it with `POST /admin/script/validate` when available. It compiles with the server kernel and parses the executable async body without running side effects. Enfyra App `FormCodeEditor` also exposes a `Validate` action for this endpoint; use it before save/run when editing through the UI. If unavailable, use `run_admin_test`/`test_flow_step` as the closest validation path before saving.',
@@ -194,7 +195,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- To check which tables are accessible via MCP tools, call `get_all_routes` and look for the route whose `mainTable.id` matches the table you need, or `get_all_metadata` to see all table names.',
     '- **Tables confirmed to have REST routes (system):** `bootstrap_script_definition`, `column_rule_definition`, `cors_origin_definition`, `extension_definition`, `field_permission_definition`, `file_definition`, `file_permission_definition`, `flow_definition`, `flow_execution_definition`, `flow_step_definition`, `folder_definition`, `gql_definition`, `guard_definition`, `guard_rule_definition`, `menu_definition`, `method_definition`, `oauth_account_definition`, `oauth_config_definition`, `package_definition`, `post_hook_definition`, `pre_hook_definition`, `relation_definition`, `role_definition`, `route_definition`, `route_handler_definition`, `route_permission_definition`, `schema_migration_definition`, `setting_definition`, `storage_config_definition`, `table_definition`, `user_definition`, `websocket_definition`, `websocket_event_definition`.',
     '- **Tables without REST routes (internal/system only):** `column_definition`, `session_definition`. Columns are managed indirectly via cascade on `table_definition` (POST/PATCH with columns arrays). The `create_table`, `create_column`/`add_column`, `update_column`, and `delete_column`/`remove_column` MCP tools handle this automatically.',
-    '- Use `create_column`/`add_column` for new scalar fields. These tools accept column metadata such as `isNullable`, `isUnique`, `isPublished`, `isPrimary`, `isGenerated`, `isSystem`, `defaultValue`, `description`, and `options`; set `isPublished=false` directly when creating secret/internal fields such as `*_encrypted`.',
+    '- Use `create_column`/`add_column` for new scalar fields. These tools accept column metadata such as `isNullable`, `isUnique`, `isPublished`, `isPrimary`, `isGenerated`, `isSystem`, `defaultValue`, `description`, and `options`; set `isPublished=false` directly when creating secret/internal fields such as `*_encrypted`. When patching an existing table, only persisted columns with an `id`/`_id` belong in the cascade payload; metadata projections such as `createdAt`, `updatedAt`, or relation-derived FK display fields without an id are not valid column-definition patch rows.',
     '- Prefer `create_relation`/`add_relation` and `delete_relation`/`remove_relation` for relation schema changes because they preserve the full table relation list and handle schema-confirm retry. Direct `create_record` on `relation_definition` only edits metadata and is not the canonical schema migration path.',
     '',
     '### Body validation & column rules',
@@ -294,6 +295,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **PageHeader is mandatory for page extensions:** eApp already renders `CommonPageHeader` from `usePageHeaderRegistry()` in the app shell. Page extensions must call `const { registerPageHeader } = usePageHeaderRegistry()` and register app-level context such as `{ title, description, leadingIcon, gradient, variant }` instead of rendering their own top `<header>` inside extension content. Use `variant: "minimal"` for operational/admin detail pages unless the page intentionally needs a larger title strip.',
     '- **Do not misuse PageHeader stats:** `PageHeader.stats` renders prominent stat cards inside the shell header. Do not put normal operational KPIs, host capacity, billing totals, or detail metrics there by default; keep those as body cards/tables where the operator can scan them with the page content. Only use PageHeader stats for a deliberately compact overview page where the stats are truly header-level context.',
     '- **Page actions belong in registries:** Move page-level buttons into `useHeaderActionRegistry` or `useSubHeaderActionRegistry`; keep the extension body for operational content only. Sensitive registry actions must include a `permission` condition, for example `{ id: "create", label: "Create project", permission: { and: [{ route: "/cloud_projects", methods: ["POST"] }] }, onClick }`.',
+    '- **Header action button variants:** choose the button variant by intent. Use `color: "primary", variant: "solid"` for the main page action. Use `color: "neutral", variant: "ghost"` for back/navigation actions and `color: "neutral", variant: "outline"` for visible secondary actions. `variant: "soft"` is only for low-emphasis secondary/chrome actions; do not use soft for critical or primary header actions just because it looks acceptable in dark mode.',
     '- **Extension navigation:** prefer `NuxtLink` or Nuxt UI components with `:to` for visible navigation links and drill-down cards/buttons. Use `navigateTo(...)` only for imperative navigation after submit, confirm, mutation, or another side effect.',
     '- **Extension runtime scope:** eApp exposes Vue APIs and injected Nuxt/Enfyra composables both to script global scope and Vue app `globalProperties`. Template expressions may call injected helpers directly, for example after a save handler can call `navigateTo("/data/cloud_projects")`, because Vue compiles template helpers to `_ctx.*`.',
     '- **Extension CSS affects shell utility ordering:** dynamic extension CSS is injected after the app shell CSS. Shell/page-header code must not put conflicting plain Tailwind utilities on the same element, such as `flex-col` plus `flex-row`, `items-start` plus `items-center`, or `text-left` plus `text-center`. Choose one mutually exclusive class per state; otherwise extension CSS can change which utility wins and shift shell layout.',
@@ -301,7 +303,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Admin menu visibility is permission-driven, not RLS:** Cloud/admin menu entries are sensitive and must set `menu_definition.permission` so they are visible only to users who have at least GET permission for the backing route or table. Permission conditions use HTTP `methods`, not CRUD `actions`. Do not show a Cloud menu merely because an extension exists or because the path is hardcoded. Example: `/cloud/hosts` menu should require `{ or: [{ route: "/cloud/admin/hosts", methods: ["GET"] }, { route: "/cloud_servers", methods: ["GET"] }] }`.',
     '- **PermissionGate is mandatory inside admin extensions:** every sensitive action button, form, mutation, destructive workflow, and data shortcut must be wrapped in `PermissionGate` or guarded with `usePermissions()` before rendering/enabling. Default gates: list/detail visibility needs `methods: ["GET"]`; create and custom flow-trigger routes usually need `methods: ["POST"]`; native record edits need `methods: ["PATCH"]`; native delete routes need `methods: ["DELETE"]`. Root admin still passes through normal permission helpers, but extension code must not rely on root-only assumptions.',
     '- **Extension permission UX:** if the current user can read a page but cannot perform an action, hide the action by default. If hiding would confuse the workflow, render a disabled state with a short reason. Never let the button render active and depend only on the server rejection; server permissions are the final boundary, not the UI contract.',
-    '- **Cloud project admin operations:** use canonical `cloud_projects` table routes as the single source of truth. Admin manual create uses `POST /cloud_projects` with schema-safe fields `owner: { id }`, `plan: { id }`, `admin_email`, `admin_password`, `name`, `subdomain`, and `status: "creating"`. The UI must show tenant admin credential as an email/password pair and include a generate-password action before create; do not build an email-only credential form. Project detail is the place for destructive lifecycle actions. Disable uses `PATCH /cloud_projects/:id` with body `{ status: "disabled" }` and `confirm_tenant_id`/`confirm_hash` in query params. Enable uses `PATCH /cloud_projects/:id` with body `{ status: "running" }`. Delete uses `DELETE /cloud_projects/:id` with typed `confirm_tenant_id`, returned `requiredConfirmHash`, and the matching hash before triggering `cloud-delete-project`. Do not create separate one-off `/cloud/admin/projects/*` action routes for create/disable/enable/delete when the canonical table route can own the workflow.',
+    '- **Cloud project admin operations:** use canonical `cloud_projects` table routes as the single source of truth. Admin manual create uses `POST /cloud_projects` with schema-safe fields `owner: { id }`, `plan: { id }`, `expiredAt`, and `status: "creating"`. The UI searches/selects `user_definition` by email and selects a plan by card; do not ask the operator to type raw user ids, plan ids, project names, subdomains, tenant admin emails, or passwords when the handler can derive them server-side. Project detail is the place for destructive lifecycle actions. Disable uses `PATCH /cloud_projects/:id` with body `{ status: "disabled" }` and `confirm_tenant_id`/`confirm_hash` in query params. Enable uses `PATCH /cloud_projects/:id` with body `{ status: "running" }`. Renew uses `PATCH /cloud_projects/:id` with a future `expiredAt`. Delete uses `DELETE /cloud_projects/:id` with typed `confirm_tenant_id`, returned `requiredConfirmHash`, and the matching hash before triggering `cloud-delete-project`. Do not create separate one-off `/cloud/admin/projects/*` action routes for create/disable/enable/delete when the canonical table route can own the workflow.',
     '- **Cloud admin terminology:** in Cloud admin UI, call physical tenant workloads "projects" everywhere. Do not label creation or details as "instance" unless the user explicitly asks for that word.',
     '- **Cloud project create UI:** manual Cloud project creation should use `CommonDrawer`, not a wide modal. Let the operator search/select `user_definition` by email and select a plan with cards; do not expose duplicate free-text `user id` or `plan id` inputs when selectors exist. Prefer sending only the selected owner id, plan id, and required workflow fields such as `expiredAt` when the canonical handler can derive customer email, project name, subdomain, and password. Expiry selection should use quick presets plus a manual calendar (`UCalendar` when available, loaded through `install_package`/`getPackages` if an app package is needed).',
     '- **Cloud host settings and creation UI:** host settings store only provider selection codes Enfyra controls, currently location and server type. Do not expose or save provider-derived RAM, disk, vCPU, or cost values by hand. Query the provider catalog route, show real package/location cards, support load-more/search when the list is long, and snapshot provider facts onto `cloud_servers` only during host creation.',
@@ -380,7 +382,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '#### Important patterns:',
     '- **useApi:** Must call `execute()` — does NOT auto-run. Supports batch operations with `ids` or `files` options.',
-    '- **Header actions:** `useHeaderActionRegistry([{ id: \'refresh\', label: \'Refresh\', onClick: fn, color: \'primary\', icon: \'lucide:refresh\', order: 0 }])`',
+    '- **Header actions:** `useHeaderActionRegistry([{ id: \'back\', label: \'Hosts\', icon: \'lucide:arrow-left\', color: \'neutral\', variant: \'ghost\', order: 0, onClick: goBack }, { id: \'refresh\', label: \'Refresh\', icon: \'lucide:refresh-cw\', color: \'primary\', variant: \'solid\', order: 1, onClick: refresh }])`',
     '- **Schema:** Call `fetchSchema()` first, then use `definition.value`, `editableFields.value`, `getField(\'fieldName\')`.',
     '- **Permissions:** Use `checkPermissionCondition({ or: [{ route: \'/posts\', methods: [\'GET\'] }] })` for complex rules. In templates, wrap sensitive controls with `<PermissionGate :condition="{ and: [{ route: \'/admin/action\', methods: [\'POST\'] }] }">...</PermissionGate>` instead of only disabling them visually.',
     '- **After menu/extension create/update:** open eApp tabs should update through the `$system:reload` contract. Do not tell the user to press F5 unless you have verified the natural reload event failed or the server/eApp version does not support menu/extension reload yet.',

package/src/lib/table-tools.js

@@ -84,11 +84,21 @@ function normalizeRelationForTablePatch(relation) {
   return normalized;
 }
 
+function getId(record) {
+  return record?.id ?? record?._id ?? null;
+}
+
 function normalizeColumnForTablePatch(column) {
   const { table, ...rest } = column;
   return rest;
 }
 
+function getPatchableColumns(columns) {
+  return (columns || [])
+    .filter((column) => getId(column) !== null)
+    .map(normalizeColumnForTablePatch);
+}
+
 function buildColumnDefinition({
   name,
   type,
@@ -127,7 +137,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       return { content: [{ type: 'text', text: `Error: Table with ID ${args.tableId} not found.` }] };
     }
 
-    const existingColumns = (tableData.columns || []).map(normalizeColumnForTablePatch);
+    const existingColumns = getPatchableColumns(tableData.columns);
     const newCol = buildColumnDefinition(args);
     const result = await patchTableAutoConfirm(ENFYRA_API_URL, args.tableId, { columns: [...existingColumns, newCol] });
 
@@ -161,7 +171,8 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     }
 
     const columns = (tableData.columns || [])
-      .filter(col => String(col.id) !== String(columnId))
+      .filter((col) => getId(col) !== null)
+      .filter(col => String(getId(col)) !== String(columnId))
       .map(normalizeColumnForTablePatch);
 
     const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, { columns });
@@ -372,7 +383,8 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     [
       'Add a column to an existing table via PATCH /table_definition/{tableId}.',
       'Columns are managed through cascade with table_definition — there is NO direct /column_definition endpoint.',
-      'This tool fetches existing columns, appends the new one, and PATCHes the table.',
+      'This tool fetches existing columns, keeps only persisted column rows with id/_id, appends the new one, and PATCHes the table.',
+      'Generated metadata projections such as createdAt, updatedAt, or relation-derived FK display fields without id are not valid cascade rows and are skipped.',
       'Run schema changes sequentially — migration locks DB per operation.',
     ].join(' '),
     {
@@ -386,6 +398,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     [
       'Alias for create_column. Add a column to an existing table through the canonical table_definition cascade.',
       'Use this for schema additions, including hidden secret fields with isPublished=false.',
+      'Skips non-persisted generated/derived column metadata without id/_id when rebuilding the table columns payload.',
       'Run schema changes sequentially — migration locks DB per operation.',
     ].join(' '),
     columnCreateSchema,
@@ -398,7 +411,8 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     'update_column',
     [
       'Update an existing column on a table via PATCH /table_definition/{tableId}.',
-      'Fetches all columns, modifies the target column, and PATCHes the table.',
+      'Fetches table columns, keeps only persisted rows with id/_id, modifies the target column, and PATCHes the table.',
+      'Generated metadata projections such as createdAt, updatedAt, or relation-derived FK display fields without id are skipped.',
       'Run schema changes sequentially — migration locks DB per operation.',
     ].join(' '),
     {
@@ -418,9 +432,9 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
       }
 
-      const columns = (tableData.columns || []).map(col => {
+      const columns = (tableData.columns || []).filter((col) => getId(col) !== null).map(col => {
         const rest = normalizeColumnForTablePatch(col);
-        if (String(col.id) === String(columnId)) {
+        if (String(getId(col)) === String(columnId)) {
           if (name !== undefined) rest.name = name;
           if (type !== undefined) rest.type = type;
           if (isNullable !== undefined) rest.isNullable = isNullable;
@@ -446,7 +460,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     'delete_column',
     [
       'Delete a column from a table via PATCH /table_definition/{tableId}.',
-      'Fetches all columns, removes the target, and PATCHes the table.',
+      'Fetches table columns, keeps only persisted rows with id/_id, removes the target, and PATCHes the table.',
       'The physical column is dropped from the database. System columns (id, createdAt, updatedAt) cannot be deleted.',
       'Run schema changes sequentially — migration locks DB per operation.',
     ].join(' '),
@@ -461,6 +475,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     [
       'Alias for delete_column. Remove a column through the canonical table_definition cascade.',
       'This drops the physical column. Confirm destructive schema changes before calling.',
+      'Skips non-persisted generated/derived column metadata without id/_id when rebuilding the table columns payload.',
       'Run schema changes sequentially — migration locks DB per operation.',
     ].join(' '),
     columnDeleteSchema,

package/src/mcp-server-entry.mjs

@@ -1283,7 +1283,8 @@ server.tool(
 
     await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
 
-    return { content: [{ type: 'text', text: `Route created (ID: ${result.id}). Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
+    const created = firstDataRecord(result);
+    return { content: [{ type: 'text', text: `Route created (ID: ${getId(created)}). Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
   },
 );
 
@@ -1338,7 +1339,7 @@ server.tool(
   {
     routeId: z.union([z.string(), z.number()]).describe('Route definition ID'),
     name: z.string().describe('Hook name (unique per route)'),
-    code: z.string().describe('Hook JavaScript code'),
+    code: z.string().describe('Hook JavaScript sourceCode. MCP stores it as sourceCode and lets Enfyra compile compiledCode.'),
     methods: z.array(z.enum(['GET', 'POST', 'PATCH', 'DELETE'])).optional()
       .describe('Methods this hook applies to. Default: all REST methods.'),
     priority: z.number().optional().default(0).describe('Execution order (lower = first)'),
@@ -1353,7 +1354,8 @@ server.tool(
       body: JSON.stringify({
         route: { id: routeId },
         name,
-        code,
+        sourceCode: code,
+        scriptLanguage: 'javascript',
         methods: resolveMethodIds(methodMap, methodNames),
         priority,
         isEnabled,
@@ -1362,7 +1364,8 @@ server.tool(
 
     await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
 
-    return { content: [{ type: 'text', text: `Pre-hook "${name}" created (ID: ${result.id}). Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
+    const created = firstDataRecord(result);
+    return { content: [{ type: 'text', text: `Pre-hook "${name}" created (ID: ${getId(created)}). Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
   },
 );
 
@@ -1377,7 +1380,7 @@ server.tool(
   {
     routeId: z.union([z.string(), z.number()]).describe('Route definition ID'),
     name: z.string().describe('Hook name (unique per route)'),
-    code: z.string().describe('Hook JavaScript code'),
+    code: z.string().describe('Hook JavaScript sourceCode. MCP stores it as sourceCode and lets Enfyra compile compiledCode.'),
     methods: z.array(z.enum(['GET', 'POST', 'PATCH', 'DELETE'])).optional()
       .describe('Methods this hook applies to. Default: all REST methods.'),
     priority: z.number().optional().default(0).describe('Execution order (lower = first)'),
@@ -1392,7 +1395,8 @@ server.tool(
       body: JSON.stringify({
         route: { id: routeId },
         name,
-        code,
+        sourceCode: code,
+        scriptLanguage: 'javascript',
         methods: resolveMethodIds(methodMap, methodNames),
         priority,
         isEnabled,
@@ -1401,7 +1405,8 @@ server.tool(
 
     await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
 
-    return { content: [{ type: 'text', text: `Post-hook "${name}" created (ID: ${result.id}). Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
+    const created = firstDataRecord(result);
+    return { content: [{ type: 'text', text: `Post-hook "${name}" created (ID: ${getId(created)}). Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
   },
 );
 
@@ -1691,7 +1696,7 @@ server.tool('get_all_roles', 'Get all role definitions', {}, async () => {
 });
 
 server.tool('login', 'Force authentication to Enfyra and get a new access token', {
-  apiToken: z.string().optional().describe('API token; preferred for MCP and automation'),
+  apiToken: z.string().optional().describe('API token for MCP and automation'),
 }, async ({ apiToken }) => {
   const token = apiToken || ENFYRA_API_TOKEN;
   if (token) {
@@ -1825,7 +1830,8 @@ server.tool('create_menu', 'Create a menu item in the navigation', {
     body.path = '/' + body.path;
   }
   const result = await fetchAPI(ENFYRA_API_URL, '/menu_definition', { method: 'POST', body: JSON.stringify(body) });
-  return { content: [{ type: 'text', text: `Menu created (ID: ${result.id}):\n${JSON.stringify(result, null, 2)}` }] };
+  const created = firstDataRecord(result);
+  return { content: [{ type: 'text', text: `Menu created (ID: ${getId(created)}):\n${JSON.stringify(result, null, 2)}` }] };
 });
 
 server.tool(
@@ -1850,7 +1856,8 @@ server.tool(
       delete body.menuId;
     }
     const result = await fetchAPI(ENFYRA_API_URL, '/extension_definition', { method: 'POST', body: JSON.stringify(body) });
-    return { content: [{ type: 'text', text: `Extension created (ID: ${result.id}). Open eApp tabs should update through the realtime reload contract.\n${JSON.stringify(result, null, 2)}` }] };
+    const created = firstDataRecord(result);
+    return { content: [{ type: 'text', text: `Extension created (ID: ${getId(created)}). Open eApp tabs should update through the realtime reload contract.\n${JSON.stringify(result, null, 2)}` }] };
   },
 );