@enfyra/mcp-server 0.0.68 → 0.0.70

package/package.json

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

package/src/lib/mcp-examples.js

@@ -890,6 +890,24 @@ return order && order.total > 1000`,
           'Children run according to branch true/false.',
         ],
       },
+      {
+        name: 'Split a provisioning workflow into focused steps',
+        code: `[
+  { "key": "load_project", "stepOrder": 10, "type": "script" },
+  { "key": "reserve_capacity", "stepOrder": 20, "type": "script" },
+  { "key": "create_database_user", "stepOrder": 30, "type": "script" },
+  { "key": "apply_database_guardrails", "stepOrder": 40, "type": "script" },
+  { "key": "start_container", "stepOrder": 50, "type": "script" },
+  { "key": "apply_container_guardrails", "stepOrder": 60, "type": "script" },
+  { "key": "check_health", "stepOrder": 70, "type": "script" },
+  { "key": "finalize_project", "stepOrder": 80, "type": "script" }
+]`,
+        notes: [
+          'Prefer operation-sized flow steps with clear keys over one large script that performs SSH, Docker, DB, API, email, and finalization work together.',
+          'Each step should return only ids, booleans, status keys, or small counters that later steps need.',
+          'When refactoring an existing flow, add or extract adjacent focused flow_step_definition rows instead of making an oversized sourceCode block longer.',
+        ],
+      },
       {
         name: 'Flow query step config',
         code: `{

package/src/lib/mcp-instructions.js

@@ -48,7 +48,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **GraphQL:** `gql_definition` enables tables in GraphQL. GraphQL endpoint and schema share `ENFYRA_API_URL`; GraphQL requires Bearer auth.',
     '- **Files/storage/assets:** `file_definition`, `file_permission_definition`, `folder_definition`, `storage_config_definition` plus upload/assets routes and file helpers.',
     '- **WebSocket:** `websocket_definition` and `websocket_event_definition` define Socket.IO gateways/events. Use `run_admin_test` for websocket scripts.',
-    '- **Flows:** `flow_definition`, `flow_step_definition`, `flow_execution_definition`; use `test_flow_step`, `run_admin_test`, and `trigger_flow` for runtime checks.',
+    '- **Flows:** `flow_definition`, `flow_step_definition`, `flow_execution_definition`; compose workflows from small operation-sized steps, use `test_flow_step`, `run_admin_test`, and `trigger_flow` for runtime checks.',
     '- **Extensions/packages/menus:** `extension_definition`, `menu_definition`, `package_definition`, `bootstrap_script_definition`; extensions are Vue SFC only, and packages should be installed with `install_package`.',
     '- **Platform config:** `setting_definition`, `cors_origin_definition`, reload endpoints, logs, and metadata endpoints.',
     '',
@@ -288,8 +288,10 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Execution history** (`flow_execution_definition`): `flow` → flow id, `status`, `payload`, `completedSteps`, `currentStep`, `error`, `startedAt`, `completedAt`, `duration`. There is no persisted `context` column; failed executions store diagnostics in `error`. Query separately — NOT nested under flow_definition.',
     '- **triggerConfig examples**: schedule: `{"cron":"0 2 * * *","timezone":"UTC"}`, manual: `{}`. For event/webhook use cases, create a handler/hook with `@TRIGGER("flow-name", payload)` instead.',
     '- **Step config examples**: script: `{"code":"return #user_definition.find({limit:10})"}`, condition: `{"code":"return @FLOW_LAST?.data?.length > 0"}` (uses JS truthy/falsy: `return user` = truthy if exists, `return null` = falsy), query: `{"table":"user_definition","filter":{"status":{"_eq":"active"}},"limit":10}`, http: `{"url":"https://api.example.com","method":"POST","body":{}}` (auto Content-Type: application/json; **http `url` must be public-safe**—see Safety), sleep: `{"ms":5000}`, trigger_flow: `{"flowId":2}`.',
+    '- **Flow step sizing:** prefer many small, named steps over one large script. Split workflows at real operation boundaries such as load context, reserve capacity, create remote resource, apply DB/user guardrails, start container, check health, write final state, and send notifications. A script step that mixes unrelated SSH/Docker/DB/API/email/reconciliation work, returns huge objects, or grows beyond roughly 100-150 lines should be split before saving.',
     '- **Data chain**: Steps access previous results via `@FLOW.<stepKey>` and `@FLOW_LAST`. Input payload via `@FLOW_PAYLOAD`. Repos via `#table_name`.',
     '- **Flow step output discipline:** Script/condition steps must return only the small values that later steps genuinely need, such as ids, booleans, status keys, or counters. Do not return full records, host objects, package objects, DB URLs, SSH keys, API tokens, generated passwords, or other secrets. Later steps should re-query the records they need from ids/payload. Flow execution history already records errors; successful runs do not need full success snapshots.',
+    '- **Flow refactor rule:** when changing an existing oversized flow step, prefer adding or extracting adjacent focused `flow_step_definition` rows with clear keys and `stepOrder` instead of making the original `sourceCode` longer. Keep branch `parent`/`branch` relationships explicit, and re-read saved steps after mutation to verify order and executable source.',
     '- **Template syntax (flows)**: `@FLOW_PAYLOAD` → `$ctx.$flow.$payload` (input data), `@FLOW_LAST` → `$ctx.$flow.$last`, `@FLOW` → `$ctx.$flow`, `@FLOW_META` → `$ctx.$flow.$meta`, `#table_name` → `$ctx.$repos.table_name`, `@HELPERS` → `$ctx.$helpers`, `@THROW400`–`@THROW503` / `@THROW` → `$ctx.$throw[...]`. Trigger other flows in handlers via `@TRIGGER(name, payload)` or `$ctx.$trigger(name, payload)`.',
     '- **Condition branching**: Condition step uses JavaScript truthy/falsy evaluation (e.g. `return user` → truthy if exists, falsy if null/0/undefined). Children with matching `parent: {id: conditionStepId}` and `branch: "true"/"false"` execute. Root steps (no parent) always execute sequentially.',
     '- **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.',

package/src/lib/table-tools.js

@@ -34,6 +34,12 @@ export function resolveTableFromMetadata(metadata, tableId) {
     .find((table) => String(getId(table)) === String(tableId)) || null;
 }
 
+export function resolveTableFromMetadataByName(metadata, tableName) {
+  if (!tableName) return null;
+  return normalizeTablesFromMetadata(metadata)
+    .find((table) => table?.name === tableName || table?.alias === tableName) || null;
+}
+
 /**
  * Helper: fetch table with full columns and relations.
  * Dynamic table_definition relation fields can be paginated/truncated, so schema
@@ -46,7 +52,9 @@ export async function fetchTableWithDetails(ENFYRA_API_URL, tableId) {
     fetchAPI(ENFYRA_API_URL, '/metadata'),
   ]);
   const tableData = tableResult?.data?.[0] || tableResult?.[0] || null;
-  const metadataTable = resolveTableFromMetadata(metadata, tableId);
+  const metadataTable =
+    resolveTableFromMetadata(metadata, tableId) ||
+    resolveTableFromMetadataByName(metadata, tableData?.name);
   if (!metadataTable) {
     throw new Error(`Full metadata for table ${tableId} was not found; refusing schema cascade patch.`);
   }

package/src/mcp-server-entry.mjs

@@ -64,7 +64,7 @@ const CAPABILITY_AREAS = [
   {
     area: 'Flows',
     tables: ['flow_definition', 'flow_step_definition', 'flow_execution_definition'],
-    workflow: 'Create flows and steps via CRUD, test steps with test_flow_step/run_admin_test, trigger with trigger_flow.',
+    workflow: 'Create flows as small operation-sized steps via CRUD, test steps with test_flow_step/run_admin_test, trigger with trigger_flow. Split oversized scripts instead of adding more work to one step.',
   },
   {
     area: 'Extensions, menus, packages',