@enfyra/mcp-server 0.0.51 → 0.0.53

package/package.json

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

package/src/lib/mcp-examples.js

@@ -184,12 +184,52 @@ 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': {
     title: 'REST queries, filters, meta counts, and deep relation fetches',
     useWhen: 'Use when fetching records, filtering by relations, loading nested data, or counting efficiently.',
     examples: [
+      {
+        name: 'Minimal MCP query then explicit detail query',
+        code: `query_table({
+  tableName: "user_definition",
+  fields: ["id", "email"],
+  filter: "{\\"email\\":{\\"_contains\\":\\"@example.com\\"}}",
+  limit: 10
+})`,
+        notes: [
+          'Always pass fields when you need more than ids; query_table without fields intentionally returns only the primary key.',
+          'Use inspect_table first when you do not know valid column names or relation propertyName values.',
+          'Use count_records when only the count is needed.',
+        ],
+      },
       {
         name: 'List current user conversations through RLS',
         code: `GET /enfyra/chat_conversation?fields=id,kind,title,lastMessage.id,lastMessage.text,lastMessage.createdAt&limit=0`,
@@ -243,6 +283,23 @@ window.location.href = url.toString()`,
     title: 'Custom handlers, pre-hooks, post-hooks, and script macros',
     useWhen: 'Use when writing Enfyra dynamic JavaScript for REST behavior.',
     examples: [
+      {
+        name: 'Create a route handler with current script fields',
+        code: `create_handler({
+  routeId: "<route_id>",
+  method: "POST",
+  scriptLanguage: "javascript",
+  sourceCode: \`const email = @BODY.email
+if (!email) @THROW400("Email is required")
+
+return { ok: true, email }\`
+})`,
+        notes: [
+          'Use sourceCode, not logic. The server generates compiledCode.',
+          'Use method for one handler, or methods only when the same sourceCode should be saved for multiple methods.',
+          'Do not pass name to route_handler_definition; one handler is identified by route + method.',
+        ],
+      },
       {
         name: 'Custom register handler',
         code: `const email = @BODY.email
@@ -289,19 +346,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 +398,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 +739,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

@@ -36,6 +36,8 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- If generating concrete code, schema payloads, SSR app config, OAuth wiring, Socket.IO clients/events, flows, files, extensions, or permission/RLS examples, call **`get_enfyra_examples`** for the matching category before writing the final answer. Examples are grouped by category and are intentionally more concrete than these global rules.',
     '- Treat hardcoded instructions as operating rules, but use live discovery as the final check for this running instance. Do not infer missing capabilities from a narrow tool schema; check metadata/routes or the relevant specialized tool first.',
     '- If there is no dedicated MCP tool for a subsystem, use the route-backed metadata table with `query_table` / `create_record` / `update_record` / `delete_record`, after confirming that table has a route. If the table is no-route, use the canonical specialized tool or parent table workflow instead.',
+    '- MCP read tools are intentionally **minimal by default**. `query_table` without `fields` returns only the table primary key with a small hint. Always pass explicit `fields` when you need details, and use `inspect_table` / `inspect_route` before guessing field names.',
+    '- MCP mutation tools return only ids/status by default. If you need the saved row, immediately call `find_one_record` or `query_table` with explicit `fields`; do not expect create/update tools to echo full records.',
     '',
     '### Capability map (current Enfyra system)',
     '- **Schema/metadata:** `table_definition`, `relation_definition`, and schema tools manage tables, columns, relations, validation, and migrations. `column_definition` is internal/no-route; columns are created/updated through table schema operations.',
@@ -74,6 +76,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Wrong pattern:** calling **`create_table`** just to get an HTTP path, then overriding handlers on the **default** auto route `/{table_name}`. That adds unnecessary schema and breaks the usual CRUD surface for that table.',
     '- **`create_table`** is only when the user needs **new persisted data** (new entity + columns). It is **not** the right tool when the goal is only a new path or custom script.',
     '- **Right pattern:** **`create_route`** → optional **`create_handler`** / **`create_pre_hook`** / **`create_post_hook`** on **that route’s id** (from **`get_all_routes`** after create). Same underlying table can have **multiple** routes (e.g. default CRUD at `/orders` and custom `/orders/stats` both pointing at `mainTable` orders).',
+    '- **Handler contract:** `create_handler` takes `routeId`, `method` (or `methods` for batch), `sourceCode`, optional `scriptLanguage`, and optional `timeout`. Do **not** send `logic`, `name`, or `compiledCode`; backend CRUD rejects `logic` and `compiledCode` is generated by the server.',
     '',
     '### After a new table is created',
     '- MCP **`create_table` supports creating columns and relations in the same call**: pass `columns` and `relations` as JSON arrays. Use `create_relation` only when adding a relation to an existing table later.',
@@ -103,6 +106,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `- **No** **GET** \`${base}/<table_name>/<id>\`. For one row by id use **GET** \`${getOneById}\` or MCP \`query_table\` / \`find_one_record\`.`,
     '',
     '### Relation field format (create_record / update_record)',
+'- For generic MCP `create_record` and `update_record`, the `data` argument is a **JSON string**, not a JavaScript object. Example: `data: "{\\"name\\":\\"Starter\\"}"`. If the host gives a validation error saying `data` expected string, stringify the object before calling the tool.',
 '- Relation fields (mainTable, publishedMethods, availableMethods, handlers, preHooks, postHooks, etc.) use **object references with `id`**:',
 '  - **Many-to-one:** `"mainTable": {"id": 4}` (single object with id)',
 '  - **One-to-many / many-to-many:** `"publishedMethods": [{"id": 1}, {"id": 2}]` (array of objects with id)',
@@ -134,6 +138,8 @@ 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.',
+    '- For route handlers specifically, the field is also `sourceCode`. Older names such as `logic` are wrong for current Enfyra REST CRUD and will be rejected. Use MCP `create_handler` so it writes `sourceCode` and resolves method ids correctly.',
+    '- 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.',
@@ -191,10 +197,11 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '### System tables — which have REST routes',
     '- **Not all system tables have a REST route.** `query_table`, `find_one_record`, `create_record`, etc. all go through the dynamic REST API and will return **404** if the table has no registered route.',
     '- **`column_definition` and `session_definition` have NO route** — do NOT call `query_table("column_definition", …)` or `query_table("session_definition", …)`. They will 404.',
+    '- Do not invent singular/legacy system route names such as `hook_definition`, `oauth_provider_definition`, or physical FK tables. If a route name is not listed by `get_all_routes`, it is not a REST endpoint for generic CRUD. Use the concrete tables (`pre_hook_definition`, `post_hook_definition`, `oauth_config_definition`, etc.) or the dedicated MCP tool.',
     '- 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 +301,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.',
@@ -380,7 +388,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

@@ -199,6 +199,31 @@ function summarizeRoutes(routesResult) {
   }));
 }
 
+function summarizeMetadata(metadata, { search, limit } = {}) {
+  const tables = normalizeTables(metadata);
+  const q = search ? search.toLowerCase() : null;
+  const summarized = tables.map((table) => ({
+    id: table.id ?? table._id,
+    name: table.name,
+    alias: table.alias,
+    primaryKey: getPrimaryColumn(table)?.name || null,
+    columnCount: (table.columns || []).length,
+    relationCount: (table.relations || []).length,
+    routeHint: `Use get_table_metadata({ tableName: "${table.name}" }) for fields and relations.`,
+  }));
+  const matched = q
+    ? summarized.filter((table) => JSON.stringify(table).toLowerCase().includes(q))
+    : summarized;
+  const outputLimit = limit || 30;
+  return {
+    tableCount: tables.length,
+    matchedTableCount: matched.length,
+    returnedTableCount: Math.min(matched.length, outputLimit),
+    search: search || null,
+    tables: matched.slice(0, outputLimit),
+  };
+}
+
 function unwrapData(result) {
   return Array.isArray(result?.data) ? result.data : [];
 }
@@ -250,6 +275,29 @@ function pickCodeSummary(record, fieldName) {
   };
 }
 
