@enfyra/mcp-server 0.0.15 → 0.0.17

package/package.json

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

package/src/lib/mcp-instructions.js

@@ -54,6 +54,10 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Otherwise the client must send an **Authorization** header with **Bearer** JWT from login. Then the user must satisfy **routePermissions** (unless root admin).',
     '- MCP tools that use `fetchAPI` authenticate with the configured admin credentials; explain to users that **direct HTTP** calls need a token unless the route/method is published.',
     '',
+    '### 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.',
+    '- You may **mutate** `@DATA` / `$ctx.$data` in place, or **return** a value: a non-`undefined` return replaces `$ctx.$data` as the response body.',
+    '',
     '### OAuth login (browser / frontend — not the MCP `login` tool)',
     '- **MCP `login`** uses **email + password** → `POST {base}/auth/login`. It cannot complete OAuth (no browser redirect).',
     '- **Supported providers (server):** `google`, `facebook`, `github` only.',
@@ -98,7 +102,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `- **POST** \`${graphqlHttpUrl}\` — GraphQL endpoint (body: GraphQL query). With Nuxt base: e.g. \`http://localhost:3000/api/graphql\`. With direct Nest: e.g. \`http://localhost:1105/graphql\`.`,
     `- **GET** \`${graphqlSchemaUrl}\` — current schema SDL (text); same base pattern as above.`,
     '- A table appears in the schema if some **enabled route** for that table has **both** `GQL_QUERY` and `GQL_MUTATION` in `availableMethods` and a **`mainTable`** pointing at the table. The route **`path` does not need to be** `/<table_name>` (custom paths still qualify).',
-    '- **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`. No mutations if no non-PK columns for input.',
+    '- **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:** `publishedMethods` may include `GQL_QUERY` and/or `GQL_MUTATION` **separately** — each controls anonymous access for queries vs mutations. Otherwise Bearer JWT + `routePermissions` must list the same method key (`GQL_QUERY` / `GQL_MUTATION`).',
     '- MCP does not wrap GraphQL; use REST tools or tell users the URLs above.',
     '',
@@ -130,7 +134,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **triggerConfig examples**: schedule: `{"cron":"0 2 * * *","timezone":"UTC"}`, manual: `{}`. For event/webhook use cases, create a handler/hook with `@DISPATCH.trigger("flow-name", payload)` instead.',
     '- **Step config examples**: script: `{"code":"return #user_definition.find({limit:10})"}`, condition: `{"code":"return @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}`.',
     '- **Data chain**: Steps access previous results via `@FLOW.<stepKey>` and `@LAST`. Input payload via `@PAYLOAD`. Repos via `#table_name`.',
-    '- **Template syntax (flows)**: `@PAYLOAD` → `$ctx.$flow.$payload` (input data), `@LAST` → `$ctx.$flow.$last`, `@FLOW` → `$ctx.$flow`, `@META` → `$ctx.$flow.$meta`, `#table_name` → `$ctx.$repos.table_name`, `@HELPERS` → `$ctx.$helpers`, `@THROW4xx/5xx` → error helpers. Trigger other flows in handlers via `@DISPATCH.trigger(name, payload)` or `$ctx.$dispatch.trigger(name, payload)`.',
+    '- **Template syntax (flows)**: `@PAYLOAD` → `$ctx.$flow.$payload` (input data), `@LAST` → `$ctx.$flow.$last`, `@FLOW` → `$ctx.$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 `@DISPATCH.trigger(name, payload)` or `$ctx.$dispatch.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). `$dispatch.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}`.',
@@ -166,6 +170,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **useConfirm:** Confirmation dialogs. Returns `{ confirm({ title, content, confirmText, cancelText }), isVisible, options, onConfirm, onCancel }`.',
     '- **useHeaderActionRegistry:** Register header actions. Pass array: `useHeaderActionRegistry([{ id, label, onClick, color, icon, order, side, global }])`. Action has `{ id, label, onClick, color, icon, order, side: \'left\'|\'right\', global, component }`.',
     '- **useSubHeaderActionRegistry:** Same as header but for sub-header.',
+    '- **usePageHeaderRegistry:** Page title strip. `{ registerPageHeader, clearPageHeader, pageHeader, hasPageHeader }`. Config: `title`, optional `description`, `stats`, `variant`, `gradient` (`purple`|`blue`|`cyan`|`none` — horizontal strip + leading icon tint), `leadingIcon` (icon name), `hideLeadingIcon`. Call `registerPageHeader` again when title/stats must update (plain object snapshot, not refs inside the config).',
     '- **useMenuRegistry:** Menu management. Returns `{ menuItems, menuGroups, registerMenuItem, unregisterMenuItem, getMenuItemsBySidebar, findParentMenuIdByPath }`.',
     '- **useMenuApi:** Low-level menu API.',
     '- **useFilterQuery:** Filter builder. Returns `{ buildQuery(filter), buildFilterObject(filter), createEmptyFilter(), hasActiveFilters(filter), getFilterSummary(filter, fields), encodeFilterToUrl(filter), parseFilterFromUrl(searchParams) }`.',
