@ema.co/mcp-toolkit 1.5.2 → 1.6.0

package/docs/tool-consolidation-proposal.md

@@ -1,427 +1,215 @@
-# MCP Tool Consolidation Proposal
-
-> Consolidate 45 tools into 9 core commands following Unix CLI patterns.
-
-## Status: Implementation Complete
-
-Files created:
-- `src/mcp/tools-consolidated.ts` - New tool definitions
-- `src/mcp/handlers-consolidated.ts` - New handlers with mode-based dispatch
-
-## Design Principles
-
-1. **Consistent terminology**: Use "persona" everywhere (not "ai_employee")
-2. **Get/List as flags**: `persona("id")` vs `persona(all=True)`
-3. **Related functions as modes**: `workflow(mode="analyze")` includes detect, validate, suggest
-4. **Flags over separate tools**: `template(type="voice")` not `get_voice_template()`
-
----
-
-## Proposed Tool Structure
-
-### 1. `persona` - AI Employee Management
-
-**Replaces:** `find_personas`, `get_persona`, `create_ai_employee`, `update_ai_employee`, `compare_ai_employees`
+# ✅ IMPLEMENTED: Consolidate `persona` and `workflow` Tools
+
+> **Status**: Implemented. The `persona` tool now handles everything. `workflow` is deprecated.
+
+## The Problem
+
+Current tool separation is confusing:
+
+```mermaid
+graph TD
+    subgraph "Current: Confusing Separation"
+        USER[User: "Create an AI Employee"]
+        
+        USER --> PERSONA[persona tool]
+        USER --> WORKFLOW[workflow tool]
+        
+        PERSONA --> |"mode=create"| P_CREATE["Creates empty shell<br/>(no workflow = FAILS)"]
+        PERSONA --> |"mode=get"| P_GET[Get metadata]
+        PERSONA --> |"mode=update"| P_UPDATE[Update metadata only]
+        
+        WORKFLOW --> |"input + type"| W_CREATE["Creates full AI Employee<br/>(config + workflow)"]
+        WORKFLOW --> |"persona_id + input"| W_MODIFY[Modify existing]
+        WORKFLOW --> |"persona_id"| W_ANALYZE[Analyze]
+        
+        P_CREATE -.->|"⚠️ Useless without workflow"| BROKEN[Broken Persona]
+        W_CREATE -->|"✅ Actually works"| SUCCESS[Working AI Employee]
+    end
+```
+
+**Problems:**
+1. `persona(mode="create")` creates a broken persona (no workflow)
+2. `workflow()` actually creates personas, but it's called "workflow"
+3. User has to know "use workflow for create, persona for get" - confusing!
+4. Tool descriptions have to warn "don't use this for X, use that instead"
+
+## The Reality
+
+An AI Employee is ONE thing with two aspects:
+
+```mermaid
+graph TD
+    subgraph "Reality: AI Employee is ONE Entity"
+        AIE[AI Employee / Persona]
+        
+        AIE --> CONFIG[Proto Config<br/>- Voice settings<br/>- Welcome message<br/>- Widgets]
+        AIE --> WF[Workflow<br/>- Trigger<br/>- Nodes/Actions<br/>- Connections]
+        
+        CONFIG -.->|"Inseparable"| WF
+    end
+```
+
+## Proposed Solution: Single `persona` Tool
+
+Consolidate everything into ONE tool called `persona`:
+
+```mermaid
+graph TD
+    subgraph "Proposed: Single persona Tool"
+        USER[User: "Create an AI Employee"]
+        
+        USER --> PERSONA[persona tool]
+        
+        PERSONA --> |"input + type + name"| CREATE["CREATE<br/>Full AI Employee"]
+        PERSONA --> |"id + input"| MODIFY["MODIFY<br/>Change workflow"]
+        PERSONA --> |"id"| GET["GET/ANALYZE<br/>Fetch & analyze"]
+        PERSONA --> |"id + optimize"| OPTIMIZE["OPTIMIZE<br/>Auto-fix issues"]
+        PERSONA --> |"all=true"| LIST["LIST<br/>Search personas"]
+        
+        CREATE --> SUCCESS[Working AI Employee]
+        MODIFY --> SUCCESS
+        GET --> INFO[Persona + Analysis]
+        OPTIMIZE --> SUCCESS
+        LIST --> RESULTS[Search Results]
+    end
+```
+
+## New `persona` Tool Schema
 
 ```typescript
-interface PersonaArgs {
-  // Identifier (optional - if omitted with all=true, lists all)
-  id?: string;  // ID or exact name
-  
-  // Mode
-  mode?: "get" | "create" | "update" | "delete" | "compare" | "sync";
-  
-  // List/Search flags
-  all?: boolean;
-  query?: string;
-  status?: "active" | "inactive" | "draft";
-  trigger_type?: "voice" | "chat" | "dashboard";
-  limit?: number;
+persona({
+  // === IDENTITY ===
+  id: string,           // Get/modify existing (UUID or name)
   
-  // Get flags
-  include_workflow?: boolean;
-  include_fingerprint?: boolean;
+  // === CREATE NEW ===
+  input: string,        // Natural language description
+  type: "voice" | "chat" | "dashboard",
+  name: string,
+  description: string,
   
-  // Create/Update flags
-  name?: string;
-  description?: string;
-  template_id?: string;
-  source_persona_id?: string;
+  // === OPERATIONS ===
+  optimize: boolean,    // Auto-fix workflow issues
+  analyze: boolean,     // Return detailed analysis
+  preview: boolean,     // Default true - preview before deploy
   
-  // Compare/Sync flags
-  compare_to?: string;
-  target_env?: string;
-  dry_run?: boolean;
+  // === LIST/SEARCH ===
+  all: boolean,
+  query: string,
+  status: string,
   
-  // Environment
-  env?: string;
-}
+  // === VERSION MANAGEMENT ===
+  mode: "version_list" | "version_get" | "version_restore" | ...,
+})
 ```
 