+function summarizeMutationResult(result, action, tableName) {
+  const record = firstDataRecord(result);
+  return {
+    action,
+    tableName,
+    id: getId(record),
+    statusCode: result?.statusCode,
+    success: result?.success,
+    detailHint: `Use find_one_record or query_table with explicit fields to inspect ${tableName}.`,
+  };
+}
+
+async function getTableSummary(tableName) {
+  const result = await fetchAPI(ENFYRA_API_URL, `/metadata/${tableName}`);
+  const table = result?.data?.table || result?.data || result?.table || result;
+  return summarizeTable(table);
+}
+
+async function getPrimaryFieldName(tableName) {
+  const table = await getTableSummary(tableName);
+  return table?.primaryKey || 'id';
+}
+
 async function fetchAll(path) {
   return unwrapData(await fetchAPI(ENFYRA_API_URL, path));
 }
@@ -290,16 +338,38 @@ const server = new McpServer(
 // METADATA TOOLS
 // ============================================================================
 
-server.tool('get_all_metadata', 'Get all metadata (tables, columns, relations, routes, hooks, etc.) from Enfyra', {}, async () => {
+server.tool('get_all_metadata', 'Get concise metadata summary for all tables. Use get_table_metadata or inspect_table for detail.', {
+  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 }) => {
   const result = await fetchAPI(ENFYRA_API_URL, '/metadata');
-  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  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.',
+      };
+  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 });
 
-server.tool('get_table_metadata', 'Get metadata for a specific table by name', {
+server.tool('get_table_metadata', 'Get concise metadata for a specific table by name', {
   tableName: z.string().describe('Table name (e.g., "user_definition", "route_definition")'),
-}, async ({ tableName }) => {
+  includeFull: z.boolean().optional().default(false).describe('Return full raw table metadata. Default false to keep MCP context small.'),
+}, async ({ tableName, includeFull }) => {
   const result = await fetchAPI(ENFYRA_API_URL, `/metadata/${tableName}`);
-  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  const table = result?.data?.table || result?.data || result?.table || result;
+  const payload = includeFull
+    ? result
+    : {
+        statusCode: result?.statusCode,
+        success: result?.success,
+        table: summarizeTable(table),
+        queryHint: `Use query_table({ tableName: "${tableName}", fields: [...] }) for records. query_table without fields returns only the primary key.`,
+      };
+  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 });
 
 server.tool(
@@ -707,27 +777,41 @@ server.tool(
   },
 );
 
-server.tool('query_table', 'Query any table in Enfyra with filters, sorting, and pagination', {
+server.tool('query_table', 'Query any route-backed table. Default response is minimal; pass fields explicitly for detail.', {
   tableName: z.string().describe('Table name to query'),
   filter: z.string().optional().describe('Filter object as JSON string. Examples: \'{"status": {"_eq": "active"}}\''),
   sort: z.string().optional().describe('Sort field. Prefix with - for descending (e.g., "createdAt", "-id")'),
   page: z.number().optional().describe('Page number (default: 1)'),
-  limit: z.number().optional().describe('Items per page (default: 50, max: 500)'),
-  fields: z.array(z.string()).optional().describe('Fields to select'),
+  limit: z.number().optional().describe('Items per page. Default: 10. Use count_records for counts.'),
+  fields: z.array(z.string()).optional().describe('Fields to select. If omitted, MCP selects only the table primary key to avoid oversized responses.'),
 }, async ({ tableName, filter, sort, page, limit, fields }) => {
   validateTableName(tableName);
   validateFilter(filter);
 
   const queryParams = new URLSearchParams();
+  const selectedFields = fields && fields.length > 0 ? fields : [await getPrimaryFieldName(tableName)];
   if (filter) queryParams.set('filter', filter);
   if (sort) queryParams.set('sort', sort);
   if (page) queryParams.set('page', String(page));
-  if (limit) queryParams.set('limit', String(limit));
-  if (fields) queryParams.set('fields', fields.join(','));
+  queryParams.set('limit', String(limit || 10));
+  queryParams.set('fields', selectedFields.join(','));
 
   const query = queryParams.toString();
   const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}${query ? `?${query}` : ''}`);
-  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  const payload = {
+    statusCode: result?.statusCode,
+    success: result?.success,
+    tableName,
+    fields: selectedFields,
+    limit: limit || 10,
+    minimalDefaultApplied: !(fields && fields.length > 0),
+    meta: result?.meta,
+    data: result?.data || [],
+    detailHint: fields && fields.length > 0
+      ? undefined
+      : 'Only the primary key was returned because fields was omitted. Re-run query_table with explicit fields for details, or use inspect_table to find valid field names.',
+  };
+  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 });
 
 server.tool(
@@ -780,26 +864,50 @@ server.tool(
     tableName: z.string().describe('Table name'),
     id: z.string().optional().describe('Record ID'),
     filter: z.string().optional().describe('Filter as JSON string to find by'),
+    fields: z.array(z.string()).optional().describe('Fields to select. If omitted, returns only the primary key.'),
   },
-  async ({ tableName, id, filter }) => {
+  async ({ tableName, id, filter, fields }) => {
     validateTableName(tableName);
+    const primaryKey = await getPrimaryFieldName(tableName);
+    const selectedFields = fields && fields.length > 0 ? fields : [primaryKey];
     if (id) {
       // Enfyra route engine does not register GET /<table>/:id (only PATCH/DELETE use /:id). Use list + filter.
-      const filterObj = JSON.stringify({ id: { _eq: id } });
+      const filterObj = JSON.stringify({ [primaryKey]: { _eq: id } });
+      const queryParams = new URLSearchParams({
+        filter: filterObj,
+        limit: '1',
+        fields: selectedFields.join(','),
+      });
       const result = await fetchAPI(
         ENFYRA_API_URL,
-        `/${tableName}?filter=${encodeURIComponent(filterObj)}&limit=1`,
+        `/${tableName}?${queryParams.toString()}`,
       );
       const one = result.data?.[0] ?? null;
-      return { content: [{ type: 'text', text: JSON.stringify(one, null, 2) }] };
+      return { content: [{ type: 'text', text: JSON.stringify({
+        tableName,
+        primaryKey,
+        fields: selectedFields,
+        data: one,
+        detailHint: fields && fields.length > 0 ? undefined : 'Only the primary key was returned. Pass fields for details.',
+      }, null, 2) }] };
     }
     if (!filter) throw new Error('Provide id or filter');
     validateFilter(filter);
+    const queryParams = new URLSearchParams({
+      filter,
+      limit: '1',
+      fields: selectedFields.join(','),
+    });
     const result = await fetchAPI(
       ENFYRA_API_URL,
-      `/${tableName}?filter=${encodeURIComponent(filter)}&limit=1`,
+      `/${tableName}?${queryParams.toString()}`,
     );
-    return { content: [{ type: 'text', text: JSON.stringify(result.data?.[0] || null, null, 2) }] };
+    return { content: [{ type: 'text', text: JSON.stringify({
+      tableName,
+      fields: selectedFields,
+      data: result.data?.[0] || null,
+      detailHint: fields && fields.length > 0 ? undefined : 'Only the primary key was returned. Pass fields for details.',
+    }, null, 2) }] };
   },
 );
 
@@ -813,7 +921,7 @@ server.tool('create_record', 'Create a new record in any table', {
 }, async ({ tableName, data }) => {
   validateTableName(tableName);
   const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}`, { method: 'POST', body: data });
-  return { content: [{ type: 'text', text: `Record created:\n${JSON.stringify(result, null, 2)}` }] };
+  return { content: [{ type: 'text', text: JSON.stringify(summarizeMutationResult(result, 'created', tableName), null, 2) }] };
 });
 
 server.tool('update_record', 'Update an existing record by ID using PATCH', {
@@ -823,7 +931,7 @@ server.tool('update_record', 'Update an existing record by ID using PATCH', {
 }, async ({ tableName, id, data }) => {
   validateTableName(tableName);
   const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}/${id}`, { method: 'PATCH', body: data });
-  return { content: [{ type: 'text', text: `Record updated:\n${JSON.stringify(result, null, 2)}` }] };
+  return { content: [{ type: 'text', text: JSON.stringify(summarizeMutationResult(result, 'updated', tableName), null, 2) }] };
 });
 
 server.tool('delete_record', 'Delete a record by ID', {
@@ -832,7 +940,13 @@ server.tool('delete_record', 'Delete a record by ID', {
 }, async ({ tableName, id }) => {
   validateTableName(tableName);
   const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}/${id}`, { method: 'DELETE' });
-  return { content: [{ type: 'text', text: `Record deleted:\n${JSON.stringify(result, null, 2)}` }] };
+  return { content: [{ type: 'text', text: JSON.stringify({
+    action: 'deleted',
+    tableName,
+    id,
+    statusCode: result?.statusCode,
+    success: result?.success,
+  }, null, 2) }] };
 });
 
 server.tool(
@@ -987,7 +1101,7 @@ function enrichRoute(route, state) {
     .map((item) => pickCodeSummary({
       ...item,
       method: item.method ? { ...item.method, method: state.methodIdNameMap[String(getId(item.method))] || item.method.method || null } : item.method,
-    }, 'logic'));
+    }, 'sourceCode'));
   const routePreHooks = withMethodNames(
     state.preHooks.filter((item) => item.isGlobal || sameId(refId(item.route), routeId)),
     state.methodIdNameMap,
@@ -1138,7 +1252,7 @@ server.tool(
       relations: table.relations?.map((relation) => ({ propertyName: relation.propertyName, description: relation.description })),
     }));
     const routeMatches = state.routes.filter((route) => matchesText(route));
-    const handlerMatches = state.handlers.filter((handler) => matchesText(handler)).map((item) => pickCodeSummary(item, 'logic'));
+    const handlerMatches = state.handlers.filter((handler) => matchesText(handler)).map((item) => pickCodeSummary(item, 'sourceCode'));
     const preHookMatches = state.preHooks.filter((hook) => matchesText(hook)).map((item) => pickCodeSummary(item, 'code'));
     const postHookMatches = state.postHooks.filter((hook) => matchesText(hook)).map((item) => pickCodeSummary(item, 'code'));
     const guardMatches = state.guards.filter((guard) => matchesText(guard));
@@ -1234,12 +1348,40 @@ server.tool(
   },
 );
 
