ema-mcp-toolkit 0.2.0

package/README.md

@@ -0,0 +1,338 @@
+# Ema MCP Toolkit
+
+A comprehensive toolkit for managing Ema AI Employees via **MCP Server** (for AI assistants like Cursor/Claude), **CLI**, and **SDK**.
+
+## Installation
+
+### Option 1: npx (Recommended - No Installation)
+
+```bash
+# Run directly without installing
+npx ema-mcp-toolkit
+```
+
+### Option 2: Global Install
+
+```bash
+npm install -g ema-mcp-toolkit
+ema-mcp  # Start MCP server
+ema      # CLI
+```
+
+### Option 3: Clone & Build (Development)
+
+```bash
+git clone https://github.com/ema-co/ema-mcp-toolkit.git
+cd ema-mcp-toolkit
+npm install
+npm run build
+```
+
+---
+
+## Quick Start
+
+### 1. Set Your Token
+
+```bash
+# Minimal setup - just one token for demo environment
+export EMA_BEARER_TOKEN="your-token-here"
+
+# Or use environment-specific naming (auto-detected)
+export EMA_DEMO_BEARER_TOKEN="your-demo-token"
+export EMA_DEV_BEARER_TOKEN="your-dev-token"
+```
+
+### 2. Add to Your AI Assistant
+
+**Cursor** (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ema": {
+      "command": "npx",
+      "args": ["ema-mcp-toolkit"],
+      "env": {
+        "EMA_DEMO_BEARER_TOKEN": "your-demo-token",
+        "EMA_DEV_BEARER_TOKEN": "your-dev-token"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ema": {
+      "command": "npx",
+      "args": ["ema-mcp-toolkit"],
+      "env": {
+        "EMA_DEMO_BEARER_TOKEN": "your-demo-token"
+      }
+    }
+  }
+}
+```
+
+### 3. Start Using
+
+Ask your AI assistant:
+- "List my AI Employees"
+- "Analyze the workflow for Customer Support Bot"
+- "Create a new Voice AI for appointment scheduling"
+
+---
+
+## Configuration
+
+### Zero-Config Mode (Recommended)
+
+No config file needed! The toolkit auto-detects environments from environment variables:
+
+```bash
+# Pattern: EMA_<ENV>_BEARER_TOKEN
+export EMA_DEMO_BEARER_TOKEN="..."   # → creates "demo" environment
+export EMA_DEV_BEARER_TOKEN="..."    # → creates "dev" environment
+export EMA_STAGING_BEARER_TOKEN="..."# → creates "staging" environment
+export EMA_PROD_BEARER_TOKEN="..."   # → creates "prod" environment
+
+# Optional: Custom URLs (auto-detected if not set)
+export EMA_DEV_BASE_URL="https://api.custom-dev.ema.co"
+
+# Optional: Set default environment
+export EMA_ENV_NAME="dev"
+```
+
+**Well-known URLs** (automatic):
+| Environment | URL |
+|-------------|-----|
+| `demo` | `https://api.demo.ema.co` |
+| `dev` | `https://api.dev.ema.co` |
+| `staging` | `https://api.staging.ema.co` |
+| `prod` | `https://api.ema.co` |
+
+### Config File (Advanced)
+
+For complex setups, create `ema.config.yaml`:
+
+```yaml
+environments:
+  - name: demo
+    baseUrl: https://api.demo.ema.co
+    bearerTokenEnv: EMA_DEMO_BEARER_TOKEN  # References env var
+    isMaster: true
+
+  - name: dev
+    baseUrl: https://api.dev.ema.co
+    bearerTokenEnv: EMA_DEV_BEARER_TOKEN
+```
+
+Then point to it:
+```bash
+export EMA_AGENT_SYNC_CONFIG=./ema.config.yaml
+```
+
+### JSON Config via Environment (CI/CD)
+
+For CI/CD, pass config as JSON:
+
+```bash
+export EMA_CONFIG_JSON='{"environments":[{"name":"demo","baseUrl":"https://api.demo.ema.co","bearerTokenEnv":"EMA_DEMO_BEARER_TOKEN","isMaster":true}]}'
+```
+
+---
+
+## Getting Your Token
+
+1. Log in to [Ema Platform](https://app.ema.co)
+2. Open browser DevTools → Network tab
+3. Make any API request and find the `Authorization: Bearer ...` header
+4. Copy the token (without "Bearer " prefix)
+
+**Note**: Tokens expire. The toolkit supports automatic token refresh if you configure a refresh callback in the SDK.
+
+---
+
+## Usage
+
+### MCP Server (AI Assistants)
+
+The MCP server provides **9 consolidated tools**, **15 prompts**, and **dynamic resources**.
+
+#### Tools
+
+| Tool | Purpose |
+|------|---------|
+| `env` | List available environments |
+| `persona` | AI Employee management (get/list/create/update/compare) |
+| `workflow` | Generate/analyze/deploy/optimize/explain/extend workflows |
+| `action` | Agent lookup, docs, and recommendations |
+| `template` | Patterns, widgets, qualifying questions |
+| `knowledge` | Data sources + embedding (upload/list/delete/toggle) |
+| `reference` | Concepts, guidance, validation, common mistakes |
+| `sync` | Sync across environments |
+| `demo` | Demo/RAG document utilities |
+
+#### Resources (Dynamic)
+
+| Resource | Source |
+|----------|--------|
+| `ema://catalog/agents` | Live from API |
+| `ema://catalog/templates` | Live from API |
+| `ema://catalog/patterns` | Workflow patterns |
+| `ema://rules/anti-patterns` | Validation rules |
+
+### CLI
+
+```bash
+# List personas
+ema personas list
+
+# Sync a persona
+ema sync persona "My Bot" --target dev --dry-run
+
+# Check sync status
+ema sync status
+```
+
+### SDK (Programmatic)
+
+```typescript
+import { EmaClient } from "ema-mcp-toolkit";
+
+const client = new EmaClient({
+  name: "demo",
+  baseUrl: "https://api.demo.ema.co",
+  bearerToken: process.env.EMA_DEMO_BEARER_TOKEN!,
+});
+
+// List AI Employees
+const personas = await client.getPersonasForTenant();
+
+// Get full persona with workflow
+const persona = await client.getPersonaById("uuid");
+
+// List available templates
+const templates = await client.getPersonaTemplates();
+
+// List available agents/actions
+const actions = await client.listActions();
+```
+
+---
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test
+npm test -- --run workflow
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+```
+
+---
+
+## Development
+
+### Project Structure
+
+```
+src/
+├── mcp/
+│   ├── server.ts      # MCP server entry
+│   ├── prompts.ts     # Prompt definitions
+│   └── resources.ts   # Resource registry
+├── sdk/
+│   ├── client.ts      # EmaClient API wrapper
+│   ├── config.ts      # Config loading
+│   ├── models.ts      # TypeScript types
+│   └── knowledge.ts   # Agent catalog, patterns
+└── cli/
+    └── index.ts       # CLI entry
+```
+
+### Adding Tools/Prompts
+
+See `docs/naming-conventions.md` for naming rules.
+
+```typescript
+// In src/mcp/prompts.ts
+my_thing_action: {
+  definition: {
+    name: "my_thing_action",  // {noun}_{action} pattern
+    description: "...",
+    arguments: [...],
+  },
+  render: (args) => [...],
+},
+```
+
+### Auto-Fix Capabilities
+
+The `workflow(mode="optimize")` can automatically fix:
+
+| Issue | Fix |
+|-------|-----|
+| `wrong_input_source` (email_to) | Adds `entity_extraction`, wires email |
+| `wrong_input_source` (query) | Rewires to correct trigger output |
+| `missing_workflow_output` | Adds results mapping |
+
+---
+
+## Environment Variables Reference
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `EMA_BEARER_TOKEN` | Yes* | Default token (if no env-specific tokens) |
+| `EMA_<ENV>_BEARER_TOKEN` | Yes* | Token for specific environment |
+| `EMA_<ENV>_BASE_URL` | No | Custom URL (auto-detected) |
+| `EMA_ENV_NAME` | No | Default environment name |
+| `EMA_AGENT_SYNC_CONFIG` | No | Path to config file |
+| `EMA_CONFIG_JSON` | No | Config as JSON string |
+| `EMA_ENABLE_LEGACY_TOOLS` | No | Enable deprecated tools |
+
+*At least one token required.
+
+---
+
+## Troubleshooting
+
+### "Missing token for environment X"
+
+Set the corresponding environment variable:
+```bash
+export EMA_X_BEARER_TOKEN="your-token"
+```
+
+### "Token expired" / 401 errors
+
+Tokens expire after ~1 hour. Get a fresh token from the Ema dashboard.
+
+### MCP server not connecting
+
+1. Check your MCP config path is correct
+2. Verify the token env vars are set
+3. Try running manually: `npx ema-mcp-toolkit`
+
+### Tests failing
+
+```bash
+npm run build && npm test
+```
+
+---
+
+## License
+
+Proprietary - Ema Inc.

package/config.example.yaml

@@ -0,0 +1,32 @@
+# Ema Toolkit Configuration Example
+# Copy to ema.config.yaml and customize
+
+environments:
+  - name: demo
+    baseUrl: https://api.demo.ema.co
+    bearerTokenEnv: EMA_DEMO_BEARER_TOKEN
+    isMaster: true
+  
+  - name: dev
+    baseUrl: https://api.dev.ema.co
+    bearerTokenEnv: EMA_DEV_BEARER_TOKEN
+  
+  # Add more environments as needed:
+  # - name: staging
+  #   baseUrl: https://api.staging.ema.co
+  #   bearerTokenEnv: EMA_STAGING_BEARER_TOKEN
+  # 
+  # - name: prod
+  #   baseUrl: https://api.ema.co
+  #   bearerTokenEnv: EMA_PROD_BEARER_TOKEN
+
+# Optional: Service mode settings (for central scheduler)
+# service:
+#   stateDbPath: ./ema-state.sqlite3
+#   scheduler:
+#     intervalSeconds: 300
+#     # cron: "0 */4 * * *"
+
+# Global settings
+dryRun: false
+verbose: true

package/dist/cli/index.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+/**
+ * Ema Agent Sync CLI
+ *
+ * Commands:
+ *   sync run              - Run a full sync
+ *   sync status [name]    - Check sync status for a persona
+ *   sync persona <name>   - Sync a specific persona by name
+ *   personas list         - List all personas from master
+ *   agents list           - List all agents (actions)
+ *   config validate       - Validate config file
+ */
+import { loadConfig } from "../sdk/config.js";
+import { EmaClient } from "../sdk/client.js";
+import { SyncSDK } from "../sdk/sync.js";
+function printUsage() {
+    console.log(`
+Ema Agent Sync CLI
+
+Usage: ema <command> [subcommand] [options]
+
+Commands:
+  sync run                     Run a full sync from master to targets
+  sync status [persona-name]   Check sync status (optionally for a specific persona)
+  sync persona <name>          Sync a specific persona by name
+  
+  personas list                List all AI Employees from master environment
+  personas get <id>            Get details of a specific AI Employee
+  
+  agents list                  List all Agents (actions) from master environment
+  
+  config validate [path]       Validate a config file (default: ./config.yaml)
+  
+  help                         Show this help message
+
+Options:
+  --config, -c <path>          Path to config file (default: ./config.yaml)
+  --dry-run                    Don't make actual changes
+  --json                       Output as JSON
+
+Environment Variables:
+  EMA_AGENT_SYNC_CONFIG        Path to config file
+  EMA_*_BEARER_TOKEN           Bearer tokens for each environment (as configured)
+
+Examples:
+  ema sync run
+  ema sync persona "My AI Employee"
+  ema personas list --json
+  ema agents list
+  ema config validate ./config.yaml
+`);
+}
+function getEnvOrThrow(name) {
+    const v = process.env[name];
+    if (!v)
+        throw new Error(`Missing environment variable: ${name}`);
+    return v;
+}
+async function runSyncCommand(subcommand, args, options) {
+    const cfg = loadConfig(options.configPath);
+    if (options.dryRun)
+        cfg.dryRun = true;
+    const sdk = new SyncSDK(cfg);
+    try {
+        switch (subcommand) {
+            case "run": {
+                console.log("Starting sync...");
+                const result = await sdk.runSync();
+                if (options.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else {
+                    console.log(`\nSync complete:`);
+                    console.log(`  Run ID:  ${result.runId}`);
+                    console.log(`  Scanned: ${result.scanned}`);
+                    console.log(`  Changed: ${result.changed}`);
+                    console.log(`  Synced:  ${result.synced}`);
+                    console.log(`  Skipped: ${result.skipped}`);
+                }
+                break;
+            }
+            case "status": {
+                const personaName = args[0];
+                if (personaName) {
+                    const persona = await sdk.getMasterPersonaByName(personaName);
+                    if (!persona) {
+                        console.error(`Persona not found: ${personaName}`);
+                        process.exit(1);
+                    }
+                    const status = await sdk.getPersonaSyncStatus(persona.id);
+                    if (options.json) {
+                        console.log(JSON.stringify(status, null, 2));
+                    }
+                    else {
+                        console.log(`Persona: ${status?.personaName} (${status?.personaId})`);
+                        console.log(`Fingerprint: ${status?.fingerprint.substring(0, 16)}...`);
+                        console.log(`In Sync: ${status?.isSynced ? "Yes" : "No"}`);
+                        console.log(`\nTarget Mappings:`);
+                        for (const m of status?.targetMappings ?? []) {
+                            console.log(`  ${m.targetEnv}: ${m.targetPersonaId} (${m.inSync ? "synced" : "out of sync"})`);
+                        }
+                    }
+                }
+                else {
+                    // Show overall sync status
+                    const master = sdk.getMasterEnvironment();
+                    const personas = await sdk.listMasterPersonas();
+                    console.log(`Master: ${master.name} (${master.baseUrl})`);
+                    console.log(`Total personas: ${personas.length}`);
+                    console.log(`\nTarget environments:`);
+                    for (const env of sdk.getEnvironments()) {
+                        if (!env.isMaster) {
+                            console.log(`  - ${env.name} (${env.baseUrl})`);
+                        }
+                    }
+                }
+                break;
+            }
+            case "persona": {
+                const personaName = args[0];
+                if (!personaName) {
+                    console.error("Error: Persona name required");
+                    console.error("Usage: ema sync persona <name>");
+                    process.exit(1);
+                }
+                console.log(`Syncing persona: ${personaName}`);
+                const result = await sdk.syncPersonaByName(personaName);
+                if (options.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else {
+                    if (result.success) {
+                        console.log(`✓ Synced to: ${result.synced.join(", ") || "already in sync"}`);
+                    }
+                    else {
+                        console.error(`✗ Failed: ${result.errors.join(", ")}`);
+                        process.exit(1);
+                    }
+                }
+                break;
+            }
+            default:
+                console.error(`Unknown sync subcommand: ${subcommand}`);
+                process.exit(1);
+        }
+    }
+    finally {
+        sdk.close();
+    }
+}
+async function runPersonasCommand(subcommand, args, options) {
+    const cfg = loadConfig(options.configPath);
+    const sdk = new SyncSDK(cfg);
+    try {
+        switch (subcommand) {
+            case "list": {
+                const personas = await sdk.listMasterPersonas();
+                if (options.json) {
+                    console.log(JSON.stringify(personas.map(p => ({
+                        id: p.id,
+                        name: p.name,
+                        description: p.description,
+                        status: p.status,
+                        template_id: p.template_id,
+                        workflow_id: p.workflow_id,
+                    })), null, 2));
+                }
+                else {
+                    console.log(`AI Employees (${personas.length}):\n`);
+                    for (const p of personas) {
+                        console.log(`  ${p.name || "(unnamed)"}`);
+                        console.log(`    ID: ${p.id}`);
+                        if (p.description)
+                            console.log(`    Description: ${p.description.substring(0, 60)}...`);
+                        console.log("");
+                    }
+                }
+                break;
+            }
+            case "get": {
+                const id = args[0];
+                if (!id) {
+                    console.error("Error: Persona ID required");
+                    process.exit(1);
+                }
+                const persona = await sdk.getMasterPersona(id);
+                if (!persona) {
+                    console.error(`Persona not found: ${id}`);
+                    process.exit(1);
+                }
+                if (options.json) {
+                    console.log(JSON.stringify(persona, null, 2));
+                }
+                else {
+                    console.log(`Name: ${persona.name}`);
+                    console.log(`ID: ${persona.id}`);
+                    console.log(`Description: ${persona.description}`);
+                    console.log(`Status: ${persona.status}`);
+                    console.log(`Template ID: ${persona.template_id}`);
+                    console.log(`Workflow ID: ${persona.workflow_id}`);
+                }
+                break;
+            }
+            default:
+                console.error(`Unknown personas subcommand: ${subcommand}`);
+                process.exit(1);
+        }
+    }
+    finally {
+        sdk.close();
+    }
+}
+async function runAgentsCommand(subcommand, args, options) {
+    const cfg = loadConfig(options.configPath);
+    const master = cfg.environments.find((e) => e.isMaster);
+    if (!master)
+        throw new Error("No master environment configured");
+    const env = {
+        name: master.name,
+        baseUrl: master.baseUrl,
+        bearerToken: getEnvOrThrow(master.bearerTokenEnv),
+    };
+    const client = new EmaClient(env);
+    switch (subcommand) {
+        case "list": {
+            const actions = await client.listAgents();
+            if (options.json) {
+                console.log(JSON.stringify(actions, null, 2));
+            }
+            else {
+                console.log(`Agents (${actions.length}):\n`);
+                for (const a of actions) {
+                    console.log(`  ${a.name || a.id}`);
+                    if (a.description)
+                        console.log(`    ${a.description.substring(0, 60)}...`);
+                    if (a.category)
+                        console.log(`    Category: ${a.category}`);
+                    console.log("");
+                }
+            }
+            break;
+        }
+        default:
+            console.error(`Unknown agents subcommand: ${subcommand}`);
+            process.exit(1);
+    }
+}
+async function runConfigCommand(subcommand, args, options) {
+    switch (subcommand) {
+        case "validate": {
+            const path = args[0] || "./config.yaml";
+            try {
+                const cfg = loadConfig(path);
+                if (options.json) {
+                    console.log(JSON.stringify({ valid: true, config: cfg }, null, 2));
+                }
+                else {
+                    console.log(`✓ Config is valid: ${path}`);
+                    console.log(`  Master: ${cfg.environments.find((e) => e.isMaster)?.name}`);
+                    console.log(`  Environments: ${cfg.environments.map((e) => e.name).join(", ")}`);
+                    console.log(`  Routing rules: ${cfg.routing?.length ?? 0}`);
+                    console.log(`  Dry run: ${cfg.dryRun}`);
+                }
+            }
+            catch (e) {
+                if (options.json) {
+                    console.log(JSON.stringify({ valid: false, error: String(e) }, null, 2));
+                }
+                else {
+                    console.error(`✗ Invalid config: ${e instanceof Error ? e.message : e}`);
+                }
+                process.exit(1);
+            }
+            break;
+        }
+        default:
+            console.error(`Unknown config subcommand: ${subcommand}`);
+            process.exit(1);
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    // Parse options
+    let configPath = process.env.EMA_AGENT_SYNC_CONFIG || "./config.yaml";
+    let dryRun = false;
+    let json = false;
+    const filteredArgs = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--config" || arg === "-c") {
+            configPath = args[++i];
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else {
+            filteredArgs.push(arg);
+        }
+    }
+    const [command, subcommand, ...restArgs] = filteredArgs;
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        printUsage();
+        return;
+    }
+    try {
+        switch (command) {
+            case "sync":
+                await runSyncCommand((subcommand || "run"), restArgs, { configPath, dryRun, json });
+                break;
+            case "personas":
+                await runPersonasCommand((subcommand || "list"), restArgs, { configPath, json });
+                break;
+            case "agents":
+                await runAgentsCommand((subcommand || "list"), restArgs, { configPath, json });
+                break;
+            case "config":
+                await runConfigCommand((subcommand || "validate"), restArgs, { json });
+                break;
+            default:
+                console.error(`Unknown command: ${command}`);
+                printUsage();
+                process.exit(1);
+        }
+    }
+    catch (e) {
+        console.error(`Error: ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+    }
+}
+main();