@enfyra/mcp-server 0.0.22 → 0.0.24

package/package.json

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

package/src/lib/mcp-instructions.js

@@ -64,6 +64,8 @@ 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`.',
@@ -164,6 +166,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\`.`,
@@ -300,6 +304,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

@@ -108,23 +108,27 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       '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).',
       'There is NO `GET /<table>/:id`. To fetch one row by id, use GET `/<table>?filter={"id":{"_eq":"<id>"}}&limit=1` or tool query_table / find_one_record.',
+      '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, 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, description, columns: [idColumn, ...userColumns], relations: userRelations };
+      if (isSingleRecord !== undefined) body.isSingleRecord = isSingleRecord;
       const result = await fetchAPI(ENFYRA_API_URL, '/table_definition', {
         method: 'POST',
-        body: JSON.stringify({ name, alias, description, columns: [idColumn, ...userColumns], relations: userRelations }),
+        body: JSON.stringify(body),
       });
       const createdTable = Array.isArray(result?.data) ? result.data[0] : result;
       const createdTableId = createdTable?.id ?? createdTable?._id;

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 columns and relations arrays in the same cascade call. MCP create_table exposes both.',
+        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')
@@ -498,6 +498,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: [
@@ -626,6 +627,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 +705,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).',