-server.tool('get_all_routes', 'List all route definitions (path, mainTable, handlers, hooks, permissions). Call before create_route to avoid duplicate paths and to pick routeId for hooks/handlers.', {
+server.tool('get_all_routes', 'List route definitions with minimal fields. Call inspect_route for handlers/hooks/permissions detail.', {
   includeDisabled: z.boolean().optional().default(false).describe('Include disabled routes'),
-}, async ({ includeDisabled }) => {
+  search: z.string().optional().describe('Optional path or table substring filter. Use this before creating a route to check duplicates.'),
+  limit: z.number().optional().describe('Maximum routes returned after search. Default 50 to keep response small.'),
+}, async ({ includeDisabled, search, limit }) => {
   const filter = includeDisabled ? {} : { isEnabled: { _eq: true } };
-  const result = await fetchAPI(ENFYRA_API_URL, `/route_definition?filter=${encodeURIComponent(JSON.stringify(filter))}&limit=500`);
-  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  const queryParams = new URLSearchParams({
+    filter: JSON.stringify(filter),
+    fields: 'id,path,mainTable.name,availableMethods.*,publishedMethods.*,isEnabled',
+    limit: '1000',
+  });
+  const result = await fetchAPI(ENFYRA_API_URL, `/route_definition?${queryParams.toString()}`);
+  const routeLimit = limit || 50;
+  const q = search ? search.toLowerCase() : null;
+  const allRoutes = summarizeRoutes(result);
+  const matchedRoutes = q
+    ? allRoutes.filter((route) => JSON.stringify({
+        path: route.path,
+        mainTable: route.mainTable,
+      }).toLowerCase().includes(q))
+    : allRoutes;
+  const payload = {
+    statusCode: result?.statusCode,
+    success: result?.success,
+    totalRouteCount: allRoutes.length,
+    matchedRouteCount: matchedRoutes.length,
+    returnedRouteCount: Math.min(matchedRoutes.length, routeLimit),
+    search: search || null,
+    routes: matchedRoutes.slice(0, routeLimit),
+    detailHint: matchedRoutes.length > routeLimit
+      ? `Response truncated to ${routeLimit} routes. Re-run with search or a higher limit, then inspect_route({ path }) for details.`
+      : 'Use inspect_route({ path }) or inspect_route({ routeId }) for handlers, hooks, permissions, and guards.',
+  };
+  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 });
 
 server.tool(
@@ -1283,7 +1425,19 @@ 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: JSON.stringify({
+      action: 'created',
+      route: {
+        id: getId(created),
+        path: created?.path,
+        mainTableId,
+        availableMethods: methods,
+        publishedMethods: publishedMethods || [],
+      },
+      routesReloaded: true,
+      next: `Use create_handler({ routeId: ${JSON.stringify(getId(created))}, method: "GET"|"POST"|"PATCH"|"DELETE", sourceCode }) for custom code.`,
+    }, null, 2) }] };
   },
 );
 
