@ema.co/mcp-toolkit 2026.1.24 → 2026.1.26-3

package/docs/tool-consolidation-v2.md

@@ -1,225 +0,0 @@
-# MCP Tool Consolidation v2
-
-> **Status: IMPLEMENTED** (v2026.01.17)
-
-## Overview
-
-Consolidate tools with cleaner separation of concerns.
-
-**Primary tools (use these):**
-- `persona` - AI Employee management
-- `data` - Persona data management  
-- `reference` - All reference info (envs, actions, templates, patterns, concepts)
-- `sync` - Cross-environment sync
-
-**Legacy tools (still work, route to primary):**
-- `env`, `action`, `template`, `knowledge`, `demo`
-
-## Final Tool Design
-
-### 1. `persona` - Manage AI Employees
-
-```typescript
-persona(
-  id?: string,                    // get specific persona
-  query?: string,                 // search by name
-  all?: boolean,                  // list all
-  
-  // Create/Clone
-  name?: string,                  // for create
-  type?: "voice" | "chat" | "dashboard",
-  input?: string,                 // natural language description
-  clone_from?: string,            // clone source persona ID
-  clone_data?: boolean,           // also clone files
-  sanitize?: boolean,             // sanitize PII during clone
-  
-  // Update
-  enabled?: boolean,              // enable/disable
-  
-  // Compare
-  compare_to?: string,            // compare two personas
-  
-  // Output control
-  include_workflow?: boolean,     // include workflow_def in response
-)
-```
-
-**Examples:**
-```
-persona(all=true)                              # list all
-persona(id="abc-123")                          # get specific
-persona(query="support")                       # search
-persona(name="My Bot", type="voice", input="...") # create
-persona(clone_from="abc", name="Clone", clone_data=true, sanitize=true)
-```
-
----
-
-### 2. `data` - Manage Persona Data
-
-```typescript
-data(
-  persona_id: string,             // REQUIRED - data belongs to persona
-  mode?: "list" | "get" | "upload" | "delete" | "sanitize",  // default: list
-  file_id?: string,               // for get/delete specific
-  include_results?: boolean,      // for dashboard: show extracted values
-)
-```
-
-**Examples:**
-```
-data(persona_id="abc")                         # list files
-data(persona_id="abc", file_id="x")            # get file details
-data(persona_id="abc", mode="upload")          # upload (file from context)
-data(persona_id="abc", mode="delete", file_id="x")
-data(persona_id="abc", mode="sanitize")        # sanitize all data
-data(persona_id="abc", include_results=true)   # list with extraction results
-```
-
-**For dashboard personas, file listing includes:**
-```json
-{
-  "files": [{
-    "id": "file-123",
-    "name": "contract.pdf",
-    "processing": {
-      "status": "success",
-      "extracted": { "vendor": "Acme", "amount": "$50k" }
-    }
-  }]
-}
-```
-
----
-
-### 3. `workflow` - Workflow Operations
-
-```typescript
-workflow(
-  persona_id?: string,            // target persona
-  
-  // Generate/Modify
-  input?: string,                 // natural language description
-  
-  // Analyze
-  analyze?: boolean,              // analyze current workflow
-  optimize?: boolean,             // suggest optimizations
-  
-  // Deploy
-  workflow_def?: object,          // direct workflow deployment
-  preview?: boolean,              // preview without deploying (default: true)
-)
-```
-
-**Examples:**
-```
-workflow(persona_id="abc", input="Add email notification")
-workflow(persona_id="abc", analyze=true)
-workflow(persona_id="abc", optimize=true, preview=false)
-```
-
----
-
-### 4. `reference` - All Reference Information
-
-```typescript
-reference(
-  type?: "actions" | "templates" | "patterns" | "envs" | "concepts" | "guidance",
-  
-  // For actions
-  action_id?: string,             // get specific action
-  query?: string,                 // search
-  suggest?: string,               // suggest actions for use case
-  
-  // For guidance
-  topic?: string,                 // guidance topic
-  
-  // For concepts
-  concept?: string,               // specific concept
-  
-  // Validation helpers
-  check_types?: { source: string, target: string },
-  validate_prompt?: string,
-)
-```
-
-**Examples:**
-```
-reference(type="actions")                      # list all actions
-reference(type="actions", query="email")       # search actions
-reference(type="actions", suggest="IT helpdesk")
-reference(action_id="send_email")              # get specific action
-reference(type="templates")                    # list workflow templates
-reference(type="patterns")                     # list patterns
-reference(type="envs")                         # list environments
-reference(type="concepts")                     # list concepts
-reference(concept="HITL")                      # get specific concept
-reference(type="guidance", topic="categorizer-routing")
-```
-
----
-
-### 5. `sync` - Environment Sync
-
-```typescript
-sync(
-  id?: string,                    // persona ID or name
-  target?: string,                // target environment
-  dry_run?: boolean,              // simulate without changes
-  
-  // Status
-  mode?: "run" | "status" | "config",
-  list_synced?: boolean,          // list all synced personas
-)
-```
-
-**Examples:**
-```
-sync(id="IT Support", target="dev")
-sync(id="abc-123", target="staging", dry_run=true)
-sync(mode="status", id="abc-123")
-sync(mode="config")
-```
-
----
-
-## Migration Path
-
-| Old Tool | New Location |
-|----------|--------------|
-| `env` | `reference(type="envs")` |
-| `knowledge` | `data` |
-| `demo` | Removed (generate separately or future addition) |
-| `action` | `reference(type="actions")` |
-| `template` | `reference(type="templates")` / `reference(type="patterns")` |
-
-## Mental Model
-
-```
-┌─────────────────────────────────────────┐
-│              PERSONA                    │
-│  ┌─────────┐  ┌──────────┐             │
-│  │  data   │  │ workflow │             │
-│  └─────────┘  └──────────┘             │
-└─────────────────────────────────────────┘
-         │              │
-         └──────┬───────┘
-                │
-    ┌───────────▼───────────┐
-    │      reference        │  (actions, templates, guidance)
-    └───────────────────────┘
-                │
-    ┌───────────▼───────────┐
-    │        sync           │  (copy between envs)
-    └───────────────────────┘
-```
-
-## Implementation Checklist
-
-- [x] Update `tools-consolidated.ts` with new tool definitions
-- [x] Update `handlers-consolidated.ts` with routing logic  
-- [x] Add `data` tool (wraps knowledge with simplified interface)
-- [x] Expand `reference` to support type="envs|actions|templates|patterns|widgets"
-- [x] Update tests
-- [x] Update documentation
-- [x] Keep legacy tools for backwards compatibility (they still work)

