@enfyra/mcp-server 0.1.62 → 0.1.64

package/dist/mcp-server-entry.js

@@ -64,19 +64,21 @@ import { getSupportedColumnTypesFromMetadata, registerTableTools } from './lib/t
 import { registerPlatformOperationTools, validateExtensionCode } from './lib/platform-operation-tools.js';
 import { registerRuntimeZoneTools } from './lib/runtime-zone-tools.js';
 import { registerDynamicRepositoryBuilder } from './lib/dynamic-repository-builder.js';
-import { parseRecordBatchData, parseRecordData, prepareRecordBatchMutation, prepareRecordMutation, validateScriptSourceIfPresent } from './lib/mutation-guards.js';
-import { assertDynamicCodeKnowledgeAck, assertDynamicCodeKnowledgeAckIf, assertExtensionKnowledgeAckIf, assertGlobalRulesAck, buildRequiredKnowledgePayload, dynamicCodeKnowledgeAckParam, extensionKnowledgeAckParam, globalRulesAckParam, } from './lib/required-knowledge.js';
+import { assertCreateHandlerRouteBoundary } from './lib/dynamic-endpoint-contract.js';
+import { assertGenericRecordMutationAllowed, parseRecordBatchData, parseRecordData, prepareRecordBatchMutation, prepareRecordMutation, validatePortableScriptSource, validateScriptSourceIfPresent } from './lib/mutation-guards.js';
+import { assertDynamicCodeKnowledgeAck, assertDynamicCodeKnowledgeAckIf, assertExtensionKnowledgeAckIf, assertGlobalRulesAck, acknowledgeRequiredKnowledge, buildRequiredKnowledgePayload, dynamicCodeKnowledgeAckParam, extensionKnowledgeAckParam, globalRulesAckParam, } from './lib/required-knowledge.js';
 import { validateMainTableRoutePath } from './lib/route-guards.js';
 import { installColumnarToolFormatter, jsonContent } from './lib/response-format.js';
 import { startMcpUsageTelemetry } from './lib/mcp-usage-telemetry.js';
 import { startRuntimeCacheSocket } from './lib/runtime-cache-socket.js';
 import { executeSequentialBatch } from './lib/sequential-batch.js';
 import { compactSourceFields, writeSourceArtifact } from './lib/source-artifacts.js';
