@enfyra/mcp-server 0.0.23 → 0.0.25

package/package.json

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

package/src/lib/mcp-instructions.js

@@ -65,6 +65,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '### After a new table is created',
     '- MCP **`create_table` supports creating columns and relations in the same call**: pass `columns` and `relations` as JSON arrays. Use `create_relation` only when adding a relation to an existing table later.',
     '- MCP **`create_table` supports `isSingleRecord` directly**. Set `isSingleRecord: true` in the create call for settings/config tables that should keep only one record; do not create first and then patch only for this flag.',
+    '- MCP **`create_table` does not accept `alias`**. Do not invent or send alias during table creation; default route/schema behavior is based on `name`. Use `update_table` later only when alias truly needs to change.',
     '- In `create_table.relations`, each relation uses `targetTable` (table id or `{id}`), `type`, `propertyName`, optional `inversePropertyName` or `mappedBy`, `isNullable`, `onDelete`, and `description`. The target table must already exist.',
     '- **Never ask for or provide physical FK column names** when creating/updating relations. Do not include `fkCol`, `fkColumn`, `foreignKeyColumn`, `sourceColumn`, `targetColumn`, `junctionSourceColumn`, or `junctionTargetColumn` in create/update payloads unless you are only displaying existing metadata. Enfyra relation cascade derives physical FK/junction names from `propertyName` and table metadata, then hides FK columns from app form/schema definition.',
     '- For relation CRUD payloads, the public interface is the relation `propertyName`: example create body uses `"author": {"id": 1}`, not `"authorId"` or a physical FK column. Query/deep/filter keys also use relation `propertyName`.',
@@ -107,6 +108,14 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- 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.',
     '',
+    '### `$cache` / `@CACHE` user cache',
+    '- `$ctx.$cache` and the `@CACHE` macro use Enfyra-managed **user cache**, not the internal runtime metadata cache.',
+    '- Script keys are logical keys such as `user:123` or `report:daily`. Do not include `NODE_NAME`, `user_cache:`, Redis prefixes, or another app namespace in script code.',
+    '- On Redis-backed deployments, Enfyra stores user cache under the current app `NODE_NAME` namespace as `NODE_NAME:user_cache:*`. Admin Redis Key Editor uses the same storage contract, so values edited there are visible through `$cache` and `@CACHE`.',
+    '- User cache is limited by `REDIS_USER_CACHE_LIMIT_MB` (default 30 MB). `REDIS_USER_CACHE_MAX_VALUE_BYTES` optionally rejects oversized single values when greater than 0.',
+    '- When user cache exceeds its allocation, Enfyra evicts least-recently-used **user cache** keys only. System Redis keys such as runtime cache snapshots, BullMQ queues, Socket.IO, runtime telemetry, and locks are not counted or evicted by this quota.',
+    '- Prefer `set(key, value, ttlMs)` with a TTL. `setNoExpire` is allowed, but persistent user-cache entries can still be evicted by the soft allocation limit.',
+    '',
     '### 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.',
@@ -165,6 +174,8 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- 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.',
     '- 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;`.',
     '',
     '### GraphQL (same prefix as REST / ENFYRA_API_URL)',
     `- **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\`.`,
@@ -301,6 +312,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     `- \`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)`,
+    `- \`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>\``,
     `- \`update_record\` → PATCH \`${base}/<tableName>/<id>\``,

package/src/lib/table-tools.js

@@ -111,20 +111,20 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       'Set `isSingleRecord: true` directly in create_table for settings/config tables that should keep only one record.',
       `Full URLs: ${apiBase}/<table_name> (example table post: ${apiBase}/post).`,
       'GraphQL is enabled separately per table through `gql_definition` or `update_table` with `graphqlEnabled`; it is not controlled by route availableMethods.',
+      'Do not set alias during create_table. The create tool accepts name, description, isSingleRecord, columns, and relations only; use update_table later only if alias really needs to change.',
     ].join(' '),
     {
       name: z.string().describe('Table name (e.g., "user_definition", "my_custom_table"). Must be unique, lowercase with underscores.'),
-      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.'),
       isSingleRecord: z.boolean().optional().describe('Set to true for single-record tables such as settings/config. This is passed directly to table_definition create.'),
       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"]}]'),
       relations: z.string().optional().describe('JSON array of relation definitions to create with the table in the same cascade call. Each relation: { targetTable, type, propertyName, inversePropertyName?, mappedBy?, isNullable?, onDelete?, description? }. targetTable can be an id or {"id": <id>}. Do not include physical FK/junction columns such as fkCol, foreignKeyColumn, sourceColumn, targetColumn, junctionSourceColumn, or junctionTargetColumn; Enfyra derives them and hides FK columns from app schema. Example: [{"targetTable":2,"type":"many-to-one","propertyName":"author","inversePropertyName":"posts","isNullable":false,"onDelete":"CASCADE"}]'),
     },
