@enfyra/mcp-server 0.0.106 → 0.0.107

package/README.md

@@ -188,7 +188,7 @@ The MCP server includes safety guards for LLM callers:
 - `validate_extension_code` checks Enfyra admin extension code through `/enfyra_extension/preview` without saving.
 - `compiledCode` is generated from `sourceCode` and may differ textually because macros are expanded; the MCP server never accepts hand-written `compiledCode`.
 - JSON responses include `compressionStats` with estimated token savings. Arrays of objects are converted to columnar form only when the compact shape is smaller than raw JSON.
-- Relation tools reject physical FK/junction names.
+- Relation tools reject physical FK/junction names and resolve table ids from exact table names or aliases before schema mutation.
 - Generated code should use relation property names such as `conversation`, `sender`, and `member` instead of physical FK fields such as `conversationId`, `senderId`, or `memberId`.
 - Custom route tools reject `mainTableId` unless the route is the canonical table route.
 - Platform operation tools such as `api_endpoint_workflow`, `create_api_endpoint`, `enable_route`, `disable_route`, `delete_route`, `public_route_methods`, `add_route_methods`, `set_table_graphql`, `ensure_guard`, `ensure_field_permission`, `ensure_column_rule`, `ensure_websocket_event`, `ensure_script_flow_step`, `ensure_menu`, `ensure_page_extension`, `ensure_global_extension`, and `ensure_widget_extension` resolve metadata ids and validate code before saving.
@@ -197,7 +197,7 @@ The MCP server includes safety guards for LLM callers:
 
 ## Query Notes
 
-Use explicit `fields` in read tools. Include mode is the default, such as `fields=id,email`. Any excluded field switches that scope to exclude mode: `fields=-compiledCode` returns all readable fields except `compiledCode`, and `fields=id,-compiledCode` still means all except `compiledCode`. Dotted exclusions such as `fields=-owner.avatar` work for relation fields when the relation exists in metadata. Every list/query call must pass either `limit` for a bounded page or `all: true` for a complete list. When a caller needs every matching row, pass `all: true` to `query_table` or `get_all_routes`; the tool sends REST `limit=0` instead of making the model choose an arbitrary page size like 30 or 50.
+Use explicit `fields` in read tools. Include mode is the default, such as `fields=id,email`. Any excluded field switches that scope to exclude mode: `fields=-compiledCode` returns all readable fields except `compiledCode`, and `fields=id,-compiledCode` still means all except `compiledCode`. Dotted exclusions such as `fields=-owner.avatar` work for relation fields when the relation exists in metadata. Every list/query call must pass either `limit` for a bounded page or `all: true` for a complete list. When a caller needs every matching row, pass `all: true` to `query_table`, `get_all_routes`, or `get_all_tables`; the tool should not choose an arbitrary page size like 30 or 50.
 
 ## Enfyra URL Pattern
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.106",
+  "version": "0.0.107",
   "description": "MCP server for Enfyra - manage Enfyra instances from MCP-compatible coding tools",
   "type": "module",
   "license": "MIT",

package/src/lib/mcp-instructions.js

@@ -60,7 +60,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '',
     '### Direct HTTP Mapping',
     '- Route-backed table CRUD is REST: `GET /<table>?...`, `POST /<table>`, `PATCH /<table>/<id>`, `DELETE /<table>/<id>`. There is no `GET /<table>/<id>`; use a filtered list with `limit=1` or `find_one_record`.',
-    '- REST route lifecycle is controlled by `enfyra_route.isEnabled`: disabled routes are not registered at runtime and return 404. Use `enable_route`/`disable_route` instead of raw route PATCH. REST public access is controlled by route `publicMethods`; otherwise direct HTTP needs Bearer JWT plus route permissions. GraphQL requires Bearer auth and table GraphQL enablement.',
+    '- REST route lifecycle is controlled by `enfyra_route.isEnabled`: disabled routes are not registered at runtime and return 404. Use `enable_route`/`disable_route` instead of raw route PATCH. REST public access is controlled by route `publicMethods`; otherwise direct HTTP needs Bearer JWT plus route permissions. GraphQL table data requires Bearer auth and table GraphQL enablement; anonymous root/schema probes may still return a 200 without exposing table data.',
     '',
     'When the user asks for details, fetch only the relevant live context or example category instead of relying on broad memorized rules.',
   ].join('\n');

