@enfyra/mcp-server 0.1.64 → 0.1.66

package/dist/lib/types.d.ts

@@ -15,6 +15,81 @@ export interface ToolResult {
     _meta?: Record<string, unknown>;
 }
 export type UnknownRecord = Record<string, unknown>;
+export interface McpToolAnnotations {
+    title: string;
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+export interface McpToolContract {
+    name: string;
+    annotations: McpToolAnnotations;
+    catalogExecutable: boolean;
+}
+export interface RegisteredToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations?: McpToolAnnotations;
+    handler: (...args: any[]) => any;
+    visible: boolean;
+    registration?: {
+        enabled: boolean;
+    };
+}
+export interface ToolsetRegistrationState {
+    toolset: string;
+    profile: string;
+    dynamic: boolean;
+    hiddenTools: string[];
+    getTool(name: string): RegisteredToolDefinition | undefined;
+    listTools(): RegisteredToolDefinition[];
+    listVisibleToolNames(): string[];
+    setActiveTools(toolNames: Iterable<string>): {
+        changed: boolean;
+        visibleToolNames: string[];
+        hiddenToolCount: number;
+    };
+}
+export type ToolAvailabilityStatus = 'allowed' | 'denied' | 'unknown';
+export interface ToolAvailability {
+    status: ToolAvailabilityStatus;
+    reason: string;
+}
+export interface ModelEvalTraceEvent {
+    tool: string;
+    arguments?: Record<string, unknown>;
+    result?: unknown;
+    isError?: boolean;
+}
+export interface ModelEvalRun {
+    scenarioId: string;
+    model: string;
+    events: ModelEvalTraceEvent[];
+}
+export interface ModelEvalScenario {
+    id: string;
+    prompt: string;
+    surface: string;
+    requiredToolGroups: string[][];
+    verificationTools: string[];
+    maxToolCalls: number;
+    mutationExpected: boolean;
+    destructiveExpected?: boolean;
+}
+export interface ModelEvalCheck {
+    key: string;
+    passed: boolean;
+    detail: string;
+}
+export interface ModelEvalScore {
+    scenarioId: string;
+    model: string;
+    score: number;
+    recommended: boolean;
+    checks: ModelEvalCheck[];
+}
 export interface MetadataContext {
     dbType: "postgres" | "mysql" | "mongodb" | "mariadb" | "sqlite" | null;
     enfyraVersion: string | null;

package/dist/lib/workflow-tool-packs.d.ts

@@ -0,0 +1,2 @@
+import type { ToolsetRegistrationState } from './types.js';
+export declare function registerWorkflowToolPack(server: any, state: ToolsetRegistrationState): any;

package/dist/lib/workflow-tool-packs.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { jsonContent } from './response-format.js';
+import { WORKFLOW_SURFACES, workflowToolNames } from './tool-routing.js';
+const MAX_ACTIVE_WORKFLOWS = 2;
+export function registerWorkflowToolPack(server, state) {
+    const activeSurfaces = new Set();
+    return server.tool('select_enfyra_workflow', [
+        'Select a workflow surface and expose its exact direct MCP tools for this stdio session.',
+        'Use replace for normal tasks, add only when one task genuinely spans two surfaces, and reset to return to the compact routing surface.',
+        'This changes tool visibility only; it does not grant permissions or bypass Enfyra PAT/RBAC.',
+    ].join(' '), {
+        surface: z.enum(WORKFLOW_SURFACES).optional().describe('Required for replace/add. Omit only with mode=reset.'),
+        mode: z.enum(['replace', 'add', 'reset']).optional().default('replace'),
+    }, async ({ surface, mode }) => {
+        if (mode !== 'reset' && !surface)
+            throw new Error('surface is required when mode is replace or add.');
+        if (mode === 'reset') {
+            activeSurfaces.clear();
+        }
+        else if (mode === 'replace') {
+            activeSurfaces.clear();
+            activeSurfaces.add(surface);
+        }
+        else {
+            activeSurfaces.add(surface);
+            if (activeSurfaces.size > MAX_ACTIVE_WORKFLOWS) {
+                activeSurfaces.delete(surface);
+                throw new Error(`At most ${MAX_ACTIVE_WORKFLOWS} workflow surfaces may be active. Use mode=replace or reset first.`);
+            }
+        }
+        const packTools = [...activeSurfaces].flatMap(workflowToolNames);
+        const result = state.setActiveTools(packTools);
+        return jsonContent({
+            action: 'enfyra_workflow_selected',
+            mode,
+            dynamic: state.dynamic,
+            activeSurfaces: [...activeSurfaces],
+            visibleToolCount: result.visibleToolNames.length,
+            visibleTools: result.visibleToolNames,
+            hiddenToolCount: result.hiddenToolCount,
+            changed: result.changed,
+            guidance: state.dynamic
+                ? [
+                    'Refresh tools/list after this response if the host has not already processed notifications/tools/list_changed.',
+                    'Call the newly visible workflow tools directly so their exact schemas, annotations, and safety gates remain active.',
+                    'Use search_enfyra_tools only for hidden read-only long-tail helpers.',
+                ]
+                : [
+                    'Dynamic packs are disabled for this static profile/toolset; the configured profile remains visible.',
+                    'Use ENFYRA_MCP_DYNAMIC_TOOLS=on with guided/all on hosts that support tools/list_changed.',
+                ],
+        });
+    });
+}
+//# sourceMappingURL=workflow-tool-packs.js.map

package/dist/lib/workflow-tool-packs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-tool-packs.js","sourceRoot":"","sources":["../../src/lib/workflow-tool-packs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAwB,MAAM,mBAAmB,CAAC;AAG/F,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAE/B,MAAM,UAAU,wBAAwB,CAAC,MAAW,EAAE,KAA+B;IACnF,MAAM,cAAc,GAAG,IAAI,GAAG,EAAmB,CAAC;IAElD,OAAO,MAAM,CAAC,IAAI,CAChB,wBAAwB,EACxB;QACE,yFAAyF;QACzF,wIAAwI;QACxI,6FAA6F;KAC9F,CAAC,IAAI,CAAC,GAAG,CAAC,EACX;QACE,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;QAC9G,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC;KACxE,EACD,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAoE,EAAE,EAAE;QAC5F,IAAI,IAAI,KAAK,OAAO,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;QACtG,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACrB,cAAc,CAAC,KAAK,EAAE,CAAC;QACzB,CAAC;aAAM,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YAC9B,cAAc,CAAC,KAAK,EAAE,CAAC;YACvB,cAAc,CAAC,GAAG,CAAC,OAAQ,CAAC,CAAC;QAC/B,CAAC;aAAM,CAAC;YACN,cAAc,CAAC,GAAG,CAAC,OAAQ,CAAC,CAAC;YAC7B,IAAI,cAAc,CAAC,IAAI,GAAG,oBAAoB,EAAE,CAAC;gBAC/C,cAAc,CAAC,MAAM,CAAC,OAAQ,CAAC,CAAC;gBAChC,MAAM,IAAI,KAAK,CAAC,WAAW,oBAAoB,oEAAoE,CAAC,CAAC;YACvH,CAAC;QACH,CAAC;QAED,MAAM,SAAS,GAAG,CAAC,GAAG,cAAc,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAC/C,OAAO,WAAW,CAAC;YACjB,MAAM,EAAE,0BAA0B;YAClC,IAAI;YACJ,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,cAAc,EAAE,CAAC,GAAG,cAAc,CAAC;YACnC,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,CAAC,MAAM;YAChD,YAAY,EAAE,MAAM,CAAC,gBAAgB;YACrC,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,QAAQ,EAAE,KAAK,CAAC,OAAO;gBACrB,CAAC,CAAC;oBACE,gHAAgH;oBAChH,qHAAqH;oBACrH,sEAAsE;iBACvE;gBACH,CAAC,CAAC;oBACE,qGAAqG;oBACrG,2FAA2F;iBAC5F;SACN,CAAC,CAAC;IACL,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/mcp-server-entry.js

@@ -3,7 +3,7 @@
  */
 import { config } from 'dotenv';
 config();
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { createHash } from 'node:crypto';
@@ -72,13 +72,18 @@ import { installColumnarToolFormatter, jsonContent } from './lib/response-format
 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, normalizeMcpProfile, normalizeMcpToolset, summarizeToolsetForInstructions } from './lib/toolset-filter.js';
