@ema.co/mcp-toolkit 2026.1.25 → 2026.1.26-4

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/demo-kits/README.md

@@ -1,175 +0,0 @@
-# Demo Kits
-
-Pre-packaged demo resources for Ema AI Employee demonstrations. Each kit includes personas, demo scripts, sample data, and validation queries.
-
-## Available Demo Kits
-
-| Kit ID | Name | Domain | Personas | Tags |
-|--------|------|--------|----------|------|
-| `finance-ap` | Finance - Accounts Payable | Finance | 2 | `finance`, `invoice`, `automation` |
-| `finance-ar` | Finance - Accounts Receivable | Finance | 1 | `finance`, `billing`, `revenue` |
-| `sales-sdr` | Sales Development | Sales | 2 | `sales`, `outbound`, `prospecting` |
-| `support-tier1` | Customer Support T1 | Support | 2 | `support`, `voice`, `chat` |
-| `hr-assistant` | HR Policy Assistant | HR | 1 | `hr`, `policy`, `benefits` |
-
-## Kit Structure
-
-Each demo kit contains:
-
-```
-demo-kits/
-├── {kit-id}/
-│   ├── manifest.json      # Kit metadata, personas, tags
-│   ├── demo-script.md     # Talk track, objections, ROI
-│   ├── sample-data/       # Demo data files
-│   │   ├── input.json     # Sample inputs
-│   │   └── expected.json  # Expected outputs
-│   └── validation/
-│       └── queries.json   # Pre/post-demo validation queries
-```
-
-## Usage
-
-### List Available Kits
-
-```
-reference(demo_kits=true)
-```
-
-### Get Kit Details
-
-```
-reference(demo_kit="finance-ap")
-```
-
-### Generate Demo for Persona
-
-```
-persona(method="demo_kit", id="{persona_id}", kit="finance-ap")
-```
-
-### Validate Demo Readiness
-
-```
-persona(method="validate", id="{persona_id}", checks=["demo_ready"])
-```
-
-## Tagging System
-
-Demo kits and personas use a consistent tagging system:
-
-### Domain Tags
-- `finance` - Financial operations (AP, AR, Treasury)
-- `sales` - Sales and revenue operations
-- `support` - Customer support and service
-- `hr` - Human resources
-- `it` - IT operations and security
-- `legal` - Legal and compliance
-- `marketing` - Marketing operations
-
-### Capability Tags
-- `voice` - Voice/phone interactions
-- `chat` - Chat/messaging interactions
-- `dashboard` - Dashboard/data processing
-- `document` - Document generation
-- `automation` - Process automation
-- `analysis` - Data analysis
-
-### Use Case Tags
-- `invoice` - Invoice processing
-- `billing` - Billing operations
-- `onboarding` - Employee/customer onboarding
-- `compliance` - Compliance and audit
-- `reporting` - Reporting and analytics
-
-## Creating a Demo Kit
-
-1. Create a folder in `demo-kits/`
-2. Add `manifest.json` with kit metadata
-3. Add `demo-script.md` with talk track
-4. Add sample data and validation queries
-5. Register personas in manifest
-
-### Manifest Schema
-
-```json
-{
-  "id": "kit-id",
-  "name": "Kit Display Name",
-  "version": "1.0.0",
-  "description": "What this kit demonstrates",
-  "domain": "finance|sales|support|hr|it|legal|marketing",
-  "tags": ["tag1", "tag2"],
-  "personas": [
-    {
-      "id": "uuid",
-      "name": "Persona Name",
-      "role": "primary|supporting",
-      "description": "What this persona does in the demo"
-    }
-  ],
-  "prerequisites": {
-    "integrations": ["coupa", "salesforce"],
-    "data": ["sample-invoices"],
-    "environment": "demo"
-  },
-  "demo_flow": [
-    {
-      "step": 1,
-      "title": "Setup",
-      "duration_minutes": 2,
-      "actions": ["Load persona", "Prepare data"]
-    }
-  ],
-  "target_audience": {
-    "primary": "AP Manager",
-    "secondary": ["CFO", "IT Director"],
-    "company_size": "mid-market",
-    "industries": ["manufacturing", "retail"]
-  },
-  "roi_metrics": {
-    "time_saved_per_unit": "15 minutes",
-    "volume_per_month": 10000,
-    "cost_per_unit_before": 12,
-    "cost_per_unit_after": 1.5
-  }
-}
-```
-
-## Bundling Multiple Kits
-
-Create meta-kits that combine related demos:
-
-```json
-{
-  "id": "finance-complete",
-  "name": "Complete Finance Automation",
-  "type": "bundle",
-  "includes": ["finance-ap", "finance-ar", "finance-reporting"],
-  "tags": ["finance", "bundle", "enterprise"]
-}
-```
-
-## Integration with Persona Tool
-
-The `persona` tool supports kit-related operations:
-
-```
-# Tag a persona
-persona(method="update", id="...", tags=["finance", "invoice"])
-
-# Find personas by tag
-persona(method="list", tags=["finance"])
-
-# Get demo kit for persona
-persona(method="demo_kit", id="...")
-```
-
-## Quality Standards
-
-Each demo kit must:
-- [ ] Have validated sample data
-- [ ] Include error handling scenarios
-- [ ] Work in demo environment
-- [ ] Include realistic ROI numbers
-- [ ] Have tested validation queries