@ema.co/mcp-toolkit 1.5.1 → 1.6.0

package/docs/local-generation.md

@@ -0,0 +1,508 @@
+# Local Workflow Generation
+
+> Use the conversational-workflow-builder to generate workflows locally, then deploy via MCP tools.
+
+## Overview
+
+This integration allows Cursor rules to:
+1. Generate Auto Builder prompts using MCP tools for guidance
+2. Run the prompt through a local workflow generation pipeline
+3. Get back validated `workflow_def` JSON
+4. Deploy to Ema using `workflow(mode="deploy", ...)`
+
+**Key Benefits:**
+- Full Planner → Grapher → Validator pipeline with retry logic
+- Works offline (only needs Anthropic API)
+- Supports complex multi-agent workflows
+- Returns deployable JSON directly
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+```bash
+# 1. Set up the conversational-workflow-builder
+cd .refs/conversational-workflow-builder
+
+# 2. Install dependencies (using uv)
+uv sync
+
+# 3. Set environment variable
+export ANTHROPIC_API_KEY="your-key-here"
+```
+
+### Basic Usage
+
+```bash
+# Generate workflow graph from prompt
+python generate_local.py --prompt "Create an IT helpdesk bot that routes to KB search or ticket creation"
+
+# Generate complete workflow_def for deployment
+python generate_local.py --prompt "..." --full --persona-id "my-bot-id" --pretty
+
+# Pipe prompt from file
+cat my_prompt.txt | python generate_local.py --verbose --pretty
+```
+
+---
+
+## Integration Workflow
+
+### Step 1: Gather Requirements (MCP Tools)
+
+```text
+# Get structured questions to ask user
+template(questions=true)
+
+# Get suggested agents for use case
+action(suggest="IT helpdesk with ServiceNow integration")
+
+# Get pattern template
+template(pattern="tool-calling")
+```
+
+### Step 2: Generate Auto Builder Prompt
+
+Based on MCP tool responses, craft a detailed natural language prompt:
+
+```text
+Create a Chat AI Employee for IT Helpdesk Support:
+
+TRIGGER: chat_trigger
+
+ROUTING:
+- Use chat_categorizer to classify user intent
+- Categories: Password Reset, Create Ticket, Check Status, Fallback
+
+PASSWORD RESET PATH:
+- Search knowledge base for password reset articles
+- Use respond_with_sources to answer with citations
+
+CREATE TICKET PATH:
+- Use external_action_caller with ServiceNow Create_Ticket
+- Add general_hitl for approval before creation
+- On success: confirm ticket created
+- On failure: apologize and offer alternatives
+
+CHECK STATUS PATH:
+- Use external_action_caller with ServiceNow Get_Ticket_Status
+- Return status information
+
+FALLBACK PATH:
+- Ask clarifying question using fixed_response
+
+All paths must connect to WORKFLOW_OUTPUT.
+```
+
+### Step 3: Run Local Generation
+
+```bash
+# From Cursor, run terminal command:
+cd .refs/conversational-workflow-builder && \
+python generate_local.py \
+  --prompt "Your detailed prompt here" \
+  --full \
+  --persona-id "it-helpdesk-bot" \
+  --template-name "ITHelpdeskBot" \
+  --pretty \
+  --output /tmp/workflow.json
+```
+
+### Step 4: Review and Deploy
+
+```text
+# Read the generated workflow
+cat /tmp/workflow.json
+
+# If satisfied, deploy via MCP:
+workflow(
+  mode="deploy",
+  persona_id="existing-persona-id",  # or create new one first
+  workflow_def={...from generated file...}
+)
+
+# Or create new persona and deploy
+persona(mode="create", name="IT Helpdesk", description="...", type="chat")
+# Then deploy workflow to the new persona
+```
+
+---
+
+## CLI Reference
+
+```text
+usage: generate_local.py [-h] [--prompt PROMPT | --file FILE] [--output OUTPUT]
+                         [--full] [--persona-id PERSONA_ID] [--template-name TEMPLATE_NAME]
+                         [--type {chat,document,dashboard}] [--max-retries MAX_RETRIES]
+                         [--verbose] [--pretty] [--graph-only] [--plan-only]
+
+Options:
+  --prompt, -p          Workflow description prompt
+  --file, -f            File containing the workflow prompt
+  --output, -o          Output file (default: stdout)
+  --full                Generate complete workflow_def (not just graph)
+  --persona-id          Persona ID for workflow_def generation
+  --template-name       Template name for workflow_def
+  --type, -t            Persona type hint (chat or document/dashboard)
+  --max-retries         Maximum validation retries (default: 3)
+  --verbose, -v         Print progress to stderr
+  --pretty              Pretty-print JSON output
+  --graph-only          Output only the workflow_graph
+  --plan-only           Output only the workflow_plan (markdown)
+```
+
+---
+
+## Output Formats
+
+### Default Output (--graph-only false, --full false)
+
+```json
+{
+  "success": true,
+  "workflow_graph": {
+    "user_query": "description",
+    "is_document": false,
+    "graph": {
+      "trigger": { "action_name": "chat_trigger", ... },
+      "categorizer_1": { "action_name": "chat_categorizer", ... }
+    }
+  },
+  "workflow_plan": "# Workflow Plan\n\n..."
+}
+```
+
+### Full Output (--full)
+
+```json
+{
+  "success": true,
+  "workflow_def": {
+    "workflowName": { ... },
+    "actions": [ ... ],
+    "results": { ... },
+    "enumTypes": [ ... ]
+  },
+  "workflow_graph": { ... },
+  "workflow_plan": "..."
+}
+```
+
+---
+
+## Complete Example Flow
+
+### 1. User Request
+
+"Create a bot that helps employees find benefits information and submit PTO requests"
+
+### 2. MCP Discovery
+
+```text
+action(suggest="HR bot for benefits and PTO")
+→ Suggests: chat_categorizer, search, respond_with_sources, external_action_caller, general_hitl
+
+template(pattern="intent-routing")
+→ Returns pattern template with categorizer routing
+```
+
+### 3. Generate Detailed Prompt
+
+```text
+Create a Chat AI Employee for HR Self-Service:
+
+TRIGGER: chat_trigger (receives employee questions)
+
+ROUTING (chat_categorizer):
+- "Benefits Information" - questions about health, dental, 401k
+- "PTO Request" - requests to submit time off
+- "PTO Balance" - checking remaining PTO
+- "Fallback" - unclear requests
+
+BENEFITS PATH:
+→ conversation_to_search_query (convert to search)
+→ search (query HR knowledge base)
+→ respond_with_sources (answer with citations)
+→ WORKFLOW_OUTPUT
+
+PTO REQUEST PATH:
+→ call_llm (extract dates and reason from conversation)
+→ general_hitl (manager approval required)
+  - On "HITL Success": external_action_caller (Workday submit PTO)
+    → fixed_response ("Your PTO has been submitted!")
+  - On "HITL Failure": fixed_response ("Request not approved")
+→ WORKFLOW_OUTPUT
+
+PTO BALANCE PATH:
+→ external_action_caller (Workday get PTO balance)
+→ respond_for_external_actions (format balance info)
+→ WORKFLOW_OUTPUT
+
+FALLBACK PATH:
+→ fixed_response ("I can help with benefits info, PTO requests, or checking your PTO balance.")
+→ WORKFLOW_OUTPUT
+```
+
+### 4. Run Generation
+
+```bash
+python generate_local.py \
+  --prompt "$(cat prompt.txt)" \
+  --full \
+  --type chat \
+  --persona-id "hr-self-service" \
+  --verbose \
+  --pretty \
+  --output workflow.json
+```
+
+### 5. Validate with MCP
+
+```text
+# Validate connections
+workflow(mode="analyze", workflow_def=<workflow_def>, include=["connections"])
+
+# Check for issues
+workflow(mode="analyze", workflow_def=<workflow_def>, include=["issues"])
+```
+
+### 6. Deploy
+
+```text
+# Create persona
+persona(
+  mode="create",
+  name="HR Self-Service Bot",
+  description="Helps employees with benefits and PTO",
+  type="chat"
+)
+
+# Deploy workflow
+workflow(
+  mode="deploy",
+  persona_id=<new_persona_id>,
+  workflow_def=<generated workflow_def>
+)
+```
+
+---
+
+## Error Handling
+
+### Generation Failures
+
+```json
+{
+  "success": false,
+  "error": "Failed to generate valid workflow after 3 attempts...",
+  "workflow_graph": { ... },
+  "workflow_plan": "..."
+}
+```
+
+**Recovery:**
+1. Review `workflow_plan` to understand what Planner intended
+2. Check `error` for specific validation issues
+3. Modify prompt to be more explicit about connections
+4. Increase `--max-retries` if close to success
+
+### Common Issues
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Missing Fallback category` | Categorizer without fallback | Add "Fallback" to categories |
+| `Type mismatch` | Incompatible connections | Use `reference(check_types={source: "...", target: "..."})` |
+| `HITL needs both paths` | Missing success or failure | Define both HITL outcomes |
+| `No WORKFLOW_OUTPUT` | Missing output connections | Ensure all paths reach OUTPUT |
+
+---
+
+## Best Practices
+
+### 1. Be Explicit in Prompts
+
+```text
+BAD:
+"Create a helpdesk bot"
+
+GOOD:
+"Create a Chat AI Employee for IT Helpdesk:
+- TRIGGER: chat_trigger
+- ROUTING: chat_categorizer with categories [A, B, C, Fallback]
+- PATH A: search → respond_with_sources → WORKFLOW_OUTPUT
+- PATH B: external_action_caller → WORKFLOW_OUTPUT
+- FALLBACK: fixed_response → WORKFLOW_OUTPUT"
+```
+
+### 2. Always Include Fallback
+
+Every categorizer must have a Fallback category.
+
+### 3. Define HITL Paths Completely
+
+```text
+"general_hitl for approval:
+- On HITL Success: proceed to create ticket
+- On HITL Failure: send apology message"
+```
+
+### 4. Use MCP for Validation
+
+```text
+workflow(mode="analyze", workflow_def=<workflow_def>)
+```
+
+### 5. Test Incrementally
+
+Start with a simple workflow, validate, then add complexity.
+
+---
+
+## Comparison: Local vs Auto Builder UI
+
+| Aspect | Local Generation | Auto Builder UI |
+|--------|-----------------|-----------------|
+| Input | CLI prompt | Web form |
+| Speed | ~60-90 seconds | ~60-90 seconds |
+| Retry Logic | Automatic (3 attempts) | Manual |
+| Output | JSON file | Deployed workflow |
+| Batch Processing | Yes | No |
+| CI/CD Integration | Easy | Hard |
+| Debugging | Full logs | Limited |
+
+---
+
+## Related Documentation
+
+- `../mcp/RULE.md` — MCP usage + resource-first guidance
+- `../auto-builder/RULE.md` — Auto Builder prompt authoring rules
+- `docs/mcp-tools-guide.md` — Canonical consolidated MCP tool semantics
+
+---
+
+## LLM Templating for Document Generation
+
+### Recommended Approach: LLM Templating
+
+For dynamic, context-dependent content, use **LLM templating** instead of hardcoded templates:
+
+```text
+search (gather context)
+    → call_llm (generate structured content with section prompts)
+    → generate_document (convert to document format)
+    → [optional] send_email (with proper entity extraction)
+```
+
+### How to Use LLM Templating
+
+**In your prompt to call_llm:**
+
+```text
+Generate structured content with clear ## section headers.
+Let the LLM determine appropriate sections based on:
+- Content type (the user's request)
+- Audience (who will read this)
+- Purpose (inform, analyze, recommend, etc.)
+
+Use a structured prompt like:
+"Based on the provided data, generate a professional document with:
+- Clear section headers (## format)
+- Key findings organized by themes
+- Actionable recommendations
+Format with markdown for conversion to document."
+```
+
+### Output Semantics Extraction
+
+Instead of hardcoding document types, extract semantics via LLM:
+
+| Attribute | Example Values | Determined By |
+|-----------|----------------|---------------|
+| output_type | brief, report, analysis | LLM from context |
+| tone | formal, professional, casual | Audience + relationship |
+| style | analytical, informative | Purpose |
+| audience | client, internal, executive | Context clues |
+| length | brief, standard, detailed | Explicit or implied |
+
+Use `generateOutputSemanticsPrompt(userInput)` to create the extraction prompt.
+
+### When to Use Template Engines (Rare)
+
+Only use data source templates when:
+- Strict regulatory formatting is required
+- Pixel-perfect layouts are needed
+- Content is purely data-driven (not narrative)
+
+### Document Generation Chain
+
+```yaml
+# Recommended flow
+- name: gather_context
+  action: search
+  # Search KB and/or web for relevant information
+
+- name: generate_content
+  action: call_llm
+  inputs:
+    query: user_request
+    named_inputs_KB_Results:
+      actionOutput: { actionName: gather_context, output: search_results }
+  # Prompt includes: "Generate structured content with ## sections..."
+
+- name: create_document
+  action: generate_document
+  inputs:
+    markdown_file_contents:
+      actionOutput: { actionName: generate_content, output: response_with_sources }
+
+# If sending via email:
+- name: extract_recipient
+  action: entity_extraction
+  # Extract email_address from conversation
+
+- name: confirm_send
+  action: general_hitl
+  # ALWAYS confirm before sending
+
+- name: send_email
+  action: send_email_agent
+  inputs:
+    email_to:
+      actionOutput: { actionName: extract_recipient, output: email_address }
+    # Use named_inputs for DOCUMENT type attachment
+    named_inputs_Attachment:
+      actionOutput: { actionName: create_document, output: document_link }
+```
+
+---
+
+## Email Best Practices
+
+### Critical Rules
+
+1. **email_to MUST come from entity_extraction** - Never from text summaries or LLM outputs
+2. **ALWAYS use HITL before sending** - Emails have external side effects
+3. **Use named_inputs for document attachments** - DOCUMENT type requires named_inputs, not attachment_links
+
+### Anti-Patterns to Avoid
+
+```yaml
+# ❌ WRONG - Text output as email recipient
+email_to:
+  actionOutput: { actionName: summarizer, output: summarized_conversation }
+
+# ✅ CORRECT - Extracted email address
+email_to:
+  actionOutput: { actionName: entity_extraction, output: email_address }
+```
+
+### Email Flow Pattern
+
+```text
+entity_extraction (extract email_address, recipient_name)
+    → general_hitl (confirm recipient and content)
+    → [HITL Success] send_email_agent
+    → [HITL Failure] fixed_response (cancelled message)
+```

package/docs/mcp-flow-diagram.md

@@ -0,0 +1,135 @@
+# MCP Flow Diagrams
+
+## ⚠️ THE KEY INSIGHT: ONE CALL
+
+**Creating an AI Employee should be ONE MCP call, not 45.**
+
+If an agent is making 10+ calls to create one persona, something is wrong with:
+1. The tool descriptions (not clear enough)
+2. The cursor rules (not being applied)
+3. The agent's understanding (ignoring guidance)
+
+---
+
+## Greenfield: Create New AI Employee
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Agent as Agent (LLM)
+    participant MCP
+    participant API as Ema API
+
+    User->>Agent: "Create a Voice AI for sales..."
+    
+    Note over Agent: If requirements unclear...
+    Agent->>MCP: template(questions=true, category="Voice")
+    MCP-->>Agent: { questions: ["What intents?", "Data sources?", ...] }
+    
+    Agent->>User: Asks MCP-provided questions
+    User->>Agent: Provides answers
+    
+    Note over Agent: ONE CALL with all info
+    Agent->>MCP: persona(input="Voice AI SDR...", type="voice", name="Sales SDR", preview=false)
+    
+    Note over MCP: MCP handles everything internally:<br/>1. Template selection<br/>2. Config generation<br/>3. Widget formatting<br/>4. API orchestration
+    
+    MCP->>API: createAiEmployee(template_id)
+    API-->>MCP: { persona_id: "abc" }
+    MCP->>API: getPersonaById("abc")
+    API-->>MCP: { proto_config, workflow_def }
+    MCP->>API: updateAiEmployee({ proto_config })
+    API-->>MCP: { success }
+    
+    MCP-->>Agent: { deployed_to: { persona_id, created: true } }
+    Agent->>User: "Created Sales SDR (abc-123)"
+```
+
+## Key Points: Who Does What
+
+### Agent (LLM) Responsibilities:
+1. **Ask MCP what to ask** - Call `template(questions=true)` to get qualifying questions
+2. **Ask user the MCP-provided questions** - Don't hardcode questions
+3. **Format ONE MCP call** - Single `persona()` call with all gathered info
+4. **Report results** - Show user what was created
+
+### MCP Responsibilities (ALL internal, abstracted):
+1. **Mode detection** - Greenfield vs brownfield vs analyze
+2. **Input parsing** - Extract intents, settings from natural language
+3. **Proto config generation** - Format widgets, settings properly
+4. **Template selection** - Pick correct template for type
+5. **API orchestration** - Create → Fetch → Merge → Update
+6. **Field name handling** - Uses correct API field names
+7. **Validation** - Check for issues before/after
+
+### Ema API Responsibilities:
+1. **Create persona from template** - Returns valid workflow structure
+2. **Store persona** - Persist config and workflow
+3. **Return data** - Full persona with workflow_def
+
+## Brownfield: Modify Existing AI Employee
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Agent as Agent (LLM)
+    participant MCP
+    participant API as Ema API
+
+    User->>Agent: "Add HITL before sending emails"
+    
+    Note over Agent: Optional: Understand what exists
+    Agent->>MCP: persona(id="abc-123")
+    MCP->>API: getPersonaById("abc-123")
+    API-->>MCP: { workflow_def, proto_config }
+    MCP-->>Agent: { issues, nodes, connections }
+    
+    Note over Agent: ONE CALL to modify
+    Agent->>MCP: persona(id="abc-123", input="add HITL before email", preview=false)
+    
+    Note over MCP: MCP handles internally:<br/>1. Fetch existing workflow<br/>2. Analyze modification<br/>3. Apply changes<br/>4. Validate<br/>5. Deploy
+    
+    MCP->>API: updateAiEmployee({ workflow })
+    API-->>MCP: { success }
+    
+    MCP-->>Agent: { status: "deployed", changes_applied: [...] }
+    Agent->>User: "Done! HITL added before email."
+```
+
+## Summary: One Tool, One Call
+
+```mermaid
+graph TD
+    subgraph "The Right Way"
+        USER[User Request] --> AGENT[Agent]
+        AGENT -->|"If unclear"| TEMPLATE["template(questions=true)"]
+        TEMPLATE --> ASK[Ask user questions]
+        ASK --> AGENT
+        AGENT -->|"ONE CALL"| PERSONA["persona(input=..., type=..., name=...)"]
+        PERSONA --> SUCCESS[AI Employee Created]
+    end
+    
+    subgraph "The Wrong Way ❌"
+        BAD_USER[User Request] --> BAD_AGENT[Agent]
+        BAD_AGENT --> CALL1["persona(mode=create)"]
+        CALL1 --> CALL2["template(config=voice)"]
+        CALL2 --> CALL3["persona(mode=update, proto_config)"]
+        CALL3 --> CALL4["workflow(persona_id, workflow_def)"]
+        CALL4 --> CALL5["workflow(mode=analyze)"]
+        CALL5 --> CALL6["workflow(mode=optimize)"]
+        CALL6 --> DOTS["... 40 more calls ..."]
+        DOTS --> FAIL[Confusion & Wasted Time]
+    end
+```
+
+## Tool Responsibility
+
+| What | Use `persona` for | Do NOT use |
+|------|-------------------|------------|
+| Create new AI Employee | `persona(input=..., type=..., name=...)` | `workflow` (deprecated) |
+| Modify existing | `persona(id=..., input=...)` | Manual orchestration |
+| Analyze | `persona(id=...)` | Multiple separate calls |
+| Optimize | `persona(id=..., optimize=true)` | Manual fixing |
+| List/Search | `persona(all=true)` | N/A |
+
+**The agent makes 1-2 simple calls. MCP handles all complexity.**