-**Usage Examples:**
-```bash
-# Get single
-persona("IT Support Bot")
-persona("abc-123", include_workflow=True)
+## Usage Examples
 
-# List/Search
-persona(all=True)
-persona(query="Support", status="active")
+### Create New AI Employee (ONE call)
 
-# Create
-persona(mode="create", name="New Bot", template_id="voice")
-
-# Update
-persona("abc-123", mode="update", name="Renamed")
-
-# Compare
-persona("abc-123", mode="compare", compare_to="def-456")
-
-# Sync
-persona("abc-123", mode="sync", target_env="dev", dry_run=True)
-```
-
----
-
-### 2. `workflow` - Workflow Generation & Analysis
-
-**Replaces:** `workflow`, `deploy_workflow`, `analyze_workflow`, `detect_workflow_issues`, `validate_workflow_connections`, `suggest_workflow_fixes`, `get_workflow_metrics`, `compare_workflow_versions`, `compile_workflow`
-
-```typescript
-interface WorkflowArgs {
-  // Input (one of these)
-  input?: string | object;  // Natural language or spec
-  persona_id?: string;      // For existing workflow operations
-  workflow_def?: object;    // For direct analysis
-  
-  // Mode
-  mode?: "generate" | "analyze" | "deploy" | "compare" | "compile";
-  
-  // Generate flags
-  persona_type?: "voice" | "chat" | "dashboard";
-  use_autobuilder?: boolean;
-  
-  // Analyze flags (what to include in analysis)
-  include?: ("issues" | "connections" | "fixes" | "metrics")[];
-  // Default: all of them
-  
-  // Deploy flags
-  auto_fix?: boolean;
-  validate_first?: boolean;
-  
-  // Compare flags
-  compare_to?: string;  // Another persona_id
-  
-  // Environment
-  env?: string;
-}
 ```
