@ema.co/mcp-toolkit 2026.1.26 → 2026.1.27-10

package/dist/mcp/handlers/persona/analyze.js

@@ -1,275 +0,0 @@
-/**
- * Persona ANALYZE mode handler
- *
- * Analyzes a persona for issues in workflow, config, and data.
- * Returns decompiled WorkflowSpec + schema for LLM-native modifications.
- *
- * ARCHITECTURE NOTE: MCP provides context, Agent proposes fixes.
- * The `fix` parameter is DEPRECATED - agent should build workflow_spec fixes.
- */
-import { resolvePersona } from "../utils.js";
-import { detectWorkflowIssues, suggestWorkflowFixes } from "../../../sdk/knowledge.js";
-import { autoFixWorkflow } from "../../../sdk/workflow-fixer.js";
-import { decompileWorkflow, summarizeSpec, WORKFLOW_SCHEMA_FOR_LLM } from "../../../sdk/workflow-transformer.js";
-import { hasFallback, GUIDANCE_RULES } from "../../../sdk/guidance.js";
-/**
- * Handle persona(mode="analyze") - analyze persona for issues
- *
- * @param args.id - Persona ID or name (required)
- * @param args.fix - DEPRECATED: Returns preview instead of deploying. Agent should build workflow_spec.
- * @param args.include - Aspects to analyze (workflow, config, data)
- */
-export async function handleAnalyze(args, client) {
-    const idOrName = (args.id ?? args.identifier);
-    if (!idOrName) {
-        return { status: "error", error: "id required for analyze mode" };
-    }
-    const persona = await resolvePersona(client, idOrName);
-    if (!persona) {
-        return { status: "error", error: `Persona not found: ${idOrName}` };
-    }
-    const fix = args.fix;
-    const includeAspects = args.include ?? ["workflow", "config", "data"];
-    // Collect issues across all aspects
-    const issues = [];
-    const fixesApplied = [];
-    // ── Analyze Workflow ──
-    if (includeAspects.includes("workflow") && persona.workflow_def) {
-        const workflowDef = persona.workflow_def;
-        // Use the sophisticated workflow issue detection
-        const workflowIssues = detectWorkflowIssues(workflowDef);
-        const suggestedFixes = suggestWorkflowFixes(workflowIssues);
-        // Map workflow issues to our uniform format
-        for (const issue of workflowIssues) {
-            const wfIssue = issue;
-            const severityMap = {
-                "critical": "critical",
-                "warning": "warning",
-                "info": "info",
-            };
-            const matchingFix = suggestedFixes.find(f => f.issue_type === wfIssue.type);
-            issues.push({
-                id: `wf-${wfIssue.type}-${wfIssue.node || "global"}`,
-                severity: severityMap[wfIssue.severity] || "warning",
-                category: "workflow",
-                title: `${wfIssue.type}${wfIssue.node ? `: ${wfIssue.node}` : ""}`,
-                description: wfIssue.reason,
-                auto_fixable: !!matchingFix,
-                fix_description: matchingFix?.description,
-            });
-        }
-    }
-    // ── Analyze Config ──
-    if (includeAspects.includes("config") && persona.proto_config) {
-        const protoConfig = persona.proto_config;
-        const widgets = (protoConfig.widgets || []);
-        // Check for malformed widgets
-        for (const widget of widgets) {
-            const widgetName = widget.name;
-            if (!widgetName || widgetName.trim() === "") {
-                issues.push({
-                    id: `widget-empty-name`,
-                    severity: "warning",
-                    category: "config",
-                    title: "Widget with empty name",
-                    description: "A widget has an empty or missing name field",
-                    auto_fixable: false,
-                });
-            }
-        }
-        // Check for generic description
-        const description = persona.description;
-        if (!description || description.length < 20 || description.includes("template")) {
-            issues.push({
-                id: `generic-description`,
-                severity: "info",
-                category: "metadata",
-                title: "Generic or missing description",
-                description: "Persona description appears to be a template default or too short",
-                auto_fixable: false,
-            });
-        }
-    }
-    // ── Analyze Data Sources ──
-    if (includeAspects.includes("data")) {
-        try {
-            const dataSources = await client.listDataSourceFiles(persona.id);
-            const files = dataSources.files || [];
-            // Check data source health
-            if (files.length === 0) {
-                issues.push({
-                    id: `no-data-sources`,
-                    severity: "info",
-                    category: "data",
-                    title: "No data sources uploaded",
-                    description: "Persona has no knowledge files - Knowledge Agent won't have context to search",
-                    auto_fixable: false,
-                });
-            }
-            // Check for failed uploads
-            for (const file of files) {
-                if (file.status === "failed" || file.status === "error") {
-                    issues.push({
-                        id: `failed-upload-${file.id}`,
-                        severity: "warning",
-                        category: "data",
-                        title: `Failed upload: ${file.filename}`,
-                        description: `File upload failed with status: ${file.status}`,
-                        auto_fixable: false,
-                    });
-                }
-            }
-        }
-        catch {
-            // Data source listing may fail for some persona types
-        }
-    }
-    // ── Handle fix parameter (DEPRECATED) ──
-    // DEPRECATED: fix=true no longer auto-deploys. Returns preview for agent to review.
-    // Architecture: MCP provides context, Agent proposes and builds fixes.
-    let fixPreview;
-    if (fix && persona.workflow_def) {
-        // Log deprecation warning
-        console.warn("[DEPRECATED] fix=true is deprecated. MCP should not auto-fix - agent builds workflow_spec.\n" +
-            "See CLAUDE.md 'MCP vs Agent: Separation of Duties'.\n" +
-            "Returning preview instead of deploying.");
-        const workflowDef = persona.workflow_def;
-        const fixResult = autoFixWorkflow(workflowDef);
-        // Record what would be fixed
-        for (const applied of fixResult.fixesApplied) {
-            fixesApplied.push({
-                issue_id: applied.issueType,
-                action: applied.description,
-                result: "preview", // Changed from success/failed to preview
-            });
-        }
-        // Return preview instead of deploying
-        if (fixResult.fixesApplied.length > 0 && fixResult.success) {
-            // Determine persona type for decompile
-            const protoConfig = persona.proto_config;
-            const projectSettings = protoConfig?.projectSettings;
-            const personaType = projectSettings?.projectType === 5 ? "voice" : "chat";
-            try {
-                fixPreview = {
-                    proposed_spec: decompileWorkflow(fixResult.workflowDef, personaType),
-                    changes: fixResult.fixesApplied.map(f => f.description),
-                };
-            }
-            catch {
-                // Decompile failed, just note the changes
-                fixPreview = {
-                    changes: fixResult.fixesApplied.map(f => f.description),
-                };
-            }
-        }
-    }
-    // ── Build Response ──
-    const analysisSummary = {
-        total_issues: issues.length,
-        by_severity: {
-            critical: issues.filter(i => i.severity === "critical").length,
-            warning: issues.filter(i => i.severity === "warning").length,
-            info: issues.filter(i => i.severity === "info").length,
-        },
-        by_category: {
-            workflow: issues.filter(i => i.category === "workflow").length,
-            config: issues.filter(i => i.category === "config").length,
-            data: issues.filter(i => i.category === "data").length,
-            metadata: issues.filter(i => i.category === "metadata").length,
-        },
-    };
-    const status = analysisSummary.by_severity.critical > 0
-        ? "critical"
-        : analysisSummary.total_issues > 0
-            ? "issues_found"
-            : "healthy";
-    // ── Decompile Workflow for LLM-native modifications ──
-    let workflowSpec;
-    let workflowSummary;
-    if (persona.workflow_def) {
-        const workflowDef = persona.workflow_def;
-        // Determine persona type
-        const protoConfig = persona.proto_config;
-        const projectSettings = protoConfig?.projectSettings;
-        const personaType = projectSettings?.projectType === 5 ? "voice" : "chat";
-        try {
-            workflowSpec = decompileWorkflow(workflowDef, personaType);
-            workflowSummary = summarizeSpec(workflowSpec);
-        }
-        catch (e) {
-            // Decompile failed - include error in response
-            workflowSummary = `Decompile failed: ${e instanceof Error ? e.message : String(e)}`;
-        }
-    }
-    const result = {
-        status,
-        persona: { id: persona.id, name: persona.name },
-        summary: analysisSummary,
-        issues,
-    };
-    // Include workflow_spec for LLM-native modifications (unless include_spec=false)
-    const includeSpec = args.include_spec !== false;
-    if (includeSpec && workflowSpec) {
-        result.workflow_spec = workflowSpec;
-        result.workflow_summary = workflowSummary;
-        result.schema = WORKFLOW_SCHEMA_FOR_LLM;
-        result.modification_hint =
-            "To modify this workflow:\n" +
-                "1. Analyze the workflow_spec above\n" +
-                "2. Modify the spec (add/remove/update nodes, change inputs/outputs)\n" +
-                "3. Call persona(id=\"" + persona.id + "\", update={workflow_spec: <modified_spec>})\n" +
-                "\n" +
-                "The SDK will compile your WorkflowSpec to workflow_def and deploy it.";
-        // Add workflow-specific guidance based on state
-        const workflowGuidance = [];
-        // Check for Fallback in categorizers
-        if (!hasFallback(workflowSpec)) {
-            const fallbackRule = GUIDANCE_RULES.find(r => r.id === "categorizer-fallback");
-            if (fallbackRule) {
-                workflowGuidance.push(`⚠️ ${fallbackRule.title}: ${fallbackRule.do}`);
-            }
-        }
-        // Add general workflow tips
-        const previewRule = GUIDANCE_RULES.find(r => r.id === "preview-before-deploy");
-        if (previewRule) {
-            workflowGuidance.push(`💡 ${previewRule.title}: ${previewRule.do}`);
-        }
-        if (workflowGuidance.length > 0) {
-            result.workflow_guidance = workflowGuidance;
-        }
-    }
-    if (fix) {
-        // DEPRECATED: Return preview, not deployment result
-        result.deprecation_warning =
-            "fix=true is DEPRECATED. MCP should not auto-fix workflows.\n" +
-                "The agent should review issues, ask the user which to fix, " +
-                "build the workflow_spec, and call persona(update={workflow_spec: ...})";
-        if (fixPreview) {
-            result.fix_preview = {
-                status: "preview_only",
-                proposed_changes: fixPreview.changes,
-                proposed_spec: fixPreview.proposed_spec,
-                deploy_command: `persona(id="${persona.id}", update={workflow_spec: <proposed_spec above>})`,
-            };
-        }
-        else {
-            result.fix_preview = {
-                status: "no_fixes_available",
-                message: "No auto-fixable issues found. Review issues above and build fixes manually.",
-            };
-        }
-    }
-    else {
-        // Guide agent to the correct flow (no mention of fix=true)
-        result.next_steps = {
-            has_issues: issues.length > 0,
-            agent_action: issues.length > 0
-                ? "Review issues above. Ask user which to fix. Build workflow_spec with fixes. Deploy via update."
-                : "No issues found. Persona is healthy.",
-            manual_actions: issues
-                .filter(i => !i.auto_fixable)
-                .map(i => `${i.title}: ${i.description}`),
-        };
-    }
-    return result;
-}