-    async ({ name, alias, description, isSingleRecord, columns: columnsJson, relations: relationsJson }) => {
+    async ({ name, description, isSingleRecord, columns: columnsJson, relations: relationsJson }) => {
       const idColumn = { name: 'id', type: 'int', isPrimary: true, isGenerated: true, isNullable: false };
       const userColumns = parseJsonArrayParam('columns', columnsJson);
       const userRelations = parseJsonArrayParam('relations', relationsJson).map(normalizeRelationForTablePatch);
-      const body = { name, alias, description, columns: [idColumn, ...userColumns], relations: userRelations };
+      const body = { name, description, columns: [idColumn, ...userColumns], relations: userRelations };
       if (isSingleRecord !== undefined) body.isSingleRecord = isSingleRecord;
       const result = await fetchAPI(ENFYRA_API_URL, '/table_definition', {
         method: 'POST',

package/src/mcp-server-entry.mjs

@@ -349,7 +349,7 @@ server.tool(
         customRouteWorkflow: 'For a new endpoint use create_route against an existing table, then create_handler/create_pre_hook/create_post_hook. Do not create a table just to get a path.',
       },
       schemaManagement: {
-        createTable: 'POST /table_definition supports isSingleRecord at create time and supports columns and relations arrays in the same cascade call. MCP create_table exposes isSingleRecord, columns, and relations directly.',
+        createTable: 'POST /table_definition supports isSingleRecord at create time and supports columns and relations arrays in the same cascade call. MCP create_table exposes isSingleRecord, columns, and relations directly. It does not accept alias at create time; table name drives the default route/schema behavior.',
         updateTable: 'PATCH /table_definition/:id is the canonical path for table property changes and column/relation schema changes.',
         columns: 'column_definition has no REST route; use create_table/create_column/update_column/delete_column.',
         relations: routeTables.has('relation_definition')
@@ -448,7 +448,9 @@ server.tool(
       },
       cacheAndCluster: {
         metadataMutationReloads: 'Metadata-backed mutations emit cache invalidation; admin reload endpoints exist for metadata/routes/graphql/guards/all.',
-        multiInstanceContract: 'Backend is cluster-aware through cache invalidation and Redis/BullMQ paths, but this MCP can only observe metadata/API state, not every node health.',
+        runtimeCacheContract: 'REDIS_RUNTIME_CACHE=true stores runtime definition snapshots in Redis so instances with the same NODE_NAME read the same runtime cache namespace.',
+        userCacheContract: '$cache/@CACHE uses managed user cache under NODE_NAME:user_cache:* with REDIS_USER_CACHE_LIMIT_MB default 30 MB; quota eviction only removes user cache keys, not runtime cache, BullMQ, Socket.IO, telemetry, or lock keys.',
+        multiInstanceContract: 'Backend is cluster-aware through cache invalidation, Redis runtime cache, Redis user cache, and BullMQ paths, but this MCP can only observe metadata/API state, not every node health.',
         flowWorkerContract: 'Flow jobs require the backend flow worker to be initialized after HTTP listen and websocket gateway init; trigger_flow only confirms enqueue/result from admin endpoint.',
       },
       runtimeGaps: [
@@ -498,6 +500,7 @@ server.tool(
         meta: 'Request metadata/counts where supported.',
         deep: 'Nested relation fetch object keyed by relation propertyName.',
       },
+      countPattern: 'For counts, query only fields=id with limit=1 and request meta. Use meta=totalCount without a filter, or meta=filterCount when a filter is supplied. MCP count_records wraps this pattern.',
       deep: {
         shape: '{ [relationName]: { fields?, filter?, sort?, limit?, page?, deep? } }',
         rules: [
@@ -552,13 +555,14 @@ 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/@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/@SOCKET/@TRIGGER/@DATA/@ERROR/@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',
           '@REPOS': '$ctx.$repos',
+          '@CACHE': '$ctx.$cache',
           '@HELPERS': '$ctx.$helpers',
           '@SOCKET': '$ctx.$socket',
           '@DATA': '$ctx.$data',
@@ -576,27 +580,32 @@ server.tool(
           '@FLOW_META': '$ctx.$flow.$meta',
           '#table_name': '$ctx.$repos.table_name',
         },
+        cache: {
+          contract: '@CACHE and $ctx.$cache use managed user cache. Use logical keys only; Enfyra stores Redis-backed user cache under NODE_NAME:user_cache:* and Redis Admin Key Editor uses the same storage path.',
+          quota: 'REDIS_USER_CACHE_LIMIT_MB defaults to 30 MB. If exceeded, Enfyra evicts least-recently-used user-cache keys only; system Redis keys are not counted or evicted.',
+          keyRule: 'Do not include NODE_NAME, user_cache:, or Redis namespace prefixes in scripts. Prefer TTL-based set(key, value, ttlMs); setNoExpire may still be evicted by the user-cache soft allocation.',
+        },
         throws: '@THROW400 through @THROW503 and @THROW map to $ctx.$throw helpers.',
       },
       contexts: {
         preHook: {
           runs: 'Before handler.',
-          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REPOS', '@HELPERS', '@THROW*', '@SOCKET emit helpers'],
+          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REPOS', '@CACHE', '@HELPERS', '@THROW*', '@SOCKET emit helpers'],
           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', '@HELPERS', '@PKGS', '@SOCKET emit helpers', '@TRIGGER'],
+          data: ['@BODY', '@QUERY', '@PARAMS', '@USER', '@REPOS.main', '@REPOS.secure', '@CACHE', '@HELPERS', '@PKGS', '@SOCKET emit helpers', '@TRIGGER'],
           returnBehavior: 'Return value becomes response body unless post-hook changes it.',
         },
         postHook: {
           runs: 'After handler, including error path.',
-          data: ['@DATA', '@STATUS', '@ERROR', '@BODY', '@QUERY', '@USER', '@SHARE', '@API'],
+          data: ['@DATA', '@STATUS', '@ERROR', '@BODY', '@QUERY', '@USER', '@CACHE', '@SHARE', '@API'],
           returnBehavior: 'Mutate @DATA/$ctx.$data or return a non-undefined replacement response.',
         },
         flowStep: {
           runs: 'Inside flow execution or admin flow step test.',
-          data: ['@FLOW_PAYLOAD', '@FLOW_LAST', '@FLOW', '@FLOW_META', '#table_name', '@HELPERS', '@SOCKET', '@TRIGGER'],
+          data: ['@FLOW_PAYLOAD', '@FLOW_LAST', '@FLOW', '@FLOW_META', '#table_name', '@CACHE', '@HELPERS', '@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.',
         },
@@ -626,6 +635,7 @@ server.tool(
           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.',
         packages: 'Server packages installed through install_package are exposed as $ctx.$pkgs.packageName in server scripts.',
@@ -703,6 +713,49 @@ server.tool('query_table', 'Query any table in Enfyra with filters, sorting, and
   return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
 });
 
+server.tool(
+  'count_records',
+  [
+    'Count records in a route-backed Enfyra table using the lightweight REST meta pattern.',
+    'Without filter it requests fields=id&limit=1&meta=totalCount and returns meta.totalCount.',
+    'With filter it requests fields=id&limit=1&meta=filterCount and returns meta.filterCount.',
+    'Use this instead of fetching rows when the user only needs a count.',
+  ].join(' '),
+  {
+    tableName: z.string().describe('Table name to count. Must have a REST route.'),
+    filter: z.string().optional().describe('Optional Query DSL filter as JSON string. Example: \'{"status":{"_eq":"active"}}\''),
+  },
+  async ({ tableName, filter }) => {
+    validateTableName(tableName);
+    validateFilter(filter);
+
+    const metaField = filter ? 'filterCount' : 'totalCount';
+    const queryParams = new URLSearchParams();
+    queryParams.set('fields', 'id');
+    queryParams.set('limit', '1');
+    queryParams.set('meta', metaField);
+    if (filter) queryParams.set('filter', filter);
+
+    const result = await fetchAPI(ENFYRA_API_URL, `/${tableName}?${queryParams.toString()}`);
+    const meta = result?.meta || {};
+    const hasCount = Object.prototype.hasOwnProperty.call(meta, metaField);
+    const count = hasCount ? Number(meta[metaField]) : null;
+    const payload = {
+      tableName,
+      count,
+      countField: metaField,
+      filterApplied: !!filter,
+      meta,
+      request: {
+        path: `/${tableName}`,
+        query: Object.fromEntries(queryParams.entries()),
+      },
+      warning: hasCount ? undefined : `Response meta did not include ${metaField}.`,
+    };
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+  },
+);
+
 server.tool(
   'find_one_record',
   'Find a single record by ID or filter. By ID uses GET with filter (Enfyra has no GET /table/:id route).',