@ema.co/mcp-toolkit 2026.1.27 → 2026.1.28-2

package/docs/email-patterns.md

@@ -1,120 +0,0 @@
-# Email Field Extraction Patterns
-
-## Problem
-
-`send_email_agent.to_email` expects a text email address, but `entity_extraction` outputs `extraction_columns` (a JSON object), not individual fields.
-
-**This does NOT work:**
-```
-entity_extraction.extraction_columns → send_email.to_email
-```
-
-The types are incompatible:
-- `extraction_columns` = `WELL_KNOWN_TYPE_ANY` (JSON object)
-- `to_email` = `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES` (text)
-
-## Solution Pattern
-
-```
-entity_extraction.extraction_columns 
-  → fixed_response (template: "{{email}}")
-  → send_email.to_email
-```
-
-### Why This Works
-
-1. `entity_extraction` extracts structured data into JSON: `{"email": "user@example.com", "name": "John"}`
-2. `fixed_response` with `{{email}}` template extracts the field and outputs plain text
-3. `fixed_response` output type is `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES` - compatible with `to_email`
-
-### WorkflowSpec Example
-
-```typescript
-{
-  nodes: [
-    {
-      id: "extract_entities_abc123",
-      actionType: "entity_extraction_with_documents",
-      displayName: "Extract Contact Info",
-      // outputs: extraction_columns (JSON)
-    },
-    {
-      id: "format_email_def456",
-      actionType: "fixed_response",
-      displayName: "Format Email Address",
-      inputs: {
-        query: {
-          type: "action_output",
-          actionName: "extract_entities_abc123",
-          output: "extraction_columns"
-        }
-      },
-      config: {
-        response_template: "{{email}}"  // Extracts email field
-      }
-      // outputs: response (text)
-    },
-    {
-      id: "send_email_ghi789",
-      actionType: "send_email_agent",
-      displayName: "Send Email",
-      inputs: {
-        to_email: {
-          type: "action_output",
-          actionName: "format_email_def456",
-          output: "response"
-        },
-        // ... other inputs
-      }
-    }
-  ]
-}
-```
-
-## Alternative: JSON Mapper
-
-For complex extraction or multiple fields:
-
-```
-entity_extraction.extraction_columns 
-  → json_mapper (extracts specific fields)
-  → fixed_response (formats as text)
-  → send_email.to_email
-```
-
-**Note:** `json_mapper` is not in the WorkflowSpec compiler's supported action types. Use `applySpecToWorkflow()` for workflows containing `json_mapper`.
-
-## Common Mistakes
-
-### 1. Direct Wiring
-```
-❌ entity_extraction → send_email.to_email
-```
-Type mismatch. JSON object cannot be used as email address.
-
-### 2. Assuming `.email_address` Output Exists
-```
-❌ entity_extraction.email_address → send_email.to_email
-```
-This output doesn't exist. `entity_extraction` only outputs `extraction_columns`.
-
-### 3. Skipping Template Step
-```
-❌ entity_extraction → json_mapper → send_email.to_email
-```
-Even `json_mapper` output may not be the right type. Always use `fixed_response` as the final step before `send_email` inputs.
-
-## Type Reference
-
-| Action | Output | Type |
-|--------|--------|------|
-| `entity_extraction` | `extraction_columns` | `WELL_KNOWN_TYPE_ANY` (JSON) |
-| `json_mapper` | varies | depends on mapping |
-| `fixed_response` | `response` | `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES` |
-| `call_llm` | `response` | `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES` |
-
-| Input | Expected Type |
-|-------|---------------|
-| `send_email.to_email` | `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES` |
-| `send_email.subject` | `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES` |
-| `send_email.body` | `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES` |

package/docs/mcp-tools-guide.md

