@enfyra/mcp-server 0.0.61 → 0.0.63

package/README.md

@@ -3,7 +3,7 @@
 MCP server for managing Enfyra instances from **Codex**, **Claude Code**, **Cursor**, and other MCP-compatible clients. All operations go through Enfyra's REST API.
 
 
-**LLM rules (REST, GraphQL, auth, URL, mutation `create_{tableName}`, etc.):** not in this README — see **`src/lib/mcp-instructions.js`** (content sent via MCP `instructions`), **`src/lib/mcp-examples.js`** (concrete examples loaded through `get_enfyra_examples`), and tool descriptions in **`src/index.mjs`**. This README only covers **MCP installation and configuration** for users/devs.
+**LLM rules (REST, GraphQL, auth, URL, mutation `create_{tableName}`, etc.):** not in this README — see **`src/lib/mcp-instructions.js`** (content sent via MCP `instructions`), **`src/lib/mcp-examples.js`** (concrete examples loaded through `get_enfyra_examples`), and tool descriptions in **`src/mcp-server-entry.mjs`**. This README only covers **MCP installation and configuration** for users/devs.
 
 **Official docs:** [Claude Code MCP](https://docs.anthropic.com/en/docs/claude-code/mcp) · [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings) · [Cursor MCP (`mcp.json`)](https://cursor.com/docs/context/mcp)
 
@@ -186,6 +186,10 @@ Use this block in any host-specific `mcp.json` / `mcpServers` merge (adjust env
 
 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.
 
+Quick checklist for a new LLM using Enfyra MCP: discover the live system first, inspect the specific table/route, load the matching example category, mutate with explicit fields and relation property names, validate or test scripts/routes before relying on them, re-read the saved row when mutation output is summarized, and preview destructive operations before confirming.
+
+Use `update_script_source` when updating existing long script-backed records such as `flow_step_definition`, `route_handler_definition`, hook tables, websocket scripts, GraphQL scripts, or bootstrap scripts. It accepts raw `sourceCode` directly, validates the source, and saves `sourceCode`/`scriptLanguage` without requiring the caller to manually JSON-escape the full script. Use generic `update_record` for small record patches or patches that include non-script metadata fields.
+
 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, a renewal workflow can keep `expires_at=YYYY-MM-DD` in the URL query while `validateBody` remains enabled for the table body.
 
 ### `ENFYRA_API_URL` — use the app proxy

package/package.json

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

package/src/lib/mcp-examples.js

@@ -249,7 +249,7 @@ create_column({
   },
   'queries-deep': {
     title: 'REST queries, filters, meta counts, and deep relation fetches',
-    useWhen: 'Use when fetching records, filtering by relations, loading nested data, or counting efficiently.',
+    useWhen: 'Use when fetching records, filtering by relations, loading nested relation data in the same request, or counting efficiently.',
     examples: [
       {
         name: 'Minimal MCP query then explicit detail query',
@@ -293,28 +293,64 @@ GET /enfyra/post?filter={"<primaryKeyFromMetadata>":{"_eq":123}}&limit=1`,
       },
       {
         name: 'Count without loading all rows',
-        code: `GET /enfyra/chat_message_read?fields=id&limit=1&meta=filterCount&filter={
-  "member": { "id": { "_eq": "<currentUserId>" } },
-  "isRead": { "_eq": false }
-}`,
+        code: `query_table({
+  tableName: "chat_message_read",
+  fields: ["id"],
+  limit: 1,
+  meta: "filterCount",
+  filter: JSON.stringify({
+    member: { id: { _eq: "<currentUserId>" } },
+    isRead: { _eq: false }
+  })
+})`,
         notes: [
           'Use meta=totalCount with no filter and meta=filterCount with a filter.',
+          'MCP count_records wraps this pattern for simple counts.',
           'Do not fetch all rows only to count them.',
         ],
       },
       {
-        name: 'Deep relation query',
-        code: `GET /enfyra/order?fields=id,total,customer&deep={
-  "customer": { "fields": "id,email,displayName" },
-  "items": {
-    "fields": "id,quantity,product",
-    "limit": 20,
-    "deep": {
-      "product": { "fields": "id,name,price" }
+        name: 'Relation fields without deep',
+        code: `query_table({
+  tableName: "order",
+  fields: [
+    "id",
+    "total",
+    "customer.id",
+    "customer.email",
+    "customer.displayName"
+  ],
+  limit: 20
+})`,
+        notes: [
+          'Use fields with dotted relation paths when you only need scalar fields from related records.',
+          'This is enough for simple many-to-one or one-to-one relation display such as owner.email, customer.name, or lastMessage.text.',
+          'Do not add deep when fields alone can express the relation data you need.',
+        ],
+      },
+      {
+        name: 'Deep relation query options',
+        code: `query_table({
+  tableName: "order",
+  fields: ["id", "total"],
+  deep: JSON.stringify({
+    items: {
+      fields: "id,quantity,product",
+      sort: "-createdAt",
+      limit: 20,
+      deep: {
+        product: { fields: "id,name,price" }
+      }
     }
-  }
-}`,
+  })
+})`,
         notes: [
+          'Use deep when relation loading needs query options such as filter, sort, limit, page, or nested deep.',
+          'Deep is mainly useful for controlled child collections or nested relation fetches, not for basic related-field display.',
+          'Do not use deep just to filter by a relation id; use a normal relation filter instead.',
+          'Do not use deep for counts; use count_records or meta=filterCount/totalCount.',
+          'Do not deep-load large child collections without an explicit limit/page. For heavy screens, fetch the parent list first, then load the selected child collection separately with pagination.',
+          'Use query_table deep for normal MCP reads; use test_rest_endpoint only when you need a custom raw URL or route behavior test.',
           'deep keys must be relation property names.',
           'Allowed deep options are fields, filter, sort, limit, page, and deep.',
           'Do not invent deep keys like members unless members is a relation on that table.',
@@ -512,11 +548,12 @@ return @DATA\`
   tableName: "user_definition",
   columnName: "email",
   ruleType: "format",
-  ruleConfig: JSON.stringify({ format: "email" }),
+  value: JSON.stringify({ v: "email" }),
   message: "Please enter a valid email address"
 })`,
         notes: [
           'Column rules validate canonical POST/PATCH body payloads.',
+          'The rule value payload uses the { v: ... } shape; do not pass ruleConfig.',
           'Use column rules before writing custom validation code when the rule is simple.',
         ],
       },
@@ -767,16 +804,24 @@ const uploaded = await fetch("/enfyra/files/upload", {
       },
       {
         name: 'Use uploaded file in handler',
-        code: `const file = $ctx.$uploadedFile
+        code: `const file = @UPLOADED_FILE
 if (!file) @THROW400("File is required")
 
-return {
-  filename: file.originalname,
-  mimetype: file.mimetype,
-  size: file.size
-}`,
+const saved = await @STORAGE.$upload({
+  file,
+  storageConfig: @BODY.storageConfig,
+  folder: @BODY.folder,
+  title: @BODY.title,
+  description: @BODY.description
+})
+
+return saved`,
         notes: [
           'Use file-specific context only in upload-capable routes.',
+          'For request uploads, pass file: @UPLOADED_FILE to @STORAGE.$upload/@STORAGE.$update so Enfyra streams from the temp file path.',
+          'Use @STORAGE.$registerFile when an external process already uploaded the object and the script only needs to create the file_definition record.',
+          'Do not read @UPLOADED_FILE.path into a Buffer and do not generate examples using @UPLOADED_FILE.buffer.',
+          'Use buffer only for small generated or transformed files, such as image thumbnails.',
         ],
       },
     ],

package/src/lib/mcp-instructions.js

@@ -29,6 +29,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `**Full URL:** base + path segment. Example for table \`post\`: \`${examplePost}\`.`,
     '',
     '### First-step rule: discover before answering architecture/capability questions',
+    '- **New LLM checklist:** discover live context first → inspect the specific table/route → load matching examples → mutate with explicit fields and relation property names → validate/test scripts or routes → re-read saved rows when mutation output is summarized → preview destructive actions before confirming.',
     '- If the user asks what Enfyra supports, how to build a feature, which API exists, or whether a tool/schema path can do something, call **`discover_enfyra_system`** first. It reads live metadata, route definitions, method rows, route-backed tables, no-route tables, and capability areas.',
     '- If the question depends on DB type, primary key convention, cache/reload/runtime state, active GraphQL/flow/websocket/storage counts, or admin surfaces, call **`discover_runtime_context`**.',
     '- If the question depends on filters, sorting, deep relations, relation property names, field permissions, or table-specific query examples, call **`discover_query_capabilities`**; pass `tableName` when known.',
@@ -109,6 +110,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
 '- 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.',
+'- For long script updates on existing flow steps, handlers, hooks, websocket scripts, GraphQL scripts, or bootstrap scripts, prefer **`update_script_source`** over generic `update_record`. It accepts raw `sourceCode` as a normal tool argument, validates it, then PATCHes `sourceCode`/`scriptLanguage`; this avoids brittle manual JSON escaping for large scripts.',
 '- 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.',
@@ -138,16 +140,18 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- You may **mutate** `@DATA` / `$ctx.$data` in place, or **return** a value: a non-`undefined` return replaces `$ctx.$data` as the response body.',
     '',
     '### 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`. `$ctx.$env` currently has no macro; access it directly when needed.',
+    '- When writing server-side Enfyra scripts, prefer template macros over raw `$ctx` access: use `@BODY`, `@QUERY`, `@PARAMS`, `@USER`, `@REPOS`, `@HELPERS`, `@STORAGE`, `@SOCKET`, `@TRIGGER`, `@DATA`, `@ERROR`, `@ENV`, 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 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. Do not generate new route pre-hooks for manual encryption.',
     '- Enfyra scripts use `$helpers.$crypto` for bounded crypto helpers such as `randomUUID()`, `randomBytes(size, encoding)`, `sha256(value, encoding)`, `hmacSha256(value, secret, encoding)`, and `generateSshKeyPair(comment)`. Do not generate legacy `$helpers.$ssh` or `$helpers.$secrets` usage.',
     '- `$ctx.$env` exposes only a sanitized process env snapshot. Current OSS deny keys are exact matches: `DB_URI`, `DB_REPLICA_URIS`, `REDIS_URI`, `SECRET_KEY`, and `ADMIN_PASSWORD`. Do not read secrets from `$ctx.$env`; model app secrets as unpublished `isEncrypted=true` fields instead.',
     '- 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.',
+    '- Use MCP `update_script_source` for existing long script-backed records so callers pass raw source text instead of hand-escaped JSON strings. Use generic `update_record` only when the patch is small or includes non-script metadata fields.',
     '- 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.',
     '- Before saving generated script code, validate it with `POST /admin/script/validate` when available. It compiles with the server kernel and parses the executable async body without running side effects. Enfyra App `FormCodeEditor` also exposes a `Validate` action for this endpoint; use it before save/run when editing through the UI. If unavailable, use `run_admin_test`/`test_flow_step` as the closest validation path before saving.',
     '- Do not coerce dynamic script values with `String(...)`, `Number(...)`, or `Boolean(...)`. Enfyra payloads, user ids, record ids, and relation ids should keep their runtime type; validate required values and pass them through directly.',
+    '- Multipart request files are exposed as `@UPLOADED_FILE` / `$ctx.$uploadedFile` metadata with a server temp-file path. To save or replace that request file, call `@STORAGE.$upload({ file: @UPLOADED_FILE, ... })` or `@STORAGE.$update(id, { file: @UPLOADED_FILE, ... })` so Enfyra streams from disk. To register an object that already exists in storage without uploading bytes, call `@STORAGE.$registerFile({ filename, mimetype, location, size, storageConfig, ... })`. Do not generate `@UPLOADED_FILE.buffer` examples or read the temp file into a Buffer. Use `buffer` only for small generated/transformed files.',
     '- Use raw `$ctx` only when there is no template macro for the field or helper you need.',
     '- Preferred: `const result = await @REPOS.main.create({ data: @BODY });`.',
     '- Avoid: `const result = await $ctx.$repos.main.create({ data: $ctx.$body });` unless the script truly needs an unmapped `$ctx` property.',
@@ -236,6 +240,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Full filter operators: `_eq`, `_neq`, `_gt`, `_gte`, `_lt`, `_lte`, `_in`, `_not_in`, `_nin`, `_contains`, `_starts_with`, `_ends_with`, `_between`, `_is_null`, `_is_not_null`, `_and`, `_or`, `_not`.',
     '- Field permission condition DSL is narrower and does not support `_contains`, `_starts_with`, `_ends_with`, or `_between`.',
     '- Deep shape: `{ relationName: { fields?, filter?, sort?, limit?, page?, deep? } }`. Relation keys are relation `propertyName`, not physical FK columns.',
+    '- Use dotted relation fields such as `owner.email` or `lastMessage.text` when the caller only needs basic related record fields. Use `deep` when relation loading needs query options such as `filter`, `sort`, `limit`, `page`, or nested `deep`. Do not use `deep` for simple relation-id filters, one-row lookup, counts, or large child collections that should be loaded separately with pagination.',
     '- Deep validation rejects unknown relation keys, unknown subkeys, `limit` on many-to-one/one-to-one, and invalid dotted sort through many-side relations.',
     '- To count records over REST, do not fetch full rows. Use MCP **`count_records`**, or call `GET /<table>?fields=id&limit=1&meta=totalCount` without filter and read `meta.totalCount`; with a filter use `meta=filterCount` and read `meta.filterCount`.',
     '- In custom dynamic code, use the same lightweight pattern: `const result = await @REPOS.main.find({ fields: "id", limit: 1, meta: filter ? "filterCount" : "totalCount", ...(filter ? { filter } : {}) }); const count = filter ? result.meta?.filterCount : result.meta?.totalCount;`.',
@@ -407,11 +412,12 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `- \`discover_runtime_context\` → GET metadata/routes/method/runtime-backed tables and infer live primary key/backend context`,
     `- \`discover_query_capabilities\` → GET metadata/routes and summarize Query DSL/deep/table-specific query contracts`,
     `- \`discover_script_contexts\` → static runtime macro/context map for handlers/hooks/flows/websocket/GraphQL/extensions`,
-    `- \`query_table\` → GET \`${base}/<tableName>?…\` (query string from tool args)`,
+    `- \`query_table\` → GET \`${base}/<tableName>?…\` (query string from tool args, including filter/sort/page/limit/fields plus optional meta/deep/aggregate)`,
     `- \`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>\` (optional tool queryParams append URL query)`,
     `- \`update_record\` → PATCH \`${base}/<tableName>/<id>\` (optional tool queryParams append URL query)`,
+    `- \`update_script_source\` → validates sourceCode with \`${base}/admin/script/validate\`, then PATCHes \`${base}/<script_table>/<id>\``,
     `- \`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.`,

package/src/mcp-server-entry.mjs

@@ -258,6 +258,23 @@ function parseJsonArg(value, fallback = undefined) {
   return JSON.parse(value);
 }
 
+async function reloadRoutesResult() {
+  try {
+    const result = await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' });
+    return {
+      attempted: true,
+      succeeded: true,
+      result,
+    };
+  } catch (error) {
+    return {
+      attempted: true,
+      succeeded: false,
+      error: error?.message || String(error),
+    };
+  }
+}
+
 function normalizeRestPath(path) {
   if (!path) return '/';
   if (/^https?:\/\//i.test(path)) {
@@ -698,15 +715,17 @@ server.tool(
     const payload = {
       transformer: {
         rule: 'Dynamic server scripts are transformed before sandbox execution. Macros expand to $ctx paths; comments are not transformed.',
-        preferredSyntax: 'Prefer template macros in generated Enfyra scripts. Use @BODY/@QUERY/@PARAMS/@USER/@REPOS/@CACHE/@HELPERS/@SOCKET/@TRIGGER/@DATA/@ERROR/@THROW* instead of raw $ctx access whenever a macro exists. Use raw $ctx only for fields without a macro.',
+        preferredSyntax: 'Prefer template macros in generated Enfyra scripts. Use @BODY/@QUERY/@PARAMS/@USER/@REPOS/@CACHE/@HELPERS/@STORAGE/@SOCKET/@TRIGGER/@DATA/@ERROR/@ENV/@THROW* instead of raw $ctx access whenever a macro exists. Use raw $ctx only for fields without a macro.',
         coreMacros: {
           '@BODY': '$ctx.$body',
           '@QUERY': '$ctx.$query',
           '@PARAMS': '$ctx.$params',
           '@USER': '$ctx.$user',
+          '@ENV': '$ctx.$env',
           '@REPOS': '$ctx.$repos',
           '@CACHE': '$ctx.$cache',
           '@HELPERS': '$ctx.$helpers',
+          '@STORAGE': '$ctx.$storage',
           '@SOCKET': '$ctx.$socket',
           '@DATA': '$ctx.$data',
           '@STATUS': '$ctx.$statusCode',
@@ -731,20 +750,21 @@ server.tool(
         throws: '@THROW400 through @THROW503 and @THROW map to $ctx.$throw helpers.',
         helpers: {
           crypto: '$ctx.$helpers.$crypto exposes bounded runtime crypto helpers: randomUUID(), randomBytes(size, encoding), sha256(value, encoding), hmacSha256(value, secret, encoding), and generateSshKeyPair(comment). Use generateSshKeyPair for SSH key material. Do not use legacy $ctx.$helpers.$ssh.',
+          files: '$ctx.$storage.$upload and $ctx.$storage.$update accept file: @UPLOADED_FILE for request uploads and stream from the server temp file path. $ctx.$storage.$registerFile creates a file_definition record for an object that already exists in storage without uploading bytes. Use buffer only for small generated/transformed files; do not use @UPLOADED_FILE.buffer.',
         },
         env: '$ctx.$env exposes a sanitized process env snapshot with exact sensitive keys removed: DB_URI, DB_REPLICA_URIS, REDIS_URI, SECRET_KEY, and ADMIN_PASSWORD. Store app secrets in unpublished isEncrypted fields instead of reading them from $env.',
       },
       contexts: {
         preHook: {
           runs: 'Before handler.',
-          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REPOS', '@CACHE', '@HELPERS', '@THROW*', '@SOCKET emit helpers'],
+          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REPOS', '@CACHE', '@HELPERS', '@STORAGE', '@THROW*', '@SOCKET emit helpers'],
           queryContract: '@QUERY.filter is initialized as an object. When adding RLS/scope filters in pre-hooks, merge directly with _and; do not add defensive type checks around @QUERY.filter.',
           rlsPattern: 'For relation-scoped reads, mutate @QUERY.filter instead of returning data. Example: const incomingFilter = @QUERY.filter; const scope = { memberships: { member: { id: { _eq: @USER.id } } } }; @QUERY.filter = Object.keys(incomingFilter).length ? { _and: [incomingFilter, scope] } : scope;',
           returnBehavior: 'Returning a non-undefined value skips handler and becomes response data.',
         },
         handler: {
           runs: 'Main route logic, or canonical CRUD if no handler overrides.',
-          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REPOS.main', '@REPOS.secure', '@CACHE', '@HELPERS', '@PKGS', '@SOCKET emit helpers', '@TRIGGER'],
+          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@UPLOADED_FILE for multipart request file metadata', '@REPOS.main', '@REPOS.secure', '@CACHE', '@HELPERS', '@STORAGE', '@PKGS', '@SOCKET emit helpers', '@TRIGGER'],
           returnBehavior: 'Return value becomes response body unless post-hook changes it.',
         },
         postHook: {
@@ -754,7 +774,7 @@ server.tool(
         },
         flowStep: {
           runs: 'Inside flow execution or admin flow step test.',
-          data: ['@FLOW_PAYLOAD', '@FLOW_LAST', '@FLOW', '@FLOW_META', '#table_name', '@CACHE', '@HELPERS', '@SOCKET', '@TRIGGER'],
+          data: ['@FLOW_PAYLOAD', '@FLOW_LAST', '@FLOW', '@FLOW_META', '#table_name', '@CACHE', '@HELPERS', '@STORAGE', '@SOCKET', '@TRIGGER'],
           resultBehavior: 'Step return value is injected into @FLOW.<step.key> and @FLOW_LAST.',
           branching: 'Condition steps use JavaScript truthy/falsy result; child branch is true/false.',
         },
@@ -788,7 +808,7 @@ server.tool(
         },
         socketInHttpOrFlow: 'HTTP/flow context can emitToUser/emitToRoom/emitToGateway/broadcast, but cannot reply/join/leave/disconnect because there is no bound socket.',
         packages: 'Server packages installed through install_package are exposed as $ctx.$pkgs.packageName in server scripts.',
-        files: 'Upload helpers are on $helpers; raw create_record on file_definition is not equivalent to multipart upload/storage rollback.',
+        files: 'Upload helpers are on $storage; raw create_record on file_definition is not equivalent to multipart upload/storage rollback. For multipart request files, pass file: @UPLOADED_FILE to @STORAGE.$upload/@STORAGE.$update so Enfyra streams from disk-backed temp storage. Use @STORAGE.$registerFile only when the object already exists in storage and the script should create the file_definition record without uploading bytes. Use buffer only for small generated files.',
       },
       adminTesting: {
         flowStep: 'Use test_flow_step or run_admin_test(kind=flow_step).',
@@ -846,15 +866,23 @@ server.tool('query_table', 'Query any route-backed table. Default response is mi
   page: z.number().optional().describe('Page number (default: 1)'),
   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 }) => {
+  meta: z.string().optional().describe('Optional REST meta request, e.g. "totalCount", "filterCount", or aggregate modes supported by the route. Use count_records for simple counts.'),
+  deep: z.string().optional().describe('Optional deep relation fetch object as JSON string. Keys must be relation propertyName values.'),
+  aggregate: z.string().optional().describe('Optional aggregate object as JSON string, keyed by real fields/relations. Results are returned in response.meta.aggregate when supported.'),
+}, async ({ tableName, filter, sort, page, limit, fields, meta, deep, aggregate }) => {
   validateTableName(tableName);
   validateFilter(filter);
+  parseJsonArg(deep, undefined);
+  parseJsonArg(aggregate, undefined);
 
   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 (meta) queryParams.set('meta', meta);
+  if (deep) queryParams.set('deep', deep);
+  if (aggregate) queryParams.set('aggregate', aggregate);
   queryParams.set('limit', String(limit || 10));
   queryParams.set('fields', selectedFields.join(','));
 
@@ -866,6 +894,11 @@ server.tool('query_table', 'Query any route-backed table. Default response is mi
     tableName,
     fields: selectedFields,
     limit: limit || 10,
+    queryOptions: {
+      meta: meta || null,
+      deep: deep ? parseJsonArg(deep, null) : null,
+      aggregate: aggregate ? parseJsonArg(aggregate, null) : null,
+    },
     minimalDefaultApplied: !(fields && fields.length > 0),
     meta: result?.meta,
     data: result?.data || [],
@@ -1008,6 +1041,49 @@ server.tool('update_record', 'Update an existing record by ID using PATCH. The t
   }, null, 2) }] };
 });
 
+server.tool(
+  'update_script_source',
+  [
+    'Update sourceCode on a script-backed record without forcing the caller to JSON-escape long code.',
+    'Use this for flow_step_definition, route_handler_definition, pre_hook_definition, post_hook_definition, websocket_event_definition, websocket_definition, gql_definition, and bootstrap_script_definition.',
+    'The tool validates sourceCode through /admin/script/validate before saving and never accepts compiledCode.',
+  ].join(' '),
+  {
+    tableName: z.enum([
+      'route_handler_definition',
+      'pre_hook_definition',
+      'post_hook_definition',
+      'flow_step_definition',
+      'websocket_event_definition',
+      'websocket_definition',
+      'gql_definition',
+      'bootstrap_script_definition',
+    ]).describe('Script-backed table to update'),
+    id: z.string().describe('Record ID to update'),
+    sourceCode: z.string().describe('Editable script sourceCode. Pass the raw code string; do not JSON-escape it yourself.'),
+    scriptLanguage: z.string().optional().default('javascript').describe('Script language, usually javascript or typescript'),
+  },
+  async ({ tableName, id, sourceCode, scriptLanguage }) => {
+    validateTableName(tableName);
+    const prepared = await prepareGenericMutation(
+      tableName,
+      JSON.stringify({ sourceCode, scriptLanguage }),
+    );
+    const result = await fetchAPI(
+      ENFYRA_API_URL,
+      `/${tableName}/${encodeURIComponent(String(id))}`,
+      { method: 'PATCH', body: JSON.stringify(prepared.payload) },
+    );
+    return { content: [{ type: 'text', text: JSON.stringify({
+      ...summarizeMutationResult(result, 'updated_script_source', tableName),
+      id,
+      sourceLength: sourceCode.length,
+      scriptLanguage,
+      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'),
@@ -1695,7 +1771,7 @@ server.tool(
       body: JSON.stringify(body),
     });
 
-    await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
+    const routeReload = await reloadRoutesResult();
 
     const created = firstDataRecord(result);
     return { content: [{ type: 'text', text: JSON.stringify({
@@ -1707,7 +1783,7 @@ server.tool(
         availableMethods: methods,
         publishedMethods: publishedMethods || [],
       },
-      routesReloaded: true,
+      routeReload,
       next: `Use create_handler({ routeId: ${JSON.stringify(getId(created))}, method: "GET", sourceCode }) for custom code. Create extra method_definition.name rows first for custom methods such as PUT.`,
     }, null, 2) }] };
   },
@@ -1764,13 +1840,13 @@ server.tool(
       });
     }
 
-    await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
+    const routeReload = await reloadRoutesResult();
 
     return { content: [{ type: 'text', text: JSON.stringify({
       action: 'created',
       handlers: results,
       scriptValidation,
-      routesReloaded: true,
+      routeReload,
       detailHint: 'Use inspect_route with the same routeId/path to inspect saved handlers.',
     }, null, 2) }] };
   },
@@ -1815,7 +1891,7 @@ server.tool(
       }),
     });
 
-    await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
+    const routeReload = await reloadRoutesResult();
 
     const created = firstDataRecord(result);
     return { content: [{ type: 'text', text: JSON.stringify({
@@ -1825,7 +1901,7 @@ server.tool(
       name,
       routeId,
       scriptValidation,
-      routesReloaded: true,
+      routeReload,
     }, null, 2) }] };
   },
 );
@@ -1869,7 +1945,7 @@ server.tool(
       }),
     });
 
-    await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
+    const routeReload = await reloadRoutesResult();
 
     const created = firstDataRecord(result);
     return { content: [{ type: 'text', text: JSON.stringify({
@@ -1879,7 +1955,7 @@ server.tool(
       name,
       routeId,
       scriptValidation,
-      routesReloaded: true,
+      routeReload,
     }, null, 2) }] };
   },
 );
@@ -2004,8 +2080,14 @@ server.tool(
       method: 'POST',
       body: JSON.stringify(body),
     });
-    await fetchAPI(ENFYRA_API_URL, '/admin/reload/routes', { method: 'POST' }).catch(() => {});
-    return { content: [{ type: 'text', text: `Route permission created for ${route.path}. Routes reloaded.\n${JSON.stringify(result, null, 2)}` }] };
+    const routeReload = await reloadRoutesResult();
+    return { content: [{ type: 'text', text: JSON.stringify({
+      action: 'created',
+      kind: 'route_permission',
+      route: route.path,
+      routeReload,
+      result,
+    }, null, 2) }] };
   },
 );
 
@@ -2142,7 +2224,10 @@ server.tool('search_logs', 'Search for ERROR or WARN logs across recent log file
 }, async ({ level, keyword, limit }) => {
   const logFilesResult = await fetchAPI(ENFYRA_API_URL, '/logs');
   const logFiles = logFilesResult.files || [];
-  const recentFiles = logFiles.filter(f => f.name.includes('app-') || f.name.includes('error-'));
+  const recentFiles = logFiles.filter((file) => {
+    const name = file?.name || '';
+    return /^app[.-]/.test(name) || /^error[.-]/.test(name);
+  });
   const results = [];
   for (const file of recentFiles.slice(0, 3)) {
     try {