@@ -177,7 +182,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '#### Injected UI Components (auto-resolved):',
     '- **Common:** `EmptyState`, `LoadingState`, `ErrorState`, `PageHeader`, `FormCard`, `Modal`, `Drawer`, `BreadCrumbs`, `ListItem`, `LazyImage`, `GlobalConfirm`, `UploadModal`, `UploadModalLazy`, `AvatarInitials`, `BrandingHeader`, `SettingsCard`, `RouteLoading`',
     '- **Data Table:** `DataTable`, `DataTableLazy`, `ColumnSelector`',
-    '- **Form:** `FormEditor`, `FilterEditor`, `FilterHistory`, `FieldSelector`',
+    '- **Form:** `FormEditor`, `FormEditorLazy` (same API, lazy-loaded), `FilterEditor`, `FilterHistory`, `FieldSelector`',
     '- **File Manager:** `FileManager`, `FileView`, `FileGridCard`, `CreateFolderModal`',
     '- **Menu:** `MenuRenderer`, `MenuItemEditor`',
     '- **UI:** `UButton`, `UCard`, `UInput`, `UTable`, `UBadge` (if available)',
@@ -190,7 +195,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- `$ctx` — runtime context',
     '',
     '#### Extension types:',
-    '- **FormEditor field-map:** Customize fields via `:field-map` prop. Options: `label` (override label), `description` (override description), `hideLabel`/`hideDescription` (boolean), `component` (custom Vue component replacing field), `componentProps`, `type` (override field type), `disabled`, `placeholder`. Custom component receives `modelValue`/`update:modelValue`.',
+    '- **FormEditor field-map:** Customize fields via `:field-map`. Options: `label`, `description`, `hideLabel`, `hideDescription`, `component`, `componentProps`, `type`, `disabled`, `placeholder`, `permission`, `excludedOptions`/`includedOptions`, `fieldProps` (e.g. grid `class: \'md:col-span-2\'` when `layout=\'grid\'`), `booleanWrapperClass`, `fieldWrapperClass`. Optional `:sections` — array of `{ id, title?, hideHeading?, headingClass?, class?, rootClass?, fields: string[] }`; field order follows `fields`; unlisted columns render after. Custom input component: `modelValue` / `update:modelValue`.',
     '- **type "page":** Full-page extension. Requires `menu: { id }` — create menu first (`create_menu` or `create_record` on `menu_definition`), find by path/label, then create extension with `menu: { id: menuId }`. `menu_definition` uses **label** not name — filter by `label` or `path`.',
     '- **type "widget":** Widget extension. No menu required. Embed via `<Widget :id="extensionId" />` in other extensions or pages.',
     '',

package/src/lib/table-tools.js

@@ -13,6 +13,26 @@ async function fetchTableWithDetails(ENFYRA_API_URL, tableId) {
   return result?.data?.[0] || result?.[0] || null;
 }
 
+/**
+ * PATCH table_definition with auto-confirm for schema changes.
+ * First PATCH returns preview + requiredConfirmHash; this helper
+ * automatically resends with ?schemaConfirmHash= to apply.
+ */
+async function patchTableAutoConfirm(ENFYRA_API_URL, tableId, body) {
+  const result = await fetchAPI(ENFYRA_API_URL, `/table_definition/${tableId}`, {
+    method: 'PATCH',
+    body: JSON.stringify(body),
+  });
+  const preview = Array.isArray(result?.data) ? result.data[0] : result?.data;
+  if (preview?._preview && preview?.requiredConfirmHash) {
+    return fetchAPI(ENFYRA_API_URL, `/table_definition/${tableId}?schemaConfirmHash=${preview.requiredConfirmHash}`, {
+      method: 'PATCH',
+      body: JSON.stringify(body),
+    });
+  }
+  return result;
+}
+
 /**
  * Register table tools with MCP server
  */