package/docs/tool-response-standards.md

@@ -1,256 +0,0 @@
-# MCP Tool Response Standards
-
-Uniform structure and formatting rules for all MCP tool responses.
-
-## Core Principles
-
-1. **Explicit over implicit**: Always return clear status, never silently succeed/fail
-2. **Actionable responses**: Include next steps, commands, or guidance
-3. **Consistent shape**: Same response structure within each mode category
-4. **Progressive disclosure**: Summary first, details on request
-
-## Response Categories
-
-### 1. Success Responses
-
-```typescript
-{
-  status: "success",
-  // Primary result data
-  [result_key]: data,
-  // Optional metadata
-  _meta?: {
-    duration_ms?: number;
-    cached?: boolean;
-  }
-}
-```
-
-### 2. Error Responses
-
-```typescript
-{
-  status: "error",
-  error: "Short error message",
-  details?: "Longer explanation",
-  suggestion?: "How to fix",
-  code?: "ERROR_CODE"
-}
-```
-
-### 3. Clarification Responses
-
-When mode is omitted or ambiguous:
-
-```typescript
-{
-  status: "clarification_needed",
-  message: "What operation would you like?",
-  suggested_mode?: "mode_name",  // If intent is detectable
-  options: ["mode1", "mode2", ...],
-  hint?: "Use mode='...' for direct execution",
-  examples?: ["command1", "command2"]
-}
-```
-
-### 4. Analysis Responses
-
-For analyze/review/audit operations:
-
-```typescript
-{
-  status: "healthy" | "issues_found" | "critical",
-  summary: {
-    total_issues: number,
-    by_severity: { critical: number, warning: number, info: number },
-    by_category?: Record<string, number>
-  },
-  issues: Array<{
-    id: string,
-    severity: "critical" | "warning" | "info",
-    category: string,
-    title: string,
-    description: string,
-    auto_fixable: boolean,
-    fix_description?: string
-  }>,
-  next_steps: {
-    auto_fix_available: boolean,
-    command?: string,
-    manual_actions?: string[]
-  }
-}
-```
-
-### 5. List Responses
-
-```typescript
-{
-  count: number,
-  [items_key]: Array<item>,  // e.g., "personas", "files", "templates"
-  // Optional pagination
-  pagination?: {
-    offset: number,
-    limit: number,
-    has_more: boolean
-  }
-}
-```
-
-### 6. Single Item Responses
-
-```typescript
-{
-  id: string,
-  name?: string,
-  // ... item-specific fields
-  _meta?: {
-    retrieved_at: string,
-    source: string
-  }
-}
-```
-
-## Mode + Flag Pattern
-
-### Rule: Mode defines WHAT, flags define HOW
-
-```typescript
-// Mode = the operation type
-mode: "analyze" | "list" | "get" | "create" | "update" | "delete" | ...
-
-// Flags modify the operation behavior
-fix: boolean       // Auto-apply fixes (for analyze)
-preview: boolean   // Don't persist changes (for create/update)
-include: string[]  // What to include in response
-force: boolean     // Skip confirmations
-```
-
-### Anti-Pattern: Mode as flag
-
-```typescript
-// ❌ BAD: Using mode to toggle behavior
-mode: "optimize"  // This is just mode="analyze" + fix=true
-
-// ✅ GOOD: Clear mode + flag
-mode: "analyze", fix: true
-```
-
-### Anti-Pattern: Flag that changes operation type
-
-```typescript
-// ❌ BAD: Flag changes what the operation does
-mode: "get", optimize: true  // Does this get or optimize?
-
-// ✅ GOOD: Mode is explicit
-mode: "analyze", fix: true   // Analyze and apply fixes
-```
-
-## Severity Levels
-
-| Level | Meaning | Action |
-|-------|---------|--------|
-| `critical` | Breaks functionality, must fix | Block deployment |
-| `warning` | Degraded behavior, should fix | Warn on deployment |
-| `info` | Improvement opportunity | Optional |
-
-## Standard Fields
-
-### Identifiers
-
-- `id` - Primary identifier (UUID preferred)
-- `name` - Human-readable name
-- `identifier` - DEPRECATED, use `id`
-
-### Status
-
-- `status` - Current state: "active", "inactive", "draft", "error"
-- `enabled` - Boolean toggle
-
-### Timestamps
-
-- Use ISO 8601 format
-- Field names: `created_at`, `updated_at`, `retrieved_at`
-
-## Tool-Specific Standards
-
-### persona tool
-
-| Mode | Primary Response Key | Status Field |
-|------|---------------------|--------------|
-| list | `personas` | `count` |
-| get | (flat object) | `status` |
-| create | `persona_id`, `name` | `success` |
-| update | `updated` | `success` |
-| analyze | `issues` | `status` (healthy/issues_found/critical) |
-
-### data tool
-
-| Mode | Primary Response Key | Status Field |
-|------|---------------------|--------------|
-| list | `files` | `count` |
-| get | (flat object) | - |
-| upload | `file_id` | `success` |
-| generate | `document` | `status` |
-| analyze | `issues` | `status` |
-
-### sync tool
-
-| Mode | Primary Response Key | Status Field |
-|------|---------------------|--------------|
-| run | `synced` | `success` |
-| status | `sync_status` | `status` |
-| config | `config` | - |
-
-## Example: Uniform Analyze Response
-
-```json
-{
-  "status": "issues_found",
-  "summary": {
-    "total_issues": 5,
-    "by_severity": { "critical": 0, "warning": 2, "info": 3 },
-    "by_category": { "workflow": 3, "config": 1, "data": 1 }
-  },
-  "issues": [
-    {
-      "id": "orphaned-node-1",
-      "severity": "warning",
-      "category": "workflow",
-      "title": "Orphaned node: general_inquiry handler",
-      "description": "Node 'call_llm_general' has no incoming connections",
-      "auto_fixable": true,
-      "fix_description": "Remove orphaned node"
-    },
-    {
-      "id": "missing-embedding-1",
-      "severity": "info",
-      "category": "data",
-      "title": "File without embedding",
-      "description": "company-faq.pdf has embedding disabled",
-      "auto_fixable": true,
-      "fix_description": "Enable embedding for file"
-    }
-  ],
-  "next_steps": {
-    "auto_fix_available": true,
-    "command": "persona(mode=\"analyze\", id=\"...\", fix=true)",
-    "manual_actions": [
-      "Review orphaned node before removal",
-      "Verify FAQ file should be searchable"
-    ]
-  }
-}
-```
-
-## Checklist for New Modes
-
-When adding a new mode to any tool:
-
-- [ ] Response follows category pattern (success/error/list/analysis)
-- [ ] Error responses include `suggestion` field
-- [ ] Status field uses standard values
-- [ ] Identifiers use `id` not `identifier`
-- [ ] List responses have `count` + array field
-- [ ] Analysis responses have `summary` + `issues` + `next_steps`
-- [ ] Flags don't change operation type (only modify behavior)

