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

package/docs/migration/action-composition-migration.md

@@ -1,270 +0,0 @@
-# Migration Guide: Action Composition
-
-> **Version**: Introduced in 2026.01.19  
-> **Status**: Optional (backward compatible)  
-> **Breaking Changes**: None - legacy flag syntax still works
-
-## Overview
-
-This release introduces **action composition** as an alternative to flag-based parameters for multi-step operations. The old syntax continues to work but the new syntax is recommended for new code.
-
-## What Changed
-
-### Old Way (Flag-Based)
-
-```typescript
-// Clone with data copy and sanitization
-persona(
-  method="create",
-  from="source-persona",
-  name="Demo Clone",
-  include_data=true,
-  sanitize=true,
-  sanitize_examples=["Acme Corp", "john@example.com"]
-)
-```
-
-### New Way (Action-Based)
-
-```typescript
-// Same operation with explicit actions
-persona(
-  method="create",
-  from="source-persona",
-  name="Demo Clone",
-  actions=[
-    {tool:"data", args:{method:"copy", from:"$source"}},
-    {tool:"data", args:{method:"sanitize", examples:["Acme Corp", "john@example.com"]}},
-    {tool:"snapshot", args:{message:"Demo clone ready"}},
-  ]
-)
-```
-
-## Why Change?
-
-| Issue with Flags | Benefit of Actions |
-|------------------|-------------------|
-| Semantics encoded in names (`include_data`) | Operations explicit (`method:"copy"`) |
-| Coupled parameters (`sanitize_examples` requires `sanitize=true`) | Each action self-contained |
-| Hidden execution order | Array order = execution order |
-| Schema grows with features | Schema stable |
-| Hard to add new capabilities | Add new action tools freely |
-
-## Migration Guide
-
-### For MCP Clients (LLMs/Agents)
-
-**No action required.** The old flag syntax continues to work:
-
-```typescript
-// This still works (backward compatible)
-persona(method="create", from="src", name="Clone", include_data=true, sanitize=true)
-```
-
-**To use the new syntax** (recommended for new code):
-
-```typescript
-// New syntax with explicit actions
-persona(method="create", from="src", name="Clone", actions=[
-  {tool:"data", args:{method:"copy", from:"$source"}},
-  {tool:"data", args:{method:"sanitize"}},
-])
-```
-
-### For Cursor Rules / Agent Instructions
-
-Update any rules that hardcode the old flag syntax:
-
-```diff
-# Before
-- persona(method="create", from="src", name="Clone", include_data=true, sanitize=true)
-
-# After (recommended)
-+ persona(method="create", from="src", name="Clone", actions=[
-+   {tool:"data", args:{method:"copy", from:"$source"}},
-+   {tool:"data", args:{method:"sanitize"}},
-+ ])
-```
-
-### For TypeScript SDK Users
-
-The SDK automatically handles both syntaxes. No code changes required.
-
-## Syntax Reference
-
-### Action Spec Format
-
-```typescript
-{
-  tool: "data" | "snapshot" | "validate",  // Tool to invoke
-  args: { ... }                            // Arguments (same as direct tool call)
-}
-```
-
-### Context Variables
-
-| Variable | Description |
-|----------|-------------|
-| `$source` | The `from` parameter (template/persona being cloned) |
-| `$target` | ID of the created/modified persona |
-| `$env` | Current environment name |
-
-### Built-in Aliases
-
-Instead of writing full action specs, you can use aliases:
-
-```typescript
-// Using alias
-persona(method="create", from="src", name="Clone", actions=["copy-and-sanitize"])
-
-// Equivalent to
-persona(method="create", from="src", name="Clone", actions=[
-  {tool:"data", args:{method:"copy", from:"$source"}},
-  {tool:"data", args:{method:"sanitize"}},
-])
-```
-
-| Alias | Expands To |
-|-------|-----------|
-| `"copy-data"` | Copy data from source |
-| `"copy-and-sanitize"` | Copy data, then sanitize |
-| `"standard-demo-setup"` | Copy, sanitize, create snapshot |
-| `"validate-workflow"` | Run workflow validation |
-
-### Available Action Tools
-
-| Tool | Methods | Purpose |
-|------|---------|---------|
-| `data` | copy, sanitize, upload | Data operations |
-| `snapshot` | (message) | Create version checkpoint |
-| `validate` | (checks) | Run validation checks |
-
-## Examples
-
-### Clone with Data Copy
-
-```typescript
-// Old
-persona(method="create", from="src", name="Clone", include_data=true)
-
-// New
-persona(method="create", from="src", name="Clone", actions=[
-  {tool:"data", args:{method:"copy", from:"$source"}}
-])
-
-// New (with alias)
-persona(method="create", from="src", name="Clone", actions=["copy-data"])
-```
-
-### Clone with Sanitization
-
-```typescript
-// Old
-persona(method="create", from="src", name="Clone", include_data=true, sanitize=true, sanitize_examples=["Acme"])
-
-// New
-persona(method="create", from="src", name="Clone", actions=[
-  {tool:"data", args:{method:"copy", from:"$source"}},
-  {tool:"data", args:{method:"sanitize", examples:["Acme"]}},
-])
-
-// New (with alias)
-persona(method="create", from="src", name="Clone", actions=["copy-and-sanitize"])
-```
-
-### Clone with LLM-Generated Content
-
-```typescript
-// No old equivalent - this is new functionality
-persona(method="create", from="template-id", name="Test Dashboard", actions=[
-  {tool:"data", args:{
-    method:"upload",
-    content:[
-      {document:{text:"Contract 1..."}, title:"Contract A", value:50000},
-      {document:{text:"Contract 2..."}, title:"Contract B", value:75000},
-    ]
-  }},
-  {tool:"snapshot", args:{message:"Test data loaded"}},
-])
-```
-
-### Multiple Operations with Checkpoint
-
-```typescript
-persona(method="create", from="prod-persona", name="Demo", actions=[
-  {tool:"data", args:{method:"copy", from:"$source"}},
-  {tool:"data", args:{method:"sanitize", examples:["Acme Corp", "john@acme.com"]}},
-  {tool:"validate", args:{checks:["workflow", "config"]}},
-  {tool:"snapshot", args:{message:"Demo environment ready"}},
-])
-```
-
-## Response Format
-
-When using actions, the response includes an `actions` field:
-
-```json
-{
-  "success": true,
-  "persona_id": "new-persona-123",
-  "name": "Demo Clone",
-  "actions": {
-    "executed": 3,
-    "succeeded": 3,
-    "failed": 0,
-    "results": [
-      {"tool": "data", "status": "success", "result": {...}, "duration_ms": 150},
-      {"tool": "data", "status": "success", "result": {...}, "duration_ms": 89},
-      {"tool": "snapshot", "status": "success", "result": {...}, "duration_ms": 12}
-    ]
-  }
-}
-```
-
-If an action fails, execution stops and the response includes details:
-
-```json
-{
-  "success": false,
-  "partial": true,
-  "persona_id": "new-persona-123",
-  "actions": {
-    "executed": 2,
-    "succeeded": 1,
-    "failed": 1,
-    "stopped_on_error": true,
-    "results": [
-      {"tool": "data", "status": "success", ...},
-      {"tool": "data", "status": "error", "error": "Source persona not found"}
-    ]
-  }
-}
-```
-
-## FAQ
-
-### Do I have to migrate?
-
-No. The old syntax works and will continue to work. Migration is optional but recommended for new code.
-
-### Can I mix old and new syntax?
-
-No. If you provide `actions`, the flag parameters (`include_data`, `sanitize`, etc.) are ignored. Choose one approach per call.
-
-### What if an action fails?
-
-Execution stops at the first error. The base operation (e.g., persona creation) is still completed, but subsequent actions are skipped. The response indicates `partial: true` and includes error details.
-
-### How do I know what actions are available?
-
-Use `catalog(method="list", type="concepts")` or check the tool description in your MCP client. The available actions are documented in the `persona` tool description.
-
-### Can I create custom aliases?
-
-Not yet. Currently only built-in aliases are supported. Custom aliases may be added in a future version.
-
-## Related Documentation
-
-- Design doc: `docs/proposals/action-composition.md`
-- Naming conventions: `docs/naming-conventions.md`
-- Full tools guide: `docs/mcp-tools-guide.md`