-import { installToolsetFilter, normalizeMcpToolset, summarizeToolsetForInstructions } from './lib/toolset-filter.js';
+import { installToolsetFilter, normalizeMcpProfile, 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 MCP_PROFILE = normalizeMcpProfile(process.env.ENFYRA_MCP_PROFILE);
 const CAPABILITY_AREAS = [
     {
         area: 'Schema and metadata',
@@ -808,12 +810,12 @@ const server = new McpServer({
     version: '1.0.0',
 }, {
     instructions: buildMcpServerInstructions(ENFYRA_API_URL, {
-        toolsetSummary: summarizeToolsetForInstructions(MCP_TOOLSET),
+        toolsetSummary: summarizeToolsetForInstructions(MCP_TOOLSET, MCP_PROFILE),
     }),
 });
 installColumnarToolFormatter(server);
-installToolsetFilter(server, MCP_TOOLSET);
-startMcpUsageTelemetry(ENFYRA_API_URL, MCP_TOOLSET);
+installToolsetFilter(server, MCP_TOOLSET, MCP_PROFILE);
+startMcpUsageTelemetry(ENFYRA_API_URL, `${MCP_TOOLSET}:${MCP_PROFILE}`);
 // ============================================================================
 // METADATA TOOLS
 // ============================================================================
@@ -822,8 +824,12 @@ server.tool('get_enfyra_required_knowledge', [
     'Call this before creating or updating dynamic server code or Enfyra extension code. Read the returned contracts and pass the matching ack key into write tools.',
     'Pass scope to only load rules for the current task domain: "schema" (table/data/route/permission/guard work), "dynamic-code" (handler/hook/websocket/resolver scripts), "extension" (admin UI/menu/shell), or "flow". Omitting scope returns all rules.',
 ].join(' '), {
-    scope: z.enum(['schema', 'dynamic-code', 'extension', 'flow']).optional().describe('Limit knowledge to one domain. Omit to load all rules.'),
-}, async ({ scope }) => jsonContent(buildRequiredKnowledgePayload(scope)));
+    scope: z.enum(['full', 'schema', 'dynamic-code', 'extension', 'flow']).optional().describe('Limit knowledge to one domain. Use full or omit scope to load all rules.'),
+}, async ({ scope }) => {
+    const payload = buildRequiredKnowledgePayload(scope);
+    const sessionAcknowledgement = acknowledgeRequiredKnowledge(scope);
+    return jsonContent({ ...payload, sessionAcknowledgement });
+});
 server.tool('get_all_metadata', 'Get a lightweight table catalog. Use get_table_metadata or inspect_table to fetch one table schema.', {
     includeFull: z.boolean().optional().default(false).describe('Fetch per-table metadata for the selected catalog entries. Default false keeps discovery lightweight.'),
     search: z.string().optional().describe('Optional table-name/alias substring filter.'),
@@ -898,7 +904,7 @@ server.tool('discover_enfyra_workflows', [
     risk: z.string().optional().default('unknown').describe('Highest expected operation risk. Preferred values: read, write, destructive, debug, unknown. Natural terms such as low, medium, or high are accepted and normalized.'),
     detail: z.enum(['summary', 'plan', 'full']).optional().default('summary').describe('summary lists candidate workflows; plan adds tool sequence and avoidTools; full also includes matching keywords.'),
     limit: z.number().int().positive().max(10).optional().default(5).describe('Maximum workflows to return.'),
-}, async (input) => jsonContent(discoverWorkflowRoutes(input)));
+}, async (input) => jsonContent(discoverWorkflowRoutes(input, MCP_PROFILE)));
 server.tool('discover_enfyra_system', [
     'Call this first when you need to understand the live Enfyra instance.',
     'Returns a concise capability map from live metadata/routes/method rows, including schema management, REST route behavior, GraphQL enablement, and relation handling.',
@@ -971,7 +977,7 @@ server.tool('discover_enfyra_system', [
         adminTesting: {
             runAdminTest: 'run_admin_test wraps POST /admin/test/run for flow_step, websocket_event, and websocket_connection scripts.',
             testFlowStep: 'test_flow_step also wraps POST /admin/test/run with kind=flow_step.',
-            triggerFlow: 'trigger_flow wraps POST /admin/flow/trigger/:id and enqueues a flow execution.',
+            triggerFlow: 'trigger_flow resolves a saved enabled flow, then wraps POST /admin/flow/trigger/:id. Use test_flow_step for disabled flows.',
         },
         graphql: {
             endpoint: `${ENFYRA_API_URL.replace(/\/$/, '')}/graphql`,
@@ -1203,6 +1209,12 @@ server.tool('discover_script_contexts', [
                 '@STATUS': '$ctx.$statusCode',
                 '@ERROR': '$ctx.$error',
             },
+            logging: '@LOGS is a callable function. Use @LOGS(message, details?) such as @LOGS("Approval requested", { requestId }); do not use @LOGS.info, @LOGS.warn, @LOGS.error, or @LOGS.debug.',
+            socket: {
+                contract: '@SOCKET has no generic emit() method.',
+                boundWebsocketMethods: ['reply(event, data)', 'join(room)', 'leave(room)', 'emitToCurrentRoom(room, event, data)', 'broadcastToRoom(room, event, data)', 'disconnect()'],
+                globalMethods: ['emitToGateway(path, event, data)', 'emitToRoom(path, room, event, data)', 'emitToUser(userId, event, data)', 'broadcast(event, data)', 'roomSize(room)'],
+            },
             flowMacros: {
                 '@FLOW': '$ctx.$flow',
                 '@FLOW_PAYLOAD': '$ctx.$flow.$payload',
@@ -1217,9 +1229,9 @@ server.tool('discover_script_contexts', [
             },
             throws: '@THROW maps to $ctx.$throw. Numeric helpers are raw HTTP message helpers: @THROW400(message), @THROW404(message), @THROW409(message), @THROW422(message, detailsObject?), @THROW500(message). Numeric helper details must be an object/array, e.g. @THROW404("Project not found", { id }); do not use @THROW404("Project", id) as a semantic shortcut. Use @THROW.http(status, message, details?) for dynamic status codes. Use @THROW.notFound(resource, id?) and @THROW.duplicate(resource, field, value) only when you intentionally want Enfyra-formatted semantic messages.',
             helpers: {
-                core: '$ctx.$helpers includes $bcrypt.hash/compare, autoSlug(text), $fetch, $sleep(ms) capped by the runtime, and $crypto. HTTP and GraphQL contexts also expose $jwt through $ctx.$helpers.',
+                core: '$ctx.$helpers includes $bcrypt.hash/compare, autoSlug(text), $fetch, $sleep(ms) capped by the runtime, and $crypto. HTTP and GraphQL contexts also expose $jwt through $ctx.$helpers. Every helper method crosses the async executor bridge: await its result before property access, interpolation, concatenation, or persistence.',
                 fetch: '@FETCH maps to $ctx.$helpers.$fetch for outbound HTTP calls from server scripts. Keep secrets in encrypted fields instead of embedding them in sourceCode.',
-                crypto: '$ctx.$helpers.$crypto exposes bounded runtime crypto helpers: randomUUID(), randomBytes(size, encoding), sha256(value, encoding), hmacSha256(value, secret, encoding), and generateSshKeyPair(comment). Use generateSshKeyPair for SSH key material. Do not use legacy $ctx.$helpers.$ssh.',
+                crypto: '$ctx.$helpers.$crypto exposes bounded runtime crypto helpers: randomUUID(), randomBytes(size, encoding), sha256(value, encoding), hmacSha256(value, secret, encoding), and generateSshKeyPair(comment). Await every call, including helpers whose host implementation is synchronous, for example const id = await @HELPERS.$crypto.randomUUID(). Use generateSshKeyPair for SSH key material. Do not use legacy $ctx.$helpers.$ssh.',
                 files: '$ctx.$storage.$upload and $ctx.$storage.$update accept file: @UPLOADED_FILE for request uploads and stream from the server temp file path. $ctx.$storage.$registerFile creates a enfyra_file record for an object that already exists in storage without uploading bytes. Use buffer only for small generated/transformed files; do not use @UPLOADED_FILE.buffer.',
             },
             env: '$ctx.$env exposes a sanitized process env snapshot with exact sensitive keys removed: DB_URI, DB_REPLICA_URIS, REDIS_URI, SECRET_KEY, and ADMIN_PASSWORD. Store app secrets in unpublished isEncrypted fields instead of reading them from $env.',
@@ -1499,6 +1511,7 @@ server.tool('create_records', 'Create one or more route-backed records. Always p
 }, async ({ tableName, records, queryParams, maxRecords, globalRulesAckKey, knowledgeAckKey, extensionKnowledgeAckKey }) => {
     assertGlobalRulesAck(globalRulesAckKey);
     validateTableName(tableName);
+    assertGenericRecordMutationAllowed('create', tableName);
     const parsedRecords = parseRecordBatchData(records);
     if (parsedRecords.length > maxRecords) {
         throw new Error(`create_records received ${parsedRecords.length} records, above maxRecords=${maxRecords}. Split the batch deliberately.`);
@@ -1560,6 +1573,7 @@ server.tool('update_records', 'Update one or more records in one MCP call. Pass
 }, async ({ tableName, items, maxItems, globalRulesAckKey, knowledgeAckKey, extensionKnowledgeAckKey }) => {
     assertGlobalRulesAck(globalRulesAckKey);
     validateTableName(tableName);
+    assertGenericRecordMutationAllowed('update', tableName);
     const parsedItems = parseBulkItemsArg('items', items);
     assertMaxBulkItems('update_records', parsedItems, maxItems);
     assertNoDuplicateBulkIds('update_records', parsedItems);
@@ -1747,6 +1761,7 @@ server.tool('delete_records', 'Delete one or more route-backed records in one MC
     globalRulesAckKey: globalRulesAckParam(z).optional().describe('Required when confirm=true. Use globalRulesAckKey from get_enfyra_required_knowledge.'),
 }, async ({ tableName, items, maxItems, confirm, skipNotFound, globalRulesAckKey }) => {
     validateTableName(tableName);
+    assertGenericRecordMutationAllowed('delete', tableName);
     const parsedItems = parseBulkItemsArg('items', items);
     assertMaxBulkItems('delete_records', parsedItems, maxItems);
     assertNoDuplicateBulkIds('delete_records', parsedItems);
@@ -1957,29 +1972,45 @@ server.tool('delete_method', 'Preview or delete a enfyra_method record. Only del
 server.tool('run_admin_test', [
     'Run an Enfyra admin test without saving metadata. Wraps POST /admin/test/run.',
     'Kinds: script, flow_step, websocket_event, websocket_connection. Use this to validate dynamic script, flow, or websocket behavior before creating records.',
+    'kind=script captures logs but not socket emitted calls. Use kind=websocket_event or kind=websocket_connection when emitted capture is required; admin websocket tests still do not prove a real Socket.IO client transport/handshake.',
 ].join(' '), {
     kind: z.enum(['script', 'flow_step', 'websocket_event', 'websocket_connection']).describe('Admin test kind'),
-    body: z.string().describe('JSON body for the test. Include script and optional context for script; type/config for flow_step; or script/gatewayPath/eventName/payload for websocket tests. Do not include kind; the tool adds it.'),
+    body: z.string().describe('JSON body for the test. Include script and optional context for script; type/config plus payload for flow_step; or script/gatewayPath/eventName/payload for websocket tests. Do not include kind; the tool adds it.'),
 }, async ({ kind, body }) => {
     const parsed = body ? JSON.parse(body) : {};
+    const sourceCode = kind === 'flow_step'
+        ? parsed?.config?.sourceCode ?? parsed?.config?.code
+        : parsed?.script ?? parsed?.sourceCode;
+    if (typeof sourceCode === 'string')
+        validatePortableScriptSource(sourceCode);
     const result = await fetchAPI(ENFYRA_API_URL, '/admin/test/run', {
         method: 'POST',
         body: JSON.stringify({ ...parsed, kind }),
     });
     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
 });
-server.tool('test_flow_step', 'Test a single flow step without saving it. Wraps POST /admin/test/run with kind=flow_step.', {
+server.tool('test_flow_step', 'Test a single flow step without saving it. Wraps POST /admin/test/run with kind=flow_step. Pass runtime @FLOW_PAYLOAD data through payload; the tool forwards it using the ESV test-run contract.', {
     type: z.enum(['script', 'condition', 'query', 'create', 'update', 'delete', 'http', 'trigger_flow', 'sleep', 'log']).describe('Flow step type'),
     config: z.string().describe('Step config as JSON string'),
     timeout: z.number().optional().describe('Timeout in ms'),
     key: z.string().optional().describe('Optional step key for mock flow context'),
-    mockFlow: z.string().optional().describe('Optional mockFlow JSON object'),
-}, async ({ type, config, timeout, key, mockFlow }) => {
+    payload: z.union([z.record(z.any()), z.string()]).optional().describe('Runtime payload object exposed to the script as @FLOW_PAYLOAD. A JSON object string is accepted for compatibility.'),
+    mockFlow: z.string().optional().describe('Optional advanced mockFlow JSON object for $last/$meta or other flow context. Use payload for @FLOW_PAYLOAD.'),
+}, async ({ type, config, timeout, key, payload, mockFlow }) => {
+    const parsedConfig = JSON.parse(config);
+    const sourceCode = parsedConfig?.sourceCode ?? parsedConfig?.code;
+    if (typeof sourceCode === 'string')
+        validatePortableScriptSource(sourceCode);
+    const parsedPayload = typeof payload === 'string' ? JSON.parse(payload) : payload;
+    if (parsedPayload !== undefined && (!parsedPayload || typeof parsedPayload !== 'object' || Array.isArray(parsedPayload))) {
+        throw new Error('payload must be a JSON object.');
+    }
     const body = {
         type,
-        config: JSON.parse(config),
+        config: parsedConfig,
         ...(timeout ? { timeout } : {}),
         ...(key ? { key } : {}),
+        ...(parsedPayload !== undefined ? { payload: parsedPayload } : {}),
         ...(mockFlow ? { mockFlow: JSON.parse(mockFlow) } : {}),
     };
     const result = await fetchAPI(ENFYRA_API_URL, '/admin/test/run', {
@@ -1988,11 +2019,23 @@ server.tool('test_flow_step', 'Test a single flow step without saving it. Wraps
     });
     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
 });
-server.tool('trigger_flow', 'Trigger a saved flow by id or name. Wraps POST /admin/flow/trigger/:id.', {
+server.tool('trigger_flow', 'Trigger an enabled saved flow by id or name. Disabled flows are not registered for execution; use test_flow_step to verify their step contract without enabling them.', {
     flowIdOrName: z.union([z.string(), z.number()]).describe('Flow id or name accepted by FlowService.trigger'),
     payload: z.string().optional().describe('Payload JSON object. Default {}.'),
 }, async ({ flowIdOrName, payload }) => {
-    const result = await fetchAPI(ENFYRA_API_URL, `/admin/flow/trigger/${encodeURIComponent(String(flowIdOrName))}`, {
+    const rawIdentifier = String(flowIdOrName);
+    const filter = typeof flowIdOrName === 'number' || /^\d+$/.test(rawIdentifier)
+        ? { id: { _eq: flowIdOrName } }
+        : { name: { _eq: rawIdentifier } };
+    const lookup = await fetchAPI(ENFYRA_API_URL, `/enfyra_flow?filter=${encodeURIComponent(JSON.stringify(filter))}&limit=1&fields=id,_id,name,isEnabled`);
+    const flow = unwrapData(lookup)[0];
+    if (!flow)
+        throw new Error(`Flow not found: ${rawIdentifier}`);
+    if (flow.isEnabled === false) {
+        throw new Error(`Flow "${flow.name || rawIdentifier}" is disabled and is not registered for execution. Use test_flow_step to verify its saved step contract, or explicitly enable the flow before trigger_flow.`);
+    }
+    const flowId = flow.id ?? flow._id;
+    const result = await fetchAPI(ENFYRA_API_URL, `/admin/flow/trigger/${encodeURIComponent(String(flowId))}`, {
         method: 'POST',
         body: JSON.stringify({ payload: payload ? JSON.parse(payload) : {} }),
     });
@@ -2508,7 +2551,7 @@ server.tool('get_all_routes', 'List route definitions with minimal fields. Compl
 server.tool('create_route', [
     '**Use this when the user wants a new REST API route or path** — not `create_tables`. Custom routes must omit `mainTableId`.',
     '`mainTableId` is only a marker for canonical table routes such as `/orders`; do not set it for `/orders/stats`, `/reports/summary`, `/auth/login`, or any custom path.',
-    'Do NOT create a new enfyra_table only to expose an endpoint; create a route without `mainTableId`, then have the handler/hook query explicit repos such as `$ctx.$repos.orders`.',
+    'Do NOT create a new enfyra_table only to expose an endpoint; create a route without `mainTableId`, then have the handler/hook query user-facing tables through secure explicit repos such as `#secure.orders` or `$ctx.$repos.secure.orders`.',
     'availableMethods = which REST verbs the route responds to. publicMethods = which REST verbs are public (no auth). GraphQL is enabled separately through enfyra_graphql/update_tables graphqlEnabled.',
     'After creation the tool auto-reloads routes. Then create handlers for specific methods via create_handler on this route id.',
     'Flow: create_route → create_handler (per method) → optionally create_pre_hook / create_post_hook → test via HTTP or admin test APIs (see server instructions).',
@@ -2561,7 +2604,8 @@ server.tool('create_route', [
 });
 server.tool('create_handler', [
     'Create a handler for a route+method. One handler per (route, method) pair.',
-    'Attach to the route the user cares about (`get_all_routes`): typically a path from `create_route`, not a spurious table created only for handlers.',
+    'Attach to a custom route from `create_route` for endpoint-specific or third-party behavior. Do not use this low-level tool to bypass api_endpoint_workflow canonical-collision checks.',
+    'Canonical table routes are shared with eApp/admin CRUD. Adding a new canonical handler requires allowCanonicalRoute=true and main-table repository access; otherwise create a separate custom path.',
     'Use sourceCode, not logic/name. Enfyra compiles sourceCode into compiledCode; do not send compiledCode.',
     'Handler code runs inside a sandbox with $ctx. Use macros: @BODY, @QUERY, @PARAMS, @USER, @REPOS, @HELPERS, @THROW400..@THROW503, @SOCKET, @PKGS, @LOGS, @SHARE.',
     'Call discover_script_contexts first. For explicit user-facing table repos use #secure.table_name or @REPOS.secure.table_name; use #table_name/@REPOS.table_name only for intentional trusted internal access.',
@@ -2578,9 +2622,20 @@ server.tool('create_handler', [
     timeout: z.number().optional().describe('Timeout in ms (default: system DEFAULT_HANDLER_TIMEOUT, usually 30000)'),
     globalRulesAckKey: globalRulesAckParam(z),
     knowledgeAckKey: dynamicCodeKnowledgeAckParam(z),
-}, async ({ routeId, method, methods, sourceCode, scriptLanguage, timeout, globalRulesAckKey, knowledgeAckKey }) => {
+    allowCanonicalRoute: z.boolean().optional().default(false).describe('Explicit acknowledgement for adding a new handler to a canonical main-table route. Use only when the new method intentionally belongs to the shared eApp/admin CRUD surface; third-party endpoint-specific behavior must use a separate custom route.'),
+}, async ({ routeId, method, methods, sourceCode, scriptLanguage, timeout, globalRulesAckKey, knowledgeAckKey, allowCanonicalRoute }) => {
     assertGlobalRulesAck(globalRulesAckKey);
     assertDynamicCodeKnowledgeAck(knowledgeAckKey);
+    const routeQuery = new URLSearchParams({
+        filter: JSON.stringify({ id: { _eq: routeId } }),
+        fields: 'id,path,mainTable.id,mainTable.name',
+        limit: '1',
+    });
+    const routeResult = await fetchAPI(ENFYRA_API_URL, `/enfyra_route?${routeQuery.toString()}`);
+    const targetRoute = unwrapData(routeResult)[0];
+    if (!targetRoute)
+        throw new Error(`Route not found: ${String(routeId)}`);
+    assertCreateHandlerRouteBoundary(targetRoute, sourceCode, allowCanonicalRoute);
     const methodNames = methods && methods.length > 0 ? methods : method ? [method] : [];
     if (methodNames.length === 0)
         throw new Error('Provide method or methods');
@@ -2614,6 +2669,7 @@ server.tool('create_handler', [
     return { content: [{ type: 'text', text: JSON.stringify({
                     action: 'created',
                     handlers: results,
+                    canonicalRouteAcknowledged: Boolean(targetRoute?.mainTable && allowCanonicalRoute),
                     scriptValidation,
                     routeReload,
                     detailHint: 'Use inspect_route with the same routeId/path to inspect saved handlers.',
@@ -2880,7 +2936,7 @@ server.tool('ensure_route_access', [
     return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 });
 // Register table tools
-registerTableTools(server, ENFYRA_API_URL);
+registerTableTools(server, ENFYRA_API_URL, { toolset: MCP_TOOLSET });
 registerPlatformOperationTools(server, ENFYRA_API_URL);
 registerRuntimeZoneTools(server, ENFYRA_API_URL);
 registerDynamicRepositoryBuilder(server);