@ema.co/mcp-toolkit 2026.1.17 → 2026.1.24

package/README.md

@@ -7,7 +7,7 @@ MCP (Model Context Protocol) server for managing Ema AI Employees. Works with Cu
 ### Option 1: npx (Recommended)
 
 ```bash
-npx @ema.co/mcp-toolkit
+npx -y @ema.co/mcp-toolkit@latest
 ```
 
 ### Option 2: Global Install
@@ -63,7 +63,7 @@ Then reload: `source ~/.zshrc`
   "mcpServers": {
     "ema": {
       "command": "npx",
-      "args": ["@ema.co/mcp-toolkit"],
+      "args": ["-y", "@ema.co/mcp-toolkit@latest"],
       "env": {
         "EMA_ENV_NAME": "demo",
         "EMA_PROD_BEARER_TOKEN": "${env:EMA_PROD_BEARER_TOKEN}",
@@ -77,6 +77,8 @@ Then reload: `source ~/.zshrc`
 ```
 
 > **Important**: 
+> - Use `@latest` to always get the newest version (npx caches aggressively without it)
+> - The `-y` flag auto-confirms the npx install prompt
 > - Use `${env:VAR_NAME}` syntax to reference shell environment variables
 > - After changing mcp.json, restart the MCP server: `Cmd+Shift+P` → "MCP: Restart Server"
 > - After changing ~/.zshrc, reload it AND restart Cursor for changes to take effect
@@ -88,7 +90,7 @@ Then reload: `source ~/.zshrc`
   "mcpServers": {
     "ema": {
       "command": "npx",
-      "args": ["@ema.co/mcp-toolkit"],
+      "args": ["-y", "@ema.co/mcp-toolkit@latest"],
       "env": {
         "EMA_ENV_NAME": "demo",
         "EMA_DEMO_BEARER_TOKEN": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
@@ -202,46 +204,71 @@ environments:
 
 | Tool | Purpose |
 |------|---------|
-| `env` | List available environments |
-| `persona` | AI Employee management (get/list/create/clone/sanitize/compare) |
-| `workflow` | Generate/extend/optimize/analyze workflows |
-| `action` | Agent lookup, docs, and recommendations |
-| `template` | Patterns, widgets, qualifying questions |
-| `knowledge` | Data sources + embedding + dashboard data (upload/list/dashboard_rows/dashboard_clone) |
-| `reference` | Concepts, guidance, validation, common mistakes |
+| `persona` | **Primary**: AI Employee management (create/clone/modify/analyze/sanitize/optimize) |
+| `data` | **v2**: Simplified data management (list/upload/delete/sanitize/embedding) |
+| `reference` | **v2**: All reference info (envs, actions, templates, patterns, concepts, guidance) |
 | `sync` | Sync across environments |
+| `knowledge` | Data sources (legacy, use `data`) |
+| `action` | Agent lookup (legacy, use `reference(type="actions")`) |
+| `template` | Patterns (legacy, use `reference`) |
+| `env` | Environments (legacy, use `reference(type="envs")`) |
 | `demo` | Demo/RAG document utilities |
 
 ### Common Workflows
 
-**Create new AI Employee (greenfield):**
+**Create new AI Employee:**
 ```typescript
-workflow(input="IT helpdesk with KB search", type="chat")
-// Preview by default, use preview=false to deploy
+persona(input="IT helpdesk with KB search", type="chat", name="IT Support", preview=false)
 ```
 
-**Extend existing AI Employee (brownfield):**
+**Modify existing AI Employee:**
 ```typescript
-// Combine multiple changes in one command!
-workflow(mode="extend", persona_id="abc-123", input="add caller_type categorizer, add HITL before email, add compliance intent")
-// Preview by default, use preview=false to deploy
+persona(id="abc-123", input="add HITL before email, add compliance intent", preview=false)
 ```
 
 **Fix issues automatically:**
 ```typescript
-workflow(mode="optimize", persona_id="abc-123")
-// Preview by default, use preview=false to apply fixes
+persona(id="abc-123", optimize=true, preview=false)
+```
+
+**Get reference info:**
+```typescript
+reference(type="envs")                          // List environments
+reference(type="actions", id="send_email")      // Get action details
+reference(type="patterns", pattern="intent-routing")  // Get pattern
 ```
 
 ## Dynamic Resources
 
-| Resource | Source |
-|----------|--------|
-| `ema://catalog/agents` | Live from API |
-| `ema://catalog/templates` | Live from API |
+| Resource | Purpose |
+|----------|---------|
+| `ema://catalog/agents` | Live action catalog from API |
+| `ema://catalog/templates` | Persona templates from API |
 | `ema://catalog/patterns` | Workflow patterns |
-| `ema://rules/anti-patterns` | Validation rules |
-| `ema://rules/mcp-usage` | MCP usage guide for agents |
+| `ema://docs/usage-guide` | Complete usage guide (generated) |
+| `ema://guidance/rules` | Structured rules as JSON |
+| `ema://guidance/cursor-rule` | Export as Cursor .mdc rule |
+| `ema://guidance/server-instructions` | Server instructions text |
+
+---
+
+## Self-Contained Guidance
+
+The MCP is fully self-contained—no external configuration files needed.
+
+**How it works:**
+- Server instructions are injected on MCP init (system prompt)
+- Tools include usage tips in their descriptions
+- Responses include `_tip` and `_next_step` fields with contextual guidance
+- `env()` returns a getting_started guide with workflow patterns
+- `persona(..., analyze=true)` includes workflow_guidance with state-specific tips
+
+**For other services:**
+- Read `ema://guidance/rules` (JSON) for programmatic consumption
+- Read `ema://docs/usage-guide` (markdown) for documentation
+- Read `ema://guidance/cursor-rule` (.mdc) for IDE integration
+
+All guidance flows from a single source (`src/sdk/guidance.ts`).
 
 ---
 

package/dist/mcp/handlers/action/index.js

@@ -0,0 +1,148 @@
+/**
+ * Action Handler
+ *
+ * Provides action/agent lookup, filtering, and documentation.
+ */
+import { AGENT_CATALOG, getAgentByName, suggestAgentsForUseCase, } from "../../../sdk/knowledge.js";
+// Deprecated param mappings for backwards compatibility
+const DEPRECATED_PARAMS = {
+    identifier: { newName: "id", message: "'identifier' is deprecated, use 'id' instead (will be removed in v2.0.0)" },
+};
+function checkDeprecatedParams(args) {
+    const warnings = [];
+    for (const [oldName, info] of Object.entries(DEPRECATED_PARAMS)) {
+        if (args[oldName] !== undefined) {
+            warnings.push(info.message);
+        }
+    }
+    return warnings;
+}
+/**
+ * Handle action tool requests - list, get, filter, and search actions
+ */
+export async function handleAction(args, client) {
+    // Check for deprecated params and log warnings
+    const deprecationWarnings = checkDeprecatedParams(args);
+    for (const warning of deprecationWarnings) {
+        console.warn(`[action] Deprecation: ${warning}`);
+    }
+    const id = args.id;
+    const identifier = args.identifier; // deprecated alias for 'id'
+    const idOrName = id ?? identifier;
+    // 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 (idOrName) {
+        // Try API first
+        try {
+            const actions = await client.listActions();
+            const action = actions.find(a => a.id === idOrName ||
+                a.name === idOrName ||
+                a.name?.toLowerCase() === idOrName.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(idOrName);
+                if (doc) {
+                    result.documentation = doc;
+                    result.source = action ? "api+docs" : "docs";
+                }
+            }
+            if (Object.keys(result).length === 0) {
+                return { error: `Action not found: ${idOrName}` };
+            }
+            return result;
+        }
+        catch {
+            // Fallback to docs only
+            const doc = getAgentByName(idOrName);
+            if (doc) {
+                return { ...doc, source: "docs" };
+            }
+            return { error: `Action not found: ${idOrName}` };
+        }
+    }
+    // List actions
+    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);
+        }
+        if (args.enabled !== undefined) {
+            actions = actions.filter(a => a.enabled === args.enabled);
+        }
+        // Filter by persona workflow
+        if (args.persona_id) {
+            const persona = await client.getPersonaById(args.persona_id);
+            if (persona?.workflow_id) {
+                const workflowActionIds = await client.listActionsFromWorkflow(persona.workflow_id);
+                const actionIdSet = new Set(workflowActionIds);
+                actions = actions.filter(a => actionIdSet.has(a.id));
+            }
+        }
+        // Apply limit
+        const limit = args.limit || 100;
+        actions = actions.slice(0, limit);
+        // Include docs if requested
+        if (args.include_docs) {
+            return {
+                count: actions.length,
+                actions: actions.map(a => ({
+                    ...a,
+                    documentation: a.name ? getAgentByName(a.name) : undefined,
+                })),
+            };
+        }
+        return {
+            count: actions.length,
+            actions: actions.map(a => ({
+                id: a.id,
+                name: a.name,
+                category: a.category,
+                enabled: a.enabled,
+            })),
+        };
+    }
+    catch (e) {
+        // Fallback to catalog only
+        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",
+            })),
+            note: "Live API unavailable, showing catalog data",
+        };
+    }
+}