-
-**Usage Examples:**
-```bash
-# Generate
-workflow("IT helpdesk with KB search and tickets")
-workflow(input={intents: [...]}, persona_type="voice")
-
-# Analyze (unified - returns issues, connections, fixes, metrics)
-workflow(persona_id="abc-123", mode="analyze")
-
-# Analyze with specific includes
-workflow(persona_id="abc-123", mode="analyze", include=["issues", "metrics"])
-
-# Analyze from JSON (not deployed)
-workflow(workflow_def={...}, mode="analyze")
-
-# Deploy
-workflow(persona_id="abc-123", mode="deploy", workflow_def={...}, auto_fix=True)
-
-# Compare versions
-workflow(persona_id="abc-123", mode="compare", compare_to="def-456")
-
-# Compile spec to workflow_def
-workflow(input={nodes: [...]}, mode="compile")
+persona(
+  input="Voice AI SDR: qualifies leads, identifies use-case, sends follow-up email",
+  type="voice",
+  name="Sales SDR",
+  preview=false
+)
 ```
 
----
+### Modify Existing
 
-### 3. `action` - Workflow Actions/Agents
-
-**Replaces:** `find_workflow_actions`, `get_workflow_action`, `list_auto_builder_agents`, `get_auto_builder_agent`, `suggest_agents_for_use_case`
-
-```typescript
-interface ActionArgs {
-  // Identifier (optional)
-  id?: string;  // Action ID or name
-  
-  // List/Search flags
-  all?: boolean;
-  category?: string;
-  query?: string;
-  persona_id?: string;  // Actions in this workflow
-  enabled?: boolean;
-  
-  // Suggestion mode
-  suggest_for?: string;  // Use case description
-  
-  // Include flags
-  include_docs?: boolean;  // Include full documentation
-  
-  // Environment
-  env?: string;
-}
 ```
+// Analyze first
+persona(id="abc-123")
 
-**Usage Examples:**
-```bash
-# Get single
-action("chat_categorizer")
-action("abc-123-uuid")
-action("chat_categorizer", include_docs=True)
-
-# List/Search
-action(all=True)
-action(category="routing")
-action(persona_id="abc-123")  # Actions in workflow
-action(query="search")
-
-# Suggest for use case
-action(suggest_for="IT helpdesk with ServiceNow")
+// Modify
+persona(id="abc-123", input="add HITL before email", preview=false)
 ```
 
----
-
-### 4. `template` - Templates & Patterns
-
-**Replaces:** `get_workflow_pattern`, `list_workflow_patterns`, `get_widget_reference`, `get_voice_persona_template`, `list_ai_employee_templates`
+### List/Search
 
-```typescript
-interface TemplateArgs {
-  // What to get
-  type?: "voice" | "chat" | "dashboard";  // Persona config template
-  pattern?: string;  // Workflow pattern name
-  widgets?: "voice" | "chat" | "dashboard";  // Widget reference
-  
-  // List flags
-  all?: boolean;
-  patterns?: boolean;  // List workflow patterns
-  
-  // Environment
-  env?: string;
-}
 ```
-
-**Usage Examples:**
-```bash
-# Persona config templates
-template(type="voice")
-template(type="chat")
-
-# Workflow patterns
-template(pattern="intent-routing")
-template(patterns=True)  # List all patterns
-template(patterns=True, type="voice")  # Filter by persona type
-
-# Widget reference
-template(widgets="voice")
-
-# List all persona templates
-template(all=True)
+persona(all=true)
+persona(query="support", status="active")
 ```
 
----
-
-### 5. `knowledge` - Data Sources & KB
+### Optimize
 
-**Replaces:** `upload_data_source`, `delete_data_source`, `list_data_sources`, `get_embedding_status`, `toggle_embedding`
-
-```typescript
-interface KnowledgeArgs {
-  persona_id: string;
-  
-  // Mode
-  mode?: "list" | "upload" | "delete" | "status" | "toggle";
-  
-  // Upload flags
-  file_path?: string;
-  tags?: string;
-  
-  // Delete flags
-  file_id?: string;
-  
-  // Toggle flags
-  embedding_enabled?: boolean;
-  
-  // Environment
-  env?: string;
-}
 ```
-
-**Usage Examples:**
-```bash
-# List files
-knowledge(persona_id="abc-123", mode="list")
-
-# Upload
-knowledge(persona_id="abc-123", mode="upload", file_path="/path/to/file.pdf")
-
-# Delete
-knowledge(persona_id="abc-123", mode="delete", file_id="file-123")
-
-# Embedding status
-knowledge(persona_id="abc-123", mode="status")
-
-# Toggle embedding
-knowledge(persona_id="abc-123", mode="toggle", embedding_enabled=True)
+persona(id="abc-123", optimize=true, preview=false)
 ```
 
