@ema.co/mcp-toolkit 0.2.3 → 1.4.0

package/dist/mcp/handlers-consolidated.js

@@ -4,6 +4,8 @@
  * Each handler dispatches based on mode/flags following Unix CLI patterns.
  */
 import { fingerprintPersona } from "../sync.js";
+import { createVersionStorage } from "../sdk/version-storage.js";
+import { createVersionPolicyEngine } from "../sdk/version-policy.js";
 import { AGENT_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, VOICE_PERSONA_TEMPLATE, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, detectWorkflowIssues, validateWorkflowConnections, suggestWorkflowFixes, } from "../sdk/knowledge.js";
 import { compileWorkflow } from "../sdk/workflow-generator.js";
 import { parseInput, intentToSpec } from "../sdk/workflow-intent.js";
@@ -23,7 +25,7 @@ export async function handleEnv(_args, getEnvironments) {
 // ═══════════════════════════════════════════════════════════════════════════
 // PERSONA Handler
 // ═══════════════════════════════════════════════════════════════════════════
-export async function handlePersona(args, client, getTemplateId, createClientForEnv) {
+export async function handlePersona(args, client, getTemplateId, createClientForEnv, versionContext) {
     const id = args.id;
     const identifier = args.identifier; // deprecated alias
     const idOrName = id ?? identifier;
@@ -171,6 +173,251 @@ export async function handlePersona(args, client, getTemplateId, createClientFor
                 count: templates.size,
             };
         }
+        // ─────────────── Version Management Modes ───────────────
+        case "version_create": {
+            if (!idOrName) {
+                return { error: "id required for version_create mode" };
+            }
+            if (!versionContext) {
+                return { error: "Version tracking not configured. Provide workspaceRoot in context." };
+            }
+            const persona = await resolvePersona(client, idOrName);
+            if (!persona) {
+                return { error: `Persona not found: ${idOrName}` };
+            }
+            // Fetch full persona with workflow
+            const fullPersona = await client.getPersonaById(persona.id);
+            if (!fullPersona) {
+                return { error: `Could not fetch full persona: ${persona.id}` };
+            }
+            const storage = createVersionStorage(versionContext.workspaceRoot);
+            const engine = createVersionPolicyEngine(storage);
+            const result = engine.forceCreateVersion(fullPersona, {
+                environment: versionContext.environment,
+                tenant_id: versionContext.tenant_id,
+                message: args.message,
+                created_by: "mcp-toolkit",
+            });
+            if (!result.created || !result.version) {
+                return { error: result.reason };
+            }
+            return {
+                success: true,
+                version: {
+                    id: result.version.id,
+                    version_number: result.version.version_number,
+                    version_name: result.version.version_name,
+                    content_hash: result.version.content_hash,
+                    created_at: result.version.created_at,
+                    message: result.version.message,
+                },
+                changes_from_parent: result.changes_from_parent,
+                versions_pruned: result.versions_pruned,
+            };
+        }
+        case "version_list": {
+            if (!idOrName) {
+                return { error: "id required for version_list mode" };
+            }
+            if (!versionContext) {
+                return { error: "Version tracking not configured. Provide workspaceRoot in context." };
+            }
+            const persona = await resolvePersona(client, idOrName);
+            if (!persona) {
+                return { error: `Persona not found: ${idOrName}` };
+            }
+            const storage = createVersionStorage(versionContext.workspaceRoot);
+            const engine = createVersionPolicyEngine(storage);
+            const versions = engine.listVersions(persona.id, {
+                limit: args.limit,
+            });
+            return {
+                persona_id: persona.id,
+                persona_name: persona.name,
+                versions,
+                count: versions.length,
+            };
+        }
+        case "version_get": {
+            if (!idOrName) {
+                return { error: "id required for version_get mode" };
+            }
+            if (!versionContext) {
+                return { error: "Version tracking not configured. Provide workspaceRoot in context." };
+            }
+            const persona = await resolvePersona(client, idOrName);
+            if (!persona) {
+                return { error: `Persona not found: ${idOrName}` };
+            }
+            const versionId = args.version ?? "latest";
+            const storage = createVersionStorage(versionContext.workspaceRoot);
+            const engine = createVersionPolicyEngine(storage);
+            const version = engine.getVersion(persona.id, versionId);
+            if (!version) {
+                return { error: `Version not found: ${versionId}` };
+            }
+            return {
+                persona_id: persona.id,
+                persona_name: persona.name,
+                version: {
+                    id: version.id,
+                    version_number: version.version_number,
+                    version_name: version.version_name,
+                    content_hash: version.content_hash,
+                    created_at: version.created_at,
+                    created_by: version.created_by,
+                    trigger: version.trigger,
+                    message: version.message,
+                    changes_summary: version.changes_summary,
+                },
+                snapshot: {
+                    display_name: version.snapshot.display_name,
+                    description: version.snapshot.description,
+                    workflow_id: version.snapshot.workflow_id,
+                    trigger_type: version.snapshot.trigger_type,
+                    embedding_enabled: version.snapshot.embedding_enabled,
+                    has_workflow: !!version.snapshot.workflow_definition,
+                    has_proto_config: !!version.snapshot.proto_config,
+                },
+            };
+        }
+        case "version_compare": {
+            if (!idOrName) {
+                return { error: "id required for version_compare mode" };
+            }
+            if (!versionContext) {
+                return { error: "Version tracking not configured. Provide workspaceRoot in context." };
+            }
+            const v1 = args.v1;
+            const v2 = args.v2;
+            if (!v1 || !v2) {
+                return { error: "v1 and v2 required for version_compare mode" };
+            }
+            const persona = await resolvePersona(client, idOrName);
+            if (!persona) {
+                return { error: `Persona not found: ${idOrName}` };
+            }
+            const storage = createVersionStorage(versionContext.workspaceRoot);
+            const engine = createVersionPolicyEngine(storage);
+            const result = engine.compareVersions(persona.id, v1, v2);
+            if (!result.success) {
+                return { error: result.error };
+            }
+            return {
+                persona_id: persona.id,
+                persona_name: persona.name,
+                comparison: {
+                    v1: result.diff?.v1,
+                    v2: result.diff?.v2,
+                    identical: result.diff?.identical,
+                    changed_fields: result.diff?.changed_fields,
+                    workflow_diff: result.diff?.workflow_diff,
+                },
+                summary: result.summary,
+            };
+        }
+        case "version_restore": {
+            if (!idOrName) {
+                return { error: "id required for version_restore mode" };
+            }
+            if (!versionContext) {
+                return { error: "Version tracking not configured. Provide workspaceRoot in context." };
+            }
+            const versionId = args.version;
+            if (!versionId) {
+                return { error: "version required for version_restore mode" };
+            }
+            const persona = await resolvePersona(client, idOrName);
+            if (!persona) {
+                return { error: `Persona not found: ${idOrName}` };
+            }
+            const storage = createVersionStorage(versionContext.workspaceRoot);
+            const engine = createVersionPolicyEngine(storage);
+            const restoreData = engine.getRestoreData(persona.id, versionId);
+            if (!restoreData.success || !restoreData.restore_payload) {
+                return { error: restoreData.error ?? "Failed to get restore data" };
+            }
+            // Create a version snapshot before restoring (audit trail)
+            const fullPersona = await client.getPersonaById(persona.id);
+            if (fullPersona) {
+                engine.forceCreateVersion(fullPersona, {
+                    environment: versionContext.environment,
+                    tenant_id: versionContext.tenant_id,
+                    message: `Before restore to ${restoreData.version?.version_name}`,
+                    created_by: "mcp-toolkit",
+                });
+            }
+            // Apply the restore
+            const payload = restoreData.restore_payload;
+            await client.updateAiEmployee({
+                persona_id: payload.persona_id,
+                name: payload.name,
+                description: payload.description,
+                proto_config: payload.proto_config,
+                workflow: payload.workflow ?? undefined,
+                welcome_messages: payload.welcome_messages ?? undefined,
+                embedding_enabled: payload.embedding_enabled ?? undefined,
+            });
+            // Create post-restore version
+            const restoredPersona = await client.getPersonaById(persona.id);
+            if (restoredPersona) {
+                engine.forceCreateVersion(restoredPersona, {
+                    environment: versionContext.environment,
+                    tenant_id: versionContext.tenant_id,
+                    message: `Restored to ${restoreData.version?.version_name}`,
+                    created_by: "mcp-toolkit",
+                });
+            }
+            return {
+                success: true,
+                persona_id: persona.id,
+                restored_to: {
+                    version_id: restoreData.version?.id,
+                    version_name: restoreData.version?.version_name,
+                    version_number: restoreData.version?.version_number,
+                },
+                message: `Persona restored to ${restoreData.version?.version_name}`,
+            };
+        }
+        case "version_policy": {
+            if (!idOrName) {
+                return { error: "id required for version_policy mode" };
+            }
+            if (!versionContext) {
+                return { error: "Version tracking not configured. Provide workspaceRoot in context." };
+            }
+            const persona = await resolvePersona(client, idOrName);
+            if (!persona) {
+                return { error: `Persona not found: ${idOrName}` };
+            }
+            const storage = createVersionStorage(versionContext.workspaceRoot);
+            const engine = createVersionPolicyEngine(storage);
+            // Check if we're updating or just getting
+            const hasUpdates = args.auto_on_deploy !== undefined ||
+                args.auto_on_sync !== undefined ||
+                args.max_versions !== undefined;
+            if (hasUpdates) {
+                const updated = engine.updatePolicy(persona.id, {
+                    auto_version_on_deploy: args.auto_on_deploy,
+                    auto_version_on_sync: args.auto_on_sync,
+                    max_versions: args.max_versions,
+                });
+                return {
+                    success: true,
+                    persona_id: persona.id,
+                    persona_name: persona.name,
+                    policy: updated,
+                    message: "Policy updated",
+                };
+            }
+            // Just get current policy
+            const policy = engine.getPolicy(persona.id);
+            return {
+                persona_id: persona.id,
+                persona_name: persona.name,
+                policy,
+            };
+        }
         default:
             return { error: `Unknown mode: ${effectiveMode}` };
     }
@@ -315,6 +562,15 @@ export async function handleWorkflow(args, client) {
             if (!persona) {
                 return { error: `Persona not found: ${personaId}` };
             }
+            // Check persona status - deployment works on disabled personas but we should inform user
+            const personaStatus = persona.status?.toLowerCase();
+            const isDisabled = personaStatus === "inactive" || personaStatus === "disabled";
+            const statusWarnings = [];
+            if (isDisabled) {
+                statusWarnings.push(`⚠️ Persona "${persona.name}" is currently DISABLED (status: ${persona.status}). ` +
+                    `Workflow will be deployed but won't be active until enabled. ` +
+                    `Use persona(mode="update", id="${personaId}", enabled=true) to enable.`);
+            }
             let deployWorkflow = workflowDef || persona.workflow_def;
             // Validate if requested (default: true)
             if (args.validate !== false) {
@@ -325,6 +581,7 @@ export async function handleWorkflow(args, client) {
                         error: "Workflow has errors",
                         issues: errors,
                         hint: "Set auto_fix=true to attempt automatic fixes",
+                        ...(statusWarnings.length > 0 && { status_warnings: statusWarnings }),
                     };
                 }
                 // Auto-fix if enabled
@@ -341,7 +598,13 @@ export async function handleWorkflow(args, client) {
             return {
                 success: true,
                 persona_id: personaId,
+                persona_name: persona.name,
+                persona_status: persona.status,
                 deployed: true,
+                ...(isDisabled && {
+                    warning: `Persona is DISABLED - workflow deployed but inactive. Enable with: persona(mode="update", id="${personaId}", enabled=true)`,
+                }),
+                ...(statusWarnings.length > 0 && { status_warnings: statusWarnings }),
             };
         }
         case "compare": {

package/dist/mcp/prompts.js

@@ -74,9 +74,16 @@ Identify what the user is asking for:
 | **Data Sources** | ✓/✗ | Knowledge base, web search, APIs? |
 | **External Tools** | ✓/✗ | ServiceNow, Salesforce, email? |
 | **Routing Logic** | ✓/✗ | How to handle different intents? |
-| **HITL Requirements** | ✓/✗ | When is human approval needed? |
+| **HITL Requirements** | ✓/✗ | DEFAULT: No approval (auto-proceed). Only add if explicitly requested. |
 | **Fallback Handling** | ✓/✗ | What if no match? |
 
+#### HITL Policy (Default: Auto-Proceed)
+For external side-effect actions (send_email, create_ticket, update_record):
+- **Default**: Proceed WITHOUT approval gate unless explicitly requested
+- **Add HITL only when**: User says "confirm before", "approval required", "human review"
+- **Skip HITL when**: User says "auto", "directly", "no approval", or specifies direct flow
+- **If ambiguous**: ASK "Should [action] require approval, or auto-proceed?"
+
 #### For BROWNFIELD (extend existing):
 | Dimension | Status | Missing Info |
 |-----------|--------|--------------|
@@ -251,7 +258,7 @@ Verify you have answers for:
 - Intents: ${args.intents || "(to be determined)"}
 - Data Sources: (ask if not clear from use case)
 - Actions: (ask if not clear from use case)
-- Approvals/HITL: (ask if external actions involved)
+- Approvals/HITL: DEFAULT is no approval (auto-proceed). Only ask if user seems to want approval gates.
 
 ### Step 2: Select Pattern + Agents
 Call \`action(suggest="${args.use_case}")\` to get recommended agents and a suggested workflow pattern.
@@ -1073,6 +1080,8 @@ Where \`<requirements>\` includes:
 ${args.intents ? `- Intents: ${args.intents}` : ""}
 ${args.tools ? `- Tools: ${args.tools}` : ""}
 
+**HITL Policy**: DEFAULT is no approval gates. Only add HITL if user explicitly requests approval/confirmation before external actions.
+
 If the tool returns \`status="needs_input"\`, ask the missing questions, then call \`workflow(...)\` again with the additional details.
 
 ### Step 2: (Optional) Validate the generated workflow