@ema.co/mcp-toolkit 0.2.0

package/docs/mcp-tools-guide.md

@@ -0,0 +1,149 @@
+# Ema MCP Tools Guide (Consolidated)
+
+This MCP server is intentionally designed for **LLM + agent ergonomics**:
+
+- **Few tools, consistent shapes**: a small set of noun-based tools with predictable `mode` / flag patterns
+- **Resources-first**: use `ema://...` resources for reference data/templates, then tools for actions
+- **Low ambiguity**: defaults are chosen to avoid “which of 5 similar tools?” confusion
+
+## Tool names in MCP clients
+
+The server defines **base tool names** like `persona`, `workflow`, `template`.
+
+Some clients show a **prefixed name** (for example Cursor: `mcp_ema_workflow`). Always call **the tool name your client displays**; the semantics are the same.
+
+## The tool set (9 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `env` | List available environments and which is default |
+| `persona` | AI Employee management (get/list/create/update/compare/templates) |
+| `workflow` | Generate/analyze/deploy/optimize/compare/compile workflows |
+| `action` | Actions/agents lookup (API + embedded docs), plus recommendations |
+| `template` | Workflow patterns, widget references, qualifying questions |
+| `knowledge` | Data sources + embedding (upload/list/delete/status/toggle) |
+| `reference` | Concepts + guidance + validation + common mistakes |
+| `sync` | Sync across environments (run/status/config) |
+| `demo` | Demo/RAG document utilities (template/consolidate/generate/validate) |
+
+## Start-here flows (LLM-friendly)
+
+### Create a new AI Employee (recommended sequence)
+
+1. **Requirements**: `template(questions=true)` (and `template(questions=true, category="Voice")` for voice)
+2. **Pick agents/pattern**: `action(suggest="<use case>")`
+3. **Get the pattern**: `template(pattern="<pattern>")`
+4. **Generate configs**:
+   - `workflow(input="<requirements>", type="chat|voice|dashboard")`
+   - If you want deterministic local generation: add `use_autobuilder=false`
+5. **Create persona** (if needed): `persona(mode="create", name="...", type="chat|voice|dashboard")`
+6. **Deploy**: `workflow(mode="deploy", persona_id="...", workflow_def=<...>, proto_config=<...>)`
+7. **Review**: `workflow(mode="analyze", persona_id="...")`
+
+### Review or debug an existing AI Employee
+
+1. Fetch full workflow: `persona(id="<id-or-exact-name>", include_workflow=true)`
+2. Analyze: `workflow(mode="analyze", persona_id="<persona_id>")`
+3. Preview fixes: `workflow(mode="optimize", persona_id="<persona_id>", preview=true)`
+4. Apply fixes: `workflow(mode="optimize", persona_id="<persona_id>")`
+
+### Upload / manage knowledge base documents
+
+1. Upload: `knowledge(persona_id="...", mode="upload", file="/path/to/file.pdf")`
+2. Enable embedding: `knowledge(persona_id="...", mode="toggle", enabled=true)`
+3. Verify: `knowledge(persona_id="...", mode="list")`
+
+### Sync between environments
+
+- Run (single): `sync(id="My Bot", source="demo", target="dev", dry_run=true|false)`
+- Run (all tagged): `sync(target="dev", scope="all", dry_run=true|false)`
+- Status: `sync(mode="status", id="My Bot", env="dev")`
+- List all synced in env: `sync(mode="status", list_synced=true, env="dev")`
+- Config: `sync(mode="config")`
+
+### Demo data → RAG-ready Markdown → upload
+
+1. Get a template: `demo(mode="template", entity="customer")`
+2. Consolidate a dataset: `demo(mode="consolidate", source="./data", output="./kb", entity="customer", primary="customers.json", joins=[...])`
+3. Upload: `knowledge(persona_id="...", mode="upload", file="/full/path/to/kb/customer_*.md")`
+
+## Tool reference (high-signal)
+
+### `persona`
+
+- **Get**: `persona(id="...", include_workflow=true)`
+- **List/search**: `persona(all=true)` / `persona(query="support", status="active")`
+- **Create**: `persona(mode="create", name="...", type="chat|voice|dashboard")`
+- **Update**: `persona(id="<id>", mode="update", name="...", description="...", enabled=true|false)`
+- **Compare**: `persona(id="<id>", mode="compare", compare_to="<id>", compare_env="dev")`
+- **Templates**: `persona(templates=true)`
+
+### `workflow`
+
+- **Generate**: `workflow(input="<requirements>", type="chat|voice|dashboard")`
+- **Analyze**:
+  - By persona: `workflow(mode="analyze", persona_id="<id>")`
+  - By JSON: `workflow(mode="analyze", workflow_def={<...>})`
+  - Limit output: `workflow(mode="analyze", persona_id="<id>", include=["issues"|"connections"|"fixes"|"metrics"])`
+- **Deploy**: `workflow(mode="deploy", persona_id="<id>", workflow_def={<...>}, proto_config={<...>}, auto_fix=true)`
+- **Optimize** (analyze + fixes + deploy): `workflow(mode="optimize", persona_id="<id>", preview=true|false)`
+- **Compare**: `workflow(mode="compare", persona_id="<before>", compare_to="<after>")`
+- **Compile** (from explicit nodes): `workflow(mode="compile", name="...", description="...", type="chat|voice|dashboard", nodes=[...], result_mappings=[...])`
+
+### `action`
+
+- **Get**: `action(id="chat_categorizer", include_docs=true)`
+- **List/search**: `action(all=true)` / `action(query="search")` / `action(category="routing")`
+- **Suggest**: `action(suggest="IT helpdesk that creates ServiceNow tickets")`
+
+### `template`
+
+- **Patterns**: `template(patterns=true)` / `template(pattern="intent-routing")`
+- **Qualifying questions**: `template(questions=true)` / `template(questions=true, category="Voice", required_only=true)`
+- **Widget reference**: `template(widgets="voice")`
+
+### `reference`
+
+- **Concept**: `reference(concept="HITL")`
+- **Guidance**: `reference(guidance="categorizer-routing")`
+- **Validate Auto Builder prompt**: `reference(validate_prompt="<prompt>")`
+- **Common mistakes**: `reference(mistakes=true)`
+- **Debug checklist**: `reference(checklist=true)`
+
+## Resources (read-first)
+
+Start with:
+
+- `ema://index/all-resources` (index)
+- `ema://docs/readme` (toolkit overview)
+- `ema://docs/ema-user-guide` (platform concepts)
+- `ema://catalog/agents-summary` (quick agent overview)
+- `ema://catalog/templates` (persona templates from API - dynamic)
+- `ema://catalog/templates-summary` (template overview - dynamic)
+- `ema://catalog/patterns` (workflow patterns)
+- `ema://rules/input-sources` and `ema://rules/anti-patterns` (validation rules)
+
+## Auto-Fix Capabilities
+
+The `workflow(mode="optimize")` can automatically fix common issues:
+
+| Issue | Auto-Fix Action |
+|-------|----------------|
+| `wrong_input_source` (email_to) | Adds `entity_extraction` node, wires to extracted `email_address` |
+| `wrong_input_source` (query) | Rewires from `chat_conversation` to `user_query` |
+| `missing_workflow_output` | Adds results mapping for response nodes |
+| `missing_category_edge` | Validates runIf pattern as alternative |
+
+Issues requiring manual intervention:
+- `incomplete_hitl` - Needs success/failure response node configuration
+- Complex routing changes - Multiple nodes affected
+
+## Legacy tools (migration only)
+
+Legacy tools are **disabled by default** to reduce duplicate semantics and tool confusion for LLMs.
+
+If you must enable them (temporary):
+
+- Set `EMA_ENABLE_LEGACY_TOOLS=true`
+- Prefer the consolidated tools for new usage
+