package/dist/mcp/handlers/action-executor.js

@@ -0,0 +1,350 @@
+/**
+ * Action Executor - Executes composable action sequences
+ *
+ * Replaces flag-based parameters with explicit action composition.
+ *
+ * Example:
+ * ```
+ * persona(
+ *   method="create",
+ *   from="source-id",
+ *   name="Clone",
+ *   actions=[
+ *     {tool:"data", args:{method:"copy", from:"$source"}},
+ *     {tool:"data", args:{method:"sanitize", examples:["Acme"]}},
+ *     {tool:"snapshot", args:{message:"Clone ready"}},
+ *   ]
+ * )
+ * ```
+ *
+ * Context variables:
+ * - $source: The `from` parameter (template/persona ID being cloned)
+ * - $target: The ID of the created/modified persona
+ * - $env: Current environment name
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Action Aliases
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Built-in action aliases for common patterns
+ */
+export const ACTION_ALIASES = {
+    // Copy data from source to target
+    "copy-data": [
+        { tool: "data", args: { method: "copy", from: "$source" } },
+    ],
+    // Copy and sanitize data
+    "copy-and-sanitize": [
+        { tool: "data", args: { method: "copy", from: "$source" } },
+        { tool: "data", args: { method: "sanitize" } },
+    ],
+    // Standard demo setup: copy, sanitize, snapshot
+    "standard-demo-setup": [
+        { tool: "data", args: { method: "copy", from: "$source" } },
+        { tool: "data", args: { method: "sanitize" } },
+        { tool: "snapshot", args: { message: "Demo setup complete" } },
+    ],
+    // Snapshot only
+    "create-snapshot": [
+        { tool: "snapshot", args: { message: "Checkpoint" } },
+    ],
+    // Validate workflow
+    "validate-workflow": [
+        { tool: "validate", args: { checks: ["workflow"] } },
+    ],
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Context Substitution
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Substitute context variables in action args
+ *
+ * Variables:
+ * - $source → context.source
+ * - $target → context.target
+ * - $env → context.env
+ */
+function substituteContext(action, context) {
+    // Deep clone args to avoid mutation
+    const args = JSON.parse(JSON.stringify(action.args));
+    function substitute(obj) {
+        for (const [key, value] of Object.entries(obj)) {
+            if (typeof value === "string") {
+                obj[key] = value
+                    .replace(/\$source/g, context.source ?? "")
+                    .replace(/\$target/g, context.target ?? "")
+                    .replace(/\$env/g, context.env ?? "");
+            }
+            else if (Array.isArray(value)) {
+                for (let i = 0; i < value.length; i++) {
+                    if (typeof value[i] === "string") {
+                        value[i] = value[i]
+                            .replace(/\$source/g, context.source ?? "")
+                            .replace(/\$target/g, context.target ?? "")
+                            .replace(/\$env/g, context.env ?? "");
+                    }
+                    else if (typeof value[i] === "object" && value[i] !== null) {
+                        substitute(value[i]);
+                    }
+                }
+            }
+            else if (typeof value === "object" && value !== null) {
+                substitute(value);
+            }
+        }
+    }
+    substitute(args);
+    return { tool: action.tool, args };
+}
+/**
+ * Expand aliases into action specs
+ */
+function expandAliases(actions) {
+    const expanded = [];
+    for (const action of actions) {
+        if (typeof action === "string") {
+            // It's an alias
+            const aliasActions = ACTION_ALIASES[action];
+            if (aliasActions) {
+                expanded.push(...aliasActions);
+            }
+            else {
+                // Unknown alias - will be reported as error during execution
+                console.warn(`[action-executor] Unknown alias: ${action}`);
+            }
+        }
+        else {
+            // It's an action spec
+            expanded.push(action);
+        }
+    }
+    return expanded;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Action Handlers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Execute a data action using the real data handler
+ */
+async function executeDataAction(args, context, client) {
+    const method = args.method;
+    const targetId = context.target;
+    if (!targetId) {
+        throw new Error("No target persona ID available for data action");
+    }
+    // Substitute context variables in args
+    const resolvedArgs = { ...args };
+    if (typeof resolvedArgs.from === "string") {
+        resolvedArgs.from = resolvedArgs.from
+            .replace(/\$source/g, context.source ?? "")
+            .replace(/\$target/g, context.target ?? "");
+    }
+    // Import and use the unified data handler
+    const { handleData } = await import("./data/index.js");
+    const result = await handleData({
+        persona_id: targetId,
+        data: { method, ...resolvedArgs },
+        mode: "data", // Legacy mode marker
+    }, client);
+    // Check for errors in result
+    if (result.error) {
+        throw new Error(result.error);
+    }
+    return result;
+}
+/**
+ * Execute a snapshot action
+ */
+async function executeSnapshotAction(args, context, client) {
+    const message = args.message ?? "Action-created snapshot";
+    const targetId = context.target;
+    if (!targetId) {
+        throw new Error("No target persona ID available for snapshot action");
+    }
+    // For now, return a placeholder
+    // Full implementation would call the version storage API
+    return {
+        status: "snapshot_created",
+        persona_id: targetId,
+        message,
+        timestamp: new Date().toISOString(),
+        note: "Full snapshot integration pending version storage implementation",
+    };
+}
+/**
+ * Execute a validate action
+ */
+async function executeValidateAction(args, context, client) {
+    const checks = args.checks ?? ["workflow", "config"];
+    const targetId = context.target;
+    if (!targetId) {
+        throw new Error("No target persona ID available for validate action");
+    }
+    // Fetch persona and run validation
+    const persona = await client.getPersonaById(targetId);
+    if (!persona) {
+        throw new Error(`Persona not found: ${targetId}`);
+    }
+    const results = {};
+    if (checks.includes("workflow")) {
+        const workflowDef = persona.workflow_def;
+        results.workflow = {
+            has_workflow: !!persona.workflow_def,
+            node_count: workflowDef?.nodes?.length ?? 0,
+        };
+    }
+    if (checks.includes("config")) {
+        const protoConfig = persona.proto_config;
+        results.config = {
+            has_proto_config: !!persona.proto_config,
+            widget_count: protoConfig?.widgets?.length ?? 0,
+        };
+    }
+    return {
+        status: "validated",
+        persona_id: targetId,
+        checks,
+        results,
+    };
+}
+/**
+ * Execute a single action
+ */
+async function executeAction(action, context, client) {
+    switch (action.tool) {
+        case "data":
+            return executeDataAction(action.args, context, client);
+        case "snapshot":
+            return executeSnapshotAction(action.args, context, client);
+        case "validate":
+            return executeValidateAction(action.args, context, client);
+        default:
+            throw new Error(`Unknown action tool: ${action.tool}`);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Main Executor
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Execute a sequence of actions with context substitution
+ *
+ * @param actions - Array of action specs or alias strings
+ * @param context - Execution context with source/target IDs
+ * @param client - EmaClient for API calls
+ * @returns Results of all action executions
+ */
+export async function executeActions(actions, context, client) {
+    const results = [];
+    let succeeded = 0;
+    let failed = 0;
+    let stoppedOnError = false;
+    // Expand aliases
+    const expanded = expandAliases(actions);
+    // Execute in sequence
+    for (const action of expanded) {
+        const startTime = Date.now();
+        // Substitute context variables
+        const substituted = substituteContext(action, context);
+        try {
+            const result = await executeAction(substituted, context, client);
+            results.push({
+                tool: action.tool,
+                status: "success",
+                result,
+                duration_ms: Date.now() - startTime,
+            });
+            succeeded++;
+        }
+        catch (error) {
+            results.push({
+                tool: action.tool,
+                status: "error",
+                error: error instanceof Error ? error.message : String(error),
+                duration_ms: Date.now() - startTime,
+            });
+            failed++;
+            stoppedOnError = true;
+            break; // Stop on first error
+        }
+    }
+    return {
+        executed: results.length,
+        succeeded,
+        failed,
+        results,
+        stopped_on_error: stoppedOnError ? true : undefined,
+    };
+}
+/**
+ * Check if actions array contains any valid actions
+ */
+export function hasActions(actions) {
+    return Array.isArray(actions) && actions.length > 0;
+}
+/**
+ * Validate actions array structure
+ */
+export function validateActions(actions) {
+    const errors = [];
+    if (!Array.isArray(actions)) {
+        return { valid: false, errors: ["actions must be an array"] };
+    }
+    for (let i = 0; i < actions.length; i++) {
+        const action = actions[i];
+        if (typeof action === "string") {
+            // Alias - check if known
+            if (!ACTION_ALIASES[action]) {
+                errors.push(`actions[${i}]: unknown alias "${action}". Valid: ${Object.keys(ACTION_ALIASES).join(", ")}`);
+            }
+        }
+        else if (typeof action === "object" && action !== null) {
+            // Action spec - check required fields
+            const spec = action;
+            if (!spec.tool) {
+                errors.push(`actions[${i}]: missing required field "tool"`);
+            }
+            else if (!["data", "snapshot", "validate"].includes(spec.tool)) {
+                errors.push(`actions[${i}]: invalid tool "${spec.tool}". Valid: data, snapshot, validate`);
+            }
+            if (!spec.args || typeof spec.args !== "object") {
+                errors.push(`actions[${i}]: missing or invalid "args" object`);
+            }
+        }
+        else {
+            errors.push(`actions[${i}]: must be object or string, got ${typeof action}`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Get list of available aliases with descriptions
+ */
+export function getAvailableAliases() {
+    return [
+        {
+            name: "copy-data",
+            description: "Copy data from source to target persona",
+            actions: ACTION_ALIASES["copy-data"],
+        },
+        {
+            name: "copy-and-sanitize",
+            description: "Copy data then sanitize PII",
+            actions: ACTION_ALIASES["copy-and-sanitize"],
+        },
+        {
+            name: "standard-demo-setup",
+            description: "Copy, sanitize, and create snapshot",
+            actions: ACTION_ALIASES["standard-demo-setup"],
+        },
+        {
+            name: "create-snapshot",
+            description: "Create a checkpoint snapshot",
+            actions: ACTION_ALIASES["create-snapshot"],
+        },
+        {
+            name: "validate-workflow",
+            description: "Run workflow validation checks",
+            actions: ACTION_ALIASES["validate-workflow"],
+        },
+    ];
+}