@enfyra/mcp-server 0.1.30 → 0.1.32

package/dist/lib/toolset-filter.d.ts

@@ -0,0 +1,9 @@
+export declare const MCP_TOOLSETS: readonly ["guided", "full"];
+export type McpToolset = typeof MCP_TOOLSETS[number];
+export declare function normalizeMcpToolset(value: unknown): McpToolset;
+export declare function isToolVisibleInToolset(toolName: string, toolset: McpToolset): boolean;
+export declare function installToolsetFilter(server: any, toolset: McpToolset): {
+    toolset: "full" | "guided";
+    hiddenTools: string[];
+};
+export declare function summarizeToolsetForInstructions(toolset: McpToolset): string;

package/dist/lib/toolset-filter.js

@@ -0,0 +1,126 @@
+export const MCP_TOOLSETS = ['guided', 'full'];
+const GUIDED_TOOL_NAMES = new Set([
+    'get_enfyra_required_knowledge',
+    'get_enfyra_examples',
+    'discover_enfyra_workflows',
+    'discover_enfyra_system',
+    'discover_runtime_context',
+    'discover_query_capabilities',
+    'discover_script_contexts',
+    'get_enfyra_api_context',
+    'get_permission_profile',
+    'search_admin_extensions',
+    'search_runtime_zone',
+    'debug_field_exposure',
+    'inspect_table',
+    'inspect_route',
+    'inspect_feature',
+    'trace_metadata_usage',
+    'get_table_metadata',
+    'get_all_tables',
+    'get_all_routes',
+    'get_schema_design_context',
+    'query_table',
+    'count_records',
+    'find_one_record',
+    'create_records',
+    'update_records',
+    'delete_records',
+    'create_tables',
+    'update_tables',
+    'delete_tables',
+    'create_columns',
+    'update_columns',
+    'delete_columns',
+    'create_relations',
+    'delete_relations',
+    'get_script_source',
+    'patch_script_source',
+    'update_script_source',
+    'validate_dynamic_script',
+    'validate_extension_code',
+    'get_extension_theme_contract',
+    'get_theme_class_reference',
+    'extension_workflow',
+    'update_extension_code',
+    'patch_extension_code',
+    'ensure_menu',
+    'reorder_menus',
+    'ensure_page_extension',
+    'ensure_global_extension',
+    'ensure_widget_extension',
+    'api_endpoint_workflow',
+    'create_pre_hook',
+    'test_rest_endpoint',
+    'run_admin_test',
+    'test_flow_step',
+    'trigger_flow',
+    'audit_route_access',
+    'ensure_route_access',
+    'enable_route',
+    'disable_route',
+    'delete_route',
+    'public_route_methods',
+    'private_route_methods',
+    'set_table_graphql',
+    'ensure_column_rule',
+    'ensure_field_permission',
+    'ensure_guard',
+    'ensure_websocket_gateway',
+    'ensure_websocket_event',
+    'ensure_manual_flow',
+    'ensure_scheduled_flow',
+    'plan_flow_steps',
+    'choose_flow_step_tool',
+    'ensure_script_flow_step',
+    'ensure_condition_flow_step',
+    'ensure_query_flow_step',
+    'ensure_http_flow_step',
+    'ensure_create_flow_step',
+    'ensure_update_flow_step',
+    'ensure_delete_flow_step',
+    'ensure_sleep_flow_step',
+    'ensure_log_flow_step',
+    'ensure_trigger_flow_step',
+    'search_logs',
+    'tail_log',
+    'search_npm',
+    'install_package',
+]);
+export function normalizeMcpToolset(value) {
+    const raw = String(value || '').trim().toLowerCase();
+    if (raw === 'full')
+        return 'full';
+    return 'guided';
+}
+export function isToolVisibleInToolset(toolName, toolset) {
+    if (toolset === 'full')
+        return true;
+    return GUIDED_TOOL_NAMES.has(toolName);
+}
+export function installToolsetFilter(server, toolset) {
+    const registerTool = server.tool.bind(server);
+    const hiddenTools = [];
+    server.tool = (name, description, schema, handler) => {
+        if (!isToolVisibleInToolset(name, toolset)) {
+            hiddenTools.push(name);
+            return undefined;
+        }
+        return registerTool(name, description, schema, handler);
+    };
+    return {
+        toolset,
+        hiddenTools,
+    };
+}
+export function summarizeToolsetForInstructions(toolset) {
+    if (toolset === 'full') {
+        return 'Toolset mode: full. All Enfyra MCP tools are visible, including low-level escape hatches.';
+    }
+    return [
+        'Toolset mode: guided. The visible tool surface is curated for weak and medium LLMs.',
+        'Prefer discover_enfyra_workflows, search_runtime_zone, inspect_* tools, and operation-level ensure/workflow tools.',
+        'Low-level escape hatches are hidden by default; set ENFYRA_MCP_TOOLSET=full only for expert debugging or compatibility work.',
+    ].join(' ');
+}
+//# sourceMappingURL=toolset-filter.js.map