@@ -40,7 +60,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     [
       'Create a new table definition with an auto-included `id` primary key column.',
       '**Not** for adding a custom API path or handler only — for that use **`create_route`** with an existing `mainTableId`. Use **`create_table`** when the user needs new stored data (new entity).',
-      'Use create_column to add more columns after creation (columns are managed via cascade PATCH on table_definition, NOT via /column_definition).',
+      'PREFERRED: pass `columns` param as JSON array to create table WITH columns in one call (cascade). Only use create_column separately if adding to an existing table later.',
       'Schema operations (create/update/delete table, add column) must run one at a time — migration locks DB; parallel calls will fail.',
       'Enfyra auto-creates a default REST route at path `/<table_name>` (same segment as `name`, not alias).',
       'REST surface for that route (matches server route engine): 4 HTTP operations — GET `/<table>` (list/filter), POST `/<table>` (create), PATCH `/<table>/:id` (update), DELETE `/<table>/:id` (delete).',
@@ -53,12 +73,14 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       alias: z.string().optional().describe('Table alias for API. If not provided, the table name will be used.'),
       description: z.string().optional().describe('Description of what this table stores.'),
       isEnabled: z.boolean().optional().default(true).describe('Enable table. Set to false to disable.'),
+      columns: z.string().optional().describe('JSON array of column definitions to create with the table (cascade). Each column: { name, type, isNullable?, isUnique?, defaultValue?, description?, options? }. The `id` column is always auto-included. Example: [{"name":"title","type":"varchar"},{"name":"status","type":"enum","options":["draft","published"]}]'),
     },
-    async ({ name, alias, description, isEnabled }) => {
+    async ({ name, alias, description, isEnabled, columns: columnsJson }) => {
       const idColumn = { name: 'id', type: 'int', isPrimary: true, isGenerated: true, isNullable: false };
+      const userColumns = columnsJson ? JSON.parse(columnsJson) : [];
       const result = await fetchAPI(ENFYRA_API_URL, '/table_definition', {
         method: 'POST',
-        body: JSON.stringify({ name, alias, description, isEnabled, columns: [idColumn] }),
+        body: JSON.stringify({ name, alias, description, isEnabled, columns: [idColumn, ...userColumns] }),
       });
       const base = ENFYRA_API_URL.replace(/\/$/, '');
       const routePath = `/${name}`;
@@ -66,8 +88,11 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         `Auto route path: ${routePath} → full base for REST: ${base}${routePath}`,
         `REST: GET+POST on ${routePath}; PATCH+DELETE on ${routePath}/:id only. No GET ${routePath}/:id.`,
       ].join('\n');
+      const colHint = userColumns.length
+        ? `Table created with ${userColumns.length} column(s) + auto id.`
+        : `Table created. Use create_column to add columns (tableId: ${result.id}).`;
       return {
-        content: [{ type: 'text', text: `Table created successfully with ID: ${result.id}. Next step: use create_column to add columns (tableId: ${result.id}).\n${restHint}\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
+        content: [{ type: 'text', text: `${colHint}\n${restHint}\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
       };
     }
   );
@@ -153,17 +178,14 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
       }
 
-      const existingColumns = (tableData.columns || []).map(col => ({ id: col.id }));
+      const existingColumns = (tableData.columns || []).map(({ table, ...col }) => col);
       const newCol = { name, type, isNullable: isNullable ?? true };
       if (isUnique) newCol.isUnique = true;
       if (defaultValue !== undefined) newCol.defaultValue = defaultValue;
       if (description) newCol.description = description;
       if (options) newCol.options = JSON.parse(options);
 
