@ema.co/mcp-toolkit 2026.1.25 → 2026.1.26-4

package/docs/mcp-tools-guide.md

@@ -28,15 +28,23 @@ Some clients show a **prefixed name** (for example Cursor: `mcp_ema_persona`). A
 | `reference` | Envs, actions, templates, patterns, concepts, guidance | No (flag-based) |
 | `sync` | Sync across environments | **YES** |
 
+### `workflow` tool (get/deploy only)
+
+| Mode | Purpose |
+|------|---------|
+| `get` | Returns workflow_def, schema, examples for LLM |
+| `deploy` | Deploys LLM-generated workflow_def |
+
+**LLM does all thinking** (analyze, compare, generate). MCP only provides data and executes.
+
 ### Deprecated tools (still work, show warnings)
 
 | Tool | Status | Use Instead |
 |------|--------|-------------|
-| `workflow` | Deprecated | `persona` |
 | `knowledge` | Deprecated | `data` |
 | `demo` | Deprecated | `data` + `persona` |
 
-> **Tip**: For new code, use `persona`, `data`, `sync`. Deprecated tools route internally to new ones.
+> **Tip**: For new code, use `persona`, `data`, `workflow`, `sync`.
 
 ## ⚠️ THE KEY INSIGHT: ONE CALL
 
