@ema.co/mcp-toolkit 1.4.0 → 1.4.3

package/dist/mcp/prompts.js

@@ -680,6 +680,140 @@ Now begin the comparison.`,
         ],
     },
     // ─────────────────────────────────────────────────────────────────────────
+    // Version Management
+    // ─────────────────────────────────────────────────────────────────────────
+    persona_version: {
+        definition: {
+            name: "persona_version",
+            description: "Manage AI Employee versions - create snapshots, list history, compare, or restore.",
+            arguments: [
+                {
+                    name: "persona_id",
+                    description: "ID or exact name of the AI Employee",
+                    required: true,
+                },
+                {
+                    name: "action",
+                    description: "Action: 'snapshot' (create), 'list' (history), 'compare' (diff), 'restore' (rollback), 'policy' (auto-settings)",
+                    required: true,
+                },
+                {
+                    name: "version",
+                    description: "Version identifier for compare/restore (e.g., 'v3', 'latest')",
+                    required: false,
+                },
+                {
+                    name: "message",
+                    description: "Message for snapshot (e.g., 'Before adding HITL')",
+                    required: false,
+                },
+                {
+                    name: "env",
+                    description: "Environment (default: demo)",
+                    required: false,
+                },
+            ],
+        },
+        render: (args) => [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Manage versions for AI Employee: ${args.persona_id}
+
+**Action**: ${args.action}
+**Environment**: ${args.env || "demo"}
+${args.version ? `**Version**: ${args.version}` : ""}
+${args.message ? `**Message**: ${args.message}` : ""}
+
+## Instructions
+
+${args.action === "snapshot" ? `
+### Create Snapshot
+1. First verify the persona exists:
+   \`persona(id="${args.persona_id}", env="${args.env || "demo"}")\`
+
+2. Create the snapshot:
+   \`persona(id="${args.persona_id}", mode="version_create", message="${args.message || "Manual snapshot"}", env="${args.env || "demo"}")\`
+
+3. Confirm the snapshot was created by listing versions:
+   \`persona(id="${args.persona_id}", mode="version_list", env="${args.env || "demo"}")\`
+` : ""}${args.action === "list" ? `
+### List Version History
+1. Get version history:
+   \`persona(id="${args.persona_id}", mode="version_list", env="${args.env || "demo"}")\`
+
+2. Present the versions in a table showing:
+   - Version name (v1, v2, etc.)
+   - Created timestamp
+   - Trigger (manual, deploy, sync)
+   - Message
+   - Content hash (for deduplication)
+` : ""}${args.action === "compare" ? `
+### Compare Versions
+1. List versions first to see available:
+   \`persona(id="${args.persona_id}", mode="version_list", env="${args.env || "demo"}")\`
+
+2. Compare two versions:
+   \`persona(id="${args.persona_id}", mode="version_compare", v1="${args.version || "v1"}", v2="latest", env="${args.env || "demo"}")\`
+
+3. Present changes:
+   - Fields that changed
+   - Nodes added/removed/modified
+   - Data sources added/removed
+` : ""}${args.action === "restore" ? `
+### Restore to Previous Version
+**Warning**: This will modify the live AI Employee!
+
+1. List versions to find the one to restore:
+   \`persona(id="${args.persona_id}", mode="version_list", env="${args.env || "demo"}")\`
+
+2. Get details of the target version:
+   \`persona(id="${args.persona_id}", mode="version_get", version="${args.version || "v1"}", env="${args.env || "demo"}")\`
+
+3. Confirm with user before proceeding, then restore:
+   \`persona(id="${args.persona_id}", mode="version_restore", version="${args.version || "v1"}", env="${args.env || "demo"}")\`
+
+Note: A "before restore" snapshot is automatically created for safety.
+` : ""}${args.action === "policy" ? `
+### Configure Auto-Versioning Policy
+1. Get current policy:
+   \`persona(id="${args.persona_id}", mode="version_policy", env="${args.env || "demo"}")\`
+
+2. Enable auto-snapshot on deploy:
+   \`persona(id="${args.persona_id}", mode="version_policy", auto_on_deploy=true, env="${args.env || "demo"}")\`
+
+3. Enable auto-snapshot on sync:
+   \`persona(id="${args.persona_id}", mode="version_policy", auto_on_sync=true, env="${args.env || "demo"}")\`
+
+4. Set max versions to keep (prunes oldest):
+   \`persona(id="${args.persona_id}", mode="version_policy", max_versions=10, env="${args.env || "demo"}")\`
+` : ""}
+## Output Format
+
+\`\`\`markdown
+## Version Management: {Persona Name}
+
+### Action: ${args.action}
+{result of the action}
+
+### Version History (if applicable)
+| Version | Created | Trigger | Message |
+|---------|---------|---------|---------|
+| v3 | 2026-01-12 | deploy | Pre-deploy snapshot |
+| v2 | 2026-01-11 | manual | Before adding HITL |
+| v1 | 2026-01-10 | manual | Initial snapshot |
+
+### Next Steps
+{recommendations based on action taken}
+\`\`\`
+
+Now proceed with the ${args.action} action.`,
+                },
+            },
+        ],
+    },
+    // ─────────────────────────────────────────────────────────────────────────
     // Validate Prompt
     // ─────────────────────────────────────────────────────────────────────────
     prompt_validate: {

package/dist/mcp/resources.js

@@ -141,10 +141,10 @@ const RESOURCE_MAP = {
         description: "Dashboard AI deployment guide: batch processing setup, input configuration",
         mimeType: "text/markdown",
     },
-    // Cursor Rules - Generation guidance
-    "ema://rules/generation": {
-        path: ".cursor/rules/platforms/ema/generation/LOCAL-GENERATION.md",
-        description: "Local workflow generation rules: how to generate workflows without Auto Builder",
+    // Cursor Rules - MCP usage guidance
+    "ema://rules/mcp-usage": {
+        path: ".cursor/rules/ema-mcp.md",
+        description: "MCP usage guide: workflow modes, preview flag, brownfield extension, common patterns",
         mimeType: "text/markdown",
     },
 };

package/dist/mcp/server.js

@@ -34,8 +34,6 @@ import { AGENT_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEP
 analyzeWorkflow, detectWorkflowIssues, validateWorkflowConnections, suggestWorkflowFixes, } from "../sdk/knowledge.js";
 // Workflow Compiler (Template-driven)
 import { compileWorkflow, } from "../sdk/workflow-generator.js";
-// Workflow Intent (Normalization layer)
-import { parseInput, intentToSpec, } from "../sdk/workflow-intent.js";
 // Consolidated Tools (Unix CLI pattern) - NEW UNIFIED INTERFACE
 import { generateConsolidatedTools, } from "./tools-consolidated.js";
 // Legacy Tools (backwards compatibility) - DEPRECATED, OFF BY DEFAULT
@@ -43,7 +41,7 @@ import { generateLegacyTools, } from "./tools-legacy.js";
 // Feature flag: Legacy tools are DISABLED by default to prevent LLM confusion
 // Set EMA_ENABLE_LEGACY_TOOLS=true only if you need backwards compatibility
 const ENABLE_LEGACY_TOOLS = process.env.EMA_ENABLE_LEGACY_TOOLS === "true";
-import { handleEnv, handlePersona, handleAction, handleTemplate, handleKnowledge, handleReference, } from "./handlers-consolidated.js";
+import { handleEnv, handlePersona, handleWorkflow, handleAction, handleTemplate, handleKnowledge, handleReference, } from "./handlers-consolidated.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // Autobuilder Prompt Generation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -4295,7 +4293,8 @@ const toolHandlers = {
         const statusLog = persona.status_log;
         const fileUploadLog = statusLog?.fileUpload ?? [];
         // Try to get actual file list from API
-        const files = await client.listDataSourceFiles(personaId);
+        const filesResult = await client.listDataSourceFiles(personaId);
+        const files = filesResult.files;
         return {
             environment: client["env"].name,
             persona_id: personaId,
@@ -4303,6 +4302,7 @@ const toolHandlers = {
             embedding_enabled: persona.embedding_enabled ?? false,
             file_count: fileCount,
             files: files.length > 0 ? files : fileUploadLog,
+            pagination: filesResult.pagination,
             use_chunking: fileUploadConfig?.useChunking ?? false,
             workflow_id: persona.workflow_id,
             actions: [
@@ -4366,215 +4366,6 @@ const toolHandlers = {
         };
     },
     // ─────────────────────────────────────────────────────────────────────────
-    // Unified Workflow Handler
-    // ─────────────────────────────────────────────────────────────────────────
-    workflow: async (args) => {
-        const client = createClient(args.env);
-        const personaId = args.persona_id ? String(args.persona_id) : undefined;
-        const mode = args.mode ?? "generate";
-        const useAutobuilder = args.use_autobuilder;
-        const autoDeploy = Boolean(args.auto_deploy);
-        const autoFix = args.auto_fix !== false; // Default true
-        // ─────────────────────────────────────────────────────────────────────────
-        // MODE: IMPROVE - Improve existing workflow
-        // ─────────────────────────────────────────────────────────────────────────
-        if (mode === "improve" && personaId) {
-            const persona = await client.getPersonaById(personaId);
-            if (!persona)
-                throw new Error(`AI Employee not found: ${personaId}`);
-            const currentWorkflow = persona.workflow_def;
-            if (!currentWorkflow)
-                throw new Error(`AI Employee "${persona.name}" has no workflow`);
-            const issues = detectWorkflowIssues(currentWorkflow);
-            if (issues.length === 0) {
-                return {
-                    environment: client["env"].name,
-                    success: true,
-                    status: "no_issues",
-                    persona_id: personaId,
-                    persona_name: persona.name,
-                    message: "Workflow has no detected issues",
-                };
-            }
-            // Try auto-fix first
-            if (autoFix) {
-                const fixResult = applyWorkflowFixes(currentWorkflow, issues, persona);
-                if (fixResult.appliedFixes.some((f) => f.applied)) {
-                    const newIssues = detectWorkflowIssues(fixResult.fixedWorkflow);
-                    if (autoDeploy) {
-                        await client.updateAiEmployee({
-                            persona_id: personaId,
-                            proto_config: persona.proto_config ?? {},
-                            workflow: fixResult.fixedWorkflow,
-                        });
-                    }
-                    return {
-                        environment: client["env"].name,
-                        success: true,
-                        status: autoDeploy ? "deployed" : "improved",
-                        persona_id: personaId,
-                        persona_name: persona.name,
-                        fixes_applied: fixResult.appliedFixes.filter((f) => f.applied).map((f) => f.description),
-                        issues_before: issues.length,
-                        issues_after: newIssues.length,
-                        deployed: autoDeploy,
-                        workflow_def: autoDeploy ? undefined : fixResult.fixedWorkflow,
-                    };
-                }
-            }
-            return {
-                environment: client["env"].name,
-                success: false,
-                status: "needs_manual_fix",
-                persona_id: personaId,
-                issues,
-            };
-        }
-        // ─────────────────────────────────────────────────────────────────────────
-        // MODE: ANALYZE - Analyze only (no generation)
-        // ─────────────────────────────────────────────────────────────────────────
-        if (mode === "analyze" && personaId) {
-            const persona = await client.getPersonaById(personaId);
-            if (!persona)
-                throw new Error(`AI Employee not found: ${personaId}`);
-            const workflowDef = persona.workflow_def;
-            if (!workflowDef) {
-                return {
-                    environment: client["env"].name,
-                    success: true,
-                    status: "no_workflow",
-                    persona_id: personaId,
-                    persona_name: persona.name,
-                };
-            }
-            const issues = detectWorkflowIssues(workflowDef);
-            return {
-                environment: client["env"].name,
-                success: true,
-                status: "analyzed",
-                persona_id: personaId,
-                persona_name: persona.name,
-                issues,
-                summary: {
-                    critical: issues.filter((i) => i.severity === "critical").length,
-                    warnings: issues.filter((i) => i.severity === "warning").length,
-                },
-            };
-        }
-        // ─────────────────────────────────────────────────────────────────────────
-        // MODE: GENERATE - Generate new workflow from input
-        // ─────────────────────────────────────────────────────────────────────────
-        const input = args.input;
-        if (!input && !personaId) {
-            return {
-                success: false,
-                status: "missing_input",
-                message: "Provide 'input' (description or spec) or 'persona_id' with mode='improve'",
-            };
-        }
-        // Parse and normalize input
-        const parseResult = parseInput(input);
-        const { intent, input_type, validation } = parseResult;
-        // Override persona_type if provided
-        if (args.persona_type) {
-            intent.persona_type = args.persona_type;
-        }
-        // If validation incomplete, return questions
-        if (!validation.complete) {
-            return {
-                environment: client["env"].name,
-                success: true,
-                status: "needs_input",
-                input_type,
-                parsed_intent: intent,
-                validation,
-                message: "Need more information to generate workflow",
-                questions: validation.questions,
-                suggestions: validation.suggestions,
-            };
-        }
-        // Decide: compile locally vs. use Auto Builder
-        const isSimple = !intent.intents || intent.intents.length <= 2;
-        const shouldUseAutobuilder = useAutobuilder ?? !isSimple;
-        let workflowDef;
-        let generationMethod;
-        if (shouldUseAutobuilder) {
-            // Use Auto Builder
-            const prompt = generateAutobuilderPrompt(intent.description, intent.persona_type);
-            const autobuilderId = await client.findAutobuilderPersona();
-            const conv = await client.createAutobuilderConversation(autobuilderId);
-            const result = await client.chatWithAutobuilder(conv.conversation_id, prompt);
-            if (!result.workflow_def) {
-                return {
-                    environment: client["env"].name,
-                    success: false,
-                    status: "generation_failed",
-                    message: "Auto Builder could not generate workflow. Try being more specific.",
-                    parsed_intent: intent,
-                    autobuilder_response: result.response,
-                };
-            }
-            workflowDef = result.workflow_def;
-            generationMethod = "autobuilder";
-        }
-        else {
-            // Compile locally from intent
-            const spec = intentToSpec(intent);
-            const compiled = compileWorkflow(spec);
-            workflowDef = compiled.workflow_def;
-            generationMethod = "local_compile";
-        }
-        // Validate generated workflow
-        const issues = detectWorkflowIssues(workflowDef);
-        let fixesApplied = [];
-        // Auto-fix if needed
-        if (issues.length > 0 && autoFix) {
-            const mockPersona = { id: personaId ?? "new", name: intent.name };
-            const fixResult = applyWorkflowFixes(workflowDef, issues, mockPersona);
-            if (fixResult.appliedFixes.some((f) => f.applied)) {
-                workflowDef = fixResult.fixedWorkflow;
-                fixesApplied = fixResult.appliedFixes.filter((f) => f.applied).map((f) => f.description);
-            }
-        }
-        const finalIssues = detectWorkflowIssues(workflowDef);
-        // Deploy if requested
-        let deployed = false;
-        if (personaId && autoDeploy) {
-            const persona = await client.getPersonaById(personaId);
-            if (persona) {
-                await client.updateAiEmployee({
-                    persona_id: personaId,
-                    proto_config: persona.proto_config ?? {},
-                    workflow: workflowDef,
-                });
-                deployed = true;
-            }
-        }
-        return {
-            environment: client["env"].name,
-            success: true,
-            status: deployed ? "deployed" : "generated",
-            input_type,
-            generation_method: generationMethod,
-            parsed_intent: intent,
-            validation: {
-                confidence: validation.confidence,
-                suggestions: validation.suggestions,
-            },
-            issues_found: issues.length,
-            auto_fixes: fixesApplied,
-            remaining_issues: finalIssues.length,
-            workflow_def: deployed ? undefined : workflowDef,
-            deployed,
-            persona_id: personaId,
-            next_steps: deployed
-                ? [`Verify: get_persona("${personaId}")`]
-                : personaId
-                    ? [`Deploy: deploy_workflow("${personaId}", workflow_def)`]
-                    : ["Create AI Employee, then deploy workflow"],
-        };
-    },
-    // ─────────────────────────────────────────────────────────────────────────
     // Demo Data Management Handlers
     // ─────────────────────────────────────────────────────────────────────────
     consolidate_demo_data: async (args) => {
@@ -5049,8 +4840,11 @@ const toolHandlers = {
         };
         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
+    // Consolidated workflow handler (replaces legacy inline handler)
+    workflow: async (args) => {
+        const client = createClient(args.env);
+        return handleWorkflow(args, client);
+    },
     action: async (args) => {
         const client = createClient(args.env);
         return handleAction(args, client);

package/dist/mcp/tools-consolidated.js

@@ -117,8 +117,13 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
                 },
                 template_id: { type: "string", description: "Template ID (for create)" },
                 clone_from: { type: "string", description: "Clone from persona ID (for create)" },
+                clone_data: { type: "boolean", description: "Also clone knowledge base files when using clone_from (default: false)" },
                 // Update flags
                 enabled: { type: "boolean", description: "Enable/disable (for update)" },
+                proto_config: {
+                    type: "object",
+                    description: "Voice/chat settings (welcomeMessage, identityAndPurpose, etc.) for update"
+                },
                 // Compare flags
                 compare_to: { type: "string", description: "Second persona ID (for compare)" },
                 compare_env: { type: "string", description: "Environment of compare_to persona" },
@@ -135,88 +140,93 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
             }),
         },
         // ═══════════════════════════════════════════════════════════════════════
-        // 3. WORKFLOW - Generation, analysis, deployment
+        // 3. WORKFLOW - Generation, analysis, extension, optimization
         // ═══════════════════════════════════════════════════════════════════════
         {
             name: "workflow",
-            description: `Unified workflow generation and analysis.
+            description: `Unified workflow operations. All modification modes default to preview=true for safety.
 
 **Greenfield** (NEW workflow from scratch):
   workflow(input="IT helpdesk with KB search")
   workflow(mode="generate", input="customer support bot")
+  workflow(mode="generate", input="...", preview=false)  # Generate AND deploy
+
+**Extend** (MODIFY existing workflow - brownfield):
+  workflow(mode="extend", persona_id="abc", input="add caller_type categorizer")
+  workflow(mode="extend", persona_id="abc", input="add HITL before email, add compliance intent")
+  workflow(mode="extend", persona_id="abc", input="...", preview=false)  # Extend AND deploy
 
-**Brownfield** (UPDATE existing workflow - auto-detected when persona_id + input provided):
-  workflow(persona_id="abc-123", input="add KB search capability")
-  workflow(persona_id="abc", input="add HITL approval for ticket creation")
+**Optimize** (FIX issues in existing workflow):
+  workflow(mode="optimize", persona_id="abc")           # Preview fixes
+  workflow(mode="optimize", persona_id="abc", preview=false)  # Apply fixes
 
-**Analyze** (inspect existing):
+**Analyze** (inspect existing - always read-only):
   workflow(persona_id="abc-123")
-  workflow(persona_id="abc-123", mode="analyze")
-  workflow(workflow_def={...}, mode="analyze")
+  workflow(mode="analyze", persona_id="abc-123")
+  workflow(mode="analyze", workflow_def={...})
 
-**Deploy**:
-  workflow(persona_id="abc-123", mode="deploy", workflow_def={...})
-  workflow(persona_id="abc", mode="deploy", auto_fix=true)
+**Compare** (diff two workflows - always read-only):
+  workflow(mode="compare", persona_id="abc", compare_to="def")
 
-**Optimize** (analyze + fix + optional deploy):
-  workflow(persona_id="abc-123", mode="optimize")
-  workflow(persona_id="abc", mode="optimize", preview=true)
+**Compile** (from explicit node spec - returns workflow_def):
+  workflow(mode="compile", name="...", description="...", nodes=[...])
 
-**Compare**:
-  workflow(persona_id="abc", mode="compare", compare_to="def")
+## Key Concepts
 
-**Compile** (from node spec):
-  workflow(mode="compile", name="...", description="...", nodes=[...], result_mappings=[...])`,
+- **preview=true** (default): Returns result without deploying. Safe for exploration.
+- **preview=false**: Deploys the result. Server handles fetching proto_config, etc.
+- **Auto-builder is abstracted**: Server decides when to use it internally.`,
             inputSchema: withEnv({
-                // Common metadata (primarily used for mode="compile")
-                name: { type: "string", description: "Workflow name (required for compile mode)" },
-                description: { type: "string", description: "Workflow description (required for compile mode)" },
-                // Input (one of these for generation)
+                // Mode - explicit operation
+                mode: {
+                    type: "string",
+                    enum: ["generate", "extend", "optimize", "analyze", "compare", "compile"],
+                    description: "Operation: 'generate' (new), 'extend' (modify existing), 'optimize' (fix issues), 'analyze' (inspect), 'compare' (diff), 'compile' (from nodes). Default: inferred from args."
+                },
+                // Input (for generate/extend)
                 input: {
                     anyOf: [
                         { type: "string", description: "Natural language description" },
                         { type: "object", description: "Workflow intent/spec object" },
                     ],
-                    description: "Natural language description OR workflow intent/spec object",
+                    description: "Natural language requirements. Can include multiple changes: 'add X, add Y, add Z'",
                 },
+                // Target persona (for extend/optimize/analyze/compare)
                 persona_id: {
                     type: "string",
-                    description: "Persona ID for existing workflow operations"
-                },
-                workflow_def: {
-                    type: "object",
-                    description: "Workflow JSON for analysis or deployment"
+                    description: "Persona ID for existing workflow operations (extend/optimize/analyze/compare)"
                 },
-                // Mode
-                mode: {
-                    type: "string",
-                    enum: ["generate", "analyze", "deploy", "optimize", "compare", "compile"],
-                    description: "Operation mode. Default: 'generate' with input, 'analyze' with persona_id. Use 'optimize' for one-click fix & deploy."
+                // Preview vs Deploy (default: preview=true for safety)
+                preview: {
+                    type: "boolean",
+                    description: "Preview changes without deploying. Default: true. Set false to deploy."
                 },
-                // Optimize flags
-                preview: { type: "boolean", description: "Preview changes without deploying (for optimize mode)" },
-                // Generate flags
+                // Persona type (for generate)
                 type: {
                     type: "string",
                     enum: ["voice", "chat", "dashboard"],
-                    description: "Persona type (default: chat)"
+                    description: "Persona type for generate mode (default: chat)"
                 },
-                use_autobuilder: { type: "boolean", description: "Force Auto Builder API" },
-                // Analyze flags - what to include
+                // Compare target
+                compare_to: { type: "string", description: "Second persona ID for compare mode" },
+                // Analyze options
                 include: {
                     type: "array",
                     items: { type: "string", enum: ["issues", "connections", "fixes", "metrics"] },
                     description: "What to include in analysis. Default: all.",
                 },
-                // Deploy flags
-                auto_fix: { type: "boolean", description: "Auto-fix issues before deploy" },
-                validate: { type: "boolean", description: "Validate before deploy (default: true)" },
-                proto_config: { type: "object", description: "Persona config (voice settings, etc.)" },
-                // Compare flags
-                compare_to: { type: "string", description: "Second persona ID for comparison" },
-                // Compile flags (for mode="compile")
-                nodes: { type: "array", description: "Node definitions for compilation" },
-                result_mappings: { type: "array", description: "Output mappings for compilation" },
+                // Direct workflow input (for analyze without persona_id)
+                workflow_def: {
+                    type: "object",
+                    description: "Workflow JSON for analysis (alternative to persona_id)"
+                },
+                // Compile mode inputs
+                name: { type: "string", description: "Workflow name (for compile mode)" },
+                description: { type: "string", description: "Workflow description (for compile mode)" },
+                nodes: { type: "array", description: "Node definitions (for compile mode)" },
+                result_mappings: { type: "array", description: "Output mappings (for compile mode)" },
+                // Proto config override
+                proto_config: { type: "object", description: "Persona config override (voice settings, etc.)" },
             }),
         },
         // ═══════════════════════════════════════════════════════════════════════
@@ -338,9 +348,12 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
             name: "knowledge",
             description: `Manage AI Employee knowledge base (data sources & embedding).
 
-**List files**:
+**List files** (with pagination):
   knowledge(persona_id="abc-123")
-  knowledge(persona_id="abc", mode="list")
+  knowledge(persona_id="abc", mode="list", limit=50, page=1)
+
+**Get aggregates** (file counts by status):
+  knowledge(persona_id="abc", mode="aggregates")
 
 **Upload file**:
   knowledge(persona_id="abc", mode="upload", file="/path/to/doc.pdf")
@@ -352,14 +365,22 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
   knowledge(persona_id="abc", mode="status")
 
 **Toggle embedding**:
-  knowledge(persona_id="abc", mode="toggle", enabled=true)`,
+  knowledge(persona_id="abc", mode="toggle", enabled=true)
+
+**Attach data source to workflow node**:
+  knowledge(persona_id="abc", mode="attach", node_name="knowledge_search_1")
+  knowledge(persona_id="abc", mode="attach", node_name="knowledge_search_1", widget_name="fileUpload")`,
             inputSchema: withEnv({
                 persona_id: { type: "string", description: "AI Employee ID (required)" },
                 mode: {
                     type: "string",
-                    enum: ["list", "upload", "delete", "status", "toggle"],
+                    enum: ["list", "aggregates", "upload", "delete", "status", "toggle", "attach"],
                     description: "Operation. Default: 'list'"
                 },
+                // List flags
+                page: { type: "number", description: "Page number (default: 1)" },
+                limit: { type: "number", description: "Items per page (default: 50)" },
+                widget_name: { type: "string", description: "Widget name (default: 'fileUpload')" },
                 // Upload flags
                 file: { type: "string", description: "File path for upload" },
                 tags: { type: "string", description: "Tags for uploaded file" },
@@ -367,6 +388,8 @@ export function generateConsolidatedTools(envNames, defaultEnv) {
                 file_id: { type: "string", description: "File ID to delete" },
                 // Toggle flags
                 enabled: { type: "boolean", description: "Enable/disable embedding" },
+                // Attach flags
+                node_name: { type: "string", description: "Workflow node name to attach data source to (e.g., 'knowledge_search_1')" },
             }, ["persona_id"]),
         },
         // ═══════════════════════════════════════════════════════════════════════