----
+## What Happens to `workflow` Tool?
 
-### 6. `reference` - Platform Knowledge
+**Option A: Deprecate with alias**
+- Keep `workflow` as an alias that routes to `persona`
+- Show deprecation warning
+- Remove in future version
 
-**Replaces:** `get_platform_concept`, `list_platform_concepts`, `get_common_mistakes`, `get_debug_checklist`, `get_workflow_execution_model`, `get_auto_builder_guidance`, `get_qualifying_questions`, `validate_workflow_prompt`, `check_type_compatibility`
+**Option B: Remove immediately**
+- Breaking change
+- Cleaner, but disruptive
 
-```typescript
-interface ReferenceArgs {
-  // What to get (one of these)
-  concept?: string;       // Platform concept (e.g., "HITL", "Workflow")
-  guidance?: string;      // Topic guidance (e.g., "categorizer-routing")
-  questions?: boolean;    // Qualifying questions
-  mistakes?: boolean;     // Common mistakes
-  checklist?: boolean;    // Debug checklist
-  execution?: boolean;    // Workflow execution model
-  
-  // List flags
-  concepts?: boolean;     // List all concepts
-  
-  // Questions filter
-  category?: string;      // Filter questions by category
-  required_only?: boolean;
-  
-  // Type compatibility check
-  check_types?: { source: string; target: string };
-  
-  // Prompt validation
-  validate_prompt?: string;
-}
-```
-
-**Usage Examples:**
-```bash
-# Concepts
-reference(concept="HITL")
-reference(concepts=True)
-
-# Guidance
-reference(guidance="categorizer-routing")
-reference(guidance="type-compatibility")
-
-# Questions
-reference(questions=True)
-reference(questions=True, category="Voice", required_only=True)
-
-# Debugging
-reference(mistakes=True)
-reference(checklist=True)
-reference(execution=True)
+**Recommendation: Option A** - Deprecate gracefully
 
-# Validation
-reference(check_types={source: "CHAT_CONVERSATION", target: "TEXT_WITH_SOURCES"})
-reference(validate_prompt="Create a bot that...")
+```mermaid
+graph LR
+    subgraph "Migration Path"
+        OLD[workflow tool] -->|"Alias + Warning"| NEW[persona tool]
+        OLD -->|"6 months"| REMOVED[Removed]
+    end
 ```
 
----
+## Benefits
 
-### 7. `sync` - Environment Sync
+1. **One tool, one concept** - "persona" = AI Employee = everything
+2. **No confusion** - Don't have to explain "use workflow for X, persona for Y"
+3. **Simpler mental model** - User thinks "I want to do X with my AI Employee" → `persona`
+4. **Matches UI** - Ema UI calls them "AI Employees", we call the tool "persona"
 
-**Replaces:** `sync`, `sync_info`
+## Implementation Plan
 
-```typescript
-interface SyncArgs {
-  // What to sync
-  id?: string;  // Persona ID or name
-  
-  // Mode
-  mode?: "run" | "status" | "config";
-  
-  // Sync flags
-  target_env: string;
-  source_env?: string;
-  scope?: "one" | "all";
-  dry_run?: boolean;
-  include_status?: boolean;
-  
-  // Status flags
-  list_synced?: boolean;
-  master_env?: string;
-}
-```
+### Phase 1: Add unified operations to `persona`
+- Add `input`, `type`, `optimize` params to persona tool
+- persona internally calls the same handlers as workflow
 
-**Usage Examples:**
-```bash
-# Sync single
-sync(id="IT Support", target_env="dev")
-sync(id="abc-123", target_env="staging", dry_run=True)
+### Phase 2: Deprecate `workflow`
+- workflow() returns result + deprecation warning
+- Update all docs/rules to use persona
 
-# Sync all
-sync(target_env="dev", scope="all")
+### Phase 3: Remove `workflow` (v2.0)
+- Breaking change, major version bump
 
-# Status
-sync(mode="status", id="abc-123")
-sync(mode="status", list_synced=True, env="dev")
+## Alternative: Rename to `employee`
 
