@enfyra/mcp-server 0.0.76 → 0.0.78

package/README.md

@@ -192,7 +192,7 @@ Generated RLS for canonical table reads must keep projection and pagination clie
 
 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.
+Use `trace_metadata_usage` before changing production features to find related tables, routes, handlers, hooks, flow steps, websocket scripts, GraphQL scripts, and bootstrap scripts. Use `get_script_source` to read full untruncated source plus a SHA-256 hash. Prefer `patch_script_source` for focused exact search/replace edits; it previews by default and, with `apply=true`, validates the patched `sourceCode` through `/admin/script/validate` before saving. Use `update_script_source` when replacing an entire existing script. Use generic `update_record` only 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.
 

package/package.json

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

package/src/lib/mcp-examples.js

@@ -697,7 +697,7 @@ ensure_route_access({
         notes: [
           'Use route permissions for authenticated access. The tool resolves role and method ids, validates the route available methods, merges existing methods, and reloads routes.',
           'Handlers or pre-hooks must still enforce owner or tenant scope; route permission only lets the request pass RoleGuard.',
-          'Use publishedMethods only for anonymous public access.',
+          'Use publicMethods only for anonymous public access.',
         ],
       },
       {
@@ -706,12 +706,12 @@ ensure_route_access({
   tableName: "route_definition",
   id: "<route_id>",
   data: {
-    publishedMethods: [{ id: "<GET_method_id_from_list_methods>" }]
+    publicMethods: [{ id: "<GET_method_id_from_list_methods>" }]
   }
 })`,
         notes: [
           'Method ids are instance data. Use list_methods or inspect_route output to resolve the GET method id first.',
-          'publishedMethods controls anonymous route access. Route permissions are not for public access.',
+          'publicMethods controls anonymous route access. Route permissions are not for public access.',
           'Route permissions apply when the method is not public.',
         ],
       },
@@ -901,7 +901,7 @@ if (message?.id) {
     data: { lastMessage: { id: message.id }, updatedAt: message.createdAt || new Date().toISOString() }
   })
 }
-@SOCKET.emitToRoom(\`conversation:\${conversationId}\`, "chat:message", {
+@SOCKET.emitToCurrentRoom(\`conversation:\${conversationId}\`, "chat:message", {
   clientId,
   message
 })

package/src/lib/mcp-instructions.js

@@ -34,6 +34,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- 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.',
     '- If writing or reviewing handler/hook/flow/websocket/extension logic, call **`discover_script_contexts`** first so macros and `$ctx` fields are not mixed across runtime surfaces.',
+    '- If changing or auditing an existing feature, table, route, or long script, call **`trace_metadata_usage`** to find related tables/routes/script-backed records, then **`get_script_source`** for full untruncated source. Use **`patch_script_source`** for exact previewed search/replace edits with hash checking and validation.',
     '- 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.',
@@ -113,17 +114,17 @@ 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.',
+'- For long script updates on existing flow steps, handlers, hooks, websocket scripts, GraphQL scripts, or bootstrap scripts, call **`get_script_source`** first to read full source and hash. Prefer **`patch_script_source`** for focused exact edits with preview/hash validation, or **`update_script_source`** when replacing the entire source. Avoid generic `update_record` for long script changes.',
 '- 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`**:',
+'- Relation fields (publicMethods, 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** are instance data, not a stable contract. Query `method_definition` or use method names through MCP route helpers before setting `publishedMethods`, `availableMethods`, `skipRoleGuardMethods`, hook methods, handler methods, or route permissions. Default CRUD records are `GET`, `POST`, `PATCH`, and `DELETE`; create extra records such as `PUT` through method tools when a route needs them.',
+'  - **One-to-many / many-to-many:** `"publicMethods": [{"id": 1}, {"id": 2}]` (array of objects with id)',
+'- **Method IDs** are instance data, not a stable contract. Query `method_definition` or use method names through MCP route helpers before setting `publicMethods`, `availableMethods`, `skipRoleGuardMethods`, hook methods, handler methods, or route permissions. Default CRUD records are `GET`, `POST`, `PATCH`, and `DELETE`; create extra records such as `PUT` through method tools when a route needs them.',
 '- `method_definition.name` is the unique backend field for the HTTP method label. Do not filter, create, or update a `method_definition.method` field. MCP method tools accept an input named `method` for usability, but they write/read `name` on the server.',
-'- **Wrong:** `"publishedMethods": ["GET"]` or `"publishedMethods": [{"method": "GET"}]` — rejected or silently ignored.',
-'- **Right:** first query method records, then pass their ids, for example `"publishedMethods": [{"id": <GET_METHOD_ID>}]`. Multiple methods use multiple id objects.',
-'- **To unset:** pass empty array `"publishedMethods": []`.',
+'- **Wrong:** `"publicMethods": ["GET"]` or `"publicMethods": [{"method": "GET"}]` — rejected or silently ignored.',
+'- **Right:** first query method records, then pass their ids, for example `"publicMethods": [{"id": <GET_METHOD_ID>}]`. Multiple methods use multiple id objects.',
+'- **To unset:** pass empty array `"publicMethods": []`.',
 '',
 '### Dynamic script `$repos` mutation return shape',
 '- In handler/hook/flow/websocket scripts, `$ctx.$repos.<table>.create({ data })` and `$ctx.$repos.<table>.update({ id, data })` return the same collection-shaped result as `find`: `{ data: [...], count? }`.',
@@ -131,13 +132,13 @@ export function buildMcpServerInstructions(apiBaseUrl) {
 '- Wrong: `const id = result.data.id`, `return result.data`, or assuming `create`/`update` returns the bare row object when the script needs one record.',
 '- Right: `const result = await @REPOS.main.create({ data: @BODY }); const record = result.data?.[0] ?? null; return record;`.',
 '',
-'### Auth and publishedMethods (Enfyra server)',
-    '- Each route has **publishedMethods** (which HTTP verbs are “public”) and **routePermissions** (roles/users for protected access).',
-    '- If the **current request method** is listed in **publishedMethods** for that route, the server allows the call **without** a Bearer token (`RoleGuard`).',
+'### Auth and publicMethods (Enfyra server)',
+    '- Each route has **publicMethods** (which HTTP verbs are “public”) and **routePermissions** (roles/users for protected access).',
+    '- If the **current request method** is listed in **publicMethods** for that route, the server allows the call **without** a Bearer token (`RoleGuard`).',
     '- Otherwise the client must send an **Authorization** header with **Bearer** JWT from login. Then the user must satisfy **routePermissions** (unless root admin).',
     '- Owner-scoped GET handlers must preserve caller filters and merge the owner scope for normal users, while root admin operational views may bypass only the owner scope with `@USER.isRootAdmin` and must keep caller filters intact. Never replace `@QUERY.filter` with `{}` for root admins; doing so breaks detail reads, pagination, and `debugMode=true` explain checks.',
     '- GET pre-hooks and handlers must preserve client-controlled query shape: do not override `@QUERY.fields`, `@QUERY.deep`, `@QUERY.sort`, `@QUERY.limit`, `@QUERY.page`, `@QUERY.meta`, `@QUERY.aggregate`, or `debugMode` for canonical table reads. RLS may only merge security filters into `@QUERY.filter`. If a route intentionally returns a fixed summary/aggregate workflow response, make it a clearly custom endpoint contract instead of changing canonical table projection.',
-    '- MCP tools that use `fetchAPI` authenticate with the configured `ENFYRA_API_TOKEN`. Explain to users that **direct HTTP** calls need a Bearer token unless the route/method is published.',
+    '- MCP tools that use `fetchAPI` authenticate with the configured `ENFYRA_API_TOKEN`. Explain to users that **direct HTTP** calls need a Bearer token unless the route/method is public.',
     '',
     '### Post-hooks (REST)',
     '- **post-hooks always run** after the handler, including when the handler or a pre-hook throws — then `@ERROR` / `$ctx.$error` is set and `@DATA` is null.',
@@ -150,7 +151,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- 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.',
+    '- Use MCP `get_script_source` for full untruncated source, `patch_script_source` for focused exact edits with preview/hash validation, and `update_script_source` for full-source replacement. 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.',
@@ -258,7 +259,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `- **GET** \`${graphqlSchemaUrl}\` — current schema SDL (text); same base pattern as above.`,
     '- A table appears in the schema when `gql_definition` has an enabled row for that table. The REST route `availableMethods` list does not enable GraphQL.',
     '- **Query** field = same string as `table_definition.name`. **Mutations** are literal concat: `create_`+tableName, `update_`+tableName, `delete_`+tableName (e.g. tableName `post` → `create_post`, input type `postInput`). See `generate-type-defs.ts`. If every column is skipped for input (only PK, or only `createdAt`/`updatedAt`, or all unpublished), the schema emits **no** `Query.<tableName>` and **no** create/update/delete mutations for that table (an output `type` may still exist for relation wiring).',
-    '- **Auth:** GraphQL currently requires `Authorization: Bearer <accessToken>`. REST route `publishedMethods` does not make GraphQL anonymous.',
+    '- **Auth:** GraphQL currently requires `Authorization: Bearer <accessToken>`. REST route `publicMethods` does not make GraphQL anonymous.',
     '- **Management workflow:** use `update_table` with `graphqlEnabled: true|false`, or create/update `gql_definition` with `table: {id}` and `isEnabled`. Reload GraphQL with `reload_graphql` if the cache has not refreshed yet.',
     '- MCP does not wrap GraphQL; use REST tools or tell users the URLs above.',
     '',
@@ -271,11 +272,13 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '-   `@SOCKET.join(room)` — join a room (WS context only).',
     '-   `@SOCKET.leave(room)` — leave a room (WS context only).',
     '-   `@SOCKET.emitToUser(userId, event, data)` — send to a specific user (across all gateways).',
-    '-   `@SOCKET.emitToRoom(room, event, data)` — send to a named room (across all gateways).',
+    '-   `@SOCKET.emitToRoom(path, room, event, data)` — send to a named room in a specific gateway/namespace.',
+    '-   `@SOCKET.emitToCurrentRoom(room, event, data)` — send to a named room in the current websocket gateway/namespace (WS context only).',
+    '-   `@SOCKET.broadcastToRoom(room, event, data)` — send to a named room in the current websocket gateway/namespace except the triggering socket (WS context only).',
     '-   `@SOCKET.emitToGateway(path, event, data)` — broadcast to all connections on a gateway/namespace.',
     '-   `@SOCKET.broadcast(event, data)` — broadcast to all connections on all gateways.',
     '-   `@SOCKET.disconnect()` — force-disconnect the current socket from the gateway (WS context only). Use in connection handler to reject, or in event handler to kick user.',
-    '-   In **HTTP** handler/hook context: `reply`, `join`, `leave`, `disconnect` are not available (no socket). Use `emitToUser`, `emitToRoom`, `emitToGateway`, `broadcast`.',
+    '-   In **HTTP** handler/hook context: `reply`, `join`, `leave`, `disconnect`, `emitToCurrentRoom`, and `broadcastToRoom` are not available (no bound socket). Use `emitToUser`, `emitToRoom(path, room, event, data)`, `emitToGateway`, and `broadcast`.',
     '- **Context**: Connection — `@BODY` = {id, ip, headers}, `@USER` if auth. Event — `@BODY` = payload, `@USER` if auth. Both have `@SOCKET`.',
     '- **ACK + results (recommended UX):** client can emit an event with Socket.IO ack callback. Server immediately acks `{ queued: true, requestId, eventName }` (or `{ queued: false, error }`). The handler result is returned asynchronously via `ws:result` or `ws:error` with the same `requestId`.',
     '- **Client**: Browser apps must connect through the app/Nuxt Socket.IO bridge, not the hidden Enfyra backend. The backend gateway metadata path is the namespace, e.g. `/chat`. A third app should connect with `io("/chat", { path: "/socket.io", withCredentials: true })` and proxy `/socket.io/**` to the Enfyra app bridge `/ws/socket.io/**`. Direct Enfyra app clients may connect with `io("/ws/chat", { path: "/ws/socket.io", withCredentials: true })` when using the built-in bridge convention.',
@@ -300,8 +303,8 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Safety**: Max nesting depth 10 (flow triggering flow). Circular flow detection prevents A→B→A loops. HTTP steps: **SSRF hardening** — only `http`/`https`; blocks `localhost`, private IPs, and hostnames resolving to private IPs (use internet-facing URLs like `https://api.example.com`, not internal services, unless server policy changes). Default HTTP timeout 30s (AbortController). `$trigger()` available inside flow steps.',
     '- **Workflow**: Create flow → `create_record` on `flow_definition`. Add steps → `create_record` on `flow_step_definition` with `flow: {id}`. For branch steps, set `parent: {id: conditionStepId}` and `branch: "true"` or `"false"`. Trigger manually via `POST /admin/flow/trigger/{flowId}`.',
     '- **Flow source sanity:** after creating or patching a multi-step flow, refetch saved `flow_step_definition` rows and verify every script/condition step has executable step-specific `sourceCode` with a body/return. A helper-only source block that parses successfully is still broken and must be patched before the user sees it in eApp.',
-    '- **Test step**: `POST /admin/flow/test-step` with body `{type, config, timeout}` — runs a single step without saving, returns `{success, result, error, duration}`.',
-    '- MCP wrappers: use **`test_flow_step`** for one step, **`run_admin_test`** with `kind:"flow_step"` for the generic admin tester, and **`trigger_flow`** for saved flows.',
+    '- **Test step**: `POST /admin/test/run` with body `{kind:"flow_step", type, config, timeout}` — runs a single step without saving, returns `{success, result, error, duration}`.',
+    '- MCP wrappers: use **`test_flow_step`** for one flow step, **`run_admin_test`** for flow/websocket tests, and **`trigger_flow`** for saved flows.',
     '- **In handlers/hooks**: Trigger flows via `$ctx.$trigger("flow-name", {payload})` or `$ctx.$trigger(flowId, {payload})`.',
     '- Before writing flow scripts, call **`discover_script_contexts`** to confirm `@FLOW`, `@FLOW_PAYLOAD`, `@FLOW_LAST`, `#table_name`, `$ctx.$trigger`, and `$socket` behavior.',
     '',
@@ -433,6 +436,9 @@ 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`,
+    `- \`trace_metadata_usage\` → scans live metadata and script-backed records for a table/route/keyword before editing`,
+    `- \`get_script_source\` → GET one script-backed record via filter+limit=1 and returns full sourceCode plus sha256`,
+    `- \`patch_script_source\` → preview or apply exact sourceCode search/replace; apply validates with \`${base}/admin/script/validate\`, then PATCHes \`${base}/<script_table>/<id>\``,
     `- \`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\``,
@@ -443,7 +449,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `- \`create_extension\` → POST \`${base}/extension_definition\` (Vue SFC only; for \`type="page"\` pass menuId, for \`type="widget"\` or \`type="global"\` omit 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\``,
-    `- \`test_flow_step\` → POST \`${base}/admin/flow/test-step\``,
+    `- \`test_flow_step\` → POST \`${base}/admin/test/run\` with \`kind:"flow_step"\``,
     `- \`trigger_flow\` → POST \`${base}/admin/flow/trigger/<flowIdOrName>\``,
     `- Other: \`${base}/menu_definition\`, \`${base}/websocket_definition\`, \`${base}/admin/reload\`, etc.`,
     '',

package/src/lib/route-permission-tools.js

@@ -44,8 +44,8 @@ export function routeAvailableMethodNames(route, methodIdNameMap = {}) {
   return methodNamesFromRecords(route?.availableMethods || [], methodIdNameMap);
 }
 
-export function routePublishedMethodNames(route, methodIdNameMap = {}) {
-  return methodNamesFromRecords(route?.publishedMethods || [], methodIdNameMap);
+export function routePublicMethodNames(route, methodIdNameMap = {}) {
+  return methodNamesFromRecords(route?.publicMethods || [], methodIdNameMap);
 }
 
 export function permissionMethodNames(permission, methodIdNameMap = {}) {
@@ -148,7 +148,7 @@ export function summarizeRouteAccess(route, routePermissions, methodIdNameMap =
     path: route?.path,
     isEnabled: route?.isEnabled !== false,
     availableMethods: routeAvailableMethodNames(route, methodIdNameMap),
-    publishedMethods: routePublishedMethodNames(route, methodIdNameMap),
+    publicMethods: routePublicMethodNames(route, methodIdNameMap),
     skipRoleGuardMethods: methodNamesFromRecords(route?.skipRoleGuardMethods || [], methodIdNameMap),
     permissions,
     expected: expectedMethods.length ? {

package/src/mcp-server-entry.mjs

@@ -8,6 +8,7 @@ config();
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { createHash } from 'node:crypto';
 
 // Configuration
 const ENFYRA_API_URL = process.env.ENFYRA_API_URL || 'http://localhost:3000/api';
@@ -27,7 +28,7 @@ import {
   normalizeMethodNames,
   resolveRoleByNameOrId,
   routeAvailableMethodNames,
-  routePublishedMethodNames,
+  routePublicMethodNames,
   summarizeRouteAccess,
   summarizeRoutePermission,
   validateMethodsForRoute,
@@ -127,6 +128,24 @@ const FIELD_PERMISSION_CONDITION_OPERATORS = [
   '_not',
 ];
 
+const SCRIPT_BACKED_TABLES = [
+  'route_handler_definition',
+  'pre_hook_definition',
+  'post_hook_definition',
+  'flow_step_definition',
+  'websocket_event_definition',
+  'websocket_definition',
+  'gql_definition',
+  'bootstrap_script_definition',
+];
+
+const SCRIPT_SOURCE_FIELDS = [
+  'sourceCode',
+  'handlerScript',
+  'connectionHandlerScript',
+  'code',
+];
+
 function normalizeTables(metadata) {
   const tablesSource = metadata?.data?.tables || metadata?.tables || metadata?.data || [];
   return Array.isArray(tablesSource)
@@ -209,7 +228,7 @@ function summarizeRoutes(routesResult) {
     path: route.path,
     mainTable: route.mainTable?.name || route.mainTableName || null,
     availableMethods: (route.availableMethods || []).map((method) => method.name).filter(Boolean),
-    publishedMethods: (route.publishedMethods || []).map((method) => method.name).filter(Boolean),
+    publicMethods: (route.publicMethods || []).map((method) => method.name).filter(Boolean),
     isEnabled: route.isEnabled,
   }));
 }
@@ -403,6 +422,107 @@ function normalizeHexColorInput(value, fieldName) {
   return color;
 }
 
+function sha256(value) {
+  return createHash('sha256').update(String(value), 'utf8').digest('hex');
+}
+
+function getScriptSourceField(record) {
+  for (const field of SCRIPT_SOURCE_FIELDS) {
+    if (typeof record?.[field] === 'string') return field;
+  }
+  if (record?.config && typeof record.config === 'object' && typeof record.config.code === 'string') {
+    return 'config.code';
+  }
+  return null;
+}
+
+function getRecordSource(record) {
+  const field = getScriptSourceField(record);
+  if (!field) return { field: null, sourceCode: '' };
+  if (field === 'config.code') return { field, sourceCode: record.config.code };
+  return { field, sourceCode: record[field] };
+}
+
+async function fetchRecordByPrimaryKey(tableName, id, fields = '*') {
+  const primaryKey = await getPrimaryFieldName(tableName);
+  const query = new URLSearchParams({
+    filter: JSON.stringify({ [primaryKey]: { _eq: id } }),
+    limit: '1',
+    fields,
+  });
+  const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}?${query.toString()}`);
+  const record = unwrapData(result)[0] || null;
+  if (!record) throw new Error(`${tableName} record ${id} was not found.`);
+  return { primaryKey, record };
+}
+
+async function fetchScriptRecord(tableName, id) {
+  validateTableName(tableName);
+  if (!SCRIPT_BACKED_TABLES.includes(tableName)) {
+    throw new Error(`Unsupported script-backed table "${tableName}". Supported: ${SCRIPT_BACKED_TABLES.join(', ')}`);
+  }
+  const { primaryKey, record } = await fetchRecordByPrimaryKey(tableName, id, '*');
+  const { field, sourceCode } = getRecordSource(record);
+  if (!field) {
+    throw new Error(`${tableName} record ${id} does not expose a known editable source field.`);
+  }
+  return { primaryKey, record, sourceField: field, sourceCode };
+}
+
+function countOccurrences(source, needle) {
+  if (!needle) return 0;
+  let count = 0;
+  let index = 0;
+  while (true) {
+    index = source.indexOf(needle, index);
+    if (index === -1) return count;
+    count += 1;
+    index += needle.length;
+  }
+}
+
+function replaceOccurrence(source, oldText, newText, mode) {
+  const occurrences = countOccurrences(source, oldText);
+  if (occurrences === 0) {
+    throw new Error('oldText was not found in the current source.');
+  }
+  if (mode === 'first') {
+    return {
+      occurrences,
+      patched: source.replace(oldText, newText),
+      replaced: 1,
+    };
+  }
+  return {
+    occurrences,
+    patched: source.split(oldText).join(newText),
+    replaced: occurrences,
+  };
+}
+
+function sourcePreview(source, aroundText) {
+  if (!aroundText) return source.slice(0, 1200);
+  const index = source.indexOf(aroundText);
+  if (index === -1) return source.slice(0, 1200);
+  const start = Math.max(0, index - 500);
+  const end = Math.min(source.length, index + aroundText.length + 500);
+  return `${start > 0 ? '...' : ''}${source.slice(start, end)}${end < source.length ? '...' : ''}`;
+}
+
+function scriptRecordLabel(tableName, record) {
+  const method = record.method?.name || record.method?.method || null;
+  const route = record.route?.path || null;
+  const flow = record.flow?.name || null;
+  return {
+    tableName,
+    id: getId(record),
+    key: record.key || record.name || record.eventName || null,
+    route,
+    method,
+    flow,
+  };
+}
+
 async function findMethodRecordByName(method) {
   const filter = encodeURIComponent(JSON.stringify({ name: { _eq: method } }));
   const result = await fetchAPI(ENFYRA_API_URL, `/method_definition?filter=${filter}&limit=1&fields=id,_id,name,buttonColor,textColor,isSystem`);
@@ -483,7 +603,7 @@ server.tool(
   async () => {
     const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
     const [routesResult, methodsResult] = await Promise.all([
-      fetchAPI(ENFYRA_API_URL, '/route_definition?fields=path,mainTable.name,availableMethods.*,publishedMethods.*&limit=1000'),
+      fetchAPI(ENFYRA_API_URL, '/route_definition?fields=path,mainTable.name,availableMethods.*,publicMethods.*&limit=1000'),
       fetchAPI(ENFYRA_API_URL, '/method_definition?limit=100'),
     ]);
 
@@ -513,7 +633,7 @@ server.tool(
       })),
       rest: {
         routePattern: 'Dynamic REST routes expose GET/POST at /<route-path> and PATCH/DELETE at /<route-path>/:id; there is no GET /<route-path>/:id.',
-        publicAccess: 'publishedMethods controls anonymous REST access per route/method; otherwise Bearer JWT + routePermissions apply.',
+        publicAccess: 'publicMethods controls anonymous REST access per route/method; otherwise Bearer JWT + routePermissions apply.',
         routeTables: routeTableList,
         noRouteTables,
         canonicalCrudTools: 'query_table/create_record/update_record/delete_record use dynamic REST routes and only work for route-backed tables.',
@@ -532,14 +652,14 @@ server.tool(
       },
       adminTesting: {
         runAdminTest: 'run_admin_test wraps POST /admin/test/run for flow_step, websocket_event, and websocket_connection scripts.',
-        testFlowStep: 'test_flow_step wraps POST /admin/flow/test-step.',
+        testFlowStep: 'test_flow_step also wraps POST /admin/test/run with kind=flow_step.',
         triggerFlow: 'trigger_flow wraps POST /admin/flow/trigger/:id and enqueues a flow execution.',
       },
       graphql: {
         endpoint: `${ENFYRA_API_URL.replace(/\/$/, '')}/graphql`,
         schemaEndpoint: `${ENFYRA_API_URL.replace(/\/$/, '')}/graphql-schema`,
         enablement: 'A table appears in GraphQL when gql_definition has an enabled row for that table. REST route availableMethods does not enable GraphQL.',
-        auth: 'GraphQL currently requires Authorization: Bearer <accessToken>; REST publishedMethods does not make GraphQL anonymous.',
+        auth: 'GraphQL currently requires Authorization: Bearer <accessToken>; REST publicMethods does not make GraphQL anonymous.',
         management: routeTables.has('gql_definition')
           ? 'Use update_table graphqlEnabled or create/update records on gql_definition, then reload_graphql if needed.'
           : 'Use update_table graphqlEnabled, then reload_graphql if needed.',
@@ -572,7 +692,7 @@ server.tool(
       settingsResult,
       meResult,
     ] = await Promise.all([
-      fetchAPI(ENFYRA_API_URL, '/route_definition?fields=path,mainTable.name,availableMethods.*,publishedMethods.*,isEnabled&limit=1000'),
+      fetchAPI(ENFYRA_API_URL, '/route_definition?fields=path,mainTable.name,availableMethods.*,publicMethods.*,isEnabled&limit=1000'),
       fetchAPI(ENFYRA_API_URL, '/method_definition?limit=100'),
       fetchAPI(ENFYRA_API_URL, '/gql_definition?limit=1000').catch((error) => ({ error: String(error.message || error), data: [] })),
       fetchAPI(ENFYRA_API_URL, '/flow_definition?limit=1000').catch((error) => ({ error: String(error.message || error), data: [] })),
@@ -586,7 +706,7 @@ server.tool(
     const routes = summarizeRoutes(routesResult);
     const routeTables = new Set(routes.map((route) => route.mainTable).filter(Boolean));
     const adminRoutes = routes.filter((route) => route.path?.startsWith('/admin'));
-    const publicRoutes = routes.filter((route) => route.publishedMethods?.length);
+    const publicRoutes = routes.filter((route) => route.publicMethods?.length);
 
     const payload = {
       apiBase: ENFYRA_API_URL.replace(/\/$/, ''),
@@ -614,7 +734,7 @@ server.tool(
         publicRoutes: publicRoutes.map((route) => ({
           path: route.path,
           mainTable: route.mainTable,
-          publishedMethods: route.publishedMethods,
+          publicMethods: route.publicMethods,
         })),
       },
       cacheAndCluster: {
@@ -647,7 +767,7 @@ server.tool(
   },
   async ({ tableName }) => {
     const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
-    const routesResult = await fetchAPI(ENFYRA_API_URL, '/route_definition?fields=path,mainTable.name,availableMethods.*,publishedMethods.*,isEnabled&limit=1000');
+    const routesResult = await fetchAPI(ENFYRA_API_URL, '/route_definition?fields=path,mainTable.name,availableMethods.*,publicMethods.*,isEnabled&limit=1000');
     const tables = normalizeTables(metadata);
     const routes = summarizeRoutes(routesResult);
     const table = tableName ? tables.find((item) => item.name === tableName) : null;
@@ -777,7 +897,7 @@ server.tool(
         },
         handler: {
           runs: 'Main route logic, or canonical CRUD if no handler overrides.',
-          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@UPLOADED_FILE for multipart request file metadata', '@REPOS.main', '@REPOS.secure', '@CACHE', '@HELPERS', '@STORAGE', '@PKGS', '@SOCKET emit helpers', '@TRIGGER'],
+          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@UPLOADED_FILE for multipart request file metadata', '@REPOS.main', '@REPOS.<table>', '@CACHE', '@HELPERS', '@STORAGE', '@PKGS', '@SOCKET emit helpers', '@TRIGGER'],
           queryContract: 'When a handler wraps a canonical table read, pass through client fields/deep/sort/page/limit/meta/aggregate/debugMode unless the route is a clearly custom summary or workflow endpoint.',
           returnBehavior: 'Return value becomes response body unless post-hook changes it.',
         },
@@ -804,7 +924,7 @@ server.tool(
         graphqlResolver: {
           runs: 'Generated GraphQL resolver delegates to dynamic repo/query services.',
           data: ['GraphQL request context', 'Bearer auth user', 'dynamic repositories'],
-          caveat: 'REST publishedMethods do not make GraphQL anonymous.',
+          caveat: 'REST publicMethods do not make GraphQL anonymous.',
         },
         extensionVueSfc: {
           runs: 'Frontend extension code, not server sandbox.',
@@ -814,13 +934,13 @@ server.tool(
       },
       helpers: {
         repos: {
-          scopes: '$repos.main enforces route main table behavior; $repos.secure.<table> enforces field permissions; $repos.<table> is trusted/internal.',
+          scopes: '$repos.main is the canonical repository for the route main table and preserves normal route query behavior. $repos.<table> is an explicit internal repository for table-specific logic. Do not generate $repos.secure.<table>; current runtime does not expose table methods there.',
           mutationReturnShape: '$repos.<table>.create({ data }) and $repos.<table>.update({ id, data }) return a collection-shaped result: { data: [...], count? }. data is always an array for create/update, even for one created/updated record. If a script needs the single record object, it must read result.data[0] or result.data?.[0] ?? null.',
           preferredExample: 'const result = await @REPOS.main.create({ data: @BODY }); const record = result.data?.[0] ?? null; return record;',
           wrongSingleRecordAccess: 'Do not use result.data.id, do not return result.data when one object is expected, and do not assume create/update returns the bare row object.',
           countPattern: 'To count records in custom code, do not fetch full rows. Use const result = await @REPOS.main.find({ fields: "id", limit: 1, meta: filter ? "filterCount" : "totalCount", ...(filter ? { filter } : {}) }); then read result.meta.filterCount or result.meta.totalCount.',
         },
-        socketInHttpOrFlow: 'HTTP/flow context can emitToUser/emitToRoom/emitToGateway/broadcast, but cannot reply/join/leave/disconnect because there is no bound socket.',
+        socketInHttpOrFlow: 'HTTP/flow context can emitToUser/emitToRoom/emitToGateway/broadcast, but cannot reply/join/leave/disconnect/emitToCurrentRoom/broadcastToRoom because there is no bound socket. emitToRoom requires an explicit gateway path: emitToRoom(path, room, event, data).',
         packages: 'Server packages installed through install_package are exposed as $ctx.$pkgs.packageName in server scripts.',
         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.',
       },
@@ -843,7 +963,7 @@ server.tool(
   [
     'Returns the resolved API base URL for this MCP session (env ENFYRA_API_URL).',
     'Use when the user asks which HTTP endpoint or full URL applies: combine enfyraApiUrl with paths from server instructions (GET/POST /{table}, PATCH/DELETE /{table}/{id}, no GET /{table}/{id}).',
-    'Auth: publishedMethods on a route can allow a method without Bearer; otherwise JWT + routePermissions — see server instructions.',
+    'Auth: publicMethods on a route can allow a method without Bearer; otherwise JWT + routePermissions — see server instructions.',
     'If path might differ from table name, use get_all_routes before asserting a URL.',
     'Same mapping as MCP tool → HTTP: query_table=GET /table?..., create_record=POST /table, update_record=PATCH /table/id, delete_record=DELETE /table/id.',
     'GraphQL: see graphqlHttpUrl / graphqlSchemaUrl in response; enable per table via gql_definition/update_table graphqlEnabled and send Bearer auth.',
@@ -862,8 +982,8 @@ server.tool(
         oneRowById: `${base}/<table_name>?filter={"<primaryKeyFromMetadata>":{"_eq":"<id>"}}&limit=1`,
       },
       auth: {
-        publishedMethods: 'If the HTTP method is published for that route, no Bearer required; else Bearer JWT and routePermissions apply.',
-        graphql: 'GraphQL currently requires Bearer auth; route publishedMethods do not make GraphQL anonymous.',
+        publicMethods: 'If the HTTP method is public for that route, no Bearer required; else Bearer JWT and routePermissions apply.',
+        graphql: 'GraphQL currently requires Bearer auth; route publicMethods do not make GraphQL anonymous.',
         mcp: 'This server uses admin credentials from env for tools (fetchAPI).',
       },
       pathResolution: 'Confirm route path with get_all_routes or metadata — path may not equal table name.',
@@ -1055,6 +1175,100 @@ server.tool('update_record', 'Update an existing record by ID using PATCH. The t
   }, null, 2) }] };
 });
 
+server.tool(
+  'get_script_source',
+  [
+    'Fetch the full editable source for one script-backed metadata record without preview truncation.',
+    'Use this before reviewing or patching long handlers, hooks, flow steps, websocket scripts, GraphQL scripts, or bootstrap scripts.',
+  ].join(' '),
+  {
+    tableName: z.enum(SCRIPT_BACKED_TABLES).describe('Script-backed table to read'),
+    id: z.string().describe('Record ID to read'),
+  },
+  async ({ tableName, id }) => {
+    const { primaryKey, record, sourceField, sourceCode } = await fetchScriptRecord(tableName, id);
+    return { content: [{ type: 'text', text: JSON.stringify({
+      tableName,
+      id,
+      primaryKey,
+      sourceField,
+      sourceCode,
+      sourceLength: sourceCode.length,
+      sourceSha256: sha256(sourceCode),
+      scriptLanguage: record.scriptLanguage || record.language || null,
+      record: scriptRecordLabel(tableName, record),
+    }, null, 2) }] };
+  },
+);
+
+server.tool(
+  'patch_script_source',
+  [
+    'Patch sourceCode on a script-backed record using exact search/replace with optional hash checking.',
+    'By default this returns a preview only. Set apply=true to validate through /admin/script/validate and save.',
+    'Use get_script_source first for long scripts, then patch only the exact block you intend to change.',
+  ].join(' '),
+  {
+    tableName: z.enum(SCRIPT_BACKED_TABLES).describe('Script-backed table to patch'),
+    id: z.string().describe('Record ID to patch'),
+    oldText: z.string().describe('Exact text to replace'),
+    newText: z.string().describe('Replacement text'),
+    occurrence: z.enum(['first', 'all']).optional().default('all').describe('Replace first occurrence or all occurrences.'),
+    expectedSourceSha256: z.string().optional().describe('Optional SHA-256 from get_script_source; fails if source changed.'),
+    scriptLanguage: z.string().optional().describe('Script language to save. Defaults to existing scriptLanguage or javascript.'),
+    apply: z.boolean().optional().default(false).describe('false returns preview only; true validates and saves.'),
+  },
+  async ({ tableName, id, oldText, newText, occurrence, expectedSourceSha256, scriptLanguage, apply }) => {
+    const { record, sourceField, sourceCode } = await fetchScriptRecord(tableName, id);
+    if (sourceField !== 'sourceCode') {
+      throw new Error(`patch_script_source only saves sourceCode records. Record uses "${sourceField}"; use update_record intentionally for this legacy field.`);
+    }
+    const beforeHash = sha256(sourceCode);
+    if (expectedSourceSha256 && expectedSourceSha256 !== beforeHash) {
+      throw new Error(`Source hash mismatch. Current sha256 is ${beforeHash}; re-read with get_script_source before patching.`);
+    }
+    const { occurrences, patched, replaced } = replaceOccurrence(sourceCode, oldText, newText, occurrence || 'all');
+    const afterHash = sha256(patched);
+    const payload = {
+      action: apply ? 'patch_script_source_applied' : 'patch_script_source_preview',
+      tableName,
+      id,
+      sourceField,
+      sourceLengthBefore: sourceCode.length,
+      sourceLengthAfter: patched.length,
+      sourceSha256Before: beforeHash,
+      sourceSha256After: afterHash,
+      occurrences,
+      replaced,
+      preview: {
+        before: sourcePreview(sourceCode, oldText),
+        after: sourcePreview(patched, newText),
+      },
+      next: apply ? undefined : 'Call patch_script_source again with apply=true and expectedSourceSha256 set to sourceSha256Before to validate and save.',
+    };
+    if (!apply) {
+      return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+    }
+    const language = scriptLanguage || record.scriptLanguage || 'javascript';
+    const prepared = await prepareGenericMutation(
+      tableName,
+      JSON.stringify({ sourceCode: patched, scriptLanguage: language }),
+    );
+    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({
+      ...payload,
+      ...summarizeMutationResult(result, 'patch_script_source_applied', tableName),
+      id,
+      scriptLanguage: language,
+      scriptValidation: prepared.scriptValidation,
+    }, null, 2) }] };
+  },
+);
+
 server.tool(
   'update_script_source',
   [
@@ -1308,7 +1522,7 @@ server.tool(
 
 server.tool(
   'test_flow_step',
-  'Test a single flow step without saving it. Wraps POST /admin/flow/test-step.',
+  'Test a single flow step without saving it. Wraps POST /admin/test/run with kind=flow_step.',
   {
     type: z.enum(['script', 'condition', 'query', 'create', 'update', 'delete', 'http', 'trigger_flow', 'sleep', 'log']).describe('Flow step type'),
     config: z.string().describe('Step config as JSON string'),
@@ -1324,9 +1538,9 @@ server.tool(
       ...(key ? { key } : {}),
       ...(mockFlow ? { mockFlow: JSON.parse(mockFlow) } : {}),
     };
-    const result = await fetchAPI(ENFYRA_API_URL, '/admin/flow/test-step', {
+    const result = await fetchAPI(ENFYRA_API_URL, '/admin/test/run', {
       method: 'POST',
-      body: JSON.stringify(body),
+      body: JSON.stringify({ ...body, kind: 'flow_step' }),
     });
     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
   },
@@ -1473,13 +1687,13 @@ function enrichRoute(route, state) {
           method: method.name || state.methodIdNameMap[String(getId(method))] || null,
         }))
       : route.availableMethods,
-    publishedMethods: Array.isArray(route.publishedMethods)
-      ? route.publishedMethods.map((method) => ({
+    publicMethods: Array.isArray(route.publicMethods)
+      ? route.publicMethods.map((method) => ({
           ...method,
           name: method.name || state.methodIdNameMap[String(getId(method))] || null,
           method: method.name || state.methodIdNameMap[String(getId(method))] || null,
         }))
-      : route.publishedMethods,
+      : route.publicMethods,
     skipRoleGuardMethods: Array.isArray(route.skipRoleGuardMethods)
       ? route.skipRoleGuardMethods.map((method) => ({
           ...method,
@@ -1555,7 +1769,7 @@ server.tool(
   'inspect_route',
   [
     'REST-first inspection for a route/path. Use before changing handlers, hooks, permissions, guards, or testing an endpoint.',
-    'Returns the backing table, available/published methods, handlers, hooks, route permissions, guards, and exact REST URL pattern.',
+    'Returns the backing table, available/public methods, handlers, hooks, route permissions, guards, and exact REST URL pattern.',
   ].join(' '),
   {
     path: z.string().optional().describe('Route path, e.g. /user_definition'),
@@ -1639,6 +1853,88 @@ server.tool(
   },
 );
 
+server.tool(
+  'trace_metadata_usage',
+  [
+    'Trace where a table, route path, keyword, or script fragment appears across live metadata and script-backed records.',
+    'Use this before changing production flows/handlers/hooks to find all callers or writers for a table such as cloud_provisioning_history.',
+  ].join(' '),
+  {
+    query: z.string().describe('Table name, route path, field name, event name, or source-code keyword to trace'),
+    includeSourcePreview: z.boolean().optional().default(true).describe('Include short source previews around matches.'),
+    limit: z.number().optional().default(25).describe('Maximum matches per section.'),
+  },
+  async ({ query, includeSourcePreview, limit }) => {
+    const q = String(query || '').trim();
+    if (!q) throw new Error('query is required.');
+    const lower = q.toLowerCase();
+    const max = Math.max(1, Math.min(Number(limit || 25), 100));
+    const state = await collectRestDefinitionState();
+    const contains = (value) => JSON.stringify(value ?? '').toLowerCase().includes(lower);
+    const sourceContains = (record) => getRecordSource(record).sourceCode.toLowerCase().includes(lower);
+
+    const scriptTableResults = await Promise.all(SCRIPT_BACKED_TABLES.map(async (tableName) => {
+      const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}?limit=1000&fields=*`).catch((error) => ({ error }));
+      return { tableName, records: unwrapData(result), error: result?.error?.message || null };
+    }));
+    const scriptMatches = [];
+    const scriptErrors = [];
+    for (const { tableName, records, error } of scriptTableResults) {
+      if (error) {
+        scriptErrors.push({ tableName, error });
+        continue;
+      }
+      for (const record of records) {
+        const { field, sourceCode } = getRecordSource(record);
+        if (!field || !sourceContains(record)) continue;
+        scriptMatches.push({
+          ...scriptRecordLabel(tableName, record),
+          sourceField: field,
+          sourceLength: sourceCode.length,
+          sourceSha256: sha256(sourceCode),
+          preview: includeSourcePreview ? sourcePreview(sourceCode, q) : undefined,
+        });
+      }
+    }
+
+    const tableMatches = state.tables.filter((table) => contains({
+      name: table.name,
+      alias: table.alias,
+      description: table.description,
+      columns: (table.columns || []).map((column) => ({ name: column.name, type: column.type, description: column.description })),
+      relations: (table.relations || []).map((relation) => ({ propertyName: relation.propertyName, type: relation.type, description: relation.description })),
+    }));
+    const routeMatches = state.routes.filter((route) => contains({
+      path: route.path,
+      mainTable: route.mainTable,
+      description: route.description,
+    }));
+    const fieldPermissionMatches = state.fieldPermissions.filter((permission) => contains(permission));
+    const guardMatches = state.guards.filter((guard) => contains(guard));
+    const routePermissionMatches = state.routePermissions.filter((permission) => contains(permission));
+
+    return { content: [{ type: 'text', text: JSON.stringify({
+      query: q,
+      counts: {
+        tables: tableMatches.length,
+        routes: routeMatches.length,
+        scripts: scriptMatches.length,
+        fieldPermissions: fieldPermissionMatches.length,
+        routePermissions: routePermissionMatches.length,
+        guards: guardMatches.length,
+      },
+      tables: tableMatches.map(summarizeTable).slice(0, max),
+      routes: routeMatches.map((route) => enrichRoute(route, state)).slice(0, max),
+      scripts: scriptMatches.slice(0, max),
+      fieldPermissions: fieldPermissionMatches.slice(0, max),
+      routePermissions: routePermissionMatches.slice(0, max),
+      guards: guardMatches.slice(0, max),
+      scriptReadErrors: scriptErrors,
+      next: 'Use inspect_route/inspect_table for structure, get_script_source for full source, and patch_script_source for exact validated edits.',
+    }, null, 2) }] };
+  },
+);
+
 server.tool(
   'test_rest_endpoint',
   [
@@ -1651,7 +1947,7 @@ server.tool(
     query: z.string().optional().describe('Optional query params JSON object, merged onto path query string'),
     body: z.string().optional().describe('Optional JSON request body string'),
     headers: z.string().optional().describe('Optional headers JSON object'),
-    useAuth: z.boolean().optional().default(true).describe('Attach MCP admin Bearer token. Set false to test published/public access.'),
+    useAuth: z.boolean().optional().default(true).describe('Attach MCP admin Bearer token. Set false to test public access.'),
   },
   async ({ method, path, query, body, headers, useAuth }) => {
     const httpMethod = normalizeMethodNameInput(method || 'GET');
@@ -1711,7 +2007,7 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Call
   const filter = includeDisabled ? {} : { isEnabled: { _eq: true } };
   const queryParams = new URLSearchParams({
     filter: JSON.stringify(filter),
-    fields: 'id,path,mainTable.name,availableMethods.*,publishedMethods.*,isEnabled',
+    fields: 'id,path,mainTable.name,availableMethods.*,publicMethods.*,isEnabled',
     limit: '1000',
   });
   const result = await fetchAPI(ENFYRA_API_URL, `/route_definition?${queryParams.toString()}`);
@@ -1745,7 +2041,7 @@ server.tool(
     '**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`, `/reports/summary`, `/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.',
+    'availableMethods = which REST verbs the route responds to. publicMethods = 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: create_route → create_handler (per method) → optionally create_pre_hook / create_post_hook → test via HTTP or admin test APIs (see server instructions).',
   ].join(' '),
@@ -1754,12 +2050,12 @@ server.tool(
     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.string())
       .describe('HTTP method names this route supports (availableMethods). Each value must exist in method_definition.name. Common: ["GET","POST","PATCH","DELETE"].'),
-    publishedMethods: z.array(z.string()).optional()
+    publicMethods: z.array(z.string()).optional()
       .describe('Methods accessible WITHOUT auth token. Omit = all methods require auth.'),
     isEnabled: z.boolean().optional().default(true).describe('Enable route immediately'),
     description: z.string().optional().describe('Route description'),
   },
-  async ({ path: routePath, mainTableId, methods, publishedMethods, isEnabled, description }) => {
+  async ({ path: routePath, mainTableId, methods, publicMethods, isEnabled, description }) => {
     const methodMap = await getMethodMap();
     const normalizedPath = normalizeRestPath(routePath);
 
@@ -1776,8 +2072,8 @@ server.tool(
       body.mainTable = { id: mainTableId };
     }
 
-    if (publishedMethods && publishedMethods.length > 0) {
-      body.publishedMethods = resolveMethodIds(methodMap, publishedMethods);
+    if (publicMethods && publicMethods.length > 0) {
+      body.publicMethods = resolveMethodIds(methodMap, publicMethods);
     }
 
     const result = await fetchAPI(ENFYRA_API_URL, '/route_definition', {
@@ -1795,7 +2091,7 @@ server.tool(
         path: created?.path,
         mainTableId: mainTableId ?? null,
         availableMethods: methods,
-        publishedMethods: publishedMethods || [],
+        publicMethods: publicMethods || [],
       },
       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.`,
@@ -2060,7 +2356,7 @@ server.tool(
   'create_route_permission',
   [
     'Create route access permission for a route and REST methods.',
-    'Use this when a non-root role/user should access an authenticated route. publishedMethods are for public access; route permissions are for authenticated role/user access.',
+    'Use this when a non-root role/user should access an authenticated route. publicMethods are for public access; route permissions are for authenticated role/user access.',
   ].join(' '),
   {
     path: z.string().optional().describe('Route path, e.g. /user_definition'),
@@ -2109,7 +2405,7 @@ server.tool(
   'audit_route_access',
   [
     'Audit route access for one or more routes.',
-    'Use this before granting access or debugging 403s. It reports available methods, public published methods, skipRoleGuard methods, route permissions, and optional missing methods for one role/user scope.',
+    'Use this before granting access or debugging 403s. It reports available methods, public methods, skipRoleGuard methods, route permissions, and optional missing methods for one role/user scope.',
   ].join(' '),
   {
     path: z.string().optional().describe('Exact route path, e.g. /orders'),
@@ -2147,7 +2443,7 @@ server.tool(
     const expectedMethods = normalizeMethodNames(methods || []);
     const payload = {
       guidance: {
-        publicAccess: 'publishedMethods bypass RoleGuard and do not require route_permission_definition.',
+        publicAccess: 'publicMethods bypass RoleGuard and do not require route_permission_definition.',
         authenticatedAccess: 'For non-public methods, eApp PermissionGate and backend RoleGuard both expect enabled route_permission_definition rows with matching route + HTTP method.',
         directUserAccess: 'allowedRoutePermissions on /me represent direct user-scoped route permissions; role.routePermissions represent role-scoped permissions.',
       },
@@ -2216,8 +2512,8 @@ server.tool(
     const existingMethods = existing ? summarizeRoutePermission(existing, methodIdNameMap).methods : [];
     const finalMethods = mergeMethodNames(existingMethods, requestedMethods, mode);
     const methodRefs = resolveMethodIds(methodMap, finalMethods);
-    const publishedMethods = routePublishedMethodNames(route, methodIdNameMap);
-    const alreadyPublic = requestedMethods.filter((method) => publishedMethods.includes(method));
+    const publicMethods = routePublicMethodNames(route, methodIdNameMap);
+    const alreadyPublic = requestedMethods.filter((method) => publicMethods.includes(method));
 
     let result;
     let action;
@@ -2257,7 +2553,7 @@ server.tool(
         id: getId(route),
         path: route.path,
         availableMethods: routeAvailableMethodNames(route, methodIdNameMap),
-        publishedMethods,
+        publicMethods,
       },
       scope: {
         role: role ? { id: getId(role), name: role.name } : null,