package/resources/docs/getting-started.md

@@ -1,97 +0,0 @@
-# Getting Started with Ema MCP
-
-Welcome! This guide helps you work effectively with Ema AI Employees.
-
-## First Steps
-
-### 1. List Available Personas
-```
-persona(mode="list")
-```
-
-### 2. Get Details on One
-```
-persona(mode="get", id="persona-name-or-id")
-```
-
-### 3. Create Your First AI Employee
-```
-persona(mode="create", name="My Assistant", type="voice", input="Handles customer support inquiries", preview=true)
-```
-
-## Key Concepts
-
-| Term | Meaning |
-|------|---------|
-| **Persona** | An AI Employee (Voice, Chat, or Dashboard) |
-| **Workflow** | The logic that powers a persona |
-| **Action** | A building block in workflows (search, email, ticket, etc.) |
-| **HITL** | Human-in-the-loop - approval before taking action |
-
-## Essential Rules
-
-### 1. Always Preview First
-```
-preview=true   # Safe - shows what would happen
-preview=false  # Deploys to production
-```
-
-### 2. One Call, Complete Information
-Don't make multiple calls. Put all parameters in one call:
-```
-# ✅ Good
-persona(mode="create", name="Bot", type="voice", input="...", preview=false)
-
-# ❌ Bad - multiple calls
-persona(mode="create", name="Bot")
-persona(mode="update", ...)
-```
-
-### 3. Ask Before Creating
-Before creating a new persona, ask:
-- What should it do? (purpose)
-- What type? (voice/chat/dashboard)
-- What name?
-
-### 4. Use Templates
-List available templates:
-```
-persona(mode="templates")
-```
-
-Create from template (recommended):
-```
-persona(mode="create", from="Voice AI Starter", name="My SDR", preview=false)
-```
-
-## Common Operations
-
-| Task | Command |
-|------|---------|
-| List all personas | `persona(mode="list")` |
-| Get one | `persona(mode="get", id="...")` |
-| Create new | `persona(mode="create", name="...", type="voice", input="...")` |
-| Update | `persona(mode="update", id="...", proto_config={...})` |
-| Analyze issues | `persona(mode="analyze", id="...")` |
-| Compare two | `persona(mode="compare", id="...", compare_to="...")` |
-
-## Getting Help
-
-- **List actions**: `action(all=true)`
-- **Get guidance**: `reference(guidance="hitl-patterns")`
-- **Common mistakes**: `reference(mistakes=true)`
-- **Check templates**: `template(patterns=true)`
-
-## Environments
-
-Most users have multiple environments (demo, staging, prod).
-
-```
-# List environments
-env()
-
-# Target specific environment
-persona(mode="list", env="prod")
-```
-
-Default is usually `demo` (safe for testing).