@ema.co/mcp-toolkit 2026.2.13 → 2026.2.23-1

package/.context/public/guides/dashboard-operations.md

@@ -1,349 +0,0 @@
----
-title: "Dashboard Operations"
-date: 2026-01-27
-audience: public
----
-# 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` |
-
-## Dashboard Columns: How They Work
-
-### Output Columns Come From resultMappings
-
-For dashboard personas, the **output columns** visible in the dashboard UI are determined **entirely** by which node outputs are mapped to `WORKFLOW_OUTPUT` via `resultMappings` in the workflow_def. Each `resultMapping` entry creates one output column in the dashboard.
-
-```json
-"results": {
-  "entity_extraction.invoice_number": {
-    "actionName": "entity_extraction",
-    "outputName": "invoice_number"
-  },
-  "entity_extraction.amount": {
-    "actionName": "entity_extraction",
-    "outputName": "amount"
-  },
-  "call_llm.summary": {
-    "actionName": "call_llm",
-    "outputName": "response_with_sources"
-  },
-  "categorizer.category": {
-    "actionName": "categorizer",
-    "outputName": "category"
-  }
-}
-```
-
-This creates 4 output columns: `entity_extraction.invoice_number`, `entity_extraction.amount`, `call_llm.summary`, and `categorizer.category`.
-
-**Key rules:**
-- If you forget to map a node output, that column **won't appear** in the dashboard
-- If you map the wrong output, you'll see unexpected data
-- Column display name in the UI = the result mapping key (e.g., `entity_extraction.invoice_number`)
-
-### Input Columns Come From the Trigger
-
-Dashboard input columns (what users fill in or upload per row) come from the `document_trigger` outputs:
-- `document_content`: For uploaded files (PDF, images, etc.)
-- `row_data`: For text/number inputs from dashboard columns
-
-Wire these to your processing nodes:
-- `entity_extraction.document` ← `trigger.document_content`
-- `call_llm.context` ← `trigger.row_data`
-
-### Column Ordering
-
-**Dashboard column order is determined by the order of resultMappings in the workflow_def.**
-
-To reorder columns, you must **remove** them from the result mappings and **re-add** them in the desired order. There is no separate "reorder" API -- the order in the JSON is the order in the UI.
-
-```
-// To change order from [Amount, Date, Status] to [Status, Date, Amount]:
-// 1. Remove all three from results
-// 2. Re-add in desired order:
-"results": {
-  "extract.status": { "actionName": "extract", "outputName": "status" },
-  "extract.date": { "actionName": "extract", "outputName": "date" },
-  "extract.amount": { "actionName": "extract", "outputName": "amount" }
-}
-```
-
-**Important:** Once columns are created and saved, the output type and multi-value settings cannot be modified via the UI. To change these, you must update the workflow_def directly.
-
-## 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 |

package/.context/public/guides/email-patterns.md

@@ -1,125 +0,0 @@
----
-title: "Email Field Extraction Patterns"
-date: 2026-01-27
-audience: public
----
-# 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` |