@enfyra/mcp-server 0.0.52 → 0.0.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
   "type": "module",
   "license": "MIT",
@@ -16,7 +16,8 @@
   "scripts": {
     "start": "node src/index.mjs",
     "dev": "node --watch src/index.mjs",
-    "mcp:config": "node src/index.mjs config"
+    "mcp:config": "node src/index.mjs config",
+    "test": "node --test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/src/lib/mcp-examples.js

@@ -216,6 +216,20 @@ create_column({
     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`,
@@ -269,6 +283,23 @@ create_column({
     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

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.',
@@ -70,10 +72,11 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- REST-first workflow for any feature: **`inspect_feature`** to locate candidates → **`inspect_table`** for table/field/relation/rule context → **`inspect_route`** for handlers/hooks/guards/permissions → **`test_rest_endpoint`** to verify the actual HTTP behavior.',
     '- Use **`create_column_rule`** for standard request validation, **`create_field_permission`** for per-field read/create/update rules, **`create_route_permission`** for authenticated route access, and **`create_guard`** for pre/post-auth request gates.',
     '- Prefer these REST inspection/operator tools over raw `query_table` on system tables when changing route behavior. They resolve ids, methods, route paths, code previews, and cache reloads for the model.',
-    '- If the user asks for a **new route**, **URL path**, **custom API endpoint**, **handler**, **pre-hook**, **post-hook**, or to **test** that kind of logic: use MCP **`create_route`** with **`mainTableId`** of an **existing** table (resolve id via **`get_all_tables`**, **`get_all_metadata`**, or **`get_all_routes`**).',
+    '- If the user asks for a **new route**, **URL path**, **custom API endpoint**, **handler**, **pre-hook**, **post-hook**, or to **test** that kind of logic: use MCP **`create_route`** and **omit `mainTableId`**. `mainTable` is only a marker for canonical table routes like `/orders`; custom paths such as `/orders/stats`, `/cloud/admin/hosts`, `/auth/login`, or `/me` must not set it.',
     '- **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).',
+    '- **Right pattern:** **`create_route`** without `mainTableId` → optional **`create_handler`** / **`create_pre_hook`** / **`create_post_hook`** on **that route’s id** (from **`get_all_routes`** after create). Handler/hook code must query explicit repos such as `$ctx.$repos.orders`; do not rely on `$repos.main` for custom routes.',
+    '- **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,8 +106,10 @@ 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)',
-'- Relation fields (mainTable, publishedMethods, availableMethods, handlers, preHooks, postHooks, etc.) use **object references with `id`**:',
-'  - **Many-to-one:** `"mainTable": {"id": 4}` (single object with id)',
+'- 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 (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)',
 '  - **One-to-many / many-to-many:** `"publishedMethods": [{"id": 1}, {"id": 2}]` (array of objects with id)',
 '- **Method IDs** (for REST route publishedMethods, availableMethods, skipRoleGuardMethods): GET=1, POST=2, PATCH=3, DELETE=4. Query `method_definition` table if unsure.',
 '- **Wrong:** `"publishedMethods": ["GET"]` or `"publishedMethods": [{"method": "GET"}]` — rejected or silently ignored.',
@@ -134,6 +139,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- For encrypted persisted fields such as `*_encrypted`, use an Enfyra route pre-hook, not a Knex/database hook. Mutate the body before persistence: `const value = @BODY.field_encrypted; if (value && value.slice(0, 7) !== "enc:v1:") @BODY.field_encrypted = @HELPERS.$encrypt.encrypt(value);`.',
     '- ASV exposes `$helpers.$encrypt.encrypt/decrypt` for encrypted strings and `$helpers.$ssh.generateKeyPair` for SSH keys. Do not generate `$helpers.$secrets` usage.',
     '- Script-backed records use one shared persistence contract: `sourceCode` is the editable source, `scriptLanguage` controls compilation, and `compiledCode` is generated by the server from `sourceCode`. Do not hand-edit or send stale `compiledCode` from generated tools; save `sourceCode`/`scriptLanguage` through `PATCH /<script_table>/<id>` and let the server persist generated `compiledCode` internally. Public metadata may mark `compiledCode` non-updatable, but the server engine must still preserve the generated value after normalization.',
+    '- 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.',
@@ -192,10 +198,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.',
-    '- 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.',
+    '- 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 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.',
-    '- 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.',
+    '- **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.',
     '',
     '### Body validation & column rules',
@@ -214,7 +221,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### Resolving the real REST path',
     '- Do **not** assume `route_definition.path` always equals `table_definition.name`. Paths are data-driven (custom prefixes, renames, multiple routes per table).',
-    '- When unsure of the URL path, use MCP **`get_all_routes`** (or **`get_all_metadata`**) to read each route’s **path** and **mainTable** before stating a full URL.',
+    '- When unsure of the URL path, use MCP **`get_all_routes`** (or **`get_all_metadata`**) to read each route’s **path**. Treat `mainTable` as canonical CRUD-route metadata only, not as the owner table for custom routes.',
     '',
     '### MongoDB vs SQL primary key',
     '- On **SQL**, filters often use **`id`**. On **MongoDB**, documents may use **`_id`** — a filter for one row might be `{"_id":{"_eq":"..."}}` instead of `id`, depending on metadata.',

package/src/lib/table-tools.js

@@ -4,13 +4,42 @@
 import { z } from 'zod';
 import { fetchAPI } from './fetch.js';
 
+export function normalizeTablesFromMetadata(metadata) {
+  const tablesSource = metadata?.data?.tables || metadata?.tables || metadata?.data || [];
+  return Array.isArray(tablesSource)
+    ? tablesSource
+    : Object.values(tablesSource || {});
+}
+
+export function resolveTableFromMetadata(metadata, tableId) {
+  return normalizeTablesFromMetadata(metadata)
+    .find((table) => String(getId(table)) === String(tableId)) || null;
+}
+
 /**
- * Helper: fetch table with columns and relations
+ * Helper: fetch table with full columns and relations.
+ * Dynamic table_definition relation fields can be paginated/truncated, so schema
+ * cascade tools must use /metadata as the complete source of columns/relations.
  */
-async function fetchTableWithDetails(ENFYRA_API_URL, tableId) {
+export async function fetchTableWithDetails(ENFYRA_API_URL, tableId) {
   const filter = encodeURIComponent(JSON.stringify({ id: { _eq: tableId } }));
-  const result = await fetchAPI(ENFYRA_API_URL, `/table_definition?filter=${filter}&limit=1&fields=*,columns.*,relations.*`);
-  return result?.data?.[0] || result?.[0] || null;
+  const [tableResult, metadata] = await Promise.all([
+    fetchAPI(ENFYRA_API_URL, `/table_definition?filter=${filter}&limit=1&fields=*`),
+    fetchAPI(ENFYRA_API_URL, '/metadata'),
+  ]);
+  const tableData = tableResult?.data?.[0] || tableResult?.[0] || null;
+  const metadataTable = resolveTableFromMetadata(metadata, tableId);
+  if (!metadataTable) {
+    throw new Error(`Full metadata for table ${tableId} was not found; refusing schema cascade patch.`);
+  }
+  if (!Array.isArray(metadataTable.columns)) {
+    throw new Error(`Full metadata for table ${tableId} did not include columns; refusing schema cascade patch.`);
+  }
+  return {
+    ...(tableData || metadataTable),
+    columns: metadataTable.columns,
+    relations: Array.isArray(metadataTable.relations) ? metadataTable.relations : [],
+  };
 }
 
 /**
@@ -99,6 +128,41 @@ function getPatchableColumns(columns) {
     .map(normalizeColumnForTablePatch);
 }
 
+function getMissingIds(beforeIds, afterIds, excludedIds = []) {
+  const afterSet = new Set(afterIds.map(String));
+  const excludedSet = new Set(excludedIds.map(String));
+  return beforeIds
+    .map(String)
+    .filter((id) => !excludedSet.has(id) && !afterSet.has(id));
+}
+
+async function verifyColumnCascade(ENFYRA_API_URL, tableId, beforeIds, {
+  action,
+  columnId,
+  columnName,
+}) {
+  const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
+  const afterColumns = getPatchableColumns(tableData.columns);
+  const afterIds = afterColumns.map((column) => String(getId(column)));
+  const excludedIds = action === 'delete' ? [columnId] : [];
+  const missingIds = getMissingIds(beforeIds, afterIds, excludedIds);
+  if (missingIds.length > 0) {
+    throw new Error(`Schema cascade verification failed: unrelated column ids disappeared: ${missingIds.join(', ')}`);
+  }
+
+  if (action === 'create' && !afterColumns.some((column) => column.name === columnName)) {
+    throw new Error(`Schema cascade verification failed: column "${columnName}" was not found after create.`);
+  }
+  if (action === 'delete' && afterIds.includes(String(columnId))) {
+    throw new Error(`Schema cascade verification failed: column ${columnId} still exists after delete.`);
+  }
+  if (action === 'update' && !afterIds.includes(String(columnId))) {
+    throw new Error(`Schema cascade verification failed: column ${columnId} was not found after update.`);
+  }
+
+  return afterColumns;
+}
+
 function buildColumnDefinition({
   name,
   type,
@@ -138,8 +202,13 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     }
 
     const existingColumns = getPatchableColumns(tableData.columns);
+    const beforeIds = existingColumns.map((column) => String(getId(column)));
     const newCol = buildColumnDefinition(args);
     const result = await patchTableAutoConfirm(ENFYRA_API_URL, args.tableId, { columns: [...existingColumns, newCol] });
+    await verifyColumnCascade(ENFYRA_API_URL, args.tableId, beforeIds, {
+      action: 'create',
+      columnName: args.name,
+    });
 
     return {
       content: [{ type: 'text', text: `Column "${args.name}" added to table ${args.tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
@@ -170,12 +239,20 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
     }
 
-    const columns = (tableData.columns || [])
-      .filter((col) => getId(col) !== null)
+    const existingColumns = getPatchableColumns(tableData.columns);
+    const beforeIds = existingColumns.map((column) => String(getId(column)));
+    if (!beforeIds.includes(String(columnId))) {
+      throw new Error(`Column ${columnId} was not found on table ${tableId}; refusing schema cascade patch.`);
+    }
+
+    const columns = existingColumns
       .filter(col => String(getId(col)) !== String(columnId))
-      .map(normalizeColumnForTablePatch);
 
     const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, { columns });
+    await verifyColumnCascade(ENFYRA_API_URL, tableId, beforeIds, {
+      action: 'delete',
+      columnId,
+    });
 
     return {
       content: [{ type: 'text', text: `Column ${columnId} deleted from table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
@@ -256,7 +333,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     'create_table',
     [
       'Create a new table definition with an auto-included `id` primary key column.',
-      '**Not** for adding a custom API path or handler only — for that use **`create_route`** with an existing `mainTableId`. Use **`create_table`** when the user needs new stored data (new entity).',
+      '**Not** for adding a custom API path or handler only — for that use **`create_route`** without `mainTableId`. Use **`create_table`** when the user needs new stored data (new entity).',
       'PREFERRED: pass `columns` and `relations` params as JSON arrays to create a table WITH columns and relations in one call (cascade). Only use create_column/create_relation separately when adding to an existing table later.',
       'Indexes and uniques are first-class table metadata. Use `indexes` for query performance and `uniques` for data integrity. Each entry is a logical field group such as [["member","isRead","conversation"]] or [{"value":["message","member"]}]. Relation property names are allowed; Enfyra resolves them to physical FK columns.',
       'Relations are supported in this same create_table call when the target table already exists. Each relation uses { targetTable, type, propertyName, inversePropertyName?, mappedBy?, isNullable?, onDelete? }; targetTable may be a table id or {id}.',
@@ -383,7 +460,7 @@ 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, keeps only persisted column rows with id/_id, appends the new one, and PATCHes the table.',
+      'This tool reads full table metadata, keeps only persisted column rows with id/_id, appends the new one, PATCHes the table, and verifies unrelated columns survived.',
       '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(' '),
@@ -398,7 +475,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.',
+      'Reads full table metadata and 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,
@@ -411,7 +488,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     'update_column',
     [
       'Update an existing column on a table via PATCH /table_definition/{tableId}.',
-      'Fetches table columns, keeps only persisted rows with id/_id, modifies the target column, and PATCHes the table.',
+      'Reads full table metadata, keeps only persisted rows with id/_id, modifies the target column, PATCHes the table, and verifies unrelated columns survived.',
       '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(' '),
@@ -432,7 +509,13 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
       }
 
-      const columns = (tableData.columns || []).filter((col) => getId(col) !== null).map(col => {
+      const existingColumns = getPatchableColumns(tableData.columns);
+      const beforeIds = existingColumns.map((column) => String(getId(column)));
+      if (!beforeIds.includes(String(columnId))) {
+        throw new Error(`Column ${columnId} was not found on table ${tableId}; refusing schema cascade patch.`);
+      }
+
+      const columns = existingColumns.map(col => {
         const rest = normalizeColumnForTablePatch(col);
         if (String(getId(col)) === String(columnId)) {
           if (name !== undefined) rest.name = name;
@@ -447,6 +530,10 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       });
 
       const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, { columns });
+      await verifyColumnCascade(ENFYRA_API_URL, tableId, beforeIds, {
+        action: 'update',
+        columnId,
+      });
 
       return {
         content: [{ type: 'text', text: `Column ${columnId} updated on table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
@@ -460,7 +547,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     'delete_column',
     [
       'Delete a column from a table via PATCH /table_definition/{tableId}.',
-      'Fetches table columns, keeps only persisted rows with id/_id, removes the target, and PATCHes the table.',
+      'Reads full table metadata, keeps only persisted rows with id/_id, removes the target, PATCHes the table, and verifies unrelated columns survived.',
       '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(' '),
@@ -475,7 +562,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.',
+      'Reads full table metadata and 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

@@ -32,7 +32,7 @@ const CAPABILITY_AREAS = [
   {
     area: 'Dynamic REST API',
     tables: ['route_definition', 'route_handler_definition', 'pre_hook_definition', 'post_hook_definition', 'route_permission_definition', 'method_definition'],
-    workflow: 'Create paths with create_route on an existing main table, then add handlers/hooks. REST methods are GET/POST/PATCH/DELETE.',
+    workflow: 'Create custom paths with create_route without mainTableId, then add handlers/hooks. mainTableId is only for canonical table routes like /table_name. REST methods are GET/POST/PATCH/DELETE.',
   },
   {
     area: 'Auth, roles, sessions, OAuth',
@@ -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,26 +1348,55 @@ 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(
   'create_route',
   [
-    '**Use this when the user wants a new REST API route or path** — not `create_table`. A route links a URL path to an existing table (`mainTableId`) and sets HTTP methods.',
-    'Do NOT create a new table_definition only to expose an endpoint; pick `mainTableId` from existing metadata unless the user explicitly needs new tables/columns.',
+    '**Use this when the user wants a new REST API route or path** — not `create_table`. Custom routes must omit `mainTableId`.',
+    '`mainTableId` is only a marker for canonical table routes such as `/orders`; do not set it for `/orders/stats`, `/cloud/admin/hosts`, `/auth/login`, or any custom path.',
+    'Do NOT create a new table_definition only to expose an endpoint; create a route without `mainTableId`, then have the handler/hook query explicit repos such as `$ctx.$repos.orders`.',
     'availableMethods = which REST verbs the route responds to. publishedMethods = which REST verbs are public (no auth). GraphQL is enabled separately through gql_definition/update_table graphqlEnabled.',
     'After creation the tool auto-reloads routes. Then create handlers for specific methods via create_handler on this route id.',
-    'Flow: resolve table id → create_route → create_handler (per method) → optionally create_pre_hook / create_post_hook → test via HTTP or admin test APIs (see server instructions).',
+    'Flow: create_route → create_handler (per method) → optionally create_pre_hook / create_post_hook → test via HTTP or admin test APIs (see server instructions).',
   ].join(' '),
   {
     path: z.string().describe('URL path, must start with / (e.g., "/my-endpoint")'),
-    mainTableId: z.union([z.string(), z.number()]).describe('ID of the table_definition this route operates on. The route\'s $repos.main will query this table.'),
+    mainTableId: z.union([z.string(), z.number()]).optional().describe('Only set for the canonical table route `/<table_name>`. Omit for every custom route.'),
     methods: z.array(z.enum(['GET', 'POST', 'PATCH', 'DELETE']))
       .describe('HTTP methods this route supports (availableMethods). Common: ["GET","POST","PATCH","DELETE"]'),
     publishedMethods: z.array(z.enum(['GET', 'POST', 'PATCH', 'DELETE'])).optional()
@@ -1266,12 +1409,15 @@ server.tool(
 
     const body = {
       path: routePath.startsWith('/') ? routePath : '/' + routePath,
-      mainTable: { id: mainTableId },
       isEnabled,
       description,
       availableMethods: resolveMethodIds(methodMap, methods),
     };
 
+    if (mainTableId !== undefined && mainTableId !== null) {
+      body.mainTable = { id: mainTableId };
+    }
+
     if (publishedMethods && publishedMethods.length > 0) {
       body.publishedMethods = resolveMethodIds(methodMap, publishedMethods);
     }
@@ -1284,7 +1430,18 @@ server.tool(
     await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
 
     const created = firstDataRecord(result);
-    return { content: [{ type: 'text', text: `Route created (ID: ${getId(created)}). Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
+    return { content: [{ type: 'text', text: JSON.stringify({
+      action: 'created',
+      route: {
+        id: getId(created),
+        path: created?.path,
+        mainTableId: mainTableId ?? null,
+        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) }] };
   },
 );
 
@@ -1293,38 +1450,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) }] };
   },
 );