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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.

This version of @ema.co/mcp-toolkit might be problematic. Click here for more details.

Files changed (87) hide show
  1. package/README.md +10 -2
  2. package/dist/mcp/handlers/action/index.js +3 -18
  3. package/dist/mcp/handlers/data/index.js +385 -41
  4. package/dist/mcp/handlers/data/templates.js +107 -0
  5. package/dist/mcp/handlers/deprecation.js +50 -0
  6. package/dist/mcp/handlers/env/index.js +8 -4
  7. package/dist/mcp/handlers/knowledge/index.js +44 -237
  8. package/dist/mcp/handlers/persona/create.js +47 -18
  9. package/dist/mcp/handlers/persona/index.js +14 -11
  10. package/dist/mcp/handlers/persona/update.js +4 -2
  11. package/dist/mcp/handlers/persona/version.js +234 -0
  12. package/dist/mcp/handlers/sync/index.js +3 -18
  13. package/dist/mcp/handlers/template/index.js +75 -10
  14. package/dist/mcp/handlers/workflow/analyze.js +171 -0
  15. package/dist/mcp/handlers/workflow/compare.js +70 -0
  16. package/dist/mcp/handlers/workflow/deploy.js +73 -0
  17. package/dist/mcp/handlers/workflow/generate.js +350 -0
  18. package/dist/mcp/handlers/workflow/index.js +294 -0
  19. package/dist/mcp/handlers/workflow/modify.js +456 -0
  20. package/dist/mcp/handlers/workflow/optimize.js +136 -0
  21. package/dist/mcp/handlers/workflow/types.js +4 -0
  22. package/dist/mcp/handlers/workflow/utils.js +30 -0
  23. package/dist/mcp/handlers-consolidated.js +73 -2696
  24. package/dist/mcp/prompts.js +83 -43
  25. package/dist/mcp/resources.js +382 -57
  26. package/dist/mcp/server.js +199 -391
  27. package/dist/mcp/{tools-v2.js → tools.js} +20 -54
  28. package/dist/mcp/workflow-operations.js +2 -2
  29. package/dist/sdk/client-adapter.js +267 -32
  30. package/dist/sdk/client.js +45 -16
  31. package/dist/sdk/ema-client.js +183 -0
  32. package/dist/sdk/generated/deprecated-actions.js +171 -0
  33. package/dist/sdk/generated/template-fallbacks.js +123 -0
  34. package/dist/sdk/guidance.js +65 -11
  35. package/dist/sdk/index.js +3 -1
  36. package/dist/sdk/knowledge.js +139 -86
  37. package/dist/sdk/workflow-intent.js +27 -0
  38. package/dist/sdk/workflow-transformer.js +0 -342
  39. package/docs/mcp-tools-guide.md +37 -45
  40. package/package.json +10 -4
  41. package/dist/mcp/handlers/persona/analyze.js +0 -275
  42. package/dist/mcp/handlers/persona/compare.js +0 -32
  43. package/dist/mcp/tools-consolidated.js +0 -875
  44. package/dist/mcp/tools-legacy.js +0 -736
  45. package/docs/CODEBASE-ANALYSIS-2026-01-23.md +0 -936
  46. package/docs/CODEBASE-ANALYSIS-PRIORITIZED.md +0 -774
  47. package/docs/api-contracts.md +0 -216
  48. package/docs/auto-builder-analysis.md +0 -271
  49. package/docs/blog/mcp-tool-design-lessons.md +0 -309
  50. package/docs/data-architecture.md +0 -166
  51. package/docs/demos/ap-invoice-generation.md +0 -347
  52. package/docs/demos/ap-invoice-processing.md +0 -271
  53. package/docs/ema-auto-builder-guide.html +0 -394
  54. package/docs/lessons-learned.md +0 -209
  55. package/docs/llm-native-workflow-design.md +0 -252
  56. package/docs/local-generation.md +0 -508
  57. package/docs/mcp-flow-diagram.md +0 -135
  58. package/docs/migration/action-composition-migration.md +0 -270
  59. package/docs/naming-conventions.md +0 -278
  60. package/docs/proposals/HANDOFF-tool-restructure.md +0 -526
  61. package/docs/proposals/action-composition.md +0 -490
  62. package/docs/proposals/explicit-method-restructure.md +0 -328
  63. package/docs/proposals/mcp-tool-restructure-2026-01.md +0 -366
  64. package/docs/proposals/self-contained-guidance.md +0 -427
  65. package/docs/proto-sdk-generation.md +0 -242
  66. package/docs/release-impact.md +0 -102
  67. package/docs/release-process.md +0 -157
  68. package/docs/staging.RULE.md +0 -142
  69. package/docs/test-persona-creation.md +0 -196
  70. package/docs/tool-consolidation-v2.md +0 -225
  71. package/docs/tool-response-standards.md +0 -256
  72. package/resources/demo-kits/README.md +0 -175
  73. package/resources/demo-kits/finance-ap/manifest.json +0 -150
  74. package/resources/demo-kits/tags.json +0 -91
  75. package/resources/docs/getting-started.md +0 -97
  76. package/resources/templates/auto-builder-rules.md +0 -224
  77. package/resources/templates/chat-ai/README.md +0 -119
  78. package/resources/templates/chat-ai/persona-config.json +0 -111
  79. package/resources/templates/dashboard-ai/README.md +0 -156
  80. package/resources/templates/dashboard-ai/persona-config.json +0 -180
  81. package/resources/templates/demo-scenarios/README.md +0 -63
  82. package/resources/templates/demo-scenarios/test-published-package.md +0 -116
  83. package/resources/templates/document-gen-ai/README.md +0 -132
  84. package/resources/templates/document-gen-ai/persona-config.json +0 -316
  85. package/resources/templates/voice-ai/README.md +0 -123
  86. package/resources/templates/voice-ai/persona-config.json +0 -74
  87. package/resources/templates/voice-ai/workflow-prompt.md +0 -121