@@ -102,21 +110,19 @@ persona(
 persona(mode="get", id="abc-123")
 
 // Modify config in ONE call
-persona(mode="update", id="abc-123", proto_config={widgets: [{name: "conversationSettings", conversationSettings: {...}}]})
+persona(mode="update", id="abc-123", config={widgets: [{name: "conversationSettings", conversationSettings: {...}}]})
 ```
 
-### Analyze/Review an AI Employee
+### Get workflow data (for LLM to analyze/modify)
 
 ```typescript
-persona(mode="get", id="abc-123")                         // Get persona
-persona(mode="get", id="abc-123", include_workflow=true)  // Include full workflow
+workflow(mode="get", persona_id="abc-123")  // Returns workflow_def, schema, examples
 ```
 
-### Optimize (auto-fix issues)
+The LLM then analyzes/modifies the workflow and deploys:
 
 ```typescript
-persona(mode="update", id="abc-123", optimize=true)                  // Preview fixes
-persona(mode="update", id="abc-123", optimize=true, preview=false)   // Apply fixes
+workflow(mode="deploy", persona_id="abc-123", workflow_def={...})  // Deploy LLM's result
 ```
 
 ### Upload / manage knowledge base documents
@@ -212,7 +218,7 @@ knowledge(persona_id="target", mode="dashboard_clone", source_persona_id="source
 persona(mode="version_create", id="My Bot", message="Before adding HITL")
 
 // Make changes...
-persona(mode="update", id="abc", proto_config={...})
+persona(mode="update", id="abc", config={...})
 
 // If something breaks - restore
 persona(mode="version_list", id="My Bot")
@@ -241,7 +247,7 @@ persona(mode="create", from="Voice AI Starter", name="My Bot", input="...", prev
 
 **Update config:**
 ```typescript
-persona(mode="update", id="abc", proto_config={widgets: [{...}]})
+persona(mode="update", id="abc", config={widgets: [{...}]})
 ```
 
 **Clone:**
@@ -249,34 +255,12 @@ persona(mode="update", id="abc", proto_config={widgets: [{...}]})
 persona(mode="clone", from="source-id", name="My Copy", include_data=true)
 ```
 
-**Compare:**
-```typescript
-persona(mode="compare", id="abc", compare_to="def")
-```
-
 **Sanitize (two-step process):**
 ```typescript
 persona(id="abc", sanitize=true)  // Step 1: Preview - identify PII
 persona(id="abc", sanitize=true, sanitize_examples=["Acme"], preview=false)  // Step 2: Apply
 ```
 
-**Analyze (recommended):**
-```typescript
-persona(mode="analyze", id="abc")                           // All aspects
-persona(mode="analyze", id="abc", include=["workflow"])     // Workflow only
-persona(mode="analyze", id="abc", include=["workflow", "config", "data"])
-```
-
-**Analyze + auto-fix:**
-```typescript
-persona(mode="analyze", id="abc", fix=true)
-```
-
-**Legacy (deprecated, use mode="analyze" instead):**
-```typescript
-persona(id="abc", optimize=true)    // Routes to workflow tool internally
-```
-
 **Intent (qualification for complex requests):**
 ```typescript
 // GREENFIELD: New persona creation
@@ -299,7 +283,7 @@ Returns:
 - `status: "needs_qualification"` → `questions` to answer before proceeding  
 - `status: "needs_llm"` → `llm_prompt` to send to LLM for IntentSpec generation
 
-For brownfield, combine with `mode="analyze"` to get current state, then use intent to qualify the change.
+For brownfield, use `workflow(mode="get")` to fetch current state, then use intent to qualify the change.
 
 **Templates:**
 ```typescript
@@ -456,19 +440,27 @@ Start with:
 - `ema://catalog/templates` (persona templates - dynamic)
 - `ema://rules/anti-patterns` (what NOT to do)
 
-## Auto-Fix Capabilities
+## Workflow Generation (LLM Does the Work)
 
-The `persona(mode="update", id="...", optimize=true)` can automatically fix common issues:
+**MCP provides data and schema. LLM generates workflow_def.**
+
+```typescript
+// 1. Get current workflow + schema
+result = workflow(mode="get", persona_id="abc")
+// Returns: workflow_def, generation_schema, example_workflow, requirements
+
+// 2. LLM analyzes and generates new workflow_def
+// (LLM uses schema and examples to build valid workflow)
+
+// 3. Deploy LLM's result
+workflow(mode="deploy", persona_id="abc", workflow_def={...})
+```
 
-| Issue | Severity | Auto-Fix? | Action |
-|-------|----------|-----------|--------|
-| `orphan` | warning | ✅ | Removes unreachable nodes |
-| `dead_end` | critical | ✅ | Adds results mapping |
-| `missing_workflow_output` | critical | ✅ | Adds results mapping |
-| `wrong_input_source` (email_to) | warning | ✅ | Adds entity_extraction |
-| `missing_fallback` | critical | ✅ | Adds Fallback category |
-| `type_mismatch` | critical | ✅ | Rewires to compatible source |
-| `cycle` | critical | ❌ | Requires manual restructuring |
+**Common issues to check when generating:**
+- Missing `WORKFLOW_OUTPUT` in results
+- Missing Fallback category in categorizers
+- Orphan nodes not connected to output
+- Type mismatches between connected nodes
 
 ## HITL (Human-in-the-Loop) Policy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "2026.1.25",
+  "version": "2026.1.26-4",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",
@@ -52,18 +52,24 @@
     "lint:unused": "knip",
     "precommit": "npm run typecheck && npm run test",
     "prepare": "husky",
-    "prepublishOnly": "npm run build && npm run test",
+    "check:publish": "tsx scripts/check-publish-content.ts",
+    "prepublishOnly": "npm run build && npm run test && npm run check:publish",
     "generate:types": "tsx scripts/generate-types.ts",
     "generate:api-client": "npx @hey-api/openapi-ts -i src/sdk/generated/openapi.json -o src/sdk/generated/api-client -c @hey-api/client-fetch",
     "generate:protos": "buf generate ../ema-repos/protos --template buf.gen.yaml",
     "generate:proto-fields": "tsx scripts/generate-proto-fields.ts",
     "generate:action-schema": "tsx scripts/generate-action-schema.ts",
-    "generate:all": "npm run generate:protos && npm run generate:api-client",
+    "generate:deprecated-actions": "tsx scripts/generate-deprecated-actions.ts",
+    "generate:skill": "tsx scripts/generate-skill.ts",
+    "generate:skill:check": "tsx scripts/generate-skill.ts --check",
+    "generate:templates": "tsx scripts/generate-templates.ts",
+    "generate:templates:check": "tsx scripts/generate-templates.ts --check",
+    "generate:all": "npm run generate:protos && npm run generate:api-client && npm run generate:templates && npm run generate:skill",
     "check:contracts": "tsx scripts/check-api-contracts.ts",
     "check:schema-sync": "tsx scripts/check-schema-handler-sync.ts",
     "check:prompt-refs": "tsx scripts/check-prompt-refs.ts",
     "check:action-aliases": "tsx scripts/check-action-aliases.ts",
-    "check:all": "npm run check:contracts && npm run check:schema-sync && npm run check:prompt-refs && npm run check:action-aliases",
+    "check:all": "npm run check:contracts && npm run check:schema-sync && npm run check:prompt-refs && npm run check:action-aliases && npm run generate:skill:check",
     "release:check": "tsx scripts/check-release-need.ts"
   },
   "repository": {

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),
-    };
-}