@ema.co/mcp-toolkit 1.7.1 → 2026.1.17

package/dist/mcp/handlers-consolidated.js

@@ -2288,25 +2288,223 @@ export async function handleKnowledge(args, client, readFile) {
     }
 }
 // ═══════════════════════════════════════════════════════════════════════════
-// REFERENCE Handler
+// REFERENCE Handler (v2 unified: envs, actions, templates, patterns, concepts, guidance)
 // ═══════════════════════════════════════════════════════════════════════════
-export function handleReference(args) {
-    // Get concept
-    if (args.concept) {
-        const concept = getConceptByTerm(args.concept);
-        if (!concept) {
-            return { error: `Concept not found: ${args.concept}` };
+export async function handleReference(args, context) {
+    const type = args.type;
+    // ─────────────────────────────────────────────────────────────────────────
+    // type="envs" - List available environments
+    // ─────────────────────────────────────────────────────────────────────────
+    if (type === "envs") {
+        const getEnvs = context?.getEnvironments;
+        if (!getEnvs) {
+            return { error: "Environment context not available" };
         }
-        return concept;
+        const envs = getEnvs();
+        return {
+            environments: envs.map(e => ({
+                name: e.name,
+                default: e.isDefault,
+            })),
+            count: envs.length,
+            toolkit: context?.toolkit ?? { name: "unknown", version: "unknown" },
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // type="actions" - Action/agent lookup (replaces handleAction)
+    // ─────────────────────────────────────────────────────────────────────────
+    if (type === "actions") {
+        const client = context?.client;
+        const id = args.id;
+        // Categories list
+        if (args.categories) {
+            const categories = [...new Set(Object.values(AGENT_CATALOG).map(a => a.category))];
+            return { categories, count: categories.length };
+        }
+        // Suggest for use case
+        if (args.suggest) {
+            const suggestions = suggestAgentsForUseCase(args.suggest);
+            return { suggestions, use_case: args.suggest };
+        }
+        // Get single action
+        if (id) {
+            // Try API first if client available
+            if (client) {
+                try {
+                    const actions = await client.listActions();
+                    const action = actions.find(a => a.id === id ||
+                        a.name === id ||
+                        a.name?.toLowerCase() === id.toLowerCase());
+                    const result = action ? {
+                        id: action.id,
+                        name: action.name,
+                        category: action.category,
+                        enabled: action.enabled,
+                        inputs: action.inputs,
+                        outputs: action.outputs,
+                        source: "api",
+                    } : {};
+                    // Include docs if requested or if not found in API
+                    if (args.include_docs || !action) {
+                        const doc = getAgentByName(id);
+                        if (doc) {
+                            result.documentation = doc;
+                            result.source = action ? "api+docs" : "docs";
+                        }
+                    }
+                    if (Object.keys(result).length === 0) {
+                        return { error: `Action not found: ${id}` };
+                    }
+                    return result;
+                }
+                catch {
+                    // Fallback to docs only
+                    const doc = getAgentByName(id);
+                    if (doc) {
+                        return { ...doc, source: "docs" };
+                    }
+                    return { error: `Action not found: ${id}` };
+                }
+            }
+            // No client - use docs only
+            const doc = getAgentByName(id);
+            if (doc) {
+                return { ...doc, source: "docs" };
+            }
+            return { error: `Action not found: ${id}` };
+        }
+        // List actions
+        if (client) {
+            try {
+                let actions = await client.listActions();
+                // Apply filters
+                if (args.query) {
+                    const q = args.query.toLowerCase();
+                    actions = actions.filter(a => a.name?.toLowerCase().includes(q));
+                }
+                if (args.category) {
+                    actions = actions.filter(a => a.category === args.category);
+                }
+                // Apply limit
+                const limit = args.limit || 100;
+                actions = actions.slice(0, limit);
+                return {
+                    count: actions.length,
+                    actions: actions.map(a => ({
+                        id: a.id,
+                        name: a.name,
+                        category: a.category,
+                        enabled: a.enabled,
+                    })),
+                };
+            }
+            catch {
+                // Fallback to catalog
+            }
+        }
+        // Fallback to catalog
+        let agents = Object.entries(AGENT_CATALOG);
+        if (args.category) {
+            agents = agents.filter(([_, a]) => a.category === args.category);
+        }
+        if (args.query) {
+            const q = args.query.toLowerCase();
+            agents = agents.filter(([name]) => name.toLowerCase().includes(q));
+        }
+        return {
+            count: agents.length,
+            actions: agents.map(([name, agent]) => ({
+                name,
+                category: agent.category,
+                description: agent.description,
+                source: "catalog",
+            })),
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // type="templates" - List persona templates
+    // ─────────────────────────────────────────────────────────────────────────
+    if (type === "templates") {
+        return {
+            templates: [
+                { id: "00000000-0000-0000-0000-00000000001e", name: "Voice AI", type: "voice" },
+                { id: "00000000-0000-0000-0000-000000000004", name: "Chat AI", type: "chat" },
+                { id: "00000000-0000-0000-0000-000000000002", name: "Dashboard AI", type: "dashboard" },
+            ],
+            note: "Use type='voice'|'chat'|'dashboard' when creating personas - template is auto-selected",
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // type="patterns" - Workflow patterns
+    // ─────────────────────────────────────────────────────────────────────────
+    if (type === "patterns") {
+        // Get specific pattern
+        if (args.pattern) {
+            const patternName = args.pattern;
+            const pattern = WORKFLOW_PATTERNS[patternName];
+            if (!pattern) {
+                return { error: `Pattern not found: ${args.pattern}` };
+            }
+            return pattern;
+        }
+        // List patterns
+        let patterns = Object.entries(WORKFLOW_PATTERNS);
+        if (args.persona_type) {
+            patterns = patterns.filter(([_, p]) => !p.personaType || p.personaType === args.persona_type);
+        }
+        return {
+            count: patterns.length,
+            patterns: patterns.map(([name, p]) => ({
+                name,
+                description: p.description,
+                use_case: p.useCase,
+                persona_type: p.personaType,
+            })),
+        };
     }
-    // List concepts
-    if (args.concepts) {
+    // ─────────────────────────────────────────────────────────────────────────
+    // type="widgets" - Widget reference
+    // ─────────────────────────────────────────────────────────────────────────
+    if (type === "widgets") {
+        const personaType = args.persona_type ?? "voice";
+        const widgets = getWidgetsForPersonaType(personaType);
+        return { type: personaType, widgets };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // type="concepts" - List all concepts
+    // ─────────────────────────────────────────────────────────────────────────
+    if (type === "concepts" || args.concepts) {
         return {
             concepts: PLATFORM_CONCEPTS,
             count: PLATFORM_CONCEPTS.length,
         };
     }
+    // ─────────────────────────────────────────────────────────────────────────
+    // questions=true - Qualifying questions
+    // ─────────────────────────────────────────────────────────────────────────
+    if (args.questions) {
+        let questions = QUALIFYING_QUESTIONS;
+        if (args.category) {
+            questions = getQualifyingQuestionsByCategory(args.category);
+        }
+        if (args.required_only) {
+            questions = getRequiredQualifyingQuestions();
+        }
+        return { questions, count: questions.length };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Get specific concept
+    // ─────────────────────────────────────────────────────────────────────────
+    if (args.concept) {
+        const concept = getConceptByTerm(args.concept);
+        if (!concept) {
+            return { error: `Concept not found: ${args.concept}` };
+        }
+        return concept;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
     // Get guidance
+    // ─────────────────────────────────────────────────────────────────────────
     if (args.guidance) {
         const topic = GUIDANCE_TOPICS[args.guidance];
         if (!topic) {
@@ -2342,7 +2540,128 @@ export function handleReference(args) {
         const result = validateWorkflowPrompt(args.validate_prompt);
         return result;
     }
-    return { error: "Specify concept, concepts=true, guidance, mistakes=true, checklist=true, execution=true, check_types, or validate_prompt" };
+    return {
+        error: "Specify type (envs|actions|templates|patterns|widgets|concepts), or use concept, guidance, questions, mistakes, checklist, execution, check_types, validate_prompt",
+        examples: [
+            'reference(type="envs")',
+            'reference(type="actions")',
+            'reference(type="actions", id="send_email")',
+            'reference(type="patterns")',
+            'reference(concept="HITL")',
+            'reference(guidance="categorizer-routing")',
+            'reference(questions=true)',
+        ],
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// DATA Handler (v2 alias for knowledge)
+// ═══════════════════════════════════════════════════════════════════════════
+export async function handleData(args, client, readFile) {
+    // Map v2 modes to knowledge modes
+    const mode = args.mode;
+    const knowledgeArgs = { ...args };
+    // Mode mapping
+    if (mode === "get" && args.file_id) {
+        knowledgeArgs.mode = "list"; // List with specific file context
+    }
+    else if (mode === "embedding") {
+        // Embedding operations
+        if (args.enabled !== undefined) {
+            knowledgeArgs.mode = "toggle";
+        }
+        else {
+            knowledgeArgs.mode = "status";
+        }
+    }
+    else if (mode === "sanitize") {
+        // Data sanitization - needs special handling
+        const personaId = args.persona_id;
+        const includeWorkflow = args.include_workflow;
+        const sanitizeExamples = args.sanitize_examples;
+        const persona = await client.getPersonaById(personaId);
+        if (!persona) {
+            return { error: `Persona not found: ${personaId}` };
+        }
+        // Create sanitization session
+        const session = new SanitizationSession();
+        // Detect and sanitize in proto_config
+        const protoConfig = persona.proto_config;
+        let sanitizedConfig = protoConfig;
+        if (protoConfig) {
+            // Apply pattern-based detection and sanitization
+            const clonedConfig = JSON.parse(JSON.stringify(protoConfig)); // Deep clone
+            // Recursively find and sanitize string values
+            const sanitizeObject = (obj) => {
+                for (const key of Object.keys(obj)) {
+                    const val = obj[key];
+                    if (typeof val === "string" && val.length > 0) {
+                        const detected = detectWithPatterns(val);
+                        for (const entity of detected) {
+                            const replacement = session.getOrCreateReplacement(entity.value, entity.type);
+                            obj[key] = obj[key].split(entity.value).join(replacement);
+                        }
+                        // Also apply user examples
+                        if (sanitizeExamples) {
+                            for (const example of sanitizeExamples) {
+                                if (obj[key].includes(example)) {
+                                    const replacement = session.getOrCreateReplacement(example, "unknown");
+                                    obj[key] = obj[key].split(example).join(replacement);
+                                }
+                            }
+                        }
+                    }
+                    else if (typeof val === "object" && val !== null) {
+                        sanitizeObject(val);
+                    }
+                }
+            };
+            sanitizeObject(clonedConfig);
+            sanitizedConfig = clonedConfig;
+        }
+        // Optionally sanitize workflow
+        let sanitizedWorkflow = persona.workflow_def;
+        if (includeWorkflow && sanitizedWorkflow) {
+            const clonedWorkflow = JSON.parse(JSON.stringify(sanitizedWorkflow));
+            const sanitizeWfObj = (obj) => {
+                for (const key of Object.keys(obj)) {
+                    const val = obj[key];
+                    if (typeof val === "string" && val.length > 0) {
+                        const detected = detectWithPatterns(val);
+                        for (const entity of detected) {
+                            const replacement = session.getOrCreateReplacement(entity.value, entity.type);
+                            obj[key] = obj[key].split(entity.value).join(replacement);
+                        }
+                    }
+                    else if (typeof val === "object" && val !== null) {
+                        sanitizeWfObj(val);
+                    }
+                }
+            };
+            sanitizeWfObj(clonedWorkflow);
+            sanitizedWorkflow = clonedWorkflow;
+        }
+        // Apply updates
+        await client.updateAiEmployee({
+            persona_id: personaId,
+            proto_config: sanitizedConfig ?? {},
+            workflow: includeWorkflow ? sanitizedWorkflow : undefined,
+        });
+        // Convert Map to array for JSON response
+        const mappingsMap = session.getMappings();
+        const mappingsArray = Array.from(mappingsMap.entries()).map(([original, replacement]) => ({
+            original,
+            replacement,
+        }));
+        return {
+            success: true,
+            persona_id: personaId,
+            entities_sanitized: mappingsMap.size,
+            mappings: mappingsArray,
+            workflow_sanitized: !!includeWorkflow,
+        };
+    }
+    // Default: delegate to knowledge handler
+    return handleKnowledge(knowledgeArgs, client, readFile);
 }
 // ═══════════════════════════════════════════════════════════════════════════
 // SYNC Handler

package/dist/mcp/server.js

@@ -51,7 +51,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, handleWorkflow, handleAction, handleTemplate, handleKnowledge, handleReference, } from "./handlers-consolidated.js";
+import { handleEnv, handlePersona, handleWorkflow, handleAction, handleData, handleTemplate, handleKnowledge, handleReference, } from "./handlers-consolidated.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // Autobuilder Prompt Generation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -4742,8 +4742,23 @@ const toolHandlers = {
         const fs = await import("fs/promises");
         return handleKnowledge(args, client, (path) => fs.readFile(path));
     },
+    // v2: data is an alias for knowledge with simplified interface
+    data: async (args) => {
+        const client = createClient(args.env);
+        const fs = await import("fs/promises");
+        return handleData(args, client, (path) => fs.readFile(path));
+    },
     reference: async (args) => {
-        return handleReference(args);
+        // v2: expanded reference handler with envs, actions, templates, patterns support
+        const client = createClient(args.env);
+        return handleReference(args, {
+            getEnvironments: () => getAvailableEnvironments().map(e => ({
+                name: e.name,
+                isDefault: e.name === getDefaultEnvName(),
+            })),
+            toolkit: { name: TOOLKIT_NAME, version: TOOLKIT_VERSION },
+            client,
+        });
     },
     // Note: 'sync' handler already exists above - keeping it for full functionality
     // Note: demo is handled via a consolidated adapter below

package/dist/mcp/tools-consolidated.js

@@ -465,75 +465,142 @@ Ask the user these questions, then put answers into ONE workflow() call.
             }, ["persona_id"]),
         },
         // ═══════════════════════════════════════════════════════════════════════
-        // 7. REFERENCE - Platform concepts, guidance, validation
+        // 7. REFERENCE - All reference info (envs, actions, templates, patterns, concepts, guidance)
         // ═══════════════════════════════════════════════════════════════════════
         {
             name: "reference",
-            description: `Get platform documentation and validation tools.
+            description: `All reference information: environments, actions, templates, patterns, concepts, guidance.
 
-**Concepts**:
-  reference(concept="HITL")
-  reference(concepts=true)  # List all
+**Environments**:
+  reference(type="envs")
+
+**Actions** (workflow building blocks):
+  reference(type="actions")                    # List all
+  reference(type="actions", query="email")     # Search
+  reference(type="actions", id="send_email")   # Get specific
+  reference(type="actions", suggest="IT helpdesk")  # Suggest for use case
+  reference(type="actions", categories=true)   # List categories
+
+**Templates & Patterns**:
+  reference(type="templates")                  # List persona templates
+  reference(type="patterns")                   # List workflow patterns
+  reference(type="patterns", pattern="intent-routing")  # Get specific
 
-**Guidance**:
+**Widgets**:
+  reference(type="widgets", persona_type="voice")
+
+**Concepts & Guidance**:
+  reference(concept="HITL")
   reference(guidance="categorizer-routing")
-  reference(guidance="type-compatibility")
-  reference(guidance="workflow-structure")  # Summarizer → Extractor → JSON mapper pattern
-  reference(guidance="search-node-timing")  # When to use search nodes, early vs late
-  reference(guidance="node-execution-conditions")  # When nodes execute or are skipped
-  reference(guidance="array-preservation")  # How to preserve arrays through extraction → mapping → downstream
-  reference(guidance="search-filtering")  # Semantic query + structured filters best practices
-  reference(guidance="fallback-response-inputs")  # Fallback should use full conversation + context
-  reference(guidance="separate-vs-merged-inputs")  # Keep separate named_inputs for multi-source data
-  reference(guidance="folder-path-filtering")  # Folder path filtering with semantic query
-  reference(guidance="automated-extraction-json")  # Automating extraction → JSON mapper pattern
-  reference(guidance="when-filters-necessary")  # When filters are required vs optional
-  reference(guidance="filter-query-guidance")  # When to use filters vs queries vs both
-  reference(guidance="workflow-structure")
-  reference(guidance="search-node-timing")
-  reference(guidance="node-execution-conditions")
+  reference(questions=true)  # Qualifying questions
 
 **Debugging**:
   reference(mistakes=true)
   reference(checklist=true)
-  reference(execution=true)  # Workflow execution model
+  reference(execution=true)
 
 **Validation**:
-  reference(check_types={source: "CHAT_CONVERSATION", target: "TEXT_WITH_SOURCES"})
-  reference(validate_prompt="Create a bot...")`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    // Concepts
-                    concept: { type: "string", description: "Get definition of platform term" },
-                    concepts: { type: "boolean", description: "List all platform concepts" },
-                    // Guidance
-                    guidance: {
-                        type: "string",
-                        enum: [
-                            "categorizer-routing", "type-compatibility", "named-inputs",
-                            "hitl-patterns", "multi-source-search", "voice-tool-calling",
-                            "guardrails", "output-mapping", "workflow-execution", "conversation-vs-query"
-                        ],
-                        description: "Get guidance on topic"
-                    },
-                    // Debugging
-                    mistakes: { type: "boolean", description: "Get common mistakes list" },
-                    checklist: { type: "boolean", description: "Get debug checklist" },
-                    execution: { type: "boolean", description: "Get workflow execution model" },
-                    // Validation
-                    check_types: {
-                        type: "object",
-                        properties: {
-                            source: { type: "string", description: "Source output type" },
-                            target: { type: "string", description: "Target input type" },
-                        },
-                        description: "Check type compatibility"
+  reference(check_types={source: "CHAT_CONVERSATION", target: "TEXT"})`,
+            inputSchema: withEnv({
+                // Type selector (v2)
+                type: {
+                    type: "string",
+                    enum: ["envs", "actions", "templates", "patterns", "widgets", "concepts"],
+                    description: "What type of reference information"
+                },
+                // Actions
+                id: { type: "string", description: "Action ID for details" },
+                query: { type: "string", description: "Search actions by name" },
+                suggest: { type: "string", description: "Suggest actions for use case" },
+                categories: { type: "boolean", description: "List action categories" },
+                category: { type: "string", description: "Filter by category" },
+                include_docs: { type: "boolean", description: "Include full documentation" },
+                limit: { type: "number", description: "Max results" },
+                // Patterns
+                pattern: {
+                    type: "string",
+                    enum: ["simple-kb-search", "intent-routing", "multi-source-search", "tool-calling", "hitl-approval", "document-processing", "guardrails-pattern"],
+                    description: "Get specific pattern"
+                },
+                // Widgets
+                persona_type: { type: "string", enum: ["voice", "chat", "dashboard"], description: "Persona type for widgets" },
+                // Concepts
+                concept: { type: "string", description: "Get definition of platform term" },
+                concepts: { type: "boolean", description: "List all platform concepts" },
+                // Questions
+                questions: { type: "boolean", description: "Get qualifying questions" },
+                required_only: { type: "boolean", description: "Only required questions" },
+                // Guidance
+                guidance: {
+                    type: "string",
+                    enum: [
+                        "categorizer-routing", "type-compatibility", "named-inputs",
+                        "hitl-patterns", "multi-source-search", "voice-tool-calling",
+                        "guardrails", "output-mapping", "workflow-execution", "conversation-vs-query"
+                    ],
+                    description: "Get guidance on topic"
+                },
+                // Debugging
+                mistakes: { type: "boolean", description: "Get common mistakes list" },
+                checklist: { type: "boolean", description: "Get debug checklist" },
+                execution: { type: "boolean", description: "Get workflow execution model" },
+                // Validation
+                check_types: {
+                    type: "object",
+                    properties: {
+                        source: { type: "string", description: "Source output type" },
+                        target: { type: "string", description: "Target input type" },
                     },
-                    validate_prompt: { type: "string", description: "Validate workflow prompt" },
+                    description: "Check type compatibility"
                 },
-                required: [],
-            },
+                validate_prompt: { type: "string", description: "Validate workflow prompt" },
+            }),
+        },
+        // ═══════════════════════════════════════════════════════════════════════
+        // 7b. DATA - Manage persona data (v2 simplified interface for knowledge)
+        // ═══════════════════════════════════════════════════════════════════════
+        {
+            name: "data",
+            description: `Manage AI Employee data (files).
+
+**List files**:
+  data(persona_id="abc")
+  data(persona_id="abc", limit=50)
+
+**Upload file** (file provided via conversation context):
+  data(persona_id="abc", mode="upload")
+
+**Delete file**:
+  data(persona_id="abc", mode="delete", file_id="file-123")
+
+**Sanitize data**:
+  data(persona_id="abc", mode="sanitize")
+  data(persona_id="abc", mode="sanitize", include_workflow=true)
+
+**Embedding**:
+  data(persona_id="abc", mode="embedding")         # Get status
+  data(persona_id="abc", mode="embedding", enabled=true)  # Toggle`,
+            inputSchema: withEnv({
+                persona_id: { type: "string", description: "AI Employee ID (required)" },
+                mode: {
+                    type: "string",
+                    enum: ["list", "upload", "delete", "sanitize", "embedding"],
+                    description: "Operation (default: list)"
+                },
+                // Get/Delete specific file
+                file_id: { type: "string", description: "File ID for delete" },
+                // List options
+                limit: { type: "number", description: "Max results (default: 50)" },
+                page: { type: "number", description: "Page number (default: 1)" },
+                // Upload
+                file: { type: "string", description: "File path for upload" },
+                tags: { type: "string", description: "Tags for uploaded file" },
+                // Sanitize options
+                include_workflow: { type: "boolean", description: "Also sanitize workflow config" },
+                sanitize_examples: { type: "array", items: { type: "string" }, description: "Additional sensitive items" },
+                // Embedding toggle
+                enabled: { type: "boolean", description: "Enable/disable embedding" },
+            }, ["persona_id"]),
         },
         // ═══════════════════════════════════════════════════════════════════════
         // 8. SYNC - Environment synchronization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "1.7.1",
+  "version": "2026.1.17",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",