package/docs/ema-auto-builder-guide.html DELETED
@@ -1,394 +0,0 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8">
5
- <title>Ema Auto Builder Quick Reference</title>
6
- <style>
7
- body {
8
- font-family: 'Google Sans', Arial, sans-serif;
9
- max-width: 900px;
10
- margin: 0 auto;
11
- padding: 40px 20px;
12
- line-height: 1.6;
13
- color: #202124;
14
- }
15
- h1 { color: #1a73e8; border-bottom: 3px solid #1a73e8; padding-bottom: 10px; }
16
- h2 { color: #185abc; margin-top: 40px; border-bottom: 1px solid #dadce0; padding-bottom: 8px; }
17
- h3 { color: #1967d2; margin-top: 25px; }
18
- h4 { color: #5f6368; }
19
- table { border-collapse: collapse; width: 100%; margin: 15px 0; }
20
- th, td { border: 1px solid #dadce0; padding: 10px 12px; text-align: left; }
21
- th { background: #f8f9fa; font-weight: 600; color: #202124; }
22
- tr:nth-child(even) { background: #fafafa; }
23
- code { background: #f1f3f4; padding: 2px 6px; border-radius: 4px; font-family: 'Roboto Mono', monospace; font-size: 0.9em; color: #d93025; }
24
- pre { background: #f8f9fa; padding: 16px; border-radius: 8px; overflow-x: auto; border: 1px solid #dadce0; }
25
- pre code { background: none; color: #202124; }
26
- blockquote { border-left: 4px solid #1a73e8; margin: 20px 0; padding: 10px 20px; background: #e8f0fe; color: #174ea6; }
27
- .callout { background: #fef7e0; border-left: 4px solid #f9ab00; padding: 12px 16px; margin: 15px 0; }
28
- .callout-info { background: #e8f0fe; border-left-color: #1a73e8; }
29
- .callout-success { background: #e6f4ea; border-left-color: #34a853; }
30
- .callout-warning { background: #fef7e0; border-left-color: #f9ab00; }
31
- .callout-error { background: #fce8e6; border-left-color: #ea4335; }
32
- ul, ol { margin: 10px 0; padding-left: 25px; }
33
- li { margin: 5px 0; }
34
- .emoji { font-size: 1.2em; }
35
- .tag { display: inline-block; background: #e8f0fe; color: #1967d2; padding: 2px 8px; border-radius: 4px; font-size: 0.85em; margin: 2px; }
36
- .tag-required { background: #fce8e6; color: #c5221f; }
37
- hr { border: none; border-top: 1px solid #dadce0; margin: 30px 0; }
38
- </style>
39
- </head>
40
- <body>
41
-
42
- <h1>🚀 Ema Auto Builder Quick Reference</h1>
43
- <p><strong>Ema AI Employee Builder (GWE)</strong>: Quick reference for natural language prompts — triggers, inputs, logic, outputs</p>
44
-
45
- <hr>
46
-
47
- <h2>🔧 MCP Tools: Use Ema MCP for Live Data</h2>
48
-
49
- <p><strong>Ema MCP Server provides real-time platform intelligence.</strong> Always leverage MCP tools.</p>
50
-
51
- <div class="callout callout-info">
52
- <strong>Tool names in Cursor:</strong> MCP server defines base tool names like <code>persona</code>, <code>workflow</code>, <code>action</code>. In <strong>Cursor</strong>, tools are prefixed with <code>mcp_ema_</code> (e.g., <code>mcp_ema_persona</code>).
53
- </div>
54
-
55
- <table>
56
- <tr><th>MCP Tool</th><th>When to Use</th></tr>
57
- <tr><td><code>mcp_ema_template(questions=true)</code></td><td><strong>FIRST</strong> — Get structured questions before asking user</td></tr>
58
- <tr><td><code>mcp_ema_action(suggest="...")</code></td><td>Match use case to recommended agents/patterns</td></tr>
59
- <tr><td><code>mcp_ema_template(pattern="...")</code></td><td>Get template with nodes, connections, anti-patterns</td></tr>
60
- <tr><td><code>mcp_ema_action(id="...", include_docs=true)</code></td><td>Get agent inputs/outputs + docs + critical rules</td></tr>
61
- <tr><td><code>mcp_ema_reference(validate_prompt="...")</code></td><td><strong>LAST</strong> — Validate before outputting</td></tr>
62
- <tr><td><code>mcp_ema_reference(mistakes=true)</code></td><td>Check against top errors before finalizing</td></tr>
63
- </table>
64
-
65
- <h3>MCP-First Generation Flow</h3>
66
- <pre><code>1. mcp_ema_template(questions=true) → Structure user questions
67
- 2. mcp_ema_action(suggest="...") → Get recommended pattern
68
- 3. mcp_ema_template(pattern="...") → Get template
69
- 4. mcp_ema_action(id="...", include_docs=true) → Get each agent's details
70
- 5. mcp_ema_reference(validate_prompt="...") → Validate before output</code></pre>
71
-
72
- <h3>Key MCP Tools by Category</h3>
73
- <table>
74
- <tr><th>Category</th><th>Tools</th></tr>
75
- <tr><td><strong>Discovery</strong></td><td><code>persona</code>, <code>env</code></td></tr>
76
- <tr><td><strong>Agents</strong></td><td><code>action</code></td></tr>
77
- <tr><td><strong>Patterns</strong></td><td><code>template</code></td></tr>
78
- <tr><td><strong>Validation</strong></td><td><code>reference(validate_prompt=...)</code>, <code>reference(check_types={...})</code></td></tr>
79
- <tr><td><strong>Guidance</strong></td><td><code>reference</code></td></tr>
80
- <tr><td><strong>Sync</strong></td><td><code>sync</code>, <code>persona(mode="compare")</code></td></tr>
81
- <tr><td><strong>Review</strong></td><td><code>workflow(mode="analyze")</code>, <code>workflow(mode="optimize")</code></td></tr>
82
- </table>
83
-
84
- <hr>
85
-
86
- <h2>⚠️ FIRST: Ask Qualifying Questions</h2>
87
-
88
- <div class="callout callout-warning">
89
- <strong>Do NOT generate a workflow prompt until you have gathered sufficient information.</strong>
90
- </div>
91
-
92
- <div class="callout callout-info">
93
- 💡 <strong>MCP Tip:</strong> Call <code>mcp_ema_template(questions=true)</code> to get structured questions organized by category with "why it matters" context.
94
- </div>
95
-
96
- <table>
97
- <tr><th>Category</th><th>Required Information</th></tr>
98
- <tr><td><strong>AI Type</strong></td><td>Voice AI, Chat AI, or Dashboard AI?</td></tr>
99
- <tr><td><strong>Intents</strong></td><td>What categories should the AI recognize? (+ Fallback)</td></tr>
100
- <tr><td><strong>Data Sources</strong></td><td>What files, APIs, or databases are needed?</td></tr>
101
- <tr><td><strong>Actions</strong></td><td>What can the AI do? (search, create ticket, send email)</td></tr>
102
- <tr><td><strong>Routing</strong></td><td>What happens for each intent category?</td></tr>
103
- <tr><td><strong>Approvals</strong></td><td>Which actions need human review?</td></tr>
104
- <tr><td><strong>Success Output</strong></td><td>What should the response include?</td></tr>
105
- <tr><td><strong>Voice Settings</strong></td><td>Welcome message, hang-up rules, wait message? (if Voice AI)</td></tr>
106
- </table>
107
-
108
- <h3>Minimum Viable Information</h3>
109
- <table>
110
- <tr><th>Must Have</th><th>Description</th></tr>
111
- <tr><td>AI Type</td><td>Voice, Chat, or Dashboard</td></tr>
112
- <tr><td>2-3 Intent Categories</td><td>Plus Fallback</td></tr>
113
- <tr><td>1 Primary Action</td><td>Data source OR external tool</td></tr>
114
- <tr><td>Success Output</td><td>What to return on completion</td></tr>
115
- </table>
116
-
117
- <hr>
118
-
119
- <h2>🎯 Prime Directive: Generate ALL THREE Parts</h2>
120
-
121
- <p>For every AI Employee, <strong>ALWAYS generate THREE parts</strong>:</p>
122
-
123
- <h3>Part 1: Workflow Prompt (for Auto Builder)</h3>
124
- <p>The backend logic — what agents, how they connect, decision flow:</p>
125
- <ul>
126
- <li>Trigger, Inputs, Agents/Nodes, Connections, Decision Logic, APIs, Outputs</li>
127
- </ul>
128
-
129
- <h3>Part 2: Persona Configuration (Voice/Chat Settings)</h3>
130
- <p>The frontend behavior — how the AI talks:</p>
131
- <ul>
132
- <li>welcomeMessage, identityAndPurpose, takeActionInstructions, hangupInstructions</li>
133
- <li>speechCharacteristics, systemPrompt, waitMessage</li>
134
- </ul>
135
-
136
- <h3>Part 3: Proto_Config JSON (Complete Configuration)</h3>
137
- <p>The full technical spec combining workflow + persona for direct deployment.</p>
138
-
139
- <hr>
140
-
141
- <h2>AI Employee Types</h2>
142
-
143
- <table>
144
- <tr><th>Type</th><th>Project Type</th><th>Key Widgets</th></tr>
145
- <tr><td><strong>Voice AI</strong></td><td>5</td><td>voiceSettings, conversationSettings, vadSettings</td></tr>
146
- <tr><td><strong>Chat AI</strong></td><td>4</td><td>chatbotSdkConfig, fileUpload, feedback</td></tr>
147
- <tr><td><strong>Dashboard AI</strong></td><td>2</td><td>dashboardConfig, inputSchema</td></tr>
148
- <tr><td><strong>Document Gen</strong></td><td>3</td><td>documentSettings, templates</td></tr>
149
- </table>
150
-
151
- <hr>
152
-
153
- <h2>🎯 Opinionated Recommendations</h2>
154
-
155
- <blockquote>When multiple options exist, choose the best one.</blockquote>
156
-
157
- <h3>Node Selection</h3>
158
- <table>
159
- <tr><th>Use Case</th><th>✅ Recommended</th><th>❌ Avoid</th></tr>
160
- <tr><td>Intent routing</td><td><code>chat_categorizer</code></td><td><code>text_categorizer</code> for chat</td></tr>
161
- <tr><td>Search-based response</td><td><code>respond_with_sources</code></td><td><code>call_llm</code> (loses citations)</td></tr>
162
- <tr><td>Static content</td><td><code>fixed_response</code></td><td><code>call_llm</code> (wasteful)</td></tr>
163
- <tr><td>Tool explanation</td><td><code>respond_for_external_actions</code></td><td><code>call_llm</code></td></tr>
164
- </table>
165
-
166
- <h3>Input Source Selection</h3>
167
- <table>
168
- <tr><th>Node</th><th>✅ Always Use</th><th>❌ Never Use</th></tr>
169
- <tr><td><code>chat_categorizer</code></td><td><code>chat_conversation</code></td><td><code>user_query</code></td></tr>
170
- <tr><td><code>search</code></td><td><code>user_query</code> or <code>summarized</code></td><td><code>chat_conversation</code></td></tr>
171
- <tr><td><code>call_llm</code> query</td><td><code>user_query</code></td><td><code>chat_conversation</code></td></tr>
172
- <tr><td><code>call_llm</code> context</td><td><code>named_inputs</code> with <code>chat_conversation</code></td><td>—</td></tr>
173
- </table>
174
-
175
- <h3>Architecture Decisions</h3>
176
- <table>
177
- <tr><th>Decision</th><th>Recommendation</th></tr>
178
- <tr><td>Categories count</td><td><strong>3-5 max</strong> per categorizer; use hierarchy for more</td></tr>
179
- <tr><td>HITL on external action</td><td><strong>Always</strong> for any action with side effects</td></tr>
180
- <tr><td>Search strategy</td><td><strong>KB first</strong>, web search secondary</td></tr>
181
- <tr><td>Error handling</td><td><strong>Always explicit</strong>; never assume happy path</td></tr>
182
- <tr><td>Fallback</td><td><strong>Always include</strong>; ask clarifying question</td></tr>
183
- </table>
184
-
185
- <hr>
186
-
187
- <h2>Auto Builder: Official Action Names</h2>
188
-
189
- <h3>Triggers & Routing</h3>
190
- <table>
191
- <tr><th>Action Name</th><th>Display Name</th><th>Output</th></tr>
192
- <tr><td><code>chat_trigger</code></td><td>Chat Trigger</td><td><code>chat_conversation</code>, <code>user_query</code></td></tr>
193
- <tr><td><code>document_trigger</code></td><td>Document Trigger</td><td><code>user_query</code> (documents)</td></tr>
194
- <tr><td><code>chat_categorizer</code></td><td>Intent Classifier</td><td><code>category_&lt;name&gt;</code></td></tr>
195
- <tr><td><code>text_categorizer</code></td><td>Text Categorizer</td><td><code>category_&lt;name&gt;</code></td></tr>
196
- <tr><td><code>conversation_to_search_query</code></td><td>Conversation Summarizer</td><td><code>summarized_conversation</code></td></tr>
197
- </table>
198
-
199
- <h3>Search & Response</h3>
200
- <table>
201
- <tr><th>Action Name</th><th>Display Name</th><th>Input → Output</th></tr>
202
- <tr><td><code>search</code></td><td>File Search</td><td>query → <code>search_results</code></td></tr>
203
- <tr><td><code>live_web_search</code></td><td>Live Web Search</td><td>query → <code>web_search_results</code></td></tr>
204
- <tr><td><code>respond_with_sources</code></td><td>Respond using Search Results</td><td>query + search_results → response</td></tr>
205
- <tr><td><code>call_llm</code></td><td>Respond</td><td>query + named_inputs → response</td></tr>
206
- <tr><td><code>external_action_caller</code></td><td>External Tool Caller</td><td>query → tool_result</td></tr>
207
- </table>
208
-
209
- <h3>Validation Rules</h3>
210
- <table>
211
- <tr><th>Action Name</th><th>Display Name</th><th>Critical Rules</th></tr>
212
- <tr><td><code>general_hitl</code></td><td>Human Collaboration</td><td>MUST have both success AND failure paths</td></tr>
213
- <tr><td><code>response_validator</code></td><td>Response Validator</td><td>Validates LLM output</td></tr>
214
- <tr><td><code>entity_extraction_with_documents</code></td><td>Entity Extraction</td><td>Works on DOCUMENTS not text</td></tr>
215
- </table>
216
-
217
- <hr>
218
-
219
- <h2>Voice AI Required Fields</h2>
220
-
221
- <table>
222
- <tr><th>UI Field</th><th>Config Key</th><th>Required</th></tr>
223
- <tr><td><strong>How should the call start?</strong></td><td><code>welcomeMessage</code></td><td><span class="tag tag-required">Required</span></td></tr>
224
- <tr><td><strong>Define identity and purpose</strong></td><td><code>identityAndPurpose</code></td><td><span class="tag tag-required">Required</span></td></tr>
225
- <tr><td><strong>Define actions AI can perform</strong></td><td><code>takeActionInstructions</code></td><td><span class="tag tag-required">Required</span></td></tr>
226
- <tr><td><strong>When should the call end?</strong></td><td><code>hangupInstructions</code></td><td><span class="tag tag-required">Required</span></td></tr>
227
- <tr><td>When to transfer to human?</td><td><code>transferCallInstructions</code></td><td>Optional</td></tr>
228
- <tr><td>Speech characteristics</td><td><code>speechCharacteristics</code></td><td>Optional</td></tr>
229
- <tr><td>Tool calling instructions</td><td><code>systemPrompt</code></td><td>Optional</td></tr>
230
- <tr><td>Wait message</td><td><code>waitMessage</code></td><td>Optional</td></tr>
231
- </table>
232
-
233
- <h3>Voice Settings Widget Types</h3>
234
- <table>
235
- <tr><th>Widget ID</th><th>Widget</th><th>Purpose</th></tr>
236
- <tr><td>38</td><td>voiceSettings</td><td>Language hints, voice model</td></tr>
237
- <tr><td>39</td><td>conversationSettings</td><td>Identity, purpose, actions</td></tr>
238
- <tr><td>43</td><td>vadSettings</td><td>turnTimeout, silenceEndCallTimeout, maxDuration</td></tr>
239
- <tr><td>42</td><td>dataStorageSettings</td><td>Audio/transcript recording</td></tr>
240
- </table>
241
-
242
- <hr>
243
-
244
- <h2>Tool Calling Rules (Voice)</h2>
245
- <ol>
246
- <li><strong>Collect all parameters</strong> before calling a tool</li>
247
- <li><strong>Wait for response</strong> before calling another tool</li>
248
- <li><strong>Never mention tool names</strong> to the user</li>
249
- <li><strong>Never guess</strong> parameter values</li>
250
- <li><strong>Plain language</strong> for what you're doing</li>
251
- <li><strong>Handle delays</strong> with "Just a moment..."</li>
252
- <li><strong>Handle errors</strong> gracefully, offer alternatives</li>
253
- </ol>
254
-
255
- <hr>
256
-
257
- <h2>Categorizer Validation (Critical!)</h2>
258
-
259
- <div class="callout callout-error">
260
- <strong>⚠️ EVERY categorizer MUST have:</strong>
261
- <ol>
262
- <li>At least one outgoing edge</li>
263
- <li>Output format: <code>category_&lt;CategoryName&gt;</code></li>
264
- <li>Target input: <code>trigger_when</code></li>
265
- <li>A Fallback category</li>
266
- </ol>
267
- </div>
268
-
269
- <h3>Type Compatibility</h3>
270
- <pre><code>chat_trigger.chat_conversation → chat_categorizer.conversation ✅
271
- chat_trigger.user_query → search.query ✅
272
- search.search_results → respond_with_sources.search_results ✅
273
- call_llm.named_inputs accepts ANY type (WELL_KNOWN_TYPE_ANY)</code></pre>
274
-
275
- <hr>
276
-
277
- <h2>Agent Quick Reference</h2>
278
-
279
- <h3>Core Workflow Agents</h3>
280
- <table>
281
- <tr><th>Agent</th><th>Use For</th></tr>
282
- <tr><td>Abstain from Answering</td><td>Decline when cannot answer</td></tr>
283
- <tr><td>Categorize Conversations and Route</td><td>First node, classify intent</td></tr>
284
- <tr><td>Combine Search Results</td><td>Merge multiple search sources</td></tr>
285
- <tr><td>Conversation Summarizer</td><td>Normalize chat to query</td></tr>
286
- <tr><td>Deep Web Search</td><td>Real-time external info</td></tr>
287
- <tr><td>Extract Entities</td><td>Pull structured data from text</td></tr>
288
- <tr><td>Fixed Response</td><td>Static/template content</td></tr>
289
- <tr><td>Human Collaboration</td><td>Route to human for approval</td></tr>
290
- <tr><td>Knowledge Search</td><td>Answer from internal docs</td></tr>
291
- <tr><td>Respond using Search Results</td><td>Synthesize search results with citations</td></tr>
292
- <tr><td>Response Validator</td><td>Validate output, abstain if fail</td></tr>
293
- <tr><td>External Tool Caller</td><td>Execute integrations (ServiceNow, Salesforce, etc.)</td></tr>
294
- </table>
295
-
296
- <h3>Domain Agents by Category</h3>
297
- <table>
298
- <tr><th>Category</th><th>Agents</th></tr>
299
- <tr><td><strong>Finance</strong></td><td>Audit Evidence Verifier, Financial Risk Assessor, Financial Statement Analyzer, Tax Advisor</td></tr>
300
- <tr><td><strong>Healthcare</strong></td><td>Medical Record Summarizer, Medical Research Assistant, Insurance Claim Summarizer</td></tr>
301
- <tr><td><strong>Legal</strong></td><td>Compliance Document Analyzer, Legal Expert, Legal Precedent Analyser</td></tr>
302
- <tr><td><strong>Sales</strong></td><td>Sales Intelligence, Sales Contract Summarizer, Email Writer</td></tr>
303
- <tr><td><strong>IT/Security</strong></td><td>Cybersecurity Expert, Phishing Email Detector, Technical Support</td></tr>
304
- <tr><td><strong>HR</strong></td><td>Employee Onboarding Customizer, Internal Job Mobility Matcher</td></tr>
305
- </table>
306
-
307
- <hr>
308
-
309
- <h2>🔍 Workflow Review & Audit</h2>
310
-
311
- <p>Use these tools to analyze existing workflows, detect issues, and propose fixes.</p>
312
-
313
- <h3>Review Command Flow</h3>
314
- <pre><code>1. mcp_ema_persona(id=persona_id, include_workflow=true, env=env) → Get workflow
315
- 2. mcp_ema_workflow(mode="analyze", persona_id=persona_id, env=env) → Full analysis
316
- 3. mcp_ema_workflow(mode="analyze", workflow_def=&lt;workflow_def&gt;, include=["issues"]) → Find issues
317
- 4. mcp_ema_workflow(mode="analyze", workflow_def=&lt;workflow_def&gt;, include=["fixes"]) → Get fix proposals
318
- 5. Apply fixes and re-validate</code></pre>
319
-
320
- <h3>Issue Detection</h3>
321
- <table>
322
- <tr><th>Issue Type</th><th>Detection</th><th>Impact</th></tr>
323
- <tr><td><strong>Loops</strong></td><td>Cycles in edge graph</td><td>Infinite execution</td></tr>
324
- <tr><td><strong>Deadlocks</strong></td><td>Unreachable inputs</td><td>Workflow hangs</td></tr>
325
- <tr><td><strong>Orphans</strong></td><td>Disconnected nodes</td><td>Wasted resources</td></tr>
326
- <tr><td><strong>Dead Ends</strong></td><td>No path to OUTPUT</td><td>Response lost</td></tr>
327
- <tr><td><strong>Type Mismatch</strong></td><td>Incompatible types</td><td>Runtime errors</td></tr>
328
- <tr><td><strong>Missing Fallback</strong></td><td>No Fallback category</td><td>Validation fails</td></tr>
329
- <tr><td><strong>Incomplete HITL</strong></td><td>Missing success/failure</td><td>Approval breaks</td></tr>
330
- </table>
331
-
332
- <h3>Input Source Selection (CRITICAL)</h3>
333
- <table>
334
- <tr><th>Node Type</th><th>✅ Use This</th><th>❌ NOT This</th></tr>
335
- <tr><td><code>chat_categorizer</code></td><td><code>chat_conversation</code></td><td><code>user_query</code> (loses context)</td></tr>
336
- <tr><td><code>search</code></td><td><code>user_query</code> or <code>summarized</code></td><td><code>chat_conversation</code> (type error)</td></tr>
337
- <tr><td><code>respond_with_sources</code></td><td><code>user_query</code> for query</td><td><code>chat_conversation</code></td></tr>
338
- <tr><td><code>call_llm</code></td><td><code>user_query</code> + <code>named_inputs</code></td><td><code>chat_conversation</code> for query</td></tr>
339
- </table>
340
-
341
- <hr>
342
-
343
- <h2>✅ Checklists</h2>
344
-
345
- <h3>All Prompts Checklist</h3>
346
- <ul>
347
- <li>☐ Persona type specified (Voice/Chat/Dashboard)</li>
348
- <li>☐ Clear one-sentence goal</li>
349
- <li>☐ Trigger event specified</li>
350
- <li>☐ Inputs with types/constraints</li>
351
- <li>☐ Pre-fill/auto-suggest behavior</li>
352
- <li>☐ Validations with API calls</li>
353
- <li>☐ Decision logic (all branches)</li>
354
- <li>☐ Actions for each outcome</li>
355
- <li>☐ Output schemas (success + exception)</li>
356
- <li>☐ Error handling/retries</li>
357
- </ul>
358
-
359
- <h3>Voice AI Specific Checklist</h3>
360
- <p><strong>REQUIRED:</strong></p>
361
- <ul>
362
- <li>☐ welcomeMessage — "Hello! I'm [Name]..."</li>
363
- <li>☐ identityAndPurpose — Role, responsibilities, guidelines</li>
364
- <li>☐ takeActionInstructions — &lt;/Case N&gt; format with triggers + params</li>
365
- <li>☐ hangupInstructions — When to end call</li>
366
- </ul>
367
- <p><strong>RECOMMENDED:</strong></p>
368
- <ul>
369
- <li>☐ transferCallInstructions — When to escalate</li>
370
- <li>☐ speechCharacteristics — TTS rules, tone</li>
371
- <li>☐ systemPrompt — Tool calling rules</li>
372
- <li>☐ waitMessage — Processing delays</li>
373
- </ul>
374
-
375
- <h3>MCP Integration Checklist</h3>
376
- <ul>
377
- <li>☐ Called <code>mcp_ema_template(questions=true)</code> before asking user</li>
378
- <li>☐ Called <code>mcp_ema_action(suggest="...")</code> for pattern recommendation</li>
379
- <li>☐ Called <code>mcp_ema_template(pattern="...")</code> for template</li>
380
- <li>☐ Called <code>mcp_ema_action(id="...", include_docs=true)</code> for each agent used</li>
381
- <li>☐ Called <code>mcp_ema_reference(validate_prompt="...")</code> before final output</li>
382
- <li>☐ Checked <code>mcp_ema_reference(mistakes=true)</code> for top errors</li>
383
- </ul>
384
-
385
- <hr>
386
-
387
- <p style="text-align: center; color: #5f6368; font-size: 0.9em;">
388
- <em>Ema Auto Builder Quick Reference Guide</em><br>
389
- Generated from ema-mcp-toolkit documentation
390
- </p>
391
-
392
- </body>
393
- </html>
394
-
package/docs/lessons-learned.md DELETED
@@ -1,209 +0,0 @@
1
- # Lessons Learned & Gotchas
2
-
3
- This document captures mistakes, gotchas, and lessons learned during development.
4
- When you encounter a recurring issue, add it here to prevent future occurrences.
5
-
6
- ---
7
-
8
- ## Architecture Ownership
9
-
10
- ### SDK Owns API Quirks (2026-01)
11
-
12
- **Mistake**: Fixing API quirks (like workflow namespace mismatch) in MCP handlers instead of SDK.
13
-
14
- **Problem**: Fix only protected one code path. Other callers (scripts, tests, future integrations) hit the same bug.
15
-
16
- **Lesson**:
17
- ```
18
- API quirk/format issue → Fix in SDK (protects ALL callers)
19
- User experience issue → Fix in MCP
20
- Not sure? → Fix in SDK
21
- ```
22
-
23
- **Reference**: `CLAUDE.md` - Architectural Ownership Rules
24
-
25
- ---
26
-
27
- ### Silent API Failures (2026-01)
28
-
29
- **Mistake**: Assuming HTTP 200 means success.
30
-
31
- **Problem**: Ema API returns `200 OK` with `proto_config_updated: false` when workflow namespace doesn't match. No error thrown.
32
-
33
- **Lesson**: Always check response body for success indicators, not just HTTP status. The SDK's `updateAiEmployee()` now handles this automatically.
34
-
35
- ---
36
-
37
- ## Dependencies & Generated Code
38
-
39
- ### Connect-ES v2 Migration (2026-01)
40
-
41
- **Mistake**: Dependabot bumped `connect-node` to v2 without bumping `connect` and `protobuf`.
42
-
43
- **Problem**: Version mismatch caused npm install failures and runtime errors.
44
-
45
- **Lesson**: Connect ecosystem packages must be upgraded together:
46
- - `@connectrpc/connect`
47
- - `@connectrpc/connect-node`
48
- - `@bufbuild/protobuf`
49
- - `@bufbuild/protoc-gen-es`
50
-
51
- In v2, `@connectrpc/protoc-gen-connect-es` is no longer needed (services generated in `_pb.ts`).
52
-
53
- ---
54
-
55
- ### Generated vs Hand-Written Code (2026-01)
56
-
57
- **Confusion**: "Where does EmaClient come from?"
58
-
59
- **Architecture**:
60
- | File | Source | Purpose |
61
- |------|--------|---------|
62
- | `src/sdk/ema-client.ts` | Thin wrapper | ✅ **RECOMMENDED**: Wraps generated OpenAPI + gRPC clients |
63
- | `src/sdk/client.ts` | Hand-written | ⚠️ **DEPRECATED**: Still used by MCP handlers (migration pending) |
64
- | `src/sdk/grpc-client.ts` | Thin wrapper | ✅ Wraps generated protos for gRPC |
65
- | `src/sdk/generated/api-client/` | Auto-generated | ✅ OpenAPI client (regenerate: `npm run generate:api-client`) |
66
- | `src/sdk/generated/protos/` | Auto-generated | ✅ Proto types (regenerate: `npm run generate:protos`) |
67
-
68
- **Migration Status** (2026-01):
69
- - `EmaClientV2` is ready but MCP handlers still use legacy `EmaClient`
70
- - Handler migration blocked on type compatibility (generated `PersonaDto` vs hand-written `PersonaDTO`)
71
- - New code should use `EmaClientV2`
72
-
73
- **Migration Example**:
74
- ```typescript
75
- // Old (deprecated):
76
- import { EmaClient } from "./sdk/client.js";
77
- const client = new EmaClient(env);
78
- const personas = await client.getPersonasForTenant();
79
-
80
- // New (recommended):
81
- import { EmaClientV2 } from "./sdk/ema-client.js";
82
- const client = new EmaClientV2(env);
83
- const personas = await client.listPersonas();
84
- ```
85
-
86
- **Lesson**:
87
- - ALWAYS prefer auto-generated clients
88
- - Hand-written clients don't scale and drift from API
89
- - Use thin wrappers for auth/interceptors on top of generated clients
90
- - Regenerate regularly: `npm run generate:api-client && npm run generate:protos`
91
-
92
- ---
93
-
94
- ## Workflow Deployment
95
-
96
- ### Namespace Mismatch (2026-01)
97
-
98
- **Mistake**: Creating a workflow with a different `workflowName.name.namespaces` than the persona's existing workflow.
99
-
100
- **Problem**: API silently rejects the update (`proto_config_updated: false`).
101
-
102
- **Lesson**: When updating a persona's workflow:
103
- 1. Fetch existing persona first
104
- 2. Copy `workflowName` from existing workflow
105
- 3. SDK's `updateAiEmployee()` does this automatically
106
-
107
- **Reference**: `src/sdk/client.ts` - `updateAiEmployee()` method
108
-
109
- ---
110
-
111
- ## MCP vs Agent Separation (2026-01)
112
-
113
- ### MCP Should Not Parse Intent
114
-
115
- **Mistake**: Creating `parseIntent()` function with regex to "understand" natural language.
116
-
117
- **Problem**: MCP tried to be the LLM instead of letting the agent reason naturally. Led to:
118
- - Circular debugging trying to add more regex patterns
119
- - `needs_llm: true` responses that confused the architecture
120
- - Wasted effort on deterministic parsing of inherently semantic input
121
-
122
- **Lesson**:
123
- ```
124
- Agent (LLM) → Understands intent, asks questions, builds workflow_spec
125
- MCP → Provides context (analyze), executes (update with workflow_spec)
126
- ```
127
-
128
- **Functions deprecated as a result**:
129
- - `parseIntent()` - MCP shouldn't parse natural language
130
- - `applyOperations()` - MCP shouldn't apply modifications
131
- - `transformWorkflowFromIntent()` - MCP shouldn't transform from intent
132
-
133
- **Reference**: `CLAUDE.md` - MCP vs Agent: Separation of Duties
134
-
135
- ---
136
-
137
- ### HITL is Optional, Not Required
138
-
139
- **Mistake**: Assuming all side effects (email, API calls) require HITL approval.
140
-
141
- **Problem**: Auto-added HITL gates without asking user. Made false assumptions about user intent.
142
-
143
- **Lesson**:
144
- ```
145
- ❌ WRONG: "I'll add approval before the email sends"
146
- ✅ RIGHT: "Should someone approve emails before they're sent?"
147
- ```
148
-
149
- - INFO severity = "Consider this" not "Must fix"
150
- - Only add HITL if user explicitly requests approval
151
- - ASK before assuming approval requirements
152
-
153
- **Reference**: `.cursor/agents/local/ema-workflow.md` - "Side Effects: Ask, Don't Assume"
154
-
155
- ---
156
-
157
- ### Auto-Fix Can Create Invalid State
158
-
159
- **Mistake**: Using `analyze(fix=true)` to auto-fix issues.
160
-
161
- **Problem**: Auto-fix created an orphan node (`convert_email_q0lx8s`) that made the workflow invalid. The fix was worse than the original issue.
162
-
163
- **Lesson**:
164
- - `analyze` should REPORT issues, not fix them
165
- - Agent should ASK which issues to fix
166
- - Agent should BUILD the fix, then deploy via `update`
167
- - Never auto-fix complex issues without user confirmation
168
-
169
- ---
170
-
171
- ## SDK Capability Discovery
172
-
173
- ### "Not Yet Implemented" Was Already Implemented (2026-01)
174
-
175
- **Mistake**: Handler code had `"not yet implemented"` placeholder for document cloning, but SDK already had all required capabilities:
176
- - `getDashboardRowResult(personaId, rowId, includeFileContents=true)` - fetches document content
177
- - `DashboardInput.document_value` - supports base64-encoded documents
178
-
179
- **Root Cause**:
180
- 1. SDK dashboard methods weren't documented in `src/sdk/README.md`
181
- 2. No rule existed to check SDK capabilities before marking something "not implemented"
182
- 3. Handler code was written without exhaustively checking SDK's existing methods
183
-
184
- **Lesson**:
185
- ```
186
- BEFORE marking anything "not yet implemented":
187
- 1. Check src/sdk/client.ts for existing methods in the feature area
188
- 2. Check type definitions for already-supported input/output formats
189
- 3. If SDK has the capability, wire it up - don't create placeholders
190
- ```
191
-
192
- **Fix Applied**:
193
- - Updated `src/sdk/README.md` with Dashboard Methods section
194
- - Added rule to `CLAUDE.md`: "Check SDK Before Implementing"
195
- - Wired up the existing SDK capabilities in the handler
196
-
197
- **Reference**: `src/mcp/handlers-consolidated.ts` - dashboard_clone case
198
-
199
- ---
200
-
201
- ## Adding New Lessons
202
-
203
- When you encounter a gotcha:
204
-
205
- 1. Add a new section with date
206
- 2. Document: Mistake → Problem → Lesson
207
- 3. Add code examples if helpful
208
- 4. Reference related files/docs
209
- 5. Update CLAUDE.md or AGENTS.md if it's a critical rule