package/dist/mcp/handlers/persona/compare.js

@@ -1,32 +0,0 @@
-/**
- * Persona COMPARE mode handler
- *
- * Compares two personas, optionally across environments.
- */
-import { resolvePersona, comparePersonas } from "../utils.js";
-/**
- * Handle persona(mode="compare") - compare two personas
- *
- * @param args.id - First persona ID or name (required)
- * @param args.compare_to - Second persona ID or name (required)
- * @param args.compare_env - Optional environment for second persona
- * @param createClientForEnv - Factory to create client for different env
- */
-export async function handleCompare(args, client, createClientForEnv) {
-    const idOrName = (args.id ?? args.identifier);
-    if (!idOrName || !args.compare_to) {
-        return { error: "id and compare_to required for compare mode" };
-    }
-    const persona1 = await resolvePersona(client, idOrName);
-    const compareEnv = args.compare_env;
-    const client2 = compareEnv && createClientForEnv ? createClientForEnv(compareEnv) : client;
-    const persona2 = await resolvePersona(client2, args.compare_to);
-    if (!persona1 || !persona2) {
-        return { error: "One or both personas not found" };
-    }
-    return {
-        persona_1: { id: persona1.id, name: persona1.name },
-        persona_2: { id: persona2.id, name: persona2.name, env: compareEnv },
-        differences: comparePersonas(persona1, persona2),
-    };
-}

