@enfyra/mcp-server 0.0.55 → 0.0.57

package/README.md

@@ -184,6 +184,10 @@ Use this block in any host-specific `mcp.json` / `mcpServers` merge (adjust env
 
 `ENFYRA_API_TOKEN` is a long-lived programmatic token, not a JWT. MCP must never send it directly as `Authorization: Bearer <token>` to REST tools. The MCP client first calls `POST {ENFYRA_API_URL}/auth/token/exchange` with `{ "apiToken": ENFYRA_API_TOKEN }`, caches the returned `accessToken`, and uses that JWT as the Bearer token for subsequent requests.
 
+Schema and script tools include safety guards for LLM callers: generic record mutations validate request fields against live metadata, script-backed records must validate `sourceCode` before save through `/admin/script/validate` and fail closed if validation is unavailable, relation metadata rejects physical FK/junction inputs, custom routes reject `mainTableId` unless the path is the canonical table route, schema tools serialize table/column/relation changes, and destructive deletes require `confirm=true` after returning a preview.
+
+For route contracts that intentionally keep workflow fields out of request bodies, generic `create_record`, `update_record`, and `delete_record` accept optional `queryParams` as a JSON object string. For example, Cloud admin project creation can keep `expired_at=YYYY-MM-DD` in the URL query while `validateBody` remains enabled for the table body.
+
 ### `ENFYRA_API_URL` — use the app proxy
 
 For normal apps and demos, set `ENFYRA_API_URL` to the Nuxt/app proxy:

package/package.json

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

package/src/lib/auth.js

@@ -41,6 +41,10 @@ export function getAccessToken() {
   return accessToken;
 }
 
+export function hasApiToken() {
+  return !!API_TOKEN;
+}
+
 /**
  * Get token expiry time
  */

package/src/lib/fetch.js

@@ -3,7 +3,7 @@
  * Handles API requests with auth, timeout, and error handling
  */
 
-import { getValidToken } from './auth.js';
+import { getValidToken, hasApiToken, resetTokens } from './auth.js';
 
 // Timeout configuration
 const FETCH_TIMEOUT = 30000; // 30 seconds
@@ -17,49 +17,57 @@ const FETCH_TIMEOUT = 30000; // 30 seconds
  */
 export async function fetchAPI(apiUrl, path, options = {}) {
   const url = `${apiUrl}${path}`;
-  const token = await getValidToken(apiUrl);
 
-  const headersList = [
-    ['Content-Type', 'application/json'],
-    ['Authorization', `Bearer ${token}`],
-  ];
+  async function requestWithCurrentToken() {
+    const token = await getValidToken(apiUrl);
+    const headersList = [
+      ['Content-Type', 'application/json'],
+      ['Authorization', `Bearer ${token}`],
+    ];
 
-  if (options.headers) {
-    const optHeaders = options.headers;
-    for (const key of Object.keys(optHeaders)) {
-      const existingIdx = headersList.findIndex(h => h[0] === key);
-      if (existingIdx >= 0) {
-        headersList[existingIdx] = [key, optHeaders[key]];
-      } else {
-        headersList.push([key, optHeaders[key]]);
+    if (options.headers) {
+      const optHeaders = options.headers;
+      for (const key of Object.keys(optHeaders)) {
+        const existingIdx = headersList.findIndex(h => h[0] === key);
+        if (existingIdx >= 0) {
+          headersList[existingIdx] = [key, optHeaders[key]];
+        } else {
+          headersList.push([key, optHeaders[key]]);
+        }
       }
     }
-  }
-
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
 
-  try {
-    const res = await fetch(url, {
-      ...options,
-      headers: headersList,
-      signal: controller.signal,
-    });
-    clearTimeout(timeoutId);
-
-    if (!res.ok) {
-      const error = await res.text().catch(() => res.statusText);
-      throw new Error(`API error (${res.status}): ${error}`);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
+    try {
+      const res = await fetch(url, {
+        ...options,
+        headers: headersList,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+      return res;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === 'AbortError') {
+        throw new Error(`Request timeout after ${FETCH_TIMEOUT}ms`);
+      }
+      throw error;
     }
+  }
 
-    return res.json();
-  } catch (error) {
-    clearTimeout(timeoutId);
-    if (error.name === 'AbortError') {
-      throw new Error(`Request timeout after ${FETCH_TIMEOUT}ms`);
-    }
-    throw error;
+  let res = await requestWithCurrentToken();
+  if ((res.status === 401 || res.status === 403) && hasApiToken()) {
+    resetTokens();
+    res = await requestWithCurrentToken();
   }
+
+  if (!res.ok) {
+    const error = await res.text().catch(() => res.statusText);
+    throw new Error(`API error (${res.status}): ${error}`);
+  }
+
+  return res.json();
 }
 
 /**

package/src/lib/mcp-examples.js

@@ -203,10 +203,21 @@ create_column({
   defaultValue: "pending",
   isPublished: true,
   description: "Email verification state controlled by server hooks."
+})
+
+create_column({
+  tableId: "<project_env_table_id>",
+  name: "value",
+  type: "text",
+  isNullable: false,
+  isPublished: false,
+  isEncrypted: true,
+  description: "Encrypted environment value."
 })`,
         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 isEncrypted=true for encryption at rest. Add isUpdatable=false separately only when the field should be immutable.',
           'Use hooks or field permissions to prevent clients from updating server-owned fields.',
         ],
       },

package/src/lib/mcp-instructions.js

@@ -107,6 +107,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### 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.',
+'- Generic MCP `create_record` and `update_record` validate body keys against live metadata before sending REST. If a field such as `expiredAt` is not in metadata, do not bypass body validation; add the metadata field through schema tools or pass route workflow fields in the tool `queryParams` JSON when that route explicitly owns a query contract such as `{"expired_at":"2026-09-20"}`.',
+'- Generic MCP script-table mutations reject `compiledCode`, reject legacy `code` aliases, and must validate `sourceCode` with `/admin/script/validate` before saving. If validation is unavailable or fails, the save must fail closed. Prefer dedicated `create_handler`, `create_pre_hook`, and `create_post_hook` tools for route code.',
+'- Generic MCP `delete_record` is destructive but preview-first: the first call without `confirm=true` returns the target preview; call it again with `confirm=true` only after the user explicitly approves deletion. Use `queryParams` for route-specific confirmation contracts instead of putting those fields in the body.',
 '- Relation fields (publishedMethods, availableMethods, handlers, preHooks, postHooks, etc.) use **object references with `id`**:',
 '- **mainTable warning:** do not set `mainTable` on custom routes. It is reserved for canonical table routes only.',
 '  - **Many-to-one:** `"someRelation": {"id": 4}` (single object with id)',
@@ -136,7 +139,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '### Dynamic script syntax preference',
     '- When writing server-side Enfyra scripts, prefer template macros over raw `$ctx` access: use `@BODY`, `@QUERY`, `@PARAMS`, `@USER`, `@REPOS`, `@HELPERS`, `@SOCKET`, `@TRIGGER`, `@DATA`, `@ERROR`, and `@THROW400`–`@THROW503`.',
     '- Use Enfyra native throw helpers for intentional errors: `@THROW400("message")`, `@THROW403()`, `@THROW404("resource", id)`, or `$ctx.$throw[400]("message")`. Do not generate `throw new Error(...)` for user/domain errors in handlers, hooks, flows, websocket events, OAuth scripts, or admin-generated scripts.',
-    '- 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);`.',
+    '- For regular app data that must be encrypted at rest, create the column with `isEncrypted=true`; Enfyra database-query hooks will encrypt on insert/update and decrypt after select. `isEncrypted` does not imply immutability; use `isUpdatable=false` separately only when the field itself must be immutable. Do not filter or sort on encrypted fields. Legacy Cloud control-plane fields named `*_encrypted` may still use route pre-hooks until migrated.',
     '- 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.',
@@ -202,8 +205,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- To check which tables have canonical CRUD routes, call `get_all_routes` and look for `mainTable`. Custom routes intentionally have no `mainTable`; inspect their handlers/hooks to see which repos they touch.',
     '- **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 by reading full table metadata first.',
-    '- 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. Never rebuild a schema cascade from `table_definition?fields=columns.*`, because nested relation fields may be paginated/truncated.',
-    '- 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.',
+    '- Use `create_column`/`add_column` for new scalar fields. These tools accept column metadata such as `isNullable`, `isUnique`, `isPublished`, `isUpdatable`, `isEncrypted`, `isPrimary`, `isGenerated`, `isSystem`, `defaultValue`, `description`, and `options`; set `isUpdatable=false` for immutable fields and set `isPublished=false` directly when creating secret/internal fields. `isEncrypted=true` encrypts stored values at rest but does not change `isUpdatable`; encrypted fields must not be used for filter/sort. 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. Never rebuild a schema cascade from `table_definition?fields=columns.*`, because nested relation fields may be paginated/truncated.',
+    '- Prefer `create_relation`/`add_relation` and `delete_relation`/`remove_relation` for relation schema changes because they preserve the full table relation list, serialize schema mutations, verify unrelated relation ids survived, and handle schema-confirm retry. Direct `create_record` on `relation_definition` only edits metadata and is not the canonical schema migration path; generic record mutations also reject physical FK/junction fields on `relation_definition`.',
+    '- Destructive schema tools and generic `delete_record` return a preview unless `confirm=true` is passed. This applies to `delete_record`, `delete_table`, `delete_column`/`remove_column`, and `delete_relation`/`remove_relation`; do not add `confirm=true` until the user has explicitly approved the destructive operation.',
     '',
     '### Body validation & column rules',
     '- Each `table_definition` has a **`validateBody`** flag (default `true` for new tables). When on, every `POST /<table>` and `PATCH /<table>/<id>` is validated server-side against the column types + any **column rules** attached to columns of that table.',
@@ -310,9 +314,9 @@ 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 }`, `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 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 body fields such as `owner: { id }`, `plan: { id }`, and `status: "creating"`; expiry is passed as query `expired_at=YYYY-MM-DD`, not body `expiredAt`. 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 the canonical renew flow/query contract and writes `cloud_project_renewals`; do not add expiry columns to `cloud_projects`. 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 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 and plan id in the schema-safe body; pass expiry as query `expired_at=YYYY-MM-DD` when the canonical handler requires it and let the handler 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.',
     '- **Flow schedule UI:** schedule trigger editors must keep the server contract as `triggerConfig.cron` and `triggerConfig.timezone`, but the UI should not be a bare cron field plus giant timezone dropdown. Provide common cadence presets, readable current-schedule summary, searchable access to all IANA timezones, suggested timezone shortcuts, and a custom cron escape hatch so operators can configure recurring checks without remembering cron syntax.',
     '- **Admin operation UI:** use eApp `CommonModal` for compact create, disable, delete, and multi-field confirmation workflows. Use `CommonDrawer` for longer setup workflows such as Cloud host settings, host creation, project creation, and provider/package selection. Open the modal/drawer immediately on click, then render loading/error/content inside it; do not wait for async fetches to finish before showing the shell.',
@@ -410,9 +414,9 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `- \`query_table\` → GET \`${base}/<tableName>?…\` (query string from tool args)`,
     `- \`count_records\` → GET \`${base}/<tableName>?fields=id&limit=1&meta=totalCount|filterCount\``,
     `- \`find_one_record\` (by id) → GET \`${base}/<tableName>?filter=…&limit=1\``,
-    `- \`create_record\` → POST \`${base}/<tableName>\``,
-    `- \`update_record\` → PATCH \`${base}/<tableName>/<id>\``,
-    `- \`delete_record\` → DELETE \`${base}/<tableName>/<id>\``,
+    `- \`create_record\` → POST \`${base}/<tableName>\` (optional tool queryParams append URL query)`,
+    `- \`update_record\` → PATCH \`${base}/<tableName>/<id>\` (optional tool queryParams append URL query)`,
+    `- \`delete_record\` → DELETE \`${base}/<tableName>/<id>\` after preview + confirm=true (optional tool queryParams append URL query)`,
     `- \`create_extension\` → POST \`${base}/extension_definition\` (Vue SFC only; for page pass menuId). \`update_record\` on extension_definition to change code.`,
     `- Flow tables: \`${base}/flow_definition\`, \`${base}/flow_step_definition\`, \`${base}/flow_execution_definition\` — use standard CRUD tools.`,
     `- \`run_admin_test\` → POST \`${base}/admin/test/run\``,

package/src/lib/mutation-guards.js

@@ -0,0 +1,118 @@
+const SCRIPT_TABLES = new Set([
+  'route_handler_definition',
+  'pre_hook_definition',
+  'post_hook_definition',
+  'flow_step_definition',
+  'websocket_event_definition',
+  'websocket_definition',
+  'gql_definition',
+  'bootstrap_script_definition',
+]);
+
+const CODE_ALIAS_FORBIDDEN_TABLES = new Set([
+  'route_handler_definition',
+  'pre_hook_definition',
+  'post_hook_definition',
+  'flow_step_definition',
+  'websocket_event_definition',
+  'websocket_definition',
+  'gql_definition',
+  'bootstrap_script_definition',
+]);
+
+const FORBIDDEN_RELATION_DEFINITION_KEYS = new Set([
+  'fkCol',
+  'fkColumn',
+  'foreignKeyColumn',
+  'sourceColumn',
+  'targetColumn',
+  'junctionSourceColumn',
+  'junctionTargetColumn',
+]);
+
+export function parseRecordData(data) {
+  const parsed = typeof data === 'string' ? JSON.parse(data) : data;
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('Record data must be a JSON object string.');
+  }
+  return parsed;
+}
+
+export function getAllowedMutationFields(table) {
+  const columns = (table?.columns || []).map((column) => column.name).filter(Boolean);
+  const relations = (table?.relations || []).map((relation) => relation.propertyName).filter(Boolean);
+  return new Set([...columns, ...relations]);
+}
+
+export function validatePayloadFields(table, payload) {
+  const allowed = getAllowedMutationFields(table);
+  if (allowed.size === 0) return;
+
+  const unknown = Object.keys(payload).filter((key) => !allowed.has(key));
+  if (unknown.length > 0) {
+    throw new Error(
+      `Payload contains fields not present in metadata for ${table.name}: ${unknown.join(', ')}. ` +
+      `Use metadata-backed fields only, or create the field through schema tools first. Known fields: ${[...allowed].sort().join(', ')}`
+    );
+  }
+}
+
+export function rejectUnsafeScriptPayload(tableName, payload) {
+  if (Object.prototype.hasOwnProperty.call(payload, 'compiledCode')) {
+    throw new Error('Do not send compiledCode. Save sourceCode/scriptLanguage and let Enfyra compile compiledCode.');
+  }
+  if (CODE_ALIAS_FORBIDDEN_TABLES.has(tableName) && Object.prototype.hasOwnProperty.call(payload, 'code')) {
+    throw new Error(`Do not send code to ${tableName}. Use sourceCode/scriptLanguage, or the dedicated MCP create_* tool for this script surface.`);
+  }
+}
+
+export function rejectUnsafeRelationDefinitionPayload(tableName, payload) {
+  if (tableName !== 'relation_definition') return;
+  const forbidden = Object.keys(payload).filter((key) => FORBIDDEN_RELATION_DEFINITION_KEYS.has(key));
+  if (forbidden.length > 0) {
+    throw new Error(
+      `Do not send physical FK/junction fields to relation_definition: ${forbidden.join(', ')}. ` +
+      'Use create_relation/add_relation with targetTable/type/propertyName; Enfyra derives physical columns.'
+    );
+  }
+}
+
+export async function validateScriptSourceIfPresent(fetchAPI, apiUrl, tableName, payload) {
+  if (!SCRIPT_TABLES.has(tableName) || typeof payload.sourceCode !== 'string') {
+    return { validated: false, reason: 'no script source' };
+  }
+
+  try {
+    const result = await fetchAPI(apiUrl, '/admin/script/validate', {
+      method: 'POST',
+      body: JSON.stringify({
+        sourceCode: payload.sourceCode,
+        scriptLanguage: payload.scriptLanguage || 'javascript',
+      }),
+    });
+    if (result?.valid === false || result?.success === false) {
+      throw new Error(result?.error?.message || 'Script validation failed.');
+    }
+    return { validated: true, skipped: false };
+  } catch (error) {
+    const message = String(error?.message || error);
+    throw new Error(`Script validation failed before save: ${message}`);
+  }
+}
+
+export async function prepareRecordMutation({ fetchAPI, apiUrl, tables, tableName, data }) {
+  const payload = parseRecordData(data);
+  const table = tables.find((item) => item?.name === tableName || item?.alias === tableName);
+  if (!table) throw new Error(`Unknown table "${tableName}"`);
+
+  validatePayloadFields(table, payload);
+  rejectUnsafeScriptPayload(table.name, payload);
+  rejectUnsafeRelationDefinitionPayload(table.name, payload);
+  const scriptValidation = await validateScriptSourceIfPresent(fetchAPI, apiUrl, table.name, payload);
+
+  return {
+    table,
+    payload,
+    scriptValidation,
+  };
+}

package/src/lib/route-guards.js

@@ -0,0 +1,24 @@
+function getId(item) {
+  return item?.id ?? item?._id ?? null;
+}
+
+function sameId(a, b) {
+  return String(a) === String(b);
+}
+
+export function validateMainTableRoutePath(tables, mainTableId, routePath) {
+  const table = tables.find((item) => sameId(getId(item), mainTableId));
+  if (!table) {
+    throw new Error(`Unknown table id "${mainTableId}"`);
+  }
+
+  const canonicalPath = `/${table.name}`;
+  if (routePath !== canonicalPath) {
+    throw new Error(
+      `mainTableId is only allowed for canonical table route "${canonicalPath}". ` +
+      `Omit mainTableId for custom route "${routePath}" and query explicit repos in handlers/hooks.`
+    );
+  }
+
+  return table;
+}

package/src/lib/table-tools.js

@@ -4,6 +4,24 @@
 import { z } from 'zod';
 import { fetchAPI } from './fetch.js';
 
+let schemaQueue = Promise.resolve();
+
+function withSchemaQueue(operation) {
+  const run = schemaQueue.then(operation, operation);
+  schemaQueue = run.catch(() => {});
+  return run;
+}
+
+const FORBIDDEN_RELATION_KEYS = [
+  'fkCol',
+  'fkColumn',
+  'foreignKeyColumn',
+  'sourceColumn',
+  'targetColumn',
+  'junctionSourceColumn',
+  'junctionTargetColumn',
+];
+
 export function normalizeTablesFromMetadata(metadata) {
   const tablesSource = metadata?.data?.tables || metadata?.tables || metadata?.data || [];
   return Array.isArray(tablesSource)
@@ -81,7 +99,12 @@ function normalizeConstraintGroups(name, groups) {
   });
 }
 
-function normalizeRelationForTablePatch(relation) {
+export function normalizeRelationForTablePatch(relation) {
+  for (const key of FORBIDDEN_RELATION_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(relation, key)) {
+      throw new Error(`Relation schema must not include physical column field "${key}". Use propertyName/targetTable only; Enfyra derives FK and junction columns.`);
+    }
+  }
   const {
     sourceTable,
     targetTable,
@@ -163,12 +186,36 @@ async function verifyColumnCascade(ENFYRA_API_URL, tableId, beforeIds, {
   return afterColumns;
 }
 
-function buildColumnDefinition({
+async function verifyRelationCascade(ENFYRA_API_URL, tableId, beforeIds, {
+  action,
+  relationId,
+  propertyName,
+}) {
+  const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
+  const afterRelations = (tableData.relations || []).map(normalizeRelationForTablePatch);
+  const afterIds = afterRelations.map((relation) => String(getId(relation))).filter((id) => id !== 'null');
+  const excludedIds = action === 'delete' ? [relationId] : [];
+  const missingIds = getMissingIds(beforeIds, afterIds, excludedIds);
+  if (missingIds.length > 0) {
+    throw new Error(`Schema cascade verification failed: unrelated relation ids disappeared: ${missingIds.join(', ')}`);
+  }
+  if (action === 'create' && !afterRelations.some((relation) => relation.propertyName === propertyName)) {
+    throw new Error(`Schema cascade verification failed: relation "${propertyName}" was not found after create.`);
+  }
+  if (action === 'delete' && afterIds.includes(String(relationId))) {
+    throw new Error(`Schema cascade verification failed: relation ${relationId} still exists after delete.`);
+  }
+  return afterRelations;
+}
+
+export function buildColumnDefinition({
   name,
   type,
   isNullable,
   isUnique,
   isPublished,
+  isUpdatable,
+  isEncrypted,
   isPrimary,
   isGenerated,
   isSystem,
@@ -180,6 +227,8 @@ function buildColumnDefinition({
   if (isNullable !== undefined) column.isNullable = isNullable;
   if (isUnique !== undefined) column.isUnique = isUnique;
   if (isPublished !== undefined) column.isPublished = isPublished;
+  if (isUpdatable !== undefined) column.isUpdatable = isUpdatable;
+  if (isEncrypted !== undefined) column.isEncrypted = isEncrypted;
   if (isPrimary !== undefined) column.isPrimary = isPrimary;
   if (isGenerated !== undefined) column.isGenerated = isGenerated;
   if (isSystem !== undefined) column.isSystem = isSystem;
@@ -196,6 +245,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
   const apiBase = ENFYRA_API_URL.replace(/\/$/, '');
 
   async function appendColumnToTable(args) {
+    return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, args.tableId);
     if (!tableData) {
       return { content: [{ type: 'text', text: `Error: Table with ID ${args.tableId} not found.` }] };
@@ -213,14 +263,17 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     return {
       content: [{ type: 'text', text: `Column "${args.name}" added to table ${args.tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
     };
+    });
   }
 
   async function appendRelationToTable({ sourceTableId, targetTableId, type, propertyName, inversePropertyName, mappedBy, isNullable, onDelete, description }) {
+    return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, sourceTableId);
     if (!tableData) {
       return { content: [{ type: 'text', text: `Error: Table with ID ${sourceTableId} not found.` }] };
     }
     const existingRelations = (tableData.relations || []).map(normalizeRelationForTablePatch);
+    const beforeIds = existingRelations.map((relation) => String(getId(relation))).filter((id) => id !== 'null');
     const newRelation = { targetTable: targetTableId, type, propertyName };
     if (inversePropertyName !== undefined) newRelation.inversePropertyName = inversePropertyName || null;
     if (mappedBy !== undefined) newRelation.mappedBy = mappedBy;
@@ -228,12 +281,18 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     if (onDelete !== undefined) newRelation.onDelete = onDelete;
     if (description !== undefined) newRelation.description = description;
     const result = await patchTableAutoConfirm(ENFYRA_API_URL, sourceTableId, { relations: [...existingRelations, newRelation] });
+    await verifyRelationCascade(ENFYRA_API_URL, sourceTableId, beforeIds, {
+      action: 'create',
+      propertyName,
+    });
     return {
       content: [{ type: 'text', text: `Relation created: ${propertyName} (${type}) from table ${sourceTableId} → ${targetTableId}.\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
     };
+    });
   }
 
-  async function removeColumnFromTable({ tableId, columnId }) {
+  async function removeColumnFromTable({ tableId, columnId, confirm }) {
+    return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
     if (!tableData) {
       return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
@@ -244,6 +303,20 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     if (!beforeIds.includes(String(columnId))) {
       throw new Error(`Column ${columnId} was not found on table ${tableId}; refusing schema cascade patch.`);
     }
+    if (!confirm) {
+      const target = existingColumns.find((column) => String(getId(column)) === String(columnId));
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          action: 'delete_column_preview',
+          tableId,
+          columnId,
+          targetColumn: target,
+          preservedColumnIds: beforeIds.filter((id) => id !== String(columnId)),
+          destructive: true,
+          next: 'Call delete_column/remove_column again with confirm=true to drop the physical column and metadata.',
+        }, null, 2) }],
+      };
+    }
 
     const columns = existingColumns
       .filter(col => String(getId(col)) !== String(columnId))
@@ -257,23 +330,49 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     return {
       content: [{ type: 'text', text: `Column ${columnId} deleted from table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
     };
+    });
   }
 
-  async function removeRelationFromTable({ tableId, relationId }) {
+  async function removeRelationFromTable({ tableId, relationId, confirm }) {
+    return withSchemaQueue(async () => {
     const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
     if (!tableData) {
       return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
     }
 
-    const relations = (tableData.relations || [])
-      .filter(rel => String(rel.id) !== String(relationId))
-      .map(normalizeRelationForTablePatch);
+    const existingRelations = (tableData.relations || []).map(normalizeRelationForTablePatch);
+    const beforeIds = existingRelations.map((relation) => String(getId(relation))).filter((id) => id !== 'null');
+    if (!beforeIds.includes(String(relationId))) {
+      throw new Error(`Relation ${relationId} was not found on table ${tableId}; refusing schema cascade patch.`);
+    }
+    if (!confirm) {
+      const target = existingRelations.find((relation) => String(getId(relation)) === String(relationId));
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          action: 'delete_relation_preview',
+          tableId,
+          relationId,
+          targetRelation: target,
+          preservedRelationIds: beforeIds.filter((id) => id !== String(relationId)),
+          destructive: true,
+          next: 'Call delete_relation/remove_relation again with confirm=true to drop relation metadata and any derived FK/junction structures.',
+        }, null, 2) }],
+      };
+    }
+
+    const relations = existingRelations
+      .filter(rel => String(getId(rel)) !== String(relationId))
 
     const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, { relations });
+    await verifyRelationCascade(ENFYRA_API_URL, tableId, beforeIds, {
+      action: 'delete',
+      relationId,
+    });
 
     return {
       content: [{ type: 'text', text: `Relation ${relationId} deleted from table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
     };
+    });
   }
 
   const columnCreateSchema = {
@@ -283,6 +382,8 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     isNullable: z.boolean().optional().default(true).describe('Set to false if column cannot be null.'),
     isUnique: z.boolean().optional().default(false).describe('Set to true for unique constraint.'),
     isPublished: z.boolean().optional().describe('Set column visibility baseline. Use false for secrets and internal fields.'),
+    isUpdatable: z.boolean().optional().describe('Set false for immutable fields that cannot be updated after creation. Independent from isEncrypted.'),
+    isEncrypted: z.boolean().optional().describe('Set true to encrypt this column at the Enfyra database-query layer. This does not change isUpdatable. Encrypted fields cannot be filtered or sorted.'),
     isPrimary: z.boolean().optional().describe('Set true only for primary key columns; normally only create_table auto id uses this.'),
     isGenerated: z.boolean().optional().describe('Set true only for generated columns such as auto id.'),
     isSystem: z.boolean().optional().describe('Set true only for system-managed columns. Avoid for normal app fields.'),
@@ -306,11 +407,13 @@ export function registerTableTools(server, ENFYRA_API_URL) {
   const columnDeleteSchema = {
     tableId: z.string().describe('Table definition ID.'),
     columnId: z.string().describe('Column definition ID to delete.'),
+    confirm: z.boolean().optional().default(false).describe('Required true to apply the destructive delete. Omit/false returns a preview only.'),
   };
 
   const relationDeleteSchema = {
     tableId: z.string().describe('Table definition ID (source table of the relation).'),
     relationId: z.string().describe('Relation definition ID to delete.'),
+    confirm: z.boolean().optional().default(false).describe('Required true to apply the destructive delete. Omit/false returns a preview only.'),
   };
 
   // ─── READ ───
@@ -351,12 +454,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       name: z.string().describe('Table name (e.g., "user_definition", "my_custom_table"). Must be unique, lowercase with underscores.'),
       description: z.string().optional().describe('Description of what this table stores.'),
       isSingleRecord: z.boolean().optional().describe('Set to true for single-record tables such as settings/config. This is passed directly to table_definition create.'),
-      columns: z.string().optional().describe('JSON array of column definitions to create with the table (cascade). Each column: { name, type, isNullable?, isUnique?, defaultValue?, description?, options? }. The `id` column is always auto-included. Example: [{"name":"title","type":"varchar"},{"name":"status","type":"enum","options":["draft","published"]}]'),
+      columns: z.string().optional().describe('JSON array of column definitions to create with the table (cascade). Each column: { name, type, isNullable?, isUnique?, isPublished?, isUpdatable?, isEncrypted?, defaultValue?, description?, options? }. Set isEncrypted=true for values encrypted at rest; set isUpdatable=false separately only when the field should be immutable. The `id` column is always auto-included. Example: [{"name":"title","type":"varchar"},{"name":"api_key","type":"varchar","isEncrypted":true,"isPublished":false}]'),
       relations: z.string().optional().describe('JSON array of relation definitions to create with the table in the same cascade call. Each relation: { targetTable, type, propertyName, inversePropertyName?, mappedBy?, isNullable?, onDelete?, description? }. targetTable can be an id or {"id": <id>}. Do not include physical FK/junction columns such as fkCol, foreignKeyColumn, sourceColumn, targetColumn, junctionSourceColumn, or junctionTargetColumn; Enfyra derives them and hides FK columns from app schema. Example: [{"targetTable":2,"type":"many-to-one","propertyName":"author","inversePropertyName":"posts","isNullable":false,"onDelete":"CASCADE"}]'),
       indexes: z.string().optional().describe('JSON array of logical index field groups. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Relation property names are allowed. Example: [["member","isRead","conversation"],["conversation","member","isRead"]]'),
       uniques: z.string().optional().describe('JSON array of logical unique field groups. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Example: [["message","member"]]'),
     },
-    async ({ name, description, isSingleRecord, columns: columnsJson, relations: relationsJson, indexes: indexesJson, uniques: uniquesJson }) => {
+    async ({ name, description, isSingleRecord, columns: columnsJson, relations: relationsJson, indexes: indexesJson, uniques: uniquesJson }) => withSchemaQueue(async () => {
       const idColumn = { name: 'id', type: 'int', isPrimary: true, isGenerated: true, isNullable: false };
       const userColumns = parseJsonArrayParam('columns', columnsJson);
       const userRelations = parseJsonArrayParam('relations', relationsJson).map(normalizeRelationForTablePatch);
@@ -391,7 +494,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       return {
         content: [{ type: 'text', text: `${colHint}\n${relHint}${constraintHint ? `\n${constraintHint}` : ''}\n${restHint}\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
       };
-    }
+    })
   );
 
   // ─── UPDATE TABLE ───
@@ -414,7 +517,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       indexes: z.string().optional().describe('Complete JSON array of logical index field groups to store on table_definition.indexes. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Omit to preserve current indexes; pass [] to clear.'),
       uniques: z.string().optional().describe('Complete JSON array of logical unique field groups to store on table_definition.uniques. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Omit to preserve current uniques; pass [] to clear.'),
     },
-    async ({ tableId, name, alias, description, isSingleRecord, graphqlEnabled, indexes: indexesJson, uniques: uniquesJson }) => {
+    async ({ tableId, name, alias, description, isSingleRecord, graphqlEnabled, indexes: indexesJson, uniques: uniquesJson }) => withSchemaQueue(async () => {
       const body = {};
       if (name !== undefined) body.name = name;
       if (alias !== undefined) body.alias = alias;
@@ -428,7 +531,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       return {
         content: [{ type: 'text', text: `Table ${tableId} updated.\n\n${JSON.stringify(result, null, 2)}` }],
       };
-    }
+    })
   );
 
   // ─── DELETE TABLE ───
@@ -442,15 +545,30 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     ].join(' '),
     {
       tableId: z.string().describe('Table definition ID to delete.'),
+      confirm: z.boolean().optional().default(false).describe('Required true to apply the destructive delete. Omit/false returns a preview only.'),
     },
-    async ({ tableId }) => {
+    async ({ tableId, confirm }) => withSchemaQueue(async () => {
+      const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
+      if (!confirm) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify({
+            action: 'delete_table_preview',
+            tableId,
+            tableName: tableData.name,
+            columnCount: (tableData.columns || []).length,
+            relationCount: (tableData.relations || []).length,
+            destructive: true,
+            next: 'Call delete_table again with confirm=true to delete metadata, routes, derived FK/junction structures, the physical table, and all table data.',
+          }, null, 2) }],
+        };
+      }
       const result = await fetchAPI(ENFYRA_API_URL, `/table_definition/${tableId}`, {
         method: 'DELETE',
       });
       return {
         content: [{ type: 'text', text: `Table ${tableId} deleted.\n\n${JSON.stringify(result, null, 2)}` }],
       };
-    }
+    })
   );
 
   // ─── CREATE COLUMN ───
@@ -499,11 +617,12 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       type: z.string().optional().describe('New column type.'),
       isNullable: z.boolean().optional().describe('Set nullable.'),
       isPublished: z.boolean().optional().describe('Set column visibility baseline. false = unpublished (omitted from response unless allowed by field permission rules).'),
+      isUpdatable: z.boolean().optional().describe('Set false for immutable fields that should be stripped from update payloads.'),
       defaultValue: z.string().optional().describe('New default value as JSON string.'),
       description: z.string().optional().describe('New description.'),
       options: z.string().optional().describe('New options as JSON string.'),
     },
-    async ({ tableId, columnId, name, type, isNullable, isPublished, defaultValue, description, options }) => {
+    async ({ tableId, columnId, name, type, isNullable, isPublished, isUpdatable, defaultValue, description, options }) => withSchemaQueue(async () => {
       const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
       if (!tableData) {
         return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
@@ -522,6 +641,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
           if (type !== undefined) rest.type = type;
           if (isNullable !== undefined) rest.isNullable = isNullable;
           if (isPublished !== undefined) rest.isPublished = isPublished;
+          if (isUpdatable !== undefined) rest.isUpdatable = isUpdatable;
           if (defaultValue !== undefined) rest.defaultValue = defaultValue;
           if (description !== undefined) rest.description = description;
           if (options !== undefined) rest.options = JSON.parse(options);
@@ -538,7 +658,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       return {
         content: [{ type: 'text', text: `Column ${columnId} updated on table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
       };
-    }
+    })
   );
 
   // ─── DELETE COLUMN ───

package/src/mcp-server-entry.mjs

@@ -19,6 +19,8 @@ import { fetchAPI, validateFilter, validateTableName } from './lib/fetch.js';
 import { buildMcpServerInstructions, buildGraphqlUrls } from './lib/mcp-instructions.js';
 import { getExamples, listExampleCategories } from './lib/mcp-examples.js';
 import { registerTableTools } from './lib/table-tools.js';
+import { prepareRecordMutation, validateScriptSourceIfPresent } from './lib/mutation-guards.js';
+import { validateMainTableRoutePath } from './lib/route-guards.js';
 
 // Initialize auth module
 initAuth(ENFYRA_API_URL, ENFYRA_API_TOKEN);
@@ -173,6 +175,8 @@ function summarizeTable(table) {
       isPrimary: !!column.isPrimary,
       isNullable: column.isNullable,
       isPublished: column.isPublished,
+      isUpdatable: column.isUpdatable !== false,
+      isEncrypted: column.isEncrypted === true,
     })),
     relations: (table.relations || []).map((relation) => ({
       id: relation.id ?? relation._id,
@@ -323,6 +327,35 @@ function resolveFieldOrThrow(table, fieldName, kind = 'column') {
   return field;
 }
 
+async function prepareGenericMutation(tableName, data) {
+  const { tables } = await getMetadataTables();
+  return prepareRecordMutation({
+    fetchAPI,
+    apiUrl: ENFYRA_API_URL,
+    tables,
+    tableName,
+    data,
+  });
+}
+
+function parseQueryParamsArg(queryParams) {
+  const parsed = parseJsonArg(queryParams, {});
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('queryParams must be a JSON object string.');
+  }
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(parsed)) {
+    if (value === undefined || value === null) continue;
+    params.set(key, String(value));
+  }
+  return params.toString();
+}
+
+function appendQuery(path, queryParams) {
+  if (!queryParams) return path;
+  return `${path}${path.includes('?') ? '&' : '?'}${queryParams}`;
+}
+
 // Create MCP server — `instructions` is sent to the host (e.g. Claude Code) for the LLM; not README
 const server = new McpServer(
   {
@@ -431,7 +464,7 @@ server.tool(
         routeTables: routeTableList,
         noRouteTables,
         canonicalCrudTools: 'query_table/create_record/update_record/delete_record use dynamic REST routes and only work for route-backed tables.',
-        customRouteWorkflow: 'For a new endpoint use create_route against an existing table, then create_handler/create_pre_hook/create_post_hook. Do not create a table just to get a path.',
+        customRouteWorkflow: 'For a new endpoint use create_route without mainTableId, then create_handler/create_pre_hook/create_post_hook. Do not create a table just to get a path.',
       },
       schemaManagement: {
         createTable: 'POST /table_definition supports isSingleRecord at create time and supports columns and relations arrays in the same cascade call. MCP create_table exposes isSingleRecord, columns, and relations directly. It does not accept alias at create time; table name drives the default route/schema behavior.',
@@ -915,31 +948,65 @@ server.tool(
 // CRUD TOOLS
 // ============================================================================
 
-server.tool('create_record', 'Create a new record in any table', {
+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.', {
   tableName: z.string().describe('Table name to insert into'),
   data: z.string().describe('Record data as JSON string'),
-}, async ({ tableName, data }) => {
+  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.'),
+}, async ({ tableName, data, queryParams }) => {
   validateTableName(tableName);
-  const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}`, { method: 'POST', body: data });
-  return { content: [{ type: 'text', text: JSON.stringify(summarizeMutationResult(result, 'created', tableName), null, 2) }] };
+  const prepared = await prepareGenericMutation(tableName, data);
+  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,
+  }, null, 2) }] };
 });
 
-server.tool('update_record', 'Update an existing record by ID using PATCH', {
+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.', {
   tableName: z.string().describe('Table name'),
   id: z.string().describe('Record ID to update'),
   data: z.string().describe('Fields to update as JSON string'),
-}, async ({ tableName, id, data }) => {
+  queryParams: z.string().optional().describe('Optional query params as JSON object string for route contracts that intentionally keep workflow fields out of the validated body.'),
+}, async ({ tableName, id, data, queryParams }) => {
   validateTableName(tableName);
-  const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}/${id}`, { method: 'PATCH', body: data });
-  return { content: [{ type: 'text', text: JSON.stringify(summarizeMutationResult(result, 'updated', tableName), null, 2) }] };
+  const prepared = await prepareGenericMutation(tableName, data);
+  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,
+  }, null, 2) }] };
 });
 
 server.tool('delete_record', 'Delete a record by ID', {
   tableName: z.string().describe('Table name'),
   id: z.string().describe('Record ID to delete'),
-}, async ({ tableName, id }) => {
+  queryParams: z.string().optional().describe('Optional query params as JSON object string for route-specific confirmation contracts.'),
+  confirm: z.boolean().optional().default(false).describe('Required true to apply the destructive delete. Omit/false returns a preview only.'),
+}, async ({ tableName, id, queryParams, confirm }) => {
   validateTableName(tableName);
-  const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}/${id}`, { method: 'DELETE' });
+  const primaryKey = await getPrimaryFieldName(tableName);
+  if (!confirm) {
+    const query = new URLSearchParams({
+      filter: JSON.stringify({ [primaryKey]: { _eq: id } }),
+      limit: '1',
+      fields: primaryKey,
+    });
+    const preview = await fetchAPI(ENFYRA_API_URL, `/${tableName}?${query.toString()}`).catch((error) => ({ error: String(error?.message || error) }));
+    return { content: [{ type: 'text', text: JSON.stringify({
+      action: 'delete_record_preview',
+      tableName,
+      id,
+      primaryKey,
+      preview: preview?.data?.[0] || null,
+      previewError: preview?.error,
+      destructive: true,
+      next: 'Call delete_record again with confirm=true to delete this route-backed record.',
+    }, null, 2) }] };
+  }
+  const query = parseQueryParamsArg(queryParams);
+  const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}/${id}`, query), { method: 'DELETE' });
   return { content: [{ type: 'text', text: JSON.stringify({
     action: 'deleted',
     tableName,
@@ -1406,15 +1473,18 @@ server.tool(
   },
   async ({ path: routePath, mainTableId, methods, publishedMethods, isEnabled, description }) => {
     const methodMap = await getMethodMap();
+    const normalizedPath = normalizeRestPath(routePath);
 
     const body = {
-      path: routePath.startsWith('/') ? routePath : '/' + routePath,
+      path: normalizedPath,
       isEnabled,
       description,
       availableMethods: resolveMethodIds(methodMap, methods),
     };
 
     if (mainTableId !== undefined && mainTableId !== null) {
+      const { tables } = await getMetadataTables();
+      validateMainTableRoutePath(tables, mainTableId, normalizedPath);
       body.mainTable = { id: mainTableId };
     }
 
@@ -1470,6 +1540,10 @@ server.tool(
     if (methodNames.length === 0) throw new Error('Provide method or methods');
     const methodMap = await getMethodMap();
     const results = [];
+    const scriptValidation = await validateScriptSourceIfPresent(fetchAPI, ENFYRA_API_URL, 'route_handler_definition', {
+      sourceCode,
+      scriptLanguage,
+    });
 
     for (const methodName of methodNames) {
       const methodId = methodMap[methodName.toUpperCase()];
@@ -1497,6 +1571,7 @@ server.tool(
     return { content: [{ type: 'text', text: JSON.stringify({
       action: 'created',
       handlers: results,
+      scriptValidation,
       routesReloaded: true,
       detailHint: 'Use inspect_route with the same routeId/path to inspect saved handlers.',
     }, null, 2) }] };
@@ -1515,14 +1590,19 @@ 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 sourceCode. MCP stores it as sourceCode and lets Enfyra compile compiledCode.'),
+    scriptLanguage: z.enum(['javascript', 'typescript']).optional().default('javascript').describe('Script language for compiler. Default javascript.'),
     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)'),
     isEnabled: z.boolean().optional().default(true).describe('Enable hook immediately'),
   },
-  async ({ routeId, name, code, methods, priority, isEnabled }) => {
+  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled }) => {
     const methodMap = await getMethodMap();
     const methodNames = methods || ['GET', 'POST', 'PATCH', 'DELETE'];
+    const scriptValidation = await validateScriptSourceIfPresent(fetchAPI, ENFYRA_API_URL, 'pre_hook_definition', {
+      sourceCode: code,
+      scriptLanguage,
+    });
 
     const result = await fetchAPI(ENFYRA_API_URL, '/pre_hook_definition', {
       method: 'POST',
@@ -1530,7 +1610,7 @@ server.tool(
         route: { id: routeId },
         name,
         sourceCode: code,
-        scriptLanguage: 'javascript',
+        scriptLanguage,
         methods: resolveMethodIds(methodMap, methodNames),
         priority,
         isEnabled,
@@ -1540,7 +1620,15 @@ server.tool(
     await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
 
     const created = firstDataRecord(result);
-    return { content: [{ type: 'text', text: `Pre-hook "${name}" created (ID: ${getId(created)}). Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
+    return { content: [{ type: 'text', text: JSON.stringify({
+      action: 'created',
+      kind: 'pre_hook',
+      id: getId(created),
+      name,
+      routeId,
+      scriptValidation,
+      routesReloaded: true,
+    }, null, 2) }] };
   },
 );
 
@@ -1556,14 +1644,19 @@ 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 sourceCode. MCP stores it as sourceCode and lets Enfyra compile compiledCode.'),
+    scriptLanguage: z.enum(['javascript', 'typescript']).optional().default('javascript').describe('Script language for compiler. Default javascript.'),
     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)'),
     isEnabled: z.boolean().optional().default(true).describe('Enable hook immediately'),
   },
-  async ({ routeId, name, code, methods, priority, isEnabled }) => {
+  async ({ routeId, name, code, scriptLanguage, methods, priority, isEnabled }) => {
     const methodMap = await getMethodMap();
     const methodNames = methods || ['GET', 'POST', 'PATCH', 'DELETE'];
+    const scriptValidation = await validateScriptSourceIfPresent(fetchAPI, ENFYRA_API_URL, 'post_hook_definition', {
+      sourceCode: code,
+      scriptLanguage,
+    });
 
     const result = await fetchAPI(ENFYRA_API_URL, '/post_hook_definition', {
       method: 'POST',
@@ -1571,7 +1664,7 @@ server.tool(
         route: { id: routeId },
         name,
         sourceCode: code,
-        scriptLanguage: 'javascript',
+        scriptLanguage,
         methods: resolveMethodIds(methodMap, methodNames),
         priority,
         isEnabled,
@@ -1581,7 +1674,15 @@ server.tool(
     await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
 
     const created = firstDataRecord(result);
-    return { content: [{ type: 'text', text: `Post-hook "${name}" created (ID: ${getId(created)}). Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
+    return { content: [{ type: 'text', text: JSON.stringify({
+      action: 'created',
+      kind: 'post_hook',
+      id: getId(created),
+      name,
+      routeId,
+      scriptValidation,
+      routesReloaded: true,
+    }, null, 2) }] };
   },
 );