-# Config
-sync(mode="config")
-```
-
----
-
-### 8. `env` - Environment Management
+Instead of `persona`, use `employee` to match UI terminology:
 
-**Replaces:** `list_environments`
-
-```typescript
-interface EnvArgs {
-  all?: boolean;  // List all environments
-}
 ```
-
-**Usage Examples:**
-```bash
-env(all=True)  # List available environments
+employee(input="Voice AI for sales", type="voice", name="Sales SDR")
+employee(id="abc-123", input="add HITL before email")
+employee(id="abc-123", optimize=true)
 ```
 
----
-
-## Summary: Before & After
-
-| Before (45+ tools) | After (8 tools) |
-|-------------------|-----------------|
-| `find_personas`, `get_persona`, `create_ai_employee`, `update_ai_employee`, `compare_ai_employees` | `persona` |
-| `workflow`, `deploy_workflow`, `analyze_workflow`, `detect_workflow_issues`, `validate_workflow_connections`, `suggest_workflow_fixes`, `get_workflow_metrics`, `compare_workflow_versions`, `compile_workflow` | `workflow` |
-| `find_workflow_actions`, `get_workflow_action`, `list_auto_builder_agents`, `get_auto_builder_agent`, `suggest_agents_for_use_case` | `action` |
-| `get_workflow_pattern`, `list_workflow_patterns`, `get_widget_reference`, `get_voice_persona_template`, `list_ai_employee_templates` | `template` |
-| `upload_data_source`, `delete_data_source`, `list_data_sources`, `get_embedding_status`, `toggle_embedding` | `knowledge` |
-| `get_platform_concept`, `list_platform_concepts`, `get_common_mistakes`, `get_debug_checklist`, `get_workflow_execution_model`, `get_auto_builder_guidance`, `get_qualifying_questions`, `validate_workflow_prompt`, `check_type_compatibility` | `reference` |
-| `sync`, `sync_info` | `sync` |
-| `list_environments` | `env` |
+**Pros:**
+- Matches "AI Employee" terminology in UI
+- Fresh name, no baggage
 
-**Result: 45+ tools → 8 commands**
+**Cons:**
+- Breaking change for existing users
+- "persona" is the API term
 
----
+## Decision Matrix
 
-## Migration Strategy
+| Approach | User Clarity | Breaking Change | Implementation Effort |
+|----------|--------------|-----------------|----------------------|
+| Keep separate (current) | ❌ Poor | None | None |
+| Consolidate to `persona` | ✅ Good | Low (deprecation) | Medium |
+| Rename to `employee` | ✅ Best | High | Medium |
 
-1. **Phase 1**: Create new consolidated tools alongside existing
-2. **Phase 2**: Mark old tools as deprecated with pointer to new
-3. **Phase 3**: Remove deprecated tools after transition period
+## Recommendation
 
-## Backward Compatibility
+**Consolidate to `persona` with `workflow` as deprecated alias.**
 
-Old tool names can be aliases:
-```typescript
-// In server.ts
-get_persona: (args) => persona({ ...args, mode: "get" }),
-find_personas: (args) => persona({ ...args, all: true }),
-analyze_workflow: (args) => workflow({ ...args, mode: "analyze" }),
-// etc.
-```
+This gives us:
+- Clear mental model (one tool = one concept)
+- Backward compatibility (workflow still works, just warns)
+- Path to clean future (remove workflow in v2)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",
@@ -43,6 +43,7 @@
     "cli": "tsx src/cli/index.ts",
     "test": "vitest run --exclude 'test/integration/**'",
     "test:watch": "vitest --exclude 'test/integration/**'",
+    "test:coverage": "vitest run --coverage --exclude 'test/integration/**'",
     "test:integration": "EMA_TEST_INTEGRATION=true vitest run test/integration/",
     "test:all": "npm run test && npm run test:integration",
     "typecheck": "tsc --noEmit",
@@ -92,6 +93,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.2",
     "@types/node-cron": "^3.0.11",
+    "@vitest/coverage-v8": "^4.0.17",
     "husky": "^9.1.7",
     "openapi-typescript": "^7.0.0",
     "tsx": "^4.19.2",