@ema.co/mcp-toolkit 0.2.0

package/docs/advisor-comms-assistant-fixes.md

@@ -0,0 +1,175 @@
+# Advisor Communications Assistant - Workflow Fixes
+
+**Persona ID**: `d5aa0b7a-792d-4e3d-8a74-ac87457ffca2`
+**Environment**: demo
+**Analysis Date**: 2026-01-10
+
+## Summary
+
+| Severity | Count | Status |
+|----------|-------|--------|
+| Critical | 3 | Needs fix |
+| Warning | 0 | - |
+| Info | 4 | Acceptable |
+
+## Critical Issues & Fixes
+
+### Issue 1: Document → Email Attachment Type Mismatch
+
+**Location**: `generate_documentnr7ttm` → `send_email_agentq7zdvj`
+
+**Problem**: 
+- `document_link` output is type `WELL_KNOWN_TYPE_DOCUMENT`
+- `attachment_links` input expects `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES`
+
+**Fix Options**:
+
+**Option A (Recommended)**: Use `named_inputs` instead
+```yaml
+# Change from:
+send_email_agentq7zdvj.inputs.attachment_links:
+  actionOutput:
+    actionName: generate_documentnr7ttm
+    output: document_link
+
+# To:
+send_email_agentq7zdvj.inputs.named_inputs:
+  multiBinding:
+    elements:
+      - namedBinding:
+          name: document_attachment
+          value:
+            actionOutput:
+              actionName: generate_documentnr7ttm
+              output: document_link
+```
+
+**Option B**: Use a fixed_response node to convert document_link to text
+
+---
+
+### Issue 2: Combined Results → Content Generator Type Mismatch
+
+**Location**: `combine_search_resultssmoo58` → `personalized_content_generatorfosf62`
+
+**Problem**:
+- `combined_results` output is type `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES`
+- `search_results` input expects `WELL_KNOWN_TYPE_SEARCH_RESULT`
+
+**Fix**:
+Route original search results directly instead of combined:
+
+```yaml
+# Change from:
+personalized_content_generatorfosf62.inputs.search_results:
+  actionOutput:
+    actionName: combine_search_resultssmoo58
+    output: combined_results
+
+# To:
+personalized_content_generatorfosf62.inputs.search_results:
+  actionOutput:
+    actionName: searchfleqzf
+    output: search_results
+```
+
+**Alternative**: Use `named_inputs` for combined results:
+```yaml
+personalized_content_generatorfosf62.inputs.named_inputs:
+  multiBinding:
+    elements:
+      - namedBinding:
+          name: combined_context
+          value:
+            actionOutput:
+              actionName: combine_search_resultssmoo58
+              output: combined_results
+```
+
+---
+
+### Issue 3: Summarized Conversation → Custom Agent Conversation Mismatch
+
+**Location**: `conversation_summarizer` → `custom_agentrjrvw6`
+
+**Problem**:
+- `summarized_conversation` is type `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES`
+- `conversation` input expects `WELL_KNOWN_TYPE_CHAT_CONVERSATION`
+
+**Fix**:
+Use the trigger's conversation output instead:
+
+```yaml
+# Change from:
+custom_agentrjrvw6.inputs.conversation:
+  actionOutput:
+    actionName: conversation_summarizer
+    output: summarized_conversation
+
+# To:
+custom_agentrjrvw6.inputs.conversation:
+  actionOutput:
+    actionName: trigger
+    output: chat_conversation
+```
+
+And pass the summarized query via `named_inputs`:
+```yaml
+custom_agentrjrvw6.inputs.named_inputs:
+  multiBinding:
+    elements:
+      - namedBinding:
+          name: context
+          value:
+            actionOutput:
+              actionName: conversation_summarizer
+              output: summarized_conversation
+```
+
+---
+
+## Info Issues (Acceptable)
+
+### Sequential Searches
+The workflow has sequential dependencies between searches:
+- `conversation_summarizer` → `live_web_search7kmyak`
+- `searchfleqzf` → `combine_search_resultssmoo58`
+
+**Assessment**: Acceptable - the searches depend on each other's outputs.
+
+### Multiple LLM Nodes
+5 LLM nodes process results from `searchfleqzf`:
+- `respond_client_update`
+- `respond_market_impact`
+- `respond_exposure`
+- `respond_compliance`
+- `respond_health`
+
+**Assessment**: Expected behavior - these are conditional branches from the categorizer.
+
+---
+
+## Application Instructions
+
+### Via Ema UI (Recommended)
+1. Open persona in Auto Builder
+2. For each critical issue:
+   - Click on the target node
+   - Modify the input binding as described
+3. Save and test
+
+### Via API
+Use the `/api/personas/update_persona` endpoint with the corrected `workflow` field.
+
+---
+
+## Type Compatibility Quick Reference
+
+| From Type | Can Connect To |
+|-----------|---------------|
+| CHAT_CONVERSATION | conversation inputs, named_inputs |
+| TEXT_WITH_SOURCES | query, named_inputs, instructions |
+| SEARCH_RESULT | search_results inputs, named_inputs |
+| DOCUMENT | named_inputs (NOT text inputs) |
+
+**Rule**: When in doubt, use `named_inputs` - it accepts ANY type.