package/src/lib/platform-operation-tools.js

@@ -871,8 +871,8 @@ async function runApiEndpointWorkflow(apiUrl, opts) {
     nextSteps,
     cleanupHints: latestState.endpoint.routeId
       ? [
-        `Preview delete route handler with delete_record({ tableName: "enfyra_route_handler", id: ${JSON.stringify(latestState.endpoint.handlerId)} }) before cleanup.`,
-        `Preview delete route with delete_record({ tableName: "enfyra_route", id: ${JSON.stringify(latestState.endpoint.routeId)} }) only when no longer needed.`,
+        `Use delete_route({ routeId: ${JSON.stringify(latestState.endpoint.routeId)}, confirm: false }) to preview route-owned handlers, hooks, guards, and permissions before cleanup.`,
+        `Then call delete_route({ routeId: ${JSON.stringify(latestState.endpoint.routeId)}, expectedPath: ${JSON.stringify(latestState.endpoint.path)}, confirm: true }) when the route contract is no longer needed.`,
       ]
       : [],
   };

package/src/lib/table-tools.js

@@ -3,6 +3,7 @@
  */
 import { z } from 'zod';
 import { fetchAPI } from './fetch.js';
+import { jsonContent } from './response-format.js';
 
 let schemaQueue = Promise.resolve();
 
@@ -43,6 +44,19 @@ export function resolveTableFromMetadataByName(metadata, tableName) {
     .find((table) => table?.name === tableName || table?.alias === tableName) || null;
 }
 