+import { compactSourceFields, readSourceArtifactResource, writeSourceArtifact } from './lib/source-artifacts.js';
+import { installToolsetFilter, normalizeDynamicToolPacks, normalizeMcpProfile, normalizeMcpToolset, summarizeToolsetForInstructions } from './lib/toolset-filter.js';
+import { installToolAnnotations } from './lib/tool-contracts.js';
+import { installToolOutputContracts } from './lib/tool-output-contracts.js';
+import { registerToolCatalogTools } from './lib/tool-catalog.js';
+import { registerWorkflowToolPack } from './lib/workflow-tool-packs.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 MCP_DYNAMIC_TOOLS = normalizeDynamicToolPacks(process.env.ENFYRA_MCP_DYNAMIC_TOOLS, MCP_TOOLSET, MCP_PROFILE);
 const CAPABILITY_AREAS = [
     {
         area: 'Schema and metadata',
@@ -418,6 +423,30 @@ function summarizePermissionProfile(user) {
         })),
     };
 }
+async function resolveCatalogToolAvailability(toolNames) {
+    const fields = DEFAULT_ME_PERMISSION_FIELDS.join(',');
+    const result = await fetchAPI(ENFYRA_API_URL, `/me?fields=${encodeURIComponent(fields)}`);
+    const user = firstDataRecord(result);
+    if (user?.isRootAdmin) {
+        return Object.fromEntries(toolNames.map((name) => [name, {
+                status: 'allowed',
+                reason: 'The configured PAT belongs to a root administrator.',
+            }]));
+    }
+    const requirements = summarizePermissionProfile(user).mcpRequirements;
+    return Object.fromEntries(toolNames.map((name) => {
+        const requirement = requirements.find((item) => item.tools.includes(name));
+        if (!requirement) {
+            return [name, {
+                    status: 'unknown',
+                    reason: 'No static admin-route capability mapping exists for this tool; Enfyra PAT/RBAC remains authoritative at execution time.',
+                }];
+        }
+        return [name, requirement.allowed
+                ? { status: 'allowed', reason: `Current PAT grants ${requirement.methods.map((item) => item.method).join(', ')} ${requirement.route}.` }
+                : { status: 'denied', reason: `Current PAT lacks one or more required methods on ${requirement.route}.` }];
+    }));
+}
 function parseJsonArg(value, fallback = undefined) {
     if (value === undefined || value === null || value === '')
         return fallback;
@@ -810,12 +839,19 @@ const server = new McpServer({
     version: '1.0.0',
 }, {
     instructions: buildMcpServerInstructions(ENFYRA_API_URL, {
-        toolsetSummary: summarizeToolsetForInstructions(MCP_TOOLSET, MCP_PROFILE),
+        toolsetSummary: summarizeToolsetForInstructions(MCP_TOOLSET, MCP_PROFILE, MCP_DYNAMIC_TOOLS),
     }),
 });
+installToolOutputContracts(server);
 installColumnarToolFormatter(server);
-installToolsetFilter(server, MCP_TOOLSET, MCP_PROFILE);
+const toolsetState = installToolsetFilter(server, MCP_TOOLSET, MCP_PROFILE, { dynamic: MCP_DYNAMIC_TOOLS });
+installToolAnnotations(server);
 startMcpUsageTelemetry(ENFYRA_API_URL, `${MCP_TOOLSET}:${MCP_PROFILE}`);
+server.registerResource('enfyra-source-artifact', new ResourceTemplate('enfyra-source://artifact/{artifactId}', { list: undefined }), {
+    title: 'Enfyra source artifact',
+    description: 'Process-scoped source or diff artifact created by an Enfyra MCP inspect or preview tool.',
+    mimeType: 'text/plain',
+}, async (uri) => ({ contents: [readSourceArtifactResource(uri.href)] }));
 // ============================================================================
 // METADATA TOOLS
 // ============================================================================
@@ -1632,10 +1668,11 @@ server.tool('update_records', 'Update one or more records in one MCP call. Pass
 });
 server.tool('get_script_source', [
     'Fetch the full editable source for one script-backed metadata record without preview truncation.',
-    'Use this before reviewing or patching long handlers, hooks, flow steps, websocket scripts, OAuth provisioning scripts, or bootstrap scripts.',
+    'Use search_runtime_zone first and pass the returned nextInspect.input to inspect the concrete record. The inspection already returns exact source artifacts.',
+    'Call get_script_source only when a fresh artifact is needed for that located record. Never guess or probe record ids.',
 ].join(' '), {
     tableName: z.enum(SCRIPT_BACKED_TABLES).describe('Script-backed table to read'),
-    id: z.string().describe('Record ID to read'),
+    id: z.string().describe('Concrete record id returned by search_runtime_zone, inspect output, or a successful create/update operation. Never guess an id.'),
 }, async ({ tableName, id }) => {
     const { primaryKey, record, sourceField, sourceCode } = await fetchScriptRecord(tableName, id);
     const sourceArtifact = writeSourceArtifact({ tableName, id, fieldName: sourceField, source: sourceCode });
@@ -3149,6 +3186,10 @@ server.tool('install_package', [
         result,
     });
 });
+registerToolCatalogTools(server, toolsetState, {
+    resolveAvailability: resolveCatalogToolAvailability,
+});
+registerWorkflowToolPack(server, toolsetState);
 // ============================================================================
 // MAIN
 // ============================================================================