package/docs/api-contracts.md

@@ -0,0 +1,216 @@
+# API Contracts
+
+This document explains how API contracts are managed between the Ema backend and the MCP toolkit.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        Ema Backend (Python)                         │
+├─────────────────────────────────────────────────────────────────────┤
+│  Pydantic Models (schema.py)  →  FastAPI  →  OpenAPI JSON          │
+│                                                                     │
+│  PersonaDTO(BaseModel)        →  @router  →  /api/openapi.json     │
+│  ConversationDTO(BaseModel)                                        │
+│  MessageDTO(BaseModel)                                             │
+└─────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    │ Auto-generated
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    OpenAPI 3.0 Specification                        │
+│                                                                     │
+│  /api/openapi.json                                                 │
+│  • paths: All REST endpoints                                       │
+│  • components/schemas: All data types                              │
+│  • securitySchemes: Authentication                                 │
+└─────────────────────────────────────────────────────────────────────┘
+                                    │
+                     ┌──────────────┴──────────────┐
+                     │                             │
+                     ▼                             ▼
+┌────────────────────────────┐    ┌────────────────────────────────┐
+│   Generated Types          │    │   Zod Runtime Validation       │
+│                            │    │                                │
+│   src/sdk/generated/       │    │   src/sdk/contracts.ts         │
+│   • api-types.ts           │    │   • PersonaDTOSchema           │
+│   • openapi.json           │    │   • validateResponse()         │
+│                            │    │   • safeValidateResponse()     │
+└────────────────────────────┘    └────────────────────────────────┘
+```
+
+## Source of Truth
+
+| Layer | File | Generated? | Runtime Validated? |
+|-------|------|------------|-------------------|
+| Backend | `ema_backend/web/api/*/schema.py` | No | Yes (Pydantic) |
+| OpenAPI | `/api/openapi.json` | Yes (from Pydantic) | N/A |
+| TypeScript Types | `src/sdk/generated/api-types.ts` | Yes (from OpenAPI) | No |
+| Zod Schemas | `src/sdk/contracts.ts` | No (manual) | Yes (Zod) |
+
+## Workflow
+
+### 1. Backend Changes (Python)
+
+When you add/modify a Pydantic model:
+
+```python
+# ema_backend/web/api/personas/schema.py
+class PersonaDTO(BaseModel):
+    id: str
+    name: str = Field(..., description="Display name of the AI Employee")
+    status: PersonaStateEnum
+```
+
+The OpenAPI spec updates automatically (FastAPI generates it).
+
+### 2. Generate TypeScript Types
+
+After backend changes, regenerate TypeScript types:
+
+```bash
+# From ema-mcp-toolkit directory
+npm run generate:types
+
+# Or with a specific URL
+npm run generate:types -- --url http://localhost:8000/api/openapi.json
+```
+
+This creates/updates:
+- `src/sdk/generated/api-types.ts` - TypeScript interfaces
+- `src/sdk/generated/openapi.json` - Cached spec for CI
+
+### 3. Update Zod Schemas (if needed)
+
+If you need runtime validation, update `src/sdk/contracts.ts`:
+
+```typescript
+export const PersonaDTOSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  status: PersonaStateSchema,
+});
+```
+
+### 4. CI Contract Check
+
+CI runs `npm run check:contracts` to detect drift:
+
+```bash
+npm run check:contracts
+
+# Output on drift:
+# ❌ API contracts have drifted!
+#    Added schemas: NewSchemaName
+#    Modified schemas: PersonaDTO
+#    Regenerate types: npm run generate:types
+```
+
+## Using Contracts
+
+### TypeScript Types (Compile-time)
+
+```typescript
+import type { PersonaDTO } from "./generated/api-types";
+
+function processPersona(persona: PersonaDTO) {
+  console.log(persona.name);
+}
+```
+
+### Zod Validation (Runtime)
+
+```typescript
+import { PersonaDTOSchema, safeValidateResponse } from "./contracts";
+
+const response = await fetch("/api/personas/123");
+const data = await response.json();
+
+const result = safeValidateResponse(PersonaDTOSchema, data);
+if (result.success) {
+  console.log("Valid persona:", result.data);
+} else {
+  console.error("Invalid response:", result.error);
+}
+```
+
+### Validating Lists
+
+```typescript
+import { PersonaDTOSchema, validateList } from "./contracts";
+
+const personas = validateList(PersonaDTOSchema, apiResponse.personas, "personas");
+// Invalid items are logged and filtered out
+```
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run generate:types` | Generate TypeScript types from OpenAPI |
+| `npm run check:contracts` | Check for drift between spec and types |
+
+### Script Options
+
+```bash
+# Generate from specific URL
+npm run generate:types -- --url http://localhost:8000/api/openapi.json
+
+# Generate from local file
+npm run generate:types -- --file ./openapi.json
+
+# Check against specific URL
+npm run check:contracts -- --url http://localhost:8000/api/openapi.json
+```
+
+## Best Practices
+
+1. **Always regenerate after backend changes**
+   ```bash
+   # After modifying schema.py files
+   npm run generate:types
+   ```
+
+2. **Commit generated files**
+   - Generated types are checked into git
+   - This ensures CI can detect drift
+   - Other developers don't need backend running
+
+3. **Use Zod for user-facing data**
+   - Validate API responses before displaying to users
+   - Log validation errors for debugging
+
+4. **Don't modify generated files**
+   - Changes will be overwritten
+   - Update backend schemas instead
+
+## Troubleshooting
+
+### "API contracts have drifted"
+
+```bash
+# Regenerate types
+npm run generate:types
+
+# Commit the changes
+git add src/sdk/generated/
+git commit -m "Regenerate API types from OpenAPI spec"
+```
+
+### "Failed to fetch OpenAPI spec"
+
+```bash
+# Check if backend is running
+curl http://localhost:8000/api/openapi.json
+
+# Use staging instead
+npm run generate:types -- --url https://staging.ema.co/api/openapi.json
+```
+
+### Type mismatch in Zod schema
+
+The Zod schemas in `contracts.ts` are manually maintained. If they're out of sync:
+
+1. Check the generated types in `api-types.ts`
+2. Update the Zod schema to match
+3. Add `.passthrough()` for objects with unknown additional fields

package/docs/auto-builder-analysis.md

@@ -0,0 +1,271 @@
+# Auto-Builder Prompt Analysis & MCP Toolkit Improvements
+
+> Analysis of the Ema Auto-Builder prompt architecture and recommended improvements for the MCP Toolkit.
+
+## Executive Summary
+
+The Ema Auto-Builder (DeltaGrapher agent) uses a **~70K token system prompt** that includes full documentation for every available agent. This is wasteful and could be optimized significantly. Our MCP Toolkit has the right abstractions but doesn't fully utilize them during workflow generation.
+
+**Key Findings:**
+1. Auto-Builder sends full agent documentation (~70K tokens) when only ~5K of constraints are needed
+2. Our `AGENT_CATALOG` is well-structured but not used during generation
+3. Our `workflow-intent.ts` uses primitive regex parsing that can't handle complex requests
+4. Validation rules are applied **after** generation instead of **during** generation
+5. No support for incremental DSL operations (add/remove nodes)
+
+---
+
+## 1. Auto-Builder Prompt Analysis
+
+### What the Prompt Contains
+
+```
+System Prompt (~70K tokens)
+├── Role Definition (~500 tokens)
+├── Language Instructions (~200 tokens)
+├── Security Instructions (~300 tokens)
+├── available_nodes (~65K tokens) ← PROBLEM
+│   └── For each of ~35 agents:
+│       ├── name, displayName, description
+│       ├── inputs (with wellKnownType, displayName, isOptional)
+│       ├── outputs (with wellKnownType, displayName)
+│       └── builderDocumentation (~2K tokens each!) ← WASTE
+├── Workflow Construction Rules (~3K tokens)
+├── Output Node Instructions (~500 tokens)
+└── DSL Operations (~500 tokens)
+```
+
+### The Problem: Token Waste
+
+Each agent includes full `builderDocumentation` which is detailed user guides:
+
+```json
+{
+  "builderDocumentation": "# Conversation Summarizer Agent\\n\\n
+    This agent converts a chat conversation into a search query...
+    [2000+ chars of examples, FAQs, use cases, etc.]"
+}
+```
+
+**For graph generation, you only need:**
+- Action name
+- Input types (wellKnownType)
+- Output types (wellKnownType)
+- Critical constraints (3-5 rules)
+
+### Token Comparison
+
+| Content | Current | Optimized |
+|---------|---------|-----------|
+| Agent definitions | ~65,000 | ~3,000 |
+| Rules & constraints | ~3,000 | ~2,000 |
+| Instructions | ~2,000 | ~2,000 |
+| **Total** | **~70,000** | **~7,000** |
+
+**90% token reduction is achievable.**
+
+---
+
+## 2. Our MCP Toolkit: Current State
+
+### What We Have (Good)
+
+1. **`AGENT_CATALOG`** - Well-structured agent definitions with types, inputs, outputs, constraints
+2. **`INPUT_SOURCE_RULES`** - Type compatibility rules (e.g., "chat_categorizer needs chat_conversation")
+3. **`ANTI_PATTERNS`** - Common mistakes to avoid
+4. **`WORKFLOW_PATTERNS`** - Template patterns (kb-search, intent-routing, tool-calling)
+5. **`compileWorkflow()`** - Spec-to-workflow compiler
+
+### What's Missing (Problems)
+
+#### Problem 1: AGENT_CATALOG Not Used During Generation
+
+Our catalog is exposed as a **resource** but not used in `intentToSpec()` or `compileWorkflow()`:
+
+```typescript
+// In resources.ts - exposed for reference
+DYNAMIC_RESOURCES.push({
+  uri: "ema://catalog/agents",
+  generate: () => JSON.stringify(AGENT_CATALOG, null, 2),
+});
+
+// In workflow-intent.ts - NOT USING AGENT_CATALOG
+const INTENT_PATTERNS = [
+  { pattern: /password\s*reset/i, name: "Password Reset", handler: "llm" },
+  // Hardcoded patterns instead of using catalog!
+];
+```
+
+#### Problem 2: No Type Validation During Generation
+
+Our compiler builds workflows but doesn't validate type compatibility:
+
+```typescript
+// In workflow-generator.ts
+function buildInputBinding(binding: InputBinding): Record<string, unknown> {
+  // Builds binding but doesn't validate types match!
+  switch (binding.type) {
+    case "action_output":
+      return { actionOutput: { ... } };
+  }
+}
+```
+
+Compare to Auto-Builder which has explicit type rules:
+```
+INPUT AND OUTPUT `wellKnownType` MUST MATCH when creating edges
+```
+
+#### Problem 3: Primitive NLP Parsing
+
+Our `parseNaturalLanguage()` uses simple regex:
+
+```typescript
+const INTENT_PATTERNS = [
+  { pattern: /password\s*reset/i, name: "Password Reset", handler: "llm" },
+  { pattern: /billing|payment|invoice/i, name: "Billing", handler: "search" },
+];
+```
+
+This can't handle complex requests like:
+> "Banking Customer Onboarding with KYC/AML screening, identity verification, risk scoring, and manual review routing"
+
+#### Problem 4: No DSL Operations
+
+Auto-Builder supports incremental edits:
+- `add_node(id, action_name, display_name)`
+- `remove_node(id)`
+- `add_edge(from_id, to_id, source_output, target_input)`
+- `remove_edge(...)`
+- `modify_node(id, display_name)`
+
+Our toolkit only supports **full workflow generation**.
+
+---
+
+## 3. Improvements Made
+
+### New: `generation-schema.ts`
+
+Created a compact schema generator that transforms `AGENT_CATALOG` into a generation-focused format:
+
+```typescript
+export function generateSchemaMarkdown(): string {
+  // Returns ~5K tokens of actionable constraints
+  // vs ~70K tokens of full documentation
+}
+
+export function isTypeCompatible(sourceType, targetType): boolean {
+  // Validates type compatibility during generation
+}
+
+export function getRecommendedInput(actionName): string {
+  // Uses INPUT_SOURCE_RULES to recommend correct inputs
+}
+```
+
+### Usage
+
+```typescript
+import { generateSchemaMarkdown, isTypeCompatible } from "./sdk/generation-schema.js";
+
+// Get compact schema for LLM prompt
+const schema = generateSchemaMarkdown(); // ~5K tokens
+
+// Validate during generation
+if (!isTypeCompatible("WELL_KNOWN_TYPE_CHAT_CONVERSATION", "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES")) {
+  throw new Error("Type mismatch: use conversation_to_search_query first");
+}
+```
+
+---
+
+## 4. Recommended Next Steps
+
+### Phase 1: Enhance Workflow Intent (Priority: High)
+
+1. **Replace regex with LLM-based parsing**
+   - Use the compact schema as context
+   - Let LLM extract intents, tools, data sources
+   
+2. **Add type validation to `intentToSpec()`**
+   - Use `isTypeCompatible()` to validate connections
+   - Suggest fixes when mismatches found
+
+### Phase 2: Add DSL Operations (Priority: Medium)
+
+Create incremental workflow editing:
+
+```typescript
+interface DSLOperation {
+  operation: "add_node" | "remove_node" | "add_edge" | "remove_edge" | "modify_node";
+  // ... params
+}
+
+function applyDSLOperations(workflow: WorkflowDef, operations: DSLOperation[]): WorkflowDef {
+  // Apply incremental changes
+}
+```
+
+### Phase 3: Optimize Auto-Builder Integration (Priority: Low)
+
+If we integrate with Auto-Builder:
+- Send compact schema instead of full docs
+- Use our validation rules to pre-validate prompts
+- Apply fixes locally before sending to Auto-Builder
+
+---
+
+## 5. Code Locations
+
+| Component | File | Status |
+|-----------|------|--------|
+| Agent Catalog | `src/sdk/knowledge.ts` | ✅ Good |
+| Validation Rules | `src/sdk/validation-rules.ts` | ✅ Good |
+| Compact Schema | `src/sdk/generation-schema.ts` | ✅ New |
+| Intent Parsing | `src/sdk/workflow-intent.ts` | ⚠️ Needs LLM |
+| Workflow Compiler | `src/sdk/workflow-generator.ts` | ⚠️ Needs validation |
+| DSL Operations | N/A | ❌ Not implemented |
+
+---
+
+## 6. Example: Optimized Prompt Structure
+
+Instead of the current 70K token prompt, use this structure:
+
+```markdown
+# Workflow Generation Schema
+
+## Available Agents (35)
+
+| Action | Category | Inputs | Outputs |
+|--------|----------|--------|---------|
+| `chat_trigger` | trigger | - | chat_conversation*, user_query* |
+| `chat_categorizer` | routing | conversation* | category |
+| `search` | search | query* | search_results |
+| `respond_with_sources` | generation | query*, search_results* | response_with_sources |
+...
+
+## Type Compatibility
+
+- `WELL_KNOWN_TYPE_CHAT_CONVERSATION` → `WELL_KNOWN_TYPE_CHAT_CONVERSATION`, `WELL_KNOWN_TYPE_ANY`
+- `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES` → `WELL_KNOWN_TYPE_TEXT_WITH_SOURCES`, `WELL_KNOWN_TYPE_ANY`
+...
+
+## Input Source Rules
+
+| Action | Recommended | Avoid | Severity |
+|--------|-------------|-------|----------|
+| `chat_categorizer` | `chat_conversation` | user_query | critical |
+| `search` | `user_query` | chat_conversation | critical |
+...
+
+## Structural Constraints
+
+### Categorizers
+- MUST have at least one outgoing edge for each category
+- MUST include a Fallback category
+...
+```
+
+This gives the LLM everything it needs in ~5K tokens instead of ~70K.