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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "2026.1.27",
+  "version": "2026.1.28-2",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",

package/dist/mcp/workflow-operations.js

@@ -1,100 +0,0 @@
-/**
- * Workflow Operations - Single Source of Truth
- *
- * This file defines supported workflow modification operations.
- * Used by:
- * - analyzeModificationRequest() in handlers-consolidated.ts
- * - Tool descriptions in tools.ts
- * - Tests to verify capabilities
- *
- * Add new operations here, and they'll automatically appear in tool docs.
- */
-/**
- * Supported incremental workflow modifications.
- * These are what `persona(method="update", input="...")` can handle.
- */
-export const SUPPORTED_OPERATIONS = [
-    {
-        type: "add",
-        name: "Add HITL/approval",
-        triggers: ["add hitl", "add approval", "confirm before", "human review"],
-        example: "add HITL before email",
-        notes: "Adds general_hitl node before specified action",
-    },
-    {
-        type: "remove",
-        name: "Remove nodes",
-        triggers: ["remove", "delete", "clean up orphan"],
-        example: "remove the search node",
-        notes: "Can remove specific nodes or orphan nodes",
-    },
-    {
-        type: "replace",
-        name: "Replace nodes",
-        triggers: ["replace X with Y", "swap", "use instead of"],
-        example: "replace LLM extraction with entity_extraction",
-    },
-    {
-        type: "consolidate",
-        name: "Consolidate nodes",
-        triggers: ["consolidate", "merge", "combine into one"],
-        example: "consolidate the 8 custom agents into one",
-    },
-    {
-        type: "rewire",
-        name: "Rewire connections",
-        triggers: ["connect", "wire", "link X to Y"],
-        example: "connect search output to response",
-    },
-];
-/**
- * Limitations of INCREMENTAL modifications (persona method="update" with input).
- * For complex workflows, use the workflow tool instead.
- */
-export const LIMITATIONS = [
-    "Build complex multi-node workflows from scratch → use workflow(mode='generate')",
-    "Add multiple interconnected nodes at once → use workflow(mode='generate')",
-];
-/**
- * Alternative approaches for complex workflows.
- */
-export const ALTERNATIVES = {
-    complexWorkflow: "workflow(mode='generate', input='...') for multi-node generation",
-    cloneExisting: "persona(method='create', from='similar-persona-id', name='New Name')",
-};
-/**
- * Generate tool description for the `input` parameter.
- * Called by tools.ts to ensure description matches actual capabilities.
- */
-export function generateInputDescription() {
-    const ops = SUPPORTED_OPERATIONS.map(op => op.example).join("', '");
-    return `Incremental workflow changes. Supports: '${ops}'. For complex multi-node workflows, clone from existing persona instead.`;
-}
-/**
- * Generate detailed capabilities for tool help text.
- */
-export function generateCapabilitiesHelp() {
-    const lines = [
-        "## Supported Workflow Modifications",
-        "",
-        "The `input` parameter supports these INCREMENTAL changes:",
-        "",
-    ];
-    for (const op of SUPPORTED_OPERATIONS) {
-        lines.push(`- **${op.name}**: \`${op.example}\``);
-        if (op.notes) {
-            lines.push(`  - ${op.notes}`);
-        }
-    }
-    lines.push("");
-    lines.push("## NOT Supported (use clone instead)");
-    lines.push("");
-    for (const limit of LIMITATIONS) {
-        lines.push(`- ${limit}`);
-    }
-    lines.push("");
-    lines.push("## For Complex Workflows");
-    lines.push("");
-    lines.push(`Clone from existing: \`${ALTERNATIVES.complexWorkflow}\``);
-    return lines.join("\n");
-}

package/dist/sdk/workflow-fixer.js

@@ -1,48 +0,0 @@
-/**
- * Workflow Fixer (SDK)
- *
- * DEPRECATED: This module used detectWorkflowIssues which has been removed.
- *
- * The LLM should analyze workflows using rules from:
- * - ema://rules/anti-patterns
- * - ema://rules/input-sources
- * - ema://rules/optimizations
- *
- * And then make structured modifications via:
- * - workflow(mode="deploy", workflow_def={...})
- * - persona(mode="update", operations=[...])
- *
- * This file is kept for backwards compatibility with minimal functionality.
- */
-// ═══════════════════════════════════════════════════════════════════════════
-// DEPRECATED FUNCTIONS (no-ops)
-// ═══════════════════════════════════════════════════════════════════════════
-/**
- * DEPRECATED: Auto-fix workflow issues.
- *
- * This function now returns the workflow unchanged with a deprecation warning.
- * Use LLM analysis with ema://rules/* instead.
- */
-export function autoFixWorkflow(workflowDef) {
-    return {
-        workflowDef: workflowDef,
-        fixesApplied: [],
-        success: true,
-        warnings: [
-            "DEPRECATED: autoFixWorkflow() no longer auto-fixes issues.",
-            "Use LLM analysis with ema://rules/anti-patterns instead.",
-        ],
-    };
-}
-/**
- * DEPRECATED: Suggest fixes for workflow issues.
- *
- * This function now returns empty results with a deprecation warning.
- * Use LLM analysis with ema://rules/* instead.
- */
-export function suggestFixes(_workflowDef) {
-    return {
-        standardFixes: [],
-        multiResponderFixes: [],
-    };
-}