package/dist/lib/toolset-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolset-filter.js","sourceRoot":"","sources":["../../src/lib/toolset-filter.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server-entry.js

@@ -37,9 +37,11 @@ import { assertDynamicCodeKnowledgeAck, assertDynamicCodeKnowledgeAckIf, assertE
 import { validateMainTableRoutePath } from './lib/route-guards.js';
 import { installColumnarToolFormatter, jsonContent } from './lib/response-format.js';
 import { compactSourceFields, writeSourceArtifact } from './lib/source-artifacts.js';
+import { installToolsetFilter, normalizeMcpToolset, summarizeToolsetForInstructions } from './lib/toolset-filter.js';
 import { findRoutePermission, mergeMethodNames, normalizeMethodNames, resolveRoleByNameOrId, routeAvailableMethodNames, routePublicMethodNames, summarizeRouteAccess, summarizeRoutePermission, validateMethodsForRoute, } from './lib/route-permission-tools.js';
 // Initialize auth module
 initAuth(ENFYRA_API_URL, ENFYRA_API_TOKEN);
+const MCP_TOOLSET = normalizeMcpToolset(process.env.ENFYRA_MCP_TOOLSET);
 const CAPABILITY_AREAS = [
     {
         area: 'Schema and metadata',
@@ -817,9 +819,12 @@ const server = new McpServer({
     name: 'enfyra-mcp',
     version: '1.0.0',
 }, {
-    instructions: buildMcpServerInstructions(ENFYRA_API_URL),
+    instructions: buildMcpServerInstructions(ENFYRA_API_URL, {
+        toolsetSummary: summarizeToolsetForInstructions(MCP_TOOLSET),
+    }),
 });
 installColumnarToolFormatter(server);
+installToolsetFilter(server, MCP_TOOLSET);
 // ============================================================================
 // METADATA TOOLS
 // ============================================================================
@@ -1308,7 +1313,7 @@ server.tool('get_enfyra_api_context', [
     };
     return jsonContent(payload);
 });
-server.tool('query_table', 'Query any route-backed table. Response is minimal unless fields is explicit. Every call must pass either limit or all=true.', {
+server.tool('query_table', 'Query any route-backed table. Response is minimal unless fields is explicit. Every call must pass either limit or all=true. Use count_records or meta=filterCount/totalCount for counts; call discover_query_capabilities before using aggregate objects instead of guessing _sum/_count operators.', {
     tableName: z.string().describe('Table name to query'),
     filter: jsonObjectParam(z, 'Filter object').optional().describe('Filter object. Example: {"status": {"_eq": "active"}}.'),
     sort: z.string().optional().describe('Sort field. Prefix with - for descending (e.g., "createdAt", "-id")'),
@@ -1318,7 +1323,7 @@ server.tool('query_table', 'Query any route-backed table. Response is minimal un
     fields: z.array(z.string()).optional().describe('Fields to select. If omitted, MCP selects only the table primary key to avoid oversized responses.'),
     meta: z.string().optional().describe('Optional REST meta request, e.g. "totalCount", "filterCount", or aggregate modes supported by the route. Use count_records for simple counts.'),
     deep: jsonObjectParam(z, 'Deep relation fetch object').optional().describe('Optional deep relation fetch object. Keys must be relation propertyName values.'),
-    aggregate: jsonObjectParam(z, 'Aggregate object').optional().describe('Optional aggregate object keyed by real fields/relations. Results are returned in response.meta.aggregate when supported. Do not request aggregates over hidden fields/private relations in user-facing APIs.'),
+    aggregate: jsonObjectParam(z, 'Aggregate object').optional().describe('Optional aggregate object keyed by real fields/relations, only after discover_query_capabilities confirms the supported operator shape for this table/route. Results are returned in response.meta.aggregate when supported. Do not guess _sum/_count; use count_records or meta=filterCount/totalCount for counts. Do not request aggregates over hidden fields/private relations in user-facing APIs.'),
 }, async ({ tableName, filter, sort, page, limit, all, fields, meta, deep, aggregate }) => {
     if (!all && limit === undefined) {
         throw new Error('query_table requires either limit or all=true. Do not rely on implicit default page sizes.');
@@ -1673,13 +1678,21 @@ server.tool('update_script_source', [
                     scriptValidation: prepared.scriptValidation,
                 }, null, 2) }] };
 });
-server.tool('delete_records', 'Delete one or more route-backed records in one MCP call. Pass items as a native JSON array; for one delete, pass one item. The tool previews every target when confirm=false, rejects duplicate ids, and deletes sequentially when confirm=true.', {
+function isNotFoundDeleteError(error) {
+    const message = String(error?.message || error || '').toLowerCase();
+    return message.includes('api error (404)')
+        || message.includes('not found')
+        || message.includes('not exists')
+        || message.includes('does not exist');
+}
+server.tool('delete_records', 'Delete one or more route-backed records in one MCP call. Pass items as a native JSON array; for one delete, pass one item. The tool previews every target when confirm=false, rejects duplicate ids, and deletes sequentially when confirm=true. By default, confirm=true skips records that were already removed by cascade or a previous cleanup step.', {
     tableName: z.string().describe('Table name'),
     items: bulkObjectArrayParam(z, 'Delete items').describe('Native JSON array of delete items: [{ "id": "...", "queryParams": { ... }? }].'),
     maxItems: z.number().int().min(1).max(100).optional().default(100).describe('Safety cap for one MCP batch. Default/max is 100.'),
     confirm: z.boolean().optional().default(false).describe('Required true to apply destructive deletes. Omit/false returns previews only.'),
+    skipNotFound: z.boolean().optional().default(true).describe('When confirm=true, continue if a target is already gone, for example because a previous delete cascaded child records. Default true.'),
     globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when confirm=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
-}, async ({ tableName, items, maxItems, confirm, globalRulesAckKey }) => {
+}, async ({ tableName, items, maxItems, confirm, skipNotFound, globalRulesAckKey }) => {
     validateTableName(tableName);
     const parsedItems = parseBulkItemsArg('items', items);
     assertMaxBulkItems('delete_records', parsedItems, maxItems);
@@ -1718,24 +1731,42 @@ server.tool('delete_records', 'Delete one or more route-backed records in one MC
     }
     assertGlobalRulesAck(globalRulesAckKey);
     const deleted = [];
+    const skippedNotFound = [];
     for (const [index, item] of parsedItems.entries()) {
         const query = parseQueryParamsArg(JSON.stringify(item.queryParams || {}));
-        const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}/${encodeURIComponent(String(item.id))}`, query), { method: 'DELETE' });
-        deleted.push({
-            index,
-            id: item.id,
-            statusCode: result?.statusCode,
-            success: result?.success,
-        });
+        try {
+            const result = await fetchAPI(ENFYRA_API_URL, appendQuery(`/${tableName}/${encodeURIComponent(String(item.id))}`, query), { method: 'DELETE' });
+            deleted.push({
+                index,
+                id: item.id,
+                statusCode: result?.statusCode,
+                success: result?.success,
+            });
+        }
+        catch (error) {
+            if (skipNotFound && isNotFoundDeleteError(error)) {
+                skippedNotFound.push({
+                    index,
+                    id: item.id,
+                    skipped: true,
+                    reason: 'not_found',
+                });
+                continue;
+            }
+            throw error;
+        }
     }
     return { content: [{ type: 'text', text: JSON.stringify({
                     action: 'deleted_records',
                     tableName,
                     requested: parsedItems.length,
                     deletedCount: deleted.length,
+                    skippedNotFoundCount: skippedNotFound.length,
                     sequential: true,
                     duplicateIdsRejected: true,
+                    skipNotFound,
                     deleted,
+                    skippedNotFound,
                 }, null, 2) }] };
 });
 server.tool('list_methods', 'List enfyra_method records with their UI colors. Use this before creating route methods or method-colored UI.', {}, async () => {
@@ -2321,13 +2352,13 @@ server.tool('test_rest_endpoint', [
     };
     return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 });
-server.tool('get_all_routes', 'List route definitions with minimal fields. Every call must pass either limit or all=true. Call inspect_route for handlers/hooks/permissions detail.', {
+server.tool('get_all_routes', 'List route definitions with minimal fields. Complete route lists must pass either limit or all=true. If search is provided without limit, the tool returns a bounded lookup window of 10 matches. Call inspect_route for handlers/hooks/permissions detail.', {
     includeDisabled: z.boolean().optional().default(false).describe('Include disabled routes'),
     search: z.string().optional().describe('Optional path or table substring filter. Use this before creating a route to check duplicates.'),
-    limit: z.number().int().positive().optional().describe('Maximum routes returned after search. Required unless all=true. Do not invent arbitrary limits for "all"; use all=true instead.'),
+    limit: z.number().int().positive().optional().describe('Maximum routes returned after search. Required unless all=true or search is provided. Do not invent arbitrary limits for "all"; use all=true instead.'),
     all: z.boolean().optional().default(false).describe('Return all matched routes. Use this when the user asks for all routes or a complete route list.'),
 }, async ({ includeDisabled, search, limit, all }) => {
-    if (!all && limit === undefined) {
+    if (!all && limit === undefined && !search?.trim()) {
         throw new Error('get_all_routes requires either limit or all=true. Do not rely on implicit default page sizes.');
     }
     if (all && limit !== undefined) {
@@ -2348,7 +2379,7 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Every
             mainTable: route.mainTable,
         }).toLowerCase().includes(q))
         : allRoutes;
-    const routeLimit = all ? matchedRoutes.length : limit;
+    const routeLimit = all ? matchedRoutes.length : (limit ?? 10);
     const payload = {
         statusCode: result?.statusCode,
         success: result?.success,
@@ -2356,6 +2387,7 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Every
         matchedRouteCount: matchedRoutes.length,
         returnedRouteCount: Math.min(matchedRoutes.length, routeLimit),
         all: !!all,
+        implicitSearchLimit: Boolean(!all && limit === undefined && search?.trim()),
         complete: all || routeLimit >= matchedRoutes.length,
         hardCap: all ? null : routeLimit,
         search: search || null,
@@ -2481,9 +2513,10 @@ server.tool('create_handler', [
                 }, null, 2) }] };
 });
 server.tool('create_pre_hook', [
-    'Create a pre-hook that runs BEFORE the handler. Use to validate, transform, or inject data.',
+    'Create a pre-hook that runs BEFORE the handler. Use to validate, transform, inject data, or enforce owner/tenant row filters (RLS).',
     'Use `routeId` from `create_route` or `get_all_routes` — do not create a new table just to get a route id.',
     'Macros: @BODY, @QUERY, @PARAMS, @USER, @REPOS, @HELPERS, @THROW400..@THROW503.',
+    'For canonical table reads, merge security filters into @QUERY.filter and preserve @QUERY.fields/deep/sort/limit/page/meta/aggregate.',
     'If the hook returns a value, that value becomes the response (handler is skipped).',
 ].join(' '), {
     routeId: z.union([z.string(), z.number()]).describe('Route definition ID'),