@@ -1292,38 +1446,56 @@ server.tool(
   [
     'Create a handler for a route+method. One handler per (route, method) pair.',
     'Attach to the route the user cares about (`get_all_routes`): typically a path from `create_route`, not a spurious table created only for handlers.',
+    'Use sourceCode, not logic/name. Enfyra compiles sourceCode into compiledCode; do not send compiledCode.',
     'Handler code runs inside a sandbox with $ctx. Use macros: @BODY, @QUERY, @PARAMS, @USER, @REPOS, @HELPERS, @THROW400..@THROW503, @SOCKET, @PKGS, @LOGS, @SHARE.',
     'Or use $ctx directly: $ctx.$body, $ctx.$repos.main.find(), $ctx.$helpers.$bcrypt.hash(), etc.',
     'require("pkg") works for installed Server packages. console.log() writes to $share.$logs.',
   ].join(' '),
   {
     routeId: z.union([z.string(), z.number()]).describe('Route definition ID'),
-    methods: z.array(z.enum(['GET', 'POST', 'PATCH', 'DELETE']))
-      .describe('Methods to create handlers for. Creates one handler per method.'),
-    logic: z.string().describe('Handler JavaScript code'),
+    method: z.enum(['GET', 'POST', 'PATCH', 'DELETE']).optional()
+      .describe('Single method to create. Prefer this for one handler.'),
+    methods: z.array(z.enum(['GET', 'POST', 'PATCH', 'DELETE'])).optional()
+      .describe('Batch create multiple handlers. Use only when the same sourceCode applies to every method.'),
+    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)'),
   },