package/dist/mcp/handlers/workflow/compile.js

@@ -1,39 +0,0 @@
-/**
- * Workflow Compile Handler
- *
- * Compiles a WorkflowSpec (simplified nodes array) into a full workflow_def.
- */
-import { compileWorkflow } from "../../../sdk/workflow-generator.js";
-import { ensureActionRegistry } from "../../../sdk/action-registry.js";
-/**
- * Handle workflow compile mode
- *
- * Accepts nodes in simplified format and compiles to workflow_def.
- * Uses the same pattern as the monolith - passes through to compileWorkflow.
- */
-export async function handleWorkflowCompile(args, client) {
-    const nodes = args.nodes;
-    const resultMappings = args.result_mappings;
-    if (!nodes) {
-        return { error: "nodes required for compile mode" };
-    }
-    // Load action registry for API-driven action versions/namespaces
-    const compileRegistry = await ensureActionRegistry(client);
-    // Build spec - use any to allow flexible node format from API
-    // compileWorkflow will validate and transform as needed
-    const spec = {
-        name: args.name || "Compiled Workflow",
-        description: args.description || "Generated workflow",
-        personaType: args.type || "chat",
-        nodes: nodes,
-        resultMappings: resultMappings || [],
-    };
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const compiled = compileWorkflow(spec, { registry: compileRegistry });
-    return {
-        mode: "compile",
-        workflow_def: compiled.workflow_def,
-        proto_config: compiled.proto_config,
-        registry_loaded: compileRegistry.isLoaded(),
-    };
-}