+export function resolveTableIdentifierFromMetadata(metadata, tableRef, label = 'table') {
+  const resolvedTable = normalizeTablesFromMetadata(metadata)
+    .find((table) => (
+      String(getId(table)) === String(tableRef) ||
+      table?.name === tableRef ||
+      table?.alias === tableRef
+    ));
+  if (!resolvedTable) {
+    throw new Error(`${label} "${tableRef}" was not found in metadata. Pass an existing table id, name, or alias from get_all_tables/inspect_table.`);
+  }
+  return getId(resolvedTable);
+}
+
 /**
  * Helper: fetch table with full columns and relations.
  * Dynamic enfyra_table relation fields can be paginated/truncated, so schema
@@ -147,6 +161,14 @@ export function normalizeRelationForTablePatch(relation) {
   return normalized;
 }
 
+function assertNoForbiddenRelationKeys(args) {
+  for (const key of FORBIDDEN_RELATION_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(args, key)) {
+      throw new Error(`create_relation must not include physical column field "${key}". Use sourceTableId/targetTableId and relation propertyName only; Enfyra derives FK and junction columns.`);
+    }
+  }
+}
+
 export function sanitizeExistingRelationForTablePatch(relation) {
   const {
     fkCol,
@@ -307,27 +329,32 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     });
   }
 
-  async function appendRelationToTable({ sourceTableId, targetTableId, type, propertyName, inversePropertyName, mappedBy, isNullable, onDelete, description }) {
+  async function appendRelationToTable(args) {
     return withSchemaQueue(async () => {
-    const tableData = await fetchTableWithDetails(ENFYRA_API_URL, sourceTableId);
+    assertNoForbiddenRelationKeys(args);
+    const { sourceTableId, targetTableId, type, propertyName, inversePropertyName, mappedBy, isNullable, onDelete, description } = args;
+    const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
+    const resolvedSourceTableId = resolveTableIdentifierFromMetadata(metadata, sourceTableId, 'sourceTableId');
+    const resolvedTargetTableId = resolveTableIdentifierFromMetadata(metadata, targetTableId, 'targetTableId');
+    const tableData = await fetchTableWithDetails(ENFYRA_API_URL, resolvedSourceTableId);
     if (!tableData) {
-      return { content: [{ type: 'text', text: `Error: Table with ID ${sourceTableId} not found.` }] };
+      return { content: [{ type: 'text', text: `Error: Table ${sourceTableId} not found.` }] };
     }
     const existingRelations = (tableData.relations || []).map(sanitizeExistingRelationForTablePatch);
     const beforeIds = existingRelations.map((relation) => String(getId(relation))).filter((id) => id !== 'null');
-    const newRelation = { targetTable: targetTableId, type, propertyName };
+    const newRelation = { targetTable: resolvedTargetTableId, type, propertyName };
     if (inversePropertyName !== undefined) newRelation.inversePropertyName = inversePropertyName || null;
     if (mappedBy !== undefined) newRelation.mappedBy = mappedBy;
     if (isNullable !== undefined) newRelation.isNullable = isNullable;
     if (onDelete !== undefined) newRelation.onDelete = onDelete;
     if (description !== undefined) newRelation.description = description;
-    const result = await patchTableAutoConfirm(ENFYRA_API_URL, sourceTableId, { relations: [...existingRelations, newRelation] });
-    await verifyRelationCascade(ENFYRA_API_URL, sourceTableId, beforeIds, {
+    const result = await patchTableAutoConfirm(ENFYRA_API_URL, resolvedSourceTableId, { relations: [...existingRelations, newRelation] });
+    await verifyRelationCascade(ENFYRA_API_URL, resolvedSourceTableId, beforeIds, {
       action: 'create',
       propertyName,
     });
     return {
-      content: [{ type: 'text', text: `Relation created: ${propertyName} (${type}) from table ${sourceTableId} → ${targetTableId}.\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
+      content: [{ type: 'text', text: `Relation created: ${propertyName} (${type}) from table ${resolvedSourceTableId} → ${resolvedTargetTableId}.\n\nFull result:\n${JSON.stringify(result, null, 2)}` }],
     };
     });
   }
@@ -434,8 +461,8 @@ export function registerTableTools(server, ENFYRA_API_URL) {
   };
 
   const relationCreateSchema = {
-    sourceTableId: z.string().describe('Source table ID (the table that owns the FK for many-to-one).'),
-    targetTableId: z.string().describe('Target table ID.'),
+    sourceTableId: z.string().describe('Source table id, exact table name, or alias. For many-to-one, this is the table that owns the relation property.'),
+    targetTableId: z.string().describe('Target table id, exact table name, or alias. MCP resolves names/aliases to ids before mutation.'),
     type: z.enum(['many-to-one', 'one-to-many', 'one-to-one', 'many-to-many']).describe('Relation type.'),
     propertyName: z.string().describe('Property name on source table (e.g., "customer", "items").'),
     inversePropertyName: z.string().optional().describe('Property name on target table for bidirectional relation (e.g., "orders"). Omit unless the reverse field is truly needed.'),
@@ -443,6 +470,13 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     isNullable: z.boolean().optional().default(true).describe('Whether the relation is nullable.'),
     onDelete: z.enum(['CASCADE', 'SET NULL', 'RESTRICT']).optional().default('SET NULL').describe('On delete behavior.'),
     description: z.string().optional().describe('Relation description.'),
+    fkCol: z.never().optional().describe('Forbidden. Use propertyName only; Enfyra derives FK columns.'),
+    fkColumn: z.never().optional().describe('Forbidden. Use propertyName only; Enfyra derives FK columns.'),
+    foreignKeyColumn: z.never().optional().describe('Forbidden. Use propertyName only; Enfyra derives FK columns.'),
+    sourceColumn: z.never().optional().describe('Forbidden. Use propertyName only; Enfyra derives FK columns.'),
+    targetColumn: z.never().optional().describe('Forbidden. Use propertyName only; Enfyra derives FK columns.'),
+    junctionSourceColumn: z.never().optional().describe('Forbidden. Use relation property names only; Enfyra derives junction columns.'),
+    junctionTargetColumn: z.never().optional().describe('Forbidden. Use relation property names only; Enfyra derives junction columns.'),
   };
 
   const columnDeleteSchema = {
@@ -461,13 +495,45 @@ export function registerTableTools(server, ENFYRA_API_URL) {
 
   server.tool(
     'get_all_tables',
-    'Get all table definitions in the system',
-    {},
-    async () => {
-      const result = await fetchAPI(ENFYRA_API_URL, '/enfyra_table?limit=500');
-      return {
-        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-      };
+    'List table definitions from metadata. Every call must pass either limit or all=true. Use search to narrow by table name or alias.',
+    {
+      limit: z.number().int().positive().optional().describe('Maximum tables returned after search. Required unless all=true.'),
+      all: z.boolean().optional().describe('Return all matched tables. Use this when a complete table list is required.'),
+      search: z.string().optional().describe('Optional table name, alias, or description substring filter.'),
+    },
+    async ({ limit, all, search }) => {
+      if (!all && limit === undefined) {
+        throw new Error('get_all_tables requires either limit or all=true. Do not invent arbitrary limits for complete table lists; use all=true.');
+      }
+      const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
+      const needle = search?.trim().toLowerCase();
+      const tables = normalizeTablesFromMetadata(metadata)
+        .map((table) => ({
+          id: getId(table),
+          name: table.name ?? null,
+          alias: table.alias ?? null,
+          description: table.description ?? null,
+          isSingleRecord: table.isSingleRecord ?? null,
+          columnCount: Array.isArray(table.columns) ? table.columns.length : null,
+          relationCount: Array.isArray(table.relations) ? table.relations.length : null,
+          routeBacked: Boolean(table.route || table.routeId || table.path),
+        }))
+        .filter((table) => {
+          if (!needle) return true;
+          return [table.name, table.alias, table.description]
+            .some((value) => String(value || '').toLowerCase().includes(needle));
+        });
+      const returnedTables = all ? tables : tables.slice(0, limit);
+      return jsonContent({
+        action: 'get_all_tables',
+        totalTableCount: normalizeTablesFromMetadata(metadata).length,
+        matchedTableCount: tables.length,
+        returnedTableCount: returnedTables.length,
+        all: Boolean(all),
+        search: search || null,
+        tables: returnedTables,
+        detailHint: 'Use inspect_table with a table id/name for columns, relations, indexes, routes, permissions, and GraphQL state.',
+      });
     }
   );
 
@@ -558,7 +624,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
       alias: z.string().optional().describe('New table alias.'),
       description: z.string().optional().describe('New description.'),
       isSingleRecord: z.boolean().optional().describe('Set to true for single-record table (e.g., settings/config).'),
-      graphqlEnabled: z.boolean().optional().describe('Enable or disable GraphQL for this table by syncing enfyra_graphql.isEnabled. GraphQL still requires Bearer auth.'),
+      graphqlEnabled: z.boolean().optional().describe('Enable or disable GraphQL for this table by syncing enfyra_graphql.isEnabled. GraphQL table data still requires Bearer auth; anonymous root or schema probes may return 200.'),
       indexes: z.string().optional().describe('Complete JSON array of logical index field groups to store on enfyra_table.indexes. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Omit to preserve current indexes; pass [] to clear.'),
       uniques: z.string().optional().describe('Complete JSON array of logical unique field groups to store on enfyra_table.uniques. Each group can be ["fieldA","fieldB"] or {"value":["fieldA","fieldB"]}. Omit to preserve current uniques; pass [] to clear.'),
     },
@@ -740,6 +806,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     'create_relation',
     [
       'Create a relation between two tables (many-to-one, one-to-many, one-to-one, many-to-many).',
+      'sourceTableId and targetTableId may be table ids, exact table names, or aliases; MCP resolves them from metadata before mutation.',
       'For many-to-one: a physical FK column is created on the source table. For one-to-many: the FK is on the target (inverse relation). This physical FK is derived by Enfyra and hidden from app schema/forms.',
       'Never ask the user for physical FK column names and never send fkCol/fkColumn/foreignKeyColumn/sourceColumn/targetColumn/junction*Column. The public API uses relation propertyName only.',
       'Run sequentially — DB migration locks per operation.',
@@ -754,6 +821,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
     'add_relation',
     [
       'Alias for create_relation. Add a relation through the canonical enfyra_table cascade.',
+      'sourceTableId and targetTableId may be table ids, exact table names, or aliases.',
       'Use relation propertyName only; never provide physical FK or junction column names.',
       'Run schema changes sequentially — migration locks DB per operation.',
     ].join(' '),

package/src/mcp-server-entry.mjs

@@ -64,7 +64,7 @@ const CAPABILITY_AREAS = [
   {
     area: 'GraphQL',
     tables: ['enfyra_graphql'],
-    workflow: 'Enable per table through enfyra_graphql or update_table graphqlEnabled. GraphQL requires Bearer auth.',
+    workflow: 'Enable per table through enfyra_graphql or update_table graphqlEnabled. GraphQL table data requires Bearer auth; anonymous root or schema probes may return 200 without exposing table data.',
   },
   {
     area: 'Files and storage',
@@ -746,7 +746,7 @@ server.tool(
         endpoint: `${ENFYRA_API_URL.replace(/\/$/, '')}/graphql`,
         schemaEndpoint: `${ENFYRA_API_URL.replace(/\/$/, '')}/graphql-schema`,
         enablement: 'A table appears in GraphQL when enfyra_graphql has an enabled row for that table. REST route availableMethods does not enable GraphQL.',
-        auth: 'GraphQL currently requires Authorization: Bearer <accessToken>; REST publicMethods does not make GraphQL anonymous.',
+        auth: 'GraphQL table data requires Authorization: Bearer <accessToken>; REST publicMethods do not make GraphQL table data anonymous. Anonymous root/schema probes may still return 200.',
         management: routeTables.has('enfyra_graphql')
           ? 'Use update_table graphqlEnabled or create/update records on enfyra_graphql, then reload_graphql if needed.'
           : 'Use update_table graphqlEnabled, then reload_graphql if needed.',
@@ -914,7 +914,7 @@ server.tool(
           : 'SQL commonly uses id; Mongo uses _id. Use table metadata primary column when available.',
         relationNames: 'API relation operations use relation propertyName, not physical FK column names.',
         relationCascadeFkContract: 'When creating relations through create_table/create_relation/enfyra_table PATCH, never provide fkCol/fkColumn/foreignKeyColumn/sourceColumn/targetColumn/junction*Column. These are physical implementation details derived by Enfyra and hidden from app schema/forms.',
-        graphql: 'GraphQL query args also accept filter/sort/page/limit, but GraphQL requires Bearer auth and table enablement via enfyra_graphql.',
+        graphql: 'GraphQL query args also accept filter/sort/page/limit. Table data requires Bearer auth and table enablement via enfyra_graphql; anonymous root/schema probes may still return 200.',
       },
       table: tableName
         ? {
@@ -1052,7 +1052,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 publicMethods do not make GraphQL anonymous.',
+          caveat: 'REST publicMethods do not make GraphQL table data anonymous.',
         },
         extensionVueSfc: {
           runs: 'Frontend extension code, not server sandbox.',
@@ -1095,7 +1095,7 @@ server.tool(
     '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 enfyra_graphql/update_table graphqlEnabled and send Bearer auth.',
+    'GraphQL: see graphqlHttpUrl / graphqlSchemaUrl in response; enable per table via enfyra_graphql/update_table graphqlEnabled and send Bearer auth for table data queries. Anonymous root/schema probes may still return 200.',
   ].join(' '),
   {},
   async () => {
@@ -1113,7 +1113,7 @@ server.tool(
       },
       auth: {
         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.',
+        graphql: 'GraphQL table data requires Bearer auth; route publicMethods do not make GraphQL table data anonymous. Anonymous root/schema probes may still return 200.',
         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.',