-  async ({ routeId, methods, logic, timeout }) => {
+  async ({ routeId, method, methods, sourceCode, scriptLanguage, timeout }) => {
+    const methodNames = methods && methods.length > 0 ? methods : method ? [method] : [];
+    if (methodNames.length === 0) throw new Error('Provide method or methods');
     const methodMap = await getMethodMap();
     const results = [];
 
-    for (const method of methods) {
-      const methodId = methodMap[method.toUpperCase()];
-      if (!methodId) throw new Error(`Unknown method: ${method}. Valid: ${Object.keys(methodMap).join(', ')}`);
+    for (const methodName of methodNames) {
+      const methodId = methodMap[methodName.toUpperCase()];
+      if (!methodId) throw new Error(`Unknown method: ${methodName}. Valid: ${Object.keys(methodMap).join(', ')}`);
 
-      const body = { route: { id: routeId }, method: { id: methodId }, logic };
+      const body = { route: { id: routeId }, method: { id: methodId }, sourceCode, scriptLanguage };
       if (timeout) body.timeout = timeout;
 
       const result = await fetchAPI(ENFYRA_API_URL, '/route_handler_definition', {
         method: 'POST',
         body: JSON.stringify(body),
       });
-      results.push(result);
+      const created = firstDataRecord(result);
+      results.push({
+        id: getId(created),
+        routeId,
+        method: methodName,
+        scriptLanguage,
+        timeout: created?.timeout ?? timeout ?? null,
+      });
     }
 
     await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
 
-    return { content: [{ type: 'text', text: `Handler(s) created for [${methods.join(', ')}]. Routes reloaded.\n${JSON.stringify(results, null, 2)}` }] };
+    return { content: [{ type: 'text', text: JSON.stringify({
+      action: 'created',
+      handlers: results,
+      routesReloaded: true,
+      detailHint: 'Use inspect_route with the same routeId/path to inspect saved handlers.',
+    }, null, 2) }] };
   },
 );
 
@@ -1338,7 +1510,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 +1525,8 @@ server.tool(
       body: JSON.stringify({
         route: { id: routeId },
         name,
-        code,
+        sourceCode: code,
+        scriptLanguage: 'javascript',
         methods: resolveMethodIds(methodMap, methodNames),
         priority,
         isEnabled,
@@ -1362,7 +1535,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 +1551,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 +1566,8 @@ server.tool(
       body: JSON.stringify({
         route: { id: routeId },
         name,
-        code,
+        sourceCode: code,
+        scriptLanguage: 'javascript',
         methods: resolveMethodIds(methodMap, methodNames),
         priority,
         isEnabled,
@@ -1401,7 +1576,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 +1867,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 +2001,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 +2027,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)}` }] };
   },
 );