@ema.co/mcp-toolkit 0.2.3 → 0.3.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}` };
     }

package/dist/mcp/server.js

@@ -25,6 +25,8 @@ import { loadConfigOptional } from "../sdk/config.js";
 import { resolveSyncBehavior, loadSyncOptions } from "../sdk/sync-options.js";
 import { SyncSDK } from "../sdk/sync.js";
 import { fingerprintPersona, transformWorkflowForTarget, getCleanDescription, buildDescriptionWithSyncTag } from "../sync.js";
+import { createVersionStorage } from "../sdk/version-storage.js";
+import { createVersionPolicyEngine } from "../sdk/version-policy.js";
 import { SYNC_METADATA_KEY } from "../sdk/models.js";
 // Auto Builder Knowledge
 import { AGENT_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, VOICE_PERSONA_TEMPLATE, PROJECT_TYPES, getAgentsByCategory, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, 
@@ -4205,13 +4207,20 @@ const toolHandlers = {
         })));
     },
     persona: async (args) => {
-        const client = createClient(args.env);
+        const targetEnv = args.env ?? getDefaultEnvName();
+        const client = createClient(targetEnv);
         const DEFAULT_TEMPLATES = {
             voice: "00000000-0000-0000-0000-00000000001e",
             chat: "00000000-0000-0000-0000-000000000004",
             dashboard: "00000000-0000-0000-0000-000000000002",
         };
-        return handlePersona(args, client, (type) => DEFAULT_TEMPLATES[type], (env) => createClient(env));
+        // Build version context for version management modes
+        const versionContext = {
+            workspaceRoot: process.cwd(),
+            environment: targetEnv,
+            tenant_id: targetEnv, // Use env name as tenant identifier
+        };
+        return handlePersona(args, client, (type) => DEFAULT_TEMPLATES[type], (env) => createClient(env), versionContext);
     },
     // Note: 'workflow' handler already exists above - consolidated version adds analyze modes
     // The existing 'workflow' handler is kept for backward compatibility
@@ -4358,7 +4367,34 @@ toolHandlers.workflow = async (args) => {
             }
             const validateFirst = normalizedArgs.validate !== false; // default true
             const autoFix = normalizedArgs.auto_fix === true; // default false
-            return legacyDeployWorkflow({
+            const targetEnv = normalizedArgs.env ?? getDefaultEnvName();
+            // ─────────────── Version tracking (pre-deploy snapshot) ───────────────
+            let versionCreated;
+            try {
+                const client = createClient(targetEnv);
+                const personaBefore = await client.getPersonaById(personaId);
+                if (personaBefore) {
+                    const storage = createVersionStorage(process.cwd());
+                    const engine = createVersionPolicyEngine(storage);
+                    // Check policy and create version if allowed
+                    const result = engine.createVersionIfAllowed(personaBefore, "deploy", {
+                        environment: targetEnv,
+                        tenant_id: targetEnv,
+                        message: "Pre-deploy snapshot",
+                        created_by: "mcp-toolkit",
+                    });
+                    if (result.created && result.version) {
+                        versionCreated = {
+                            id: result.version.id,
+                            version_name: result.version.version_name,
+                        };
+                    }
+                }
+            }
+            catch {
+                // Version tracking is best-effort - don't fail deploy if it errors
+            }
+            const deployResult = await legacyDeployWorkflow({
                 persona_id: personaId,
                 workflow_def: workflowDef,
                 proto_config: normalizedArgs.proto_config,
@@ -4366,6 +4402,11 @@ toolHandlers.workflow = async (args) => {
                 auto_fix: autoFix,
                 env: normalizedArgs.env,
             });
+            // Add version info to result if created
+            if (versionCreated && deployResult && typeof deployResult === "object") {
+                deployResult.version_snapshot = versionCreated;
+            }
+            return deployResult;
         }
         case "optimize": {
             // optimize_workflow supports both:

package/dist/mcp/tools-consolidated.js

@@ -46,7 +46,7 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
             inputSchema: { type: "object", properties: {}, required: [] },
         },
         // ═══════════════════════════════════════════════════════════════════════
-        // 2. PERSONA - AI Employee management (CRUD + compare)
+        // 2. PERSONA - AI Employee management (CRUD + compare + versioning)
         // ═══════════════════════════════════════════════════════════════════════
         {
             name: "persona",
@@ -71,7 +71,15 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
   persona(id="abc-123", mode="compare", compare_to="def-456")
 
 **Templates** (list available templates):
-  persona(templates=true)`,
+  persona(templates=true)
+
+**Version Management** (track configuration history):
+  persona(id="abc-123", mode="version_create", message="Before major update")
+  persona(id="abc-123", mode="version_list")
+  persona(id="abc-123", mode="version_get", version="v3")
+  persona(id="abc-123", mode="version_compare", v1="v2", v2="v3")
+  persona(id="abc-123", mode="version_restore", version="v2")
+  persona(id="abc-123", mode="version_policy", auto_on_deploy=true)`,
             inputSchema: withEnv({
                 // ID (or exact name) (optional - if omitted with all=true, lists all)
                 id: {
@@ -87,7 +95,7 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
                 // Mode (defaults to "get" if id provided, "list" if all=true)
                 mode: {
                     type: "string",
-                    enum: ["get", "list", "create", "update", "compare"],
+                    enum: ["get", "list", "create", "update", "compare", "version_create", "version_list", "version_get", "version_compare", "version_restore", "version_policy"],
                     description: "Operation mode. Default: 'get' with id, 'list' without."
                 },
                 // List/Search flags
@@ -116,6 +124,14 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
                 compare_env: { type: "string", description: "Environment of compare_to persona" },
                 // Templates flag
                 templates: { type: "boolean", description: "List available templates" },
+                // Version management flags
+                version: { type: "string", description: "Version identifier (e.g., 'v3', 'latest', or UUID)" },
+                v1: { type: "string", description: "First version for comparison (version_compare mode)" },
+                v2: { type: "string", description: "Second version for comparison (version_compare mode)" },
+                message: { type: "string", description: "Version message/description (version_create mode)" },
+                auto_on_deploy: { type: "boolean", description: "Auto-create version on deploy (version_policy mode)" },
+                auto_on_sync: { type: "boolean", description: "Auto-create version on sync (version_policy mode)" },
+                max_versions: { type: "number", description: "Max versions to keep (version_policy mode)" },
             }),
         },
         // ═══════════════════════════════════════════════════════════════════════

package/dist/sdk/index.js

@@ -37,3 +37,11 @@ buildVoiceConfig, buildChatConfig, } from "./workflow-generator.js";
 export { parseInput, validateIntent, intentToSpec, detectInputType, parseNaturalLanguage, parsePartialSpec, } from "./workflow-intent.js";
 // Generation Schema (Compact format for LLM-based generation)
 export { generateSchema, generateSchemaMarkdown, buildCompactAgents, buildTypeRules, buildConstraints, getAgentSchema, isTypeCompatible, getRecommendedInput, } from "./generation-schema.js";
+// Version Tracking (Persona version history management)
+export { 
+// Core functions
+hashSnapshot, generateVersionId, generateVersionName, nowIso, createSnapshotFromPersona, createVersionSnapshot, compareVersions, generateChangesSummary, fingerprintPersona, extractDataSources, } from "./version-tracking.js";
+// Version Storage (Git-backed local storage)
+export { VersionStorage, createVersionStorage, } from "./version-storage.js";
+// Version Policy Engine (Automatic versioning decisions)
+export { VersionPolicyEngine, createVersionPolicyEngine, } from "./version-policy.js";