@ema.co/mcp-toolkit 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Ema Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,321 @@
+# @ema.co/mcp-toolkit
+
+MCP (Model Context Protocol) server for managing Ema AI Employees. Works with Cursor, Claude Desktop, and other MCP clients.
+
+## Installation
+
+### Option 1: npx (Recommended)
+
+```bash
+# Run directly without installing
+npx @ema.co/mcp-toolkit
+```
+
+### Option 2: Global Install
+
+```bash
+npm install -g @ema.co/mcp-toolkit
+ema-mcp  # Start MCP server
+```
+
+### Option 3: Clone & Build (Development)
+
+```bash
+git clone https://github.com/Ema-Unlimited/@ema.co/mcp-toolkit.git
+cd @ema.co/mcp-toolkit
+npm install
+npm run build
+```
+
+---
+
+## Quick Start
+
+### 1. Set Your Credentials
+
+**Option A: API Key (Recommended)**
+
+API keys are stable and auto-refresh (24h token validity):
+
+```bash
+export EMA_API_KEY="your-api-key"
+# Or for specific environment:
+export EMA_PROD_API_KEY="your-prod-api-key"
+```
+
+**Option B: Bearer Token**
+
+```bash
+export EMA_BEARER_TOKEN="your-token"
+# Or for specific environment:
+export EMA_PROD_BEARER_TOKEN="your-prod-token"
+```
+
+### 2. Add to Your AI Assistant
+
+**Cursor** (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ema": {
+      "command": "npx",
+      "args": ["@ema.co/mcp-toolkit"],
+      "env": {
+        "EMA_API_KEY": "${EMA_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Use `${ENV_VAR}` syntax to reference environment variables from your shell. Set them in your `~/.zshrc` or `~/.bashrc`.
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ema": {
+      "command": "npx",
+      "args": ["@ema.co/mcp-toolkit"],
+      "env": {
+        "EMA_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### 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"
+
+---
+
+## Authentication
+
+### Option 1: API Key (Recommended)
+
+API keys provide stable authentication with automatic JWT refresh:
+
+1. Get your API key from the Ema team
+2. Set the environment variable:
+   ```bash
+   export EMA_API_KEY="your-api-key"
+   ```
+
+The toolkit automatically:
+- Exchanges the API key for a JWT token
+- Caches the token (valid 24 hours)
+- Refreshes before expiry
+
+### Option 2: Bearer Token
+
+For quick testing or when API keys aren't available:
+
+1. Log in to [Ema Platform](https://app.ema.co)
+2. Open browser DevTools → Network tab
+3. Find any API request's `Authorization: Bearer ...` header
+4. Copy the token (without "Bearer " prefix)
+
+```bash
+export EMA_BEARER_TOKEN="your-token"
+```
+
+> **Note**: Bearer tokens expire after ~1 hour. Use API keys for production.
+
+### Multiple Environments
+
+Use environment-specific credentials:
+
+```bash
+# API keys (preferred)
+export EMA_PROD_API_KEY="..."
+export EMA_DEMO_API_KEY="..."
+export EMA_DEV_API_KEY="..."
+
+# Or bearer tokens
+export EMA_PROD_BEARER_TOKEN="..."
+export EMA_DEMO_BEARER_TOKEN="..."
+```
+
+---
+
+## Configuration
+
+### Zero-Config Mode (Default)
+
+No config file needed! The toolkit auto-detects environments from environment variables:
+
+```bash
+# Pattern: EMA_<ENV>_API_KEY or EMA_<ENV>_BEARER_TOKEN
+export EMA_PROD_API_KEY="..."      # → creates "prod" environment
+export EMA_DEMO_API_KEY="..."      # → creates "demo" environment
+export EMA_DEV_BEARER_TOKEN="..."  # → creates "dev" environment
+```
+
+**Default Environment**:
+- External users: `prod`
+- Ema employees: `demo` (auto-detected if demo token exists)
+- Override: `export EMA_ENV_NAME="dev"`
+
+**Well-known URLs** (automatic):
+| Environment | URL |
+|-------------|-----|
+| `prod` | `https://api.ema.co` |
+| `demo` | `https://api.demo.ema.co` |
+| `dev` | `https://api.dev.ema.co` |
+| `staging` | `https://api.staging.ema.co` |
+
+### Config File (Advanced)
+
+For complex setups, create `ema.config.yaml`:
+
+```yaml
+environments:
+  - name: prod
+    baseUrl: https://api.ema.co
+    bearerTokenEnv: EMA_PROD_BEARER_TOKEN
+    isMaster: true
+
+  - name: dev
+    baseUrl: https://api.dev.ema.co
+    bearerTokenEnv: EMA_DEV_BEARER_TOKEN
+```
+
+---
+
+## MCP 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 |
+
+## Dynamic Resources
+
+| 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
+
+```typescript
+import { EmaClient } from "@ema.co/mcp-toolkit";
+
+const client = new EmaClient({
+  name: "prod",
+  baseUrl: "https://api.ema.co",
+  bearerToken: process.env.EMA_PROD_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();
+```
+
+---
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Test
+npm test
+
+# Type check
+npm run typecheck
+```
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `EMA_API_KEY` | Yes* | API key (auto-exchanges for JWT) |
+| `EMA_BEARER_TOKEN` | Yes* | Bearer token (direct auth) |
+| `EMA_<ENV>_API_KEY` | Yes* | API key for specific environment |
+| `EMA_<ENV>_BEARER_TOKEN` | Yes* | Token for specific environment |
+| `EMA_ENV_NAME` | No | Default environment name |
+| `EMA_EMPLOYEE` | No | Set to "true" to default to demo |
+| `EMA_AGENT_SYNC_CONFIG` | No | Path to config file |
+
+*At least one credential required.
+
+---
+
+## Troubleshooting
+
+### "Missing token for environment X"
+
+Set the corresponding environment variable:
+```bash
+export EMA_X_API_KEY="your-api-key"
+# or
+export EMA_X_BEARER_TOKEN="your-token"
+```
+
+### "API key not yet initialized"
+
+API keys are initialized asynchronously at startup. Either:
+- Wait a moment and retry
+- Use a bearer token instead
+
+### "Token expired" / 401 errors
+
+- **API keys**: Should auto-refresh. Check your API key is valid.
+- **Bearer tokens**: Expire after ~1 hour. Get a fresh token or switch to API keys.
+
+### MCP server not connecting
+
+1. Verify credentials are set: `echo $EMA_API_KEY`
+2. Try running manually: `npx @ema.co/mcp-toolkit`
+3. Check MCP config path is correct
+
+---
+
+## License
+
+MIT - see [LICENSE](LICENSE)

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();