-      const result = await fetchAPI(ENFYRA_API_URL, `/table_definition/${tableId}`, {
-        method: 'PATCH',
-        body: JSON.stringify({ columns: [...existingColumns, newCol] }),
-      });
+      const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, { columns: [...existingColumns, newCol] });
 
       return {
         content: [{ type: 'text', text: `Column "${name}" added to table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
@@ -186,36 +208,32 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       name: z.string().optional().describe('New column name.'),
       type: z.string().optional().describe('New column type.'),
       isNullable: z.boolean().optional().describe('Set nullable.'),
-      isHidden: z.boolean().optional().describe('Hide column from API responses.'),
+      isPublished: z.boolean().optional().describe('Set column visibility baseline. false = unpublished (omitted from response unless allowed by field permission rules).'),
       defaultValue: z.string().optional().describe('New default value as JSON string.'),
       description: z.string().optional().describe('New description.'),
       options: z.string().optional().describe('New options as JSON string.'),
     },
-    async ({ tableId, columnId, name, type, isNullable, isHidden, defaultValue, description, options }) => {
+    async ({ tableId, columnId, name, type, isNullable, isPublished, defaultValue, description, options }) => {
       const tableData = await fetchTableWithDetails(ENFYRA_API_URL, tableId);
       if (!tableData) {
         return { content: [{ type: 'text', text: `Error: Table with ID ${tableId} not found.` }] };
       }
 
       const columns = (tableData.columns || []).map(col => {
+        const { table, ...rest } = col;
         if (String(col.id) === String(columnId)) {
-          const updated = { id: col.id };
-          if (name !== undefined) updated.name = name;
-          if (type !== undefined) updated.type = type;
-          if (isNullable !== undefined) updated.isNullable = isNullable;
-          if (isHidden !== undefined) updated.isHidden = isHidden;
-          if (defaultValue !== undefined) updated.defaultValue = defaultValue;
-          if (description !== undefined) updated.description = description;
-          if (options !== undefined) updated.options = JSON.parse(options);
-          return updated;
+          if (name !== undefined) rest.name = name;
+          if (type !== undefined) rest.type = type;
+          if (isNullable !== undefined) rest.isNullable = isNullable;
+          if (isPublished !== undefined) rest.isPublished = isPublished;
+          if (defaultValue !== undefined) rest.defaultValue = defaultValue;
+          if (description !== undefined) rest.description = description;
+          if (options !== undefined) rest.options = JSON.parse(options);
         }
-        return { id: col.id };
+        return rest;
       });
 
-      const result = await fetchAPI(ENFYRA_API_URL, `/table_definition/${tableId}`, {
-        method: 'PATCH',
-        body: JSON.stringify({ columns }),
-      });
+      const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, { columns });
 
       return {
         content: [{ type: 'text', text: `Column ${columnId} updated on table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
@@ -245,12 +263,9 @@ export function registerTableTools(server, ENFYRA_API_URL) {
 
       const columns = (tableData.columns || [])
         .filter(col => String(col.id) !== String(columnId))
-        .map(col => ({ id: col.id }));
+        .map(({ table, ...col }) => col);
 
-      const result = await fetchAPI(ENFYRA_API_URL, `/table_definition/${tableId}`, {
-        method: 'PATCH',
-        body: JSON.stringify({ columns }),
-      });
+      const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, { columns });
 
       return {
         content: [{ type: 'text', text: `Column ${columnId} deleted from table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],
@@ -277,11 +292,13 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       onDelete: z.enum(['CASCADE', 'SET NULL', 'RESTRICT', 'NO ACTION']).optional().default('SET NULL').describe('On delete behavior.'),
     },
     async ({ sourceTableId, targetTableId, type, propertyName, inversePropertyName, isNullable, onDelete }) => {
-      const relation = { type, propertyName, inversePropertyName: inversePropertyName || null, isNullable, onDelete };
-      const result = await fetchAPI(ENFYRA_API_URL, `/table_definition/${sourceTableId}`, {
-        method: 'PATCH',
-        body: JSON.stringify({ relations: [{ targetTableId, ...relation }] }),
-      });
+      const tableData = await fetchTableWithDetails(ENFYRA_API_URL, sourceTableId);
+      if (!tableData) {
+        return { content: [{ type: 'text', text: `Error: Table with ID ${sourceTableId} not found.` }] };
+      }
+      const existingRelations = (tableData.relations || []).map(({ sourceTable, targetTable, ...rel }) => rel);
+      const newRelation = { targetTableId, type, propertyName, inversePropertyName: inversePropertyName || null, isNullable, onDelete };
+      const result = await patchTableAutoConfirm(ENFYRA_API_URL, sourceTableId, { relations: [...existingRelations, newRelation] });
       return {
         content: [{ type: 'text', text: `Relation created: ${propertyName} (${type}) from table ${sourceTableId} → ${targetTableId}.\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
       };
@@ -309,12 +326,9 @@ export function registerTableTools(server, ENFYRA_API_URL) {
 
       const relations = (tableData.relations || [])
         .filter(rel => String(rel.id) !== String(relationId))
-        .map(rel => ({ id: rel.id }));
+        .map(({ sourceTable, targetTable, ...rel }) => rel);
 
-      const result = await fetchAPI(ENFYRA_API_URL, `/table_definition/${tableId}`, {
-        method: 'PATCH',
-        body: JSON.stringify({ relations }),
-      });
+      const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, { relations });
 
       return {
         content: [{ type: 'text', text: `Relation ${relationId} deleted from table ${tableId}.\n\n${JSON.stringify(result, null, 2)}` }],

package/src/mcp-server-entry.mjs

@@ -333,8 +333,8 @@ server.tool(
   [
     'Create a post-hook that runs AFTER the handler. Use to transform responses or add metadata.',
     'Use `routeId` from `create_route` or `get_all_routes` — do not create a new table just to get a route id.',
-    'Macros: @DATA (handler result), @STATUS (HTTP status code), @BODY, @QUERY, @USER, @SHARE.',
-    'Must return a value — that becomes the final response.',
+    'Macros: @DATA, @STATUS, @ERROR, @BODY, @QUERY, @USER, @SHARE, @API (post-hooks always run; on error path @ERROR is set, @DATA is null).',
+    'Mutate @DATA / $ctx.$data in place, or return a value: if the hook returns anything other than undefined, that value replaces $ctx.$data as the response payload.',
   ].join(' '),
   {
     routeId: z.union([z.string(), z.number()]).describe('Route definition ID'),