@ema.co/mcp-toolkit 0.2.2 → 0.3.0

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";

package/dist/sdk/version-policy.js

@@ -0,0 +1,328 @@
+/**
+ * Persona Version Policy Engine
+ *
+ * Handles automatic versioning decisions based on policies.
+ * Determines when to create snapshots, manages retention, and
+ * enforces versioning rules.
+ */
+import { createVersionSnapshot, hashSnapshot, createSnapshotFromPersona, generateChangesSummary, compareVersions, } from "./version-tracking.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Policy Engine Class
+// ─────────────────────────────────────────────────────────────────────────────
+export class VersionPolicyEngine {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    // ─────────────── Policy Checks ───────────────
+    /**
+     * Check if a version should be created for a persona.
+     */
+    checkPolicy(persona, trigger) {
+        const policy = this.storage.getPolicy(persona.id);
+        const snapshot = createSnapshotFromPersona(persona);
+        const contentHash = hashSnapshot(snapshot);
+        // Check if this would be a duplicate
+        const isDuplicate = this.storage.hasContentHash(persona.id, contentHash);
+        // Determine if we should create based on trigger and policy
+        let shouldCreate = false;
+        let reason = "";
+        let skipReason;
+        switch (trigger) {
+            case "manual":
+                // Always allow manual creation
+                shouldCreate = true;
+                reason = "Manual version creation requested";
+                break;
+            case "deploy":
+                if (policy.auto_version_on_deploy) {
+                    if (isDuplicate) {
+                        shouldCreate = false;
+                        skipReason = "Content unchanged from existing version";
+                    }
+                    else {
+                        shouldCreate = true;
+                        reason = "Auto-versioning on deploy enabled";
+                    }
+                }
+                else {
+                    shouldCreate = false;
+                    skipReason = "Auto-versioning on deploy disabled by policy";
+                }
+                break;
+            case "sync":
+                if (policy.auto_version_on_sync) {
+                    if (isDuplicate) {
+                        shouldCreate = false;
+                        skipReason = "Content unchanged from existing version";
+                    }
+                    else {
+                        shouldCreate = true;
+                        reason = "Auto-versioning on sync enabled";
+                    }
+                }
+                else {
+                    shouldCreate = false;
+                    skipReason = "Auto-versioning on sync disabled by policy";
+                }
+                break;
+            case "auto":
+                // Check interval if specified
+                if (policy.min_interval) {
+                    const latest = this.storage.getLatestVersion(persona.id);
+                    if (latest && !this.hasIntervalPassed(latest.created_at, policy.min_interval)) {
+                        shouldCreate = false;
+                        skipReason = `Minimum interval (${policy.min_interval}) not yet passed`;
+                        break;
+                    }
+                }
+                if (isDuplicate) {
+                    shouldCreate = false;
+                    skipReason = "Content unchanged from existing version";
+                }
+                else {
+                    shouldCreate = true;
+                    reason = "Auto-snapshot triggered";
+                }
+                break;
+            case "import":
+                // Always allow imports (but check dedup)
+                if (isDuplicate) {
+                    shouldCreate = false;
+                    skipReason = "Imported content matches existing version";
+                }
+                else {
+                    shouldCreate = true;
+                    reason = "Importing version from external source";
+                }
+                break;
+        }
+        return {
+            should_create_version: shouldCreate,
+            reason: shouldCreate ? reason : skipReason ?? "Unknown reason",
+            skip_reason: shouldCreate ? undefined : skipReason,
+            content_hash: contentHash,
+            is_duplicate: isDuplicate,
+        };
+    }
+    /**
+     * Check if the minimum interval has passed since the last version.
+     */
+    hasIntervalPassed(lastCreatedAt, interval) {
+        const last = new Date(lastCreatedAt);
+        const now = new Date();
+        // Parse ISO duration (simplified - supports PT{n}H, PT{n}M, P{n}D)
+        const hours = interval.match(/PT(\d+)H/)?.[1];
+        const minutes = interval.match(/PT(\d+)M/)?.[1];
+        const days = interval.match(/P(\d+)D/)?.[1];
+        let intervalMs = 0;
+        if (hours)
+            intervalMs += parseInt(hours, 10) * 60 * 60 * 1000;
+        if (minutes)
+            intervalMs += parseInt(minutes, 10) * 60 * 1000;
+        if (days)
+            intervalMs += parseInt(days, 10) * 24 * 60 * 60 * 1000;
+        return now.getTime() - last.getTime() >= intervalMs;
+    }
+    // ─────────────── Version Creation ───────────────
+    /**
+     * Create a version if policy allows.
+     * This is the main entry point for automatic versioning.
+     */
+    createVersionIfAllowed(persona, trigger, options) {
+        // Check policy (unless forced)
+        const check = this.checkPolicy(persona, trigger);
+        if (!options.force && !check.should_create_version) {
+            return {
+                created: false,
+                reason: check.reason,
+                versions_pruned: 0,
+            };
+        }
+        // Get parent version info
+        const latest = this.storage.getLatestVersion(persona.id);
+        const previousVersionNumber = latest?.version_number;
+        const parentVersionId = latest?.id;
+        // Create the version
+        const version = createVersionSnapshot({
+            persona,
+            environment: options.environment,
+            tenant_id: options.tenant_id,
+            trigger,
+            message: options.message,
+            created_by: options.created_by,
+            previous_version_number: previousVersionNumber,
+            parent_version_id: parentVersionId,
+        });
+        // Compute changes from parent
+        let changesFromParent;
+        if (latest) {
+            const diff = compareVersions(latest, version);
+            changesFromParent = generateChangesSummary(diff);
+            version.changes_summary = changesFromParent;
+        }
+        // Save the version
+        this.storage.saveVersion(version);
+        // Prune if necessary
+        const versionsPruned = this.storage.pruneVersions(persona.id);
+        return {
+            created: true,
+            version,
+            reason: `Created ${version.version_name}${options.force ? " (forced)" : ""}`,
+            changes_from_parent: changesFromParent,
+            versions_pruned: versionsPruned,
+        };
+    }
+    /**
+     * Force create a version regardless of policy.
+     */
+    forceCreateVersion(persona, options) {
+        return this.createVersionIfAllowed(persona, "manual", {
+            ...options,
+            force: true,
+        });
+    }
+    // ─────────────── Version Restoration ───────────────
+    /**
+     * Get the snapshot data needed to restore a version.
+     * Returns the persona configuration that can be applied via updateAiEmployee.
+     */
+    getRestoreData(personaId, versionIdentifier) {
+        // Get the version
+        let version = null;
+        if (typeof versionIdentifier === "number") {
+            version = this.storage.getVersion(personaId, versionIdentifier);
+        }
+        else if (versionIdentifier.match(/^v\d+$/)) {
+            version = this.storage.getVersionByName(personaId, versionIdentifier);
+        }
+        else {
+            // Assume it's a version ID
+            version = this.storage.getVersionById(personaId, versionIdentifier);
+        }
+        if (!version) {
+            return {
+                success: false,
+                error: `Version not found: ${versionIdentifier}`,
+            };
+        }
+        // Build restore payload
+        const snapshot = version.snapshot;
+        return {
+            success: true,
+            version,
+            restore_payload: {
+                persona_id: personaId,
+                name: snapshot.display_name,
+                description: snapshot.description,
+                proto_config: snapshot.proto_config ?? {},
+                workflow: snapshot.workflow_definition,
+                welcome_messages: snapshot.welcome_messages ?? null,
+                embedding_enabled: snapshot.embedding_enabled ?? null,
+            },
+        };
+    }
+    // ─────────────── Policy Management ───────────────
+    /**
+     * Get policy for a persona.
+     */
+    getPolicy(personaId) {
+        return this.storage.getPolicy(personaId);
+    }
+    /**
+     * Update policy for a persona.
+     */
+    updatePolicy(personaId, updates) {
+        const current = this.storage.getPolicy(personaId);
+        const updated = {
+            ...current,
+            ...updates,
+            persona_id: personaId, // Ensure this is always set
+        };
+        this.storage.savePolicy(updated);
+        return updated;
+    }
+    // ─────────────── Query Methods ───────────────
+    /**
+     * List versions for a persona with optional filtering.
+     */
+    listVersions(personaId, options) {
+        let versions = this.storage.listVersions(personaId);
+        // Apply filters
+        if (options?.trigger) {
+            versions = versions.filter((v) => v.trigger === options.trigger);
+        }
+        if (options?.since) {
+            const sinceDate = new Date(options.since);
+            versions = versions.filter((v) => new Date(v.created_at) >= sinceDate);
+        }
+        // Sort by version number descending (newest first)
+        versions = versions.sort((a, b) => b.version_number - a.version_number);
+        // Apply limit
+        if (options?.limit) {
+            versions = versions.slice(0, options.limit);
+        }
+        return versions.map((v) => ({
+            id: v.id,
+            version_number: v.version_number,
+            version_name: v.version_name,
+            created_at: v.created_at,
+            trigger: v.trigger,
+            message: v.message,
+            content_hash: v.content_hash,
+        }));
+    }
+    /**
+     * Get a specific version with full details.
+     */
+    getVersion(personaId, versionIdentifier) {
+        if (versionIdentifier === "latest") {
+            return this.storage.getLatestVersion(personaId);
+        }
+        if (typeof versionIdentifier === "number") {
+            return this.storage.getVersion(personaId, versionIdentifier);
+        }
+        // Try as version name first (v1, v2, etc.)
+        if (versionIdentifier.match(/^v\d+$/)) {
+            return this.storage.getVersionByName(personaId, versionIdentifier);
+        }
+        // Try as version ID
+        return this.storage.getVersionById(personaId, versionIdentifier);
+    }
+    /**
+     * Compare two versions.
+     */
+    compareVersions(personaId, v1Identifier, v2Identifier) {
+        const v1 = this.getVersion(personaId, v1Identifier);
+        const v2 = this.getVersion(personaId, v2Identifier);
+        if (!v1) {
+            return { success: false, error: `Version not found: ${v1Identifier}` };
+        }
+        if (!v2) {
+            return { success: false, error: `Version not found: ${v2Identifier}` };
+        }
+        const diff = compareVersions(v1, v2);
+        const summary = generateChangesSummary(diff);
+        return {
+            success: true,
+            diff,
+            summary,
+        };
+    }
+    // ─────────────── Storage Access ───────────────
+    /**
+     * Get the underlying storage instance.
+     */
+    getStorage() {
+        return this.storage;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory Function
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create a VersionPolicyEngine instance.
+ */
+export function createVersionPolicyEngine(storage) {
+    return new VersionPolicyEngine(storage);
+}