package/docs/naming-conventions.md

@@ -0,0 +1,218 @@
+# MCP Naming Conventions (AUTHORITATIVE)
+
+> **THIS IS THE SINGLE SOURCE OF TRUTH FOR ALL NAMING IN THIS PROJECT.**
+> Any deviation from this document is a bug.
+
+---
+
+## Core Principle
+
+**ONE pattern for similar things. Tools and prompts that relate to the same domain MUST use the same naming structure.**
+
+---
+
+## 1. MCP Tools (Consolidated)
+
+Tools use **noun-based naming with `mode` parameter**:
+
+```
+{noun}(mode="{action}", ...)
+```
+
+### Current Consolidated Tools
+
+| Tool | Modes | Pattern |
+|------|-------|---------|
+| `workflow` | generate, analyze, deploy, optimize, compare, compile, explain, extend | `workflow(mode="deploy", ...)` |
+| `persona` | get, list, create, update, compare, templates | `persona(mode="create", ...)` |
+| `action` | list, docs, suggest, recommendations | `action(mode="suggest", ...)` |
+| `template` | (patterns, questions, widgets) | `template(pattern="...", ...)` |
+| `knowledge` | upload, list, delete, status, toggle | `knowledge(mode="upload", ...)` |
+| `reference` | (validation, guidance) | `reference(check_types=..., ...)` |
+| `sync` | run, status, config | `sync(mode="run", ...)` |
+| `demo` | template, consolidate, generate, validate | `demo(mode="generate", ...)` |
+| `env` | (list environments) | `env()` |
+
+### Legacy Tool Aliases (DEPRECATED - for backwards compatibility only)
+
+These exist ONLY for backwards compatibility and redirect to consolidated tools:
+
+```
+deploy_workflow → workflow(mode="deploy")
+optimize_workflow → workflow(mode="optimize")
+analyze_workflow → workflow(mode="analyze")
+```
+
+**DO NOT create new tools with `verb_noun` pattern.**
+
+---
+
+## 2. MCP Prompts
+
+Prompts are **guided multi-step workflows**. They MUST follow the **same `{noun}_{action}` pattern** as tools:
+
+```
+{noun}_{action}
+{noun}_{action}_{qualifier}  # only when disambiguation needed
+```
+
+### Prompt Naming Rules
+
+| Pattern | Example | Maps To Tool |
+|---------|---------|--------------|
+| `workflow_generate` | Generate a workflow | `workflow(mode="generate")` |
+| `workflow_deploy` | Deploy a workflow | `workflow(mode="deploy")` |
+| `workflow_explain` | Explain a workflow | `workflow(mode="explain")` |
+| `workflow_extend` | Extend a workflow | `workflow(mode="extend")` |
+| `workflow_analyze_intent` | Analyze workflow intent | `workflow(mode="analyze", include=["intent"])` |
+| `persona_create` | Create a persona | `persona(mode="create")` |
+| `persona_sync` | Sync a persona | `sync(mode="run")` |
+
+### FORBIDDEN Patterns
+
+```
+❌ deploy_workflow       # verb_noun is WRONG
+❌ explain_workflow      # verb_noun is WRONG  
+❌ generate_workflow_direct  # _direct suffix is unclear
+❌ analyze_workflow_intent   # should be workflow_analyze_intent
+```
+
+### Acceptable Legacy Exceptions (for backwards compat only)
+
+These prompts exist and are grandfathered but should not be used as templates:
+
+- `generate_ai_employee` - legacy, use `persona_create` for new
+- `create_voice_ai` - legacy, use `persona_create` with `type="voice"`
+- `create_chat_ai` - legacy, use `persona_create` with `type="chat"`
+
+---
+
+## 3. Functions & Interfaces
+
+### Functions
+
+```typescript
+// Pattern: {verb}{Noun} or {verb}{Noun}{Qualifier}
+parseNaturalLanguage()
+validateIntent()
+detectActionChains()
+calculateIntentConfidence()
+generateOutputSemanticsPrompt()
+applyExtractedSemantics()
+```
+
+### Interfaces/Types
+
+```typescript
+// Pattern: {Noun}{Qualifier}
+WorkflowIntent
+OutputSemantics
+IntentConfidence
+ValidationResult
+AgentDefinition
+```
+
+### Constants
+
+```typescript
+// Pattern: SCREAMING_SNAKE_CASE
+AGENT_CATALOG
+WORKFLOW_PATTERNS
+TYPE_COMPATIBILITY
+ACTION_CHAIN_PATTERNS
+```
+
+---
+
+## 4. Issue Types (Validation)
+
+Issue types use **snake_case** with category prefix:
+
+```
+{category}_{specific_problem}
+```
+
+| Category | Examples |
+|----------|----------|
+| `unused_` | `unused_output` |
+| `missing_` | `missing_entity_extraction`, `missing_category_edge` |
+| `wrong_` | `wrong_input_source` |
+| `side_effect_` | `side_effect_without_hitl` |
+| `redundant_` | `redundant_search` |
+| `sequential_` | `sequential_search` |
+| `duplicate_` | `duplicate_llm_processing` |
+
+---
+
+## 5. Resource URIs
+
+Resource URIs use **path-like structure**:
+
+```
+ema://{category}/{subcategory}/{item}
+```
+
+| Pattern | Example |
+|---------|---------|
+| Catalogs | `ema://catalog/agents`, `ema://catalog/agents/summary` |
+| Patterns | `ema://patterns/workflows` |
+| Templates | `ema://templates/voice-ai/config` |
+| Validation | `ema://validation/input-sources`, `ema://validation/anti-patterns` |
+| Index | `ema://index/all-resources` |
+
+---
+
+## 6. File Naming
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| TypeScript source | `kebab-case.ts` | `workflow-intent.ts`, `validation-rules.ts` |
+| Test files | `{module}.test.ts` | `workflow-intent.test.ts` |
+| Documentation | `kebab-case.md` | `naming-conventions.md` |
+| Config | `kebab-case.yaml/json` | `config.example.yaml` |
+
+---
+
+## Enforcement Checklist
+
+Before adding ANY new name:
+
+- [ ] Does it follow `{noun}_{action}` for prompts?
+- [ ] Does it follow `{noun}(mode="{action}")` for tools?
+- [ ] Does it follow `{verb}{Noun}` for functions?
+- [ ] Does it follow `{Noun}{Qualifier}` for interfaces?
+- [ ] Is there already a similar pattern established? If so, follow it exactly.
+- [ ] Does it avoid hardcoded specific values?
+- [ ] Is it clear what the name refers to?
+
+---
+
+## Migration Notes
+
+### Renamed in this cleanup:
+
+| Old (WRONG) | New (CORRECT) |
+|-------------|---------------|
+| `deploy_workflow` | `workflow_deploy` |
+| `explain_workflow` | `workflow_explain` |
+| `extend_workflow` | `workflow_extend` |
+| `analyze_workflow_intent` | `workflow_analyze_intent` |
+| `generate_workflow_direct` | `workflow_generate` |
+| `generate_ai_employee` | `ai_employee_generate` |
+| `review_workflow` | `workflow_review` |
+| `debug_workflow` | `workflow_debug` |
+| `create_voice_ai` | `persona_create_voice` |
+| `create_chat_ai` | `persona_create_chat` |
+| `sync_persona` | `persona_sync` |
+| `compare_personas` | `persona_compare` |
+| `validate_prompt` | `prompt_validate` |
+| `onboard_toolkit` | `toolkit_onboard` |
+| `clarify_requirements` | `requirements_clarify` |
+
+---
+
+## References
+
+- Tools defined in: `src/mcp/tools-consolidated.ts`
+- Prompts defined in: `src/mcp/prompts.ts`
+- Legacy mappings in: `src/mcp/tools-legacy.ts`