package/docs/dashboard-operations.md

@@ -1,281 +0,0 @@
-# Dashboard Operations
-
-## Overview
-
-Dashboard-type AI Employees process data in batches. Each row in a dashboard represents one execution of the workflow with specific inputs.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Dashboard Persona                        │
-├─────────────────────────────────────────────────────────────────┤
-│  workflow_dashboard_id: "dashboard-uuid"                        │
-│  trigger_type: DOCUMENT_TRIGGER                                 │
-└─────────────────────────────────────────────────────────────────┘
-         │
-         ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                         Dashboard                               │
-├────────────┬──────────────┬─────────────┬──────────────────────┤
-│   Schema   │  Input Cols  │ Output Cols │       Rows           │
-├────────────┼──────────────┼─────────────┼──────────────────────┤
-│ columnId   │ name, type   │ name, type  │ id, state, values    │
-└────────────┴──────────────┴─────────────┴──────────────────────┘
-```
-
-## SDK Methods
-
-| Method | Purpose | Key Parameters |
-|--------|---------|----------------|
-| `getDashboardRows()` | List rows with schema | `dashboardId`, `personaId`, `{ limit }` |
-| `getDashboardRowResult()` | Get single row | `personaId`, `rowId`, `includeFileContents?` |
-| `uploadAndRunDashboardRow()` | Create new row | `personaId`, `inputs[]` |
-| `rerunDashboardRow()` | Re-execute workflow | `personaId`, `rowId` |
-
-### Input Types (DashboardInput)
-
-```typescript
-type DashboardInput = {
-  name: string;                   // Column name (required)
-  string_value?: string;          // Text input
-  number_value?: number;          // Numeric input
-  boolean_value?: boolean;        // Boolean input
-  document_value?: Array<{        // File input
-    name: string;                 // Filename
-    contents: string;             // Base64-encoded content
-    is_base64_encoded: boolean;   // Always true for documents
-    mime_type: string;            // e.g., "application/pdf"
-  }>;
-};
-```
-
-## MCP Tool: Data Operations
-
-### Purpose
-Clone rows from one dashboard persona to another. Useful for:
-- Creating demo environments with real data structure
-- Testing with sanitized production data
-- Duplicating configurations across personas
-
-### Recommended: Action Composition
-
-Use the `actions` array when creating/cloning personas:
-
-```typescript
-// Clone persona with data copy and sanitization
-persona(
-  method="create",
-  from="source-persona-uuid",
-  name="Demo Dashboard",
-  actions=[
-    {tool:"data", args:{method:"copy", from:"$source"}},
-    {tool:"data", args:{method:"sanitize", examples:["john@acme.com", "Acme Corp"]}},
-  ]
-)
-
-// Or use built-in alias
-persona(method="create", from="source-persona-uuid", name="Demo Dashboard", actions=["copy-and-sanitize"])
-```
-
-### Direct Data Operations
-
-For operations on existing personas, use the `data` sub-resource:
-
-```typescript
-// Copy data from another persona
-persona(id="target-persona-uuid", data={method:"copy", from:"source-persona-uuid", sanitize:true})
-
-// List data items
-persona(id="persona-uuid", data={method:"list"})
-
-// Get input schema
-persona(id="persona-uuid", data={method:"schema"})
-```
-
-### Upload Dashboard Rows with Files
-
-Create new dashboard rows with file attachments (triggers workflow execution):
-
-```javascript
-persona(id="dashboard-uuid", data={
-  method: "upload",
-  items: [
-    {
-      "Input Document": { file: "/path/to/invoice.pdf" },
-      "Customer Name": "Acme Corp",
-      "Amount": 1500.00,
-      "Priority": true
-    }
-  ]
-})
-```
-
-**Supported value types in `items`:**
-
-| Type | Format | Result |
-|------|--------|--------|
-| String | `"value"` | `string_value` |
-| Number | `123.45` | `number_value` |
-| Boolean | `true` | `boolean_value` |
-| File | `{ file: "/path/to/doc.pdf" }` | `document_value` (auto base64) |
-| Inline Doc | `{ contents: "...", mime_type: "text/plain" }` | `document_value` |
-
-**Key differences from knowledge base upload:**
-
-| Operation | Target | Use Case |
-|-----------|--------|----------|
-| `data={method:"upload", path:"..."}` | Knowledge Base | Chat personas, RAG search |
-| `data={method:"upload", items:[...]}` | Dashboard Rows | Dashboard personas, per-row workflow |
-
-### Legacy Syntax (still works)
-
-```
-knowledge(
-  persona_id="target-persona-uuid",
-  source_persona_id="source-persona-uuid",
-  mode="dashboard_clone",
-  sanitize=true,
-  sanitize_examples=["john@acme.com", "Acme Corp"]
-)
-```
-
-### Response
-
-```json
-{
-  "success": true,
-  "source_persona": "Source Dashboard",
-  "target_persona": "Target Dashboard", 
-  "cloned_count": 5,
-  "skipped_count": 0,
-  "details": [
-    {
-      "source_row_id": "row-1",
-      "target_row_id": "new-row-1",
-      "status": "cloned"
-    }
-  ],
-  "notes": [
-    "Dashboard clone creates NEW rows in the target dashboard",
-    "Workflows will re-run on the new rows to generate output columns"
-  ]
-}
-```
-
-## Document Handling
-
-### How Document Cloning Works
-
-1. **Fetch source row** with file contents:
-   ```typescript
-   const rowResult = await client.getDashboardRowResult(
-     sourcePersonaId, 
-     rowId, 
-     true  // includeFileContents
-   );
-   ```
-
-2. **Extract file content** from `additional_column_details`:
-   ```typescript
-   const fileContent = rowResult.additional_column_details?.find(
-     d => d.column_id === columnId
-   )?.file_contents;  // Base64 encoded
-   ```
-
-3. **Build document input** for target:
-   ```typescript
-   const input: DashboardInput = {
-     name: "Document Input",
-     document_value: [{
-       name: "filename.pdf",
-       contents: fileContent,
-       is_base64_encoded: true,
-       mime_type: "application/pdf",
-     }],
-   };
-   ```
-
-4. **Upload to target dashboard**:
-   ```typescript
-   await client.uploadAndRunDashboardRow(targetPersonaId, [input]);
-   ```
-
-### MIME Type Inference
-
-When document `type` is not available, inferred from extension:
-
-| Extension | MIME Type |
-|-----------|-----------|
-| `.pdf` | `application/pdf` |
-| `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
-| `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
-| `.csv` | `text/csv` |
-| `.txt` | `text/plain` |
-| `.png` | `image/png` |
-| `.jpg`/`.jpeg` | `image/jpeg` |
-| Other | `application/octet-stream` |
-
-## Common Patterns
-
-### List Dashboard Rows
-
-```
-knowledge(persona_id="...", mode="dashboard_rows", limit=10)
-```
-
-### Clone with Sanitization
-
-**Recommended (action composition):**
-
-```typescript
-persona(
-  method="create",
-  from="source",
-  name="Demo Dashboard",
-  actions=[
-    {tool:"data", args:{method:"copy", from:"$source"}},
-    {tool:"data", args:{method:"sanitize", examples:["real-email@company.com", "Real Company Name"]}},
-  ]
-)
-```
-
-**Legacy syntax (still works):**
-
-```
-knowledge(
-  persona_id="target",
-  source_persona_id="source",
-  mode="dashboard_clone",
-  sanitize=true,
-  sanitize_examples=["real-email@company.com", "Real Company Name"]
-)
-```
-
-### Manual Row Upload
-
-Use `uploadAndRunDashboardRow` directly for programmatic row creation:
-
-```typescript
-await client.uploadAndRunDashboardRow(personaId, [
-  { name: "Input Column", string_value: "test data" },
-  { name: "Document Column", document_value: [...] },
-]);
-```
-
-## Error Handling
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| "Persona has no dashboard" | Wrong persona type | Use only with DOCUMENT_TRIGGER personas |
-| "Document content not available" | `includeFileContents` returned empty | Source document may have been deleted |
-| "Source persona not found" | Invalid `source_persona_id` | Verify persona exists in environment |
-
-## Related Files
-
-| File | Purpose |
-|------|---------|
-| `src/sdk/client.ts` | SDK methods for dashboard operations |
-| `src/mcp/handlers-consolidated.ts` | MCP handlers (dashboard_rows, dashboard_clone) |
-| `test/integration/dashboard-clone.integration.test.ts` | Integration tests |
-| `test/handlers-consolidated.test.ts` | Unit tests for cloning logic |