package/docs/naming-conventions.md

@@ -1,278 +0,0 @@
-# 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 explicit `method` parameter**:
-
-```
-{noun}(method="{action}", ...)
-```
-
-**Key principle**: The LLM explicitly declares the operation via `method`. MCP does not infer operations from parameter presence.
-
-### Current Consolidated Tools
-
-| Tool | Methods | Pattern |
-|------|---------|---------|
-| `persona` | list, get, create, update, delete, analyze, sanitize, snapshot, history, restore, compare | `persona(method="create", ...)` |
-| `catalog` | list, get, search, recommend | `catalog(method="list", type="actions")` |
-| `sync` | preview, execute, status | `sync(method="preview", ...)` |
-| `env` | (single operation) | `env()` |
-
-### Data Sub-Resource (under persona)
-
-```
-persona(id="abc", data={method:"{action}", ...})
-```
-
-| Method | Purpose | Example |
-|--------|---------|---------|
-| `list` | List data items | `data={method:"list"}` |
-| `schema` | Get input schema | `data={method:"schema"}` |
-| `upload` | Upload file or content | `data={method:"upload", path:"..."}` |
-| `copy` | Copy from another persona | `data={method:"copy", from:"..."}` |
-| `delete` | Delete item | `data={method:"delete", id:"..."}` |
-| `embed` | Toggle embeddings | `data={method:"embed", enabled:true}` |
-| `search` | Search data | `data={method:"search", query:"..."}` |
-
-### Action Composition (multi-step operations)
-
-Instead of flag parameters (`include_data=true`, `sanitize=true`), use the `actions` array:
-
-```
-persona(method="create", from="...", name="...", actions=[...])
-```
-
-| Pattern | Purpose | Example |
-|---------|---------|---------|
-| Action spec | Explicit tool + args | `{tool:"data", args:{method:"copy", from:"$source"}}` |
-| Alias | Named pattern | `"copy-and-sanitize"`, `"standard-demo-setup"` |
-
-**Context variables** (auto-substituted):
-- `$source` - The `from` parameter (template/persona being cloned)
-- `$target` - The ID of the created/modified persona
-- `$env` - Current environment
-
-**Available action tools:**
-- `data` - Data operations (copy, sanitize, upload)
-- `snapshot` - Create version checkpoint
-- `validate` - Run validation checks
-
-**Built-in aliases:**
-- `copy-data` - Copy data from source
-- `copy-and-sanitize` - Copy then sanitize
-- `standard-demo-setup` - Copy, sanitize, snapshot
-
-**Key principle**: Operations are explicit, not encoded in parameter names.
-
-```typescript
-// ❌ BAD: Semantics encoded in names
-persona(method="create", ..., include_data=true, sanitize=true, sanitize_examples=[...])
-
-// ✅ GOOD: Explicit composable actions
-persona(method="create", ..., actions=[
-  {tool:"data", args:{method:"copy", from:"$source"}},
-  {tool:"data", args:{method:"sanitize", examples:[...]}},
-])
-```
-
-### Legacy Tool Aliases (DEPRECATED - for backwards compatibility only)
-
-These exist ONLY for backwards compatibility and redirect to consolidated tools:
-
-```
-deploy_workflow → persona(method="update", ...)
-workflow → persona(method="update", ...)
-knowledge → persona(id="...", data={method:"..."})
-demo → persona(id="...", data={method:"upload", ...})
-```
-
-**DO NOT create new tools with `verb_noun` pattern.**
-**DO NOT infer operations from parameter presence - always use explicit `method`.**
-**DO NOT add flag parameters for operations - use `actions` array instead.**
-
----
-
-## 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 |
-|---------|---------|--------------|
-| `persona_create` | Create a persona | `persona(method="create", ...)` |
-| `persona_update` | Update a persona | `persona(method="update", ...)` |
-| `persona_analyze` | Analyze a persona | `persona(method="analyze", ...)` |
-| `persona_sanitize` | Sanitize a persona | `persona(method="sanitize", ...)` |
-| `persona_sync` | Sync a persona | `sync(method="execute", ...)` |
-| `data_upload` | Upload data | `persona(id="...", data={method:"upload", ...})` |
-| `data_copy` | Copy data | `persona(id="...", data={method:"copy", ...})` |
-
-### 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}(method="{action}")` for tools?
-- [ ] Does tool use explicit `method` parameter (not inferred from other params)?
-- [ ] 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-v2.ts`
-- Prompts defined in: `src/mcp/prompts.ts`
-- Legacy mappings in: `src/mcp/tools-legacy.ts`
-- Design doc: `docs/proposals/explicit-method-restructure.md`
-- Action composition: `docs/proposals/action-composition.md`