@@ -1,575 +0,0 @@
-# Ema MCP Tools Guide (Consolidated)
-
-This MCP server is intentionally designed for **LLM + agent ergonomics**:
-
-- **Self-contained guidance**: Server instructions, tool tips, and response hints are built-in
-- **Few tools, consistent shapes**: a small set of noun-based tools with predictable `mode` / flag patterns
-- **Resources-first**: use `ema://...` resources for reference data/templates, then tools for actions
-- **Low ambiguity**: defaults are chosen to avoid "which of 5 similar tools?" confusion
-- **Explicit mode**: tools with multiple operations require explicit `mode` - they clarify if omitted
-
-> **Note**: No external configuration files (like Cursor rules) are required. All guidance is embedded in the MCP server and delivered via server instructions, tool descriptions, and response tips.
-
-## Tool names in MCP clients
-
-The server defines **base tool names** like `persona`, `template`.
-
-Some clients show a **prefixed name** (for example Cursor: `mcp_ema_persona`). Always call **the tool name your client displays**; the semantics are the same.
-
-## The tool set (7 active tools)
-
-| Tool | Purpose | Mode Required? |
-|------|---------|----------------|
-| `env` | List environments | No (single operation) |
-| `persona` | AI Employee management | **YES** |
-| `data` | Data management + document generation | **YES** |
-| `action` | Actions/agents lookup | No (flag-based) |
-| `template` | Patterns, widgets, questions | No (flag-based) |
-| `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 |
-|------|--------|-------------|
-| `knowledge` | Deprecated | `data` |
-| `demo` | Deprecated | `data` + `persona` |
-
-> **Tip**: For new code, use `persona`, `data`, `workflow`, `sync`.
-
-## ⚠️ THE KEY INSIGHT: ONE CALL
-
-Creating an AI Employee should be **ONE `persona()` call**, not multiple calls.
-
-```typescript
-persona(
-  input="Voice AI SDR: qualifies leads, identifies use-case, sends follow-up email",
-  type="voice",
-  name="Sales SDR",
-  preview=false
-)
-```
-
-**MCP handles internally:** template selection, config generation, widget formatting, API orchestration.
-
-## Start-here flows (LLM-friendly)
-
-### Create a new AI Employee (greenfield)
-
-1. **Get qualifying questions from MCP**: `template(questions=true)`
-2. **Ask user those questions**
-3. **Create in ONE call**:
-   ```typescript
-   persona(
-     input="<everything from user answers>",
-     name="My AI Employee",
-     type="voice",
-     preview=false
-   )
-   ```
-
-### Complex Workflows (email, HITL, multi-intent)
-
-For complex workflows, MCP returns `status: "needs_llm_generation"` with a prompt you send to an LLM:
-
-```typescript
-// Step 1: Request creation
-result = persona(
-  input="SDR that qualifies leads and sends follow-up emails",
-  type="voice",
-  name="Sales SDR",
-  preview=true
-)
-
-// If result.status === "needs_llm_generation":
-// Step 2: Send result.llm_prompt to an LLM (Claude, GPT-4, etc.)
-// Step 3: Deploy the LLM's workflow response
-persona(
-  workflow_def=llm_response_json,
-  name="Sales SDR",
-  type="voice",
-  preview=false
-)
-```
-
-**Simple workflows** (basic Q&A, search + respond) deploy directly without this extra step.
-
-### Modify an existing AI Employee (brownfield)
-
-```typescript
-// Optional: Understand what exists first
-persona(mode="get", id="abc-123")
-
-// Modify config in ONE call
-persona(mode="update", id="abc-123", config={widgets: [{name: "conversationSettings", conversationSettings: {...}}]})
-```
-
-### Get workflow data (for LLM to analyze/modify)
-
-```typescript
-workflow(mode="get", persona_id="abc-123")  // Returns workflow_def, schema, examples
-```
-
-The LLM then analyzes/modifies the workflow and deploys:
-
-```typescript
-workflow(mode="deploy", persona_id="abc-123", workflow_def={...})  // Deploy LLM's result
-```
-
-### Upload / manage knowledge base documents
-
-1. Upload: `data(persona_id="...", mode="upload", file="/path/to/file.pdf")`
-2. Enable embedding: `data(persona_id="...", mode="embedding", enabled=true)`
-3. Verify: `data(persona_id="...", mode="list")`
-
-### Clone and sanitize personas for demo
-
-**Recommended: Use action composition for multi-step operations**
-
-```typescript
-// Clone with data copy and sanitization (recommended)
-persona(
-  method="create",
-  from="source-id",
-  name="Demo Clone",
-  actions=[
-    {tool:"data", args:{method:"copy", from:"$source"}},
-    {tool:"data", args:{method:"sanitize", examples:["Acme Corp", "john@example.com"]}},
-    {tool:"snapshot", args:{message:"Demo ready"}},
-  ]
-)
-
-// Or use built-in aliases for common patterns
-persona(method="create", from="source-id", name="Demo Clone", actions=["copy-and-sanitize"])
-persona(method="create", from="source-id", name="Demo Clone", actions=["standard-demo-setup"])
-```
-
-**Available aliases:**
-- `"copy-data"` - Copy data from source
-- `"copy-and-sanitize"` - Copy then sanitize
-- `"standard-demo-setup"` - Copy, sanitize, snapshot
-
-**Context variables:** `$source` (from param), `$target` (created persona ID), `$env` (environment)
-
-**Legacy syntax (still works):**
-
-```typescript
-// Clone a persona with all data (files + dashboard rows for dashboard personas)
-// Note: Dashboard cloning auto-enables the persona (required for adding rows)
-persona(mode="clone", from="source-id", name="Demo Clone", include_data=true)
-
-// Clone with data sanitization (sanitizes both config and dashboard row data)
-persona(mode="clone", from="source-id", name="Demo Clone", include_data=true, sanitize=true)
-
-// Provide custom examples of sensitive data to sanitize
-persona(mode="clone", from="source-id", name="Demo Clone", include_data=true, sanitize=true, sanitize_examples=["Acme Corp", "john@example.com"])
-```
-
-**Sanitize an existing persona (TWO STEP PROCESS):**
-
-```typescript
-// Step 1: Preview (identifies PII, returns items_needing_review count)
-persona(method="sanitize", id="abc")
-
-// Step 2: Provide known PII values and apply (only works when items_needing_review=0)
-persona(method="sanitize", id="abc", examples=["Acme Corp", "john@example.com"], apply=true)
-```
-
-**Sanitization Notes:**
-- **Two-step process**: First call returns preview with `items_needing_review` count. Changes only apply when `items_needing_review=0` AND `preview=false`
-- **Auto-detects**: emails, phones, SSNs, credit cards (by issuer prefix), API keys, JWTs
-- **NOT detected by default**: UUIDs (typically system IDs like `template_id`, `persona_id`)
-- `sanitize_examples`: for company names, person names, vendor names, custom identifiers - providing these reduces `items_needing_review`
-- **Transforms**: pseudonymize (names → fake names), mask (phones → `***-***-1234`), redact (credentials)
-- **Allowlist approach**: Only content fields sanitized (description, prompts, fixed_response), system fields preserved
-- Dashboard row sanitization: applies to row data during clone
-
-### Dashboard data operations (advanced)
-
-For fine-grained control over dashboard data:
-
-```typescript
-// List rows from a dashboard
-knowledge(persona_id="abc", mode="dashboard_rows")
-
-// Clone dashboard rows separately (usually not needed - use persona clone_data instead)
-knowledge(persona_id="target", mode="dashboard_clone", source_persona_id="source")
-```
-
-### Sync between environments
-
-- Run (single): `sync(id="My Bot", source="demo", target="dev", dry_run=true|false)`
-- Run (all tagged): `sync(target="dev", scope="all", dry_run=true|false)`
-- Status: `sync(mode="status", id="My Bot", env="dev")`
-
-### Version / snapshot AI Employees
-
-```typescript
-// Before a risky change - create a snapshot
-persona(mode="version_create", id="My Bot", message="Before adding HITL")
-
-// Make changes...
-persona(mode="update", id="abc", config={...})
-
-// If something breaks - restore
-persona(mode="version_list", id="My Bot")
-persona(mode="version_restore", id="My Bot", version="v3")
-```
-
-## Tool reference (high-signal)
-
-### `persona` (explicit mode required)
-
-**Mode is required.** If omitted, the tool will ask for clarification.
-
-**List/Get:**
-```typescript
-persona(mode="list")
-persona(mode="list", query="support", status="active")
-persona(mode="get", id="abc")
-persona(mode="get", id="abc", include_workflow=true)
-```
-
-**Create:**
-```typescript
-persona(mode="create", input="<what it does>", type="voice", name="My Bot", preview=false)
-persona(mode="create", from="Voice AI Starter", name="My Bot", input="...", preview=false)
-```
-
-**Update config:**
-```typescript
-persona(mode="update", id="abc", config={widgets: [{...}]})
-```
-
-**Clone:**
-```typescript
-persona(mode="clone", from="source-id", name="My Copy", include_data=true)
-```
-
-**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
-```
-
-**Intent (qualification for complex requests):**
-```typescript
-// GREENFIELD: New persona creation
-persona(mode="intent", input="Voice AI SDR that qualifies leads", type="voice")
-
-// BROWNFIELD: Complex modification to existing persona
-persona(mode="intent", input="Send emails with discussion items and key points", id="abc-123")
-
-// Iterative - provide answers to qualify further
-persona(mode="intent", input="...", previous_answers={gate1_q1: "inbound"}, iteration=2)
-```
-
-Intent mode applies to **both greenfield AND brownfield** scenarios. Use it when:
-- Creating complex new personas (multi-intent, HITL, email, taxonomy)
-- Modifying existing personas with complex changes that may have ripple effects
-- Any request where qualification questions help clarify WHY/WHAT/CONSTRAINTS
-
-Returns:
-- `status: "ready"` → `intent_spec` ready for WorkflowSpec transformation
-- `status: "needs_qualification"` → `questions` to answer before proceeding  
-- `status: "needs_llm"` → `llm_prompt` to send to LLM for IntentSpec generation
-
-For brownfield, use `workflow(mode="get")` to fetch current state, then use intent to qualify the change.
-
-**Templates:**
-```typescript
-persona(mode="templates")
-```
-
-**Version management:**
-```typescript
-persona(mode="version_create", id="abc", message="Before update")
-persona(mode="version_list", id="abc")
-persona(mode="version_restore", id="abc", version="v2")
-persona(mode="version_policy", id="abc", auto_on_deploy=true)
-```
-
-### `template`
-
-**Primary use - Get qualifying questions:**
-```typescript
-template(questions=true)                    // All questions
-template(questions=true, category="Voice")  // Voice-specific
-```
-
-**Reference (understand options):**
-```typescript
-template(patterns=true)
-template(pattern="intent-routing")
-template(widgets="voice")
-```
-
-### `action`
-
-```typescript
-action(id="chat_categorizer", include_docs=true)   // Get specific
-action(all=true)                                    // List all
-action(suggest="IT helpdesk with ServiceNow")      // Get recommendations
-```
-
-### `reference` (v2 expanded)
-
-**Environments:**
-```typescript
-reference(type="envs")
-```
-
-**Actions (replaces `action` tool):**
-```typescript
-reference(type="actions")                     // List all
-reference(type="actions", id="send_email")    // Get specific
-reference(type="actions", suggest="IT helpdesk")  // Recommendations
-```
-
-**Templates & Patterns:**
-```typescript
-reference(type="templates")                   // Persona templates (dynamic, tenant-specific)
-reference(type="patterns")                    // Workflow patterns
-reference(type="patterns", pattern="intent-routing")
-reference(type="widgets", persona_type="voice")
-```
-
-> **Note:** Templates are tenant-specific. Always use `reference(type="templates")` to discover available templates rather than hardcoding template IDs.
-
-**Concepts & Guidance:**
-```typescript
-reference(concept="HITL")
-reference(guidance="categorizer-routing")
-reference(questions=true)                     // Qualifying questions
-```
-
-**Debugging:**
-```typescript
-reference(mistakes=true)
-reference(checklist=true)
-reference(execution=true)
-```
-
-### `data` (explicit mode required)
-
-**Mode is required.** If omitted, the tool will ask for clarification.
-
-**List files:**
-```typescript
-data(persona_id="abc", mode="list")
-data(persona_id="abc", mode="list", limit=50)
-```
-
-**Get specific file:**
-```typescript
-data(persona_id="abc", mode="get", file_id="file-123")
-```
-
-**Upload/Delete:**
-```typescript
-data(persona_id="abc", mode="upload", file="/path/to/file.pdf")
-data(persona_id="abc", mode="delete", file_id="file-123")
-```
-
-**Upload to specific widget (Document Generation personas):**
-```typescript
-// Document Proposal Manager widget names (verified from template):
-data(persona_id="abc", mode="upload", file="/path/to/company.pdf", widget_name="upload")      // Content Repository
-data(persona_id="abc", mode="upload", file="/path/to/service-line.pdf", widget_name="upload1") // Service Line Documents
-data(persona_id="abc", mode="upload", file="/path/to/style-guide.pdf", widget_name="upload2")  // Style Guide
-```
-
-> **Important for Document Generation (Proposal Writer) personas:** Files must be uploaded to the correct widget to appear in the right repository in the UI. Without `widget_name`, files go to the default `fileUpload` widget which may not be visible in the Configuration tab.
->
-> **Document Proposal Manager widgets:** `upload` (Content Repository), `upload1` (Service Line Documents), `upload2` (Style Guide)
->
-> **For other templates:** Call `persona(id="abc", include_workflow=true)` and inspect `proto_config.widgets[].name` to find the exact widget names.
-
-**Generate content (via Document Generation API):**
-```typescript
-// From a template
-data(persona_id="abc", mode="generate", from="customer", count=5)
-data(persona_id="abc", mode="generate", from="demo-sales-sdr")
-
-// From natural language
-data(persona_id="abc", mode="generate", input="Generate 5 B2B customer profiles")
-
-// List available templates
-data(mode="templates")
-data(mode="templates", template="customer")  // Get template details
-```
-
-**Available templates:** `customer`, `product`, `faq`, `employee`, `demo-sales-sdr`, `demo-support`, `demo-hr`, `countries`, `industries`, `currencies`
-
-**Sanitize persona data:**
-```typescript
-data(persona_id="abc", mode="sanitize")
-data(persona_id="abc", mode="sanitize", include_workflow=true)
-```
-
-**File Stats:**
-```typescript
-data(persona_id="abc", mode="stats")                    // Get file counts
-data(persona_id="abc", mode="stats", widget_name="kb")  // Filter by widget
-// Returns: { total: 50, pending: 5, success: 40, failed: 5 }
-```
-
-**Replicate (copy by reference - fast, no file transfer):**
-```typescript
-// Copy knowledge base from source to target (references S3 objects, no re-upload)
-data(persona_id="target-id", mode="replicate", from="source-id")
-
-// With custom widget mappings
-data(persona_id="target-id", mode="replicate", from="source-id", 
-     widget_mappings=[{source_widget: "docs", target_widget: "documents"}])
-
-// Async (don't wait for completion)
-data(persona_id="target-id", mode="replicate", from="source-id", wait=false)
-```
-
-> **Note:** `replicate` is much faster than copying files. It copies S3 references instead of downloading and re-uploading. Use `mode="copy"` if you need to sanitize data during transfer.
-
-**Embedding:**
-```typescript
-data(persona_id="abc", mode="embedding")              // Get status
-data(persona_id="abc", mode="embedding", enabled=true) // Toggle
-```
-
-## Resources (read-first)
-
-Start with:
-
-- `ema://index/all-resources` (index)
-- `ema://docs/readme` (toolkit overview)
-- `ema://catalog/agents-summary` (quick agent overview)
-- `ema://catalog/templates` (persona templates - dynamic)
-- `ema://rules/anti-patterns` (what NOT to do)
-
-## Workflow Generation (LLM Does the Work)
-
-**MCP provides data and schema. LLM generates workflow_def.**
-
-```typescript
-// 1. Get current workflow + schema (includes deprecation_warnings!)
-result = workflow(mode="get", persona_id="abc")
-// Returns: workflow_def, generation_schema, example_workflow, requirements, deprecation_warnings
-
-// 2. LLM analyzes and generates new workflow_def
-// (LLM uses schema and examples to build valid workflow)
-// ⚠️ FIX any deprecated actions FIRST - check deprecation_warnings!
-
-// 3. Deploy LLM's result (preview first!)
-workflow(mode="deploy", persona_id="abc", workflow_def={...}, preview=true)
-workflow(mode="deploy", persona_id="abc", workflow_def={...})
-```
-
-### ⚠️ CRITICAL: Check Deprecated Actions First
-
-**BEFORE generating any workflow:**
-
-1. Check `deprecation_warnings` in `workflow(mode="get")` response
-2. Use `reference(type="actions")` to verify current versions
-3. **NEVER** copy workflow patterns from existing personas (they may use deprecated actions!)
-
-**Correct workflow pattern:**
-```
-chat_trigger → search/v2 → respond_for_external_actions → WORKFLOW_OUTPUT
-```
-
-**Deprecated (DO NOT USE):**
-```
-search/v0 → Use search/v2
-respond_with_sources → Use respond_for_external_actions
-call_llm/v0 → Use call_llm/v2
-```
-
-**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
-- **Using deprecated actions** (check deprecation_warnings!)
-
-## HITL (Human-in-the-Loop) Policy
-
-**HITL is opt-in, not forced by default.**
-
-| Scenario | Default | How to Add HITL |
-|----------|---------|-----------------|
-| Send email | ❌ No HITL | `persona(mode="update", id="...", input="add approval before sending")` |
-| External API | ❌ No HITL | Request explicitly in input |
-| Create records | ❌ No HITL | Request explicitly in input |
-
-## Auto Builder Prompt Length Limits
-
-**⚠️ CRITICAL:** Auto Builder has strict prompt length limits (~2500 chars).
-
-### Good Prompt Format
-```text
-Voice AI for [use case]. Supports [capabilities].
-
-Core Capabilities:
-1. Intent A - Brief description
-2. Intent B - Brief description
-3. Fallback - Handle unclear requests
-
-Rules:
-• Rule 1
-• Rule 2
-```
-
-### Bad Prompt Format (Times Out)
-- Narrative descriptions with multiple paragraphs
-- Example conversations embedded in prompt
-- Prompts > 2500 characters
-
-## Deprecated Tools
-
-### `workflow` → use `persona`
-
-```typescript
-// OLD (deprecated)
-workflow(input="...", type="voice", name="Bot", preview=false)
-
-// NEW
-persona(input="...", type="voice", name="Bot", preview=false)
-```
-
-### `knowledge` → use `data`
-
-```typescript
-// OLD (deprecated)
-knowledge(persona_id="abc", mode="list")
-knowledge(persona_id="abc", mode="upload", file="...")
-knowledge(persona_id="abc", mode="status")
-knowledge(persona_id="abc", mode="toggle", enabled=true)
-
-// NEW
-data(persona_id="abc", mode="list")
-data(persona_id="abc", mode="upload", file="...")
-data(persona_id="abc", mode="embedding")
-data(persona_id="abc", mode="embedding", enabled=true)
-```
-
-### `demo` → use `data` + `persona`
-
-```typescript
-// OLD (deprecated)
-demo(mode="generate", entity="customer", data={...})
-demo(mode="scenarios")
-demo(mode="template", entity="customer")
-
-// NEW
-data(persona_id="abc", mode="generate", from="customer", data={...})
-data(mode="templates")
-data(mode="templates", template="customer")
-```