@ema.co/mcp-toolkit 0.2.2 → 0.2.3

package/README.md

@@ -7,7 +7,6 @@ MCP (Model Context Protocol) server for managing Ema AI Employees. Works with Cu
 ### Option 1: npx (Recommended)
 
 ```bash
-# Run directly without installing
 npx @ema.co/mcp-toolkit
 ```
 
@@ -21,8 +20,8 @@ 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
+git clone https://github.com/Ema-Unlimited/ema-mcp-toolkit.git
+cd ema-mcp-toolkit
 npm install
 npm run build
 ```
@@ -31,27 +30,31 @@ npm run build
 
 ## Quick Start
 
-### 1. Set Your Credentials
+### 1. Get Your Bearer Token
 
-**Option A: API Key (Recommended)**
+1. Log in to your Ema environment (e.g., [app.ema.co](https://app.ema.co))
+2. Open browser DevTools (F12) → Network tab
+3. Find any API request's `Authorization: Bearer ...` header
+4. Copy the token (the part after "Bearer ")
 
-API keys are stable and auto-refresh (24h token validity):
+### 2. Set Up Environment Variables
 
-```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**
+Add to your shell profile (`~/.zshrc` or `~/.bashrc`):
 
 ```bash
-export EMA_BEARER_TOKEN="your-token"
-# Or for specific environment:
-export EMA_PROD_BEARER_TOKEN="your-prod-token"
+# Single environment
+export EMA_BEARER_TOKEN="eyJhbGciOiJSUzI1..."
+
+# Or multiple environments (recommended)
+export EMA_PROD_BEARER_TOKEN="eyJ..."    # from app.ema.co
+export EMA_DEMO_BEARER_TOKEN="eyJ..."    # from demo.ema.co
+export EMA_DEV_BEARER_TOKEN="eyJ..."     # from dev.ema.co
+export EMA_STAGING_BEARER_TOKEN="eyJ..." # from staging.ema.co
 ```
 
-### 2. Add to Your AI Assistant
+Then reload: `source ~/.zshrc`
+
+### 3. Configure Your AI Assistant
 
 **Cursor** (`~/.cursor/mcp.json`):
 
@@ -62,14 +65,38 @@ export EMA_PROD_BEARER_TOKEN="your-prod-token"
       "command": "npx",
       "args": ["@ema.co/mcp-toolkit"],
       "env": {
-        "EMA_API_KEY": "${EMA_API_KEY}"
+        "EMA_ENV_NAME": "demo",
+        "EMA_PROD_BEARER_TOKEN": "${env:EMA_PROD_BEARER_TOKEN}",
+        "EMA_DEMO_BEARER_TOKEN": "${env:EMA_DEMO_BEARER_TOKEN}",
+        "EMA_DEV_BEARER_TOKEN": "${env:EMA_DEV_BEARER_TOKEN}",
+        "EMA_STAGING_BEARER_TOKEN": "${env:EMA_STAGING_BEARER_TOKEN}"
       }
     }
   }
 }
 ```
 
-> **Note**: Use `${ENV_VAR}` syntax to reference environment variables from your shell. Set them in your `~/.zshrc` or `~/.bashrc`.
+> **Important**: 
+> - Use `${env:VAR_NAME}` syntax to reference shell environment variables
+> - After changing mcp.json, restart the MCP server: `Cmd+Shift+P` → "MCP: Restart Server"
+> - After changing ~/.zshrc, reload it AND restart Cursor for changes to take effect
+
+**Alternative: Direct tokens** (if env expansion doesn't work):
+
+```json
+{
+  "mcpServers": {
+    "ema": {
+      "command": "npx",
+      "args": ["@ema.co/mcp-toolkit"],
+      "env": {
+        "EMA_ENV_NAME": "demo",
+        "EMA_DEMO_BEARER_TOKEN": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
+      }
+    }
+  }
+}
+```
 
 **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
@@ -80,67 +107,51 @@ export EMA_PROD_BEARER_TOKEN="your-prod-token"
       "command": "npx",
       "args": ["@ema.co/mcp-toolkit"],
       "env": {
-        "EMA_API_KEY": "your-api-key-here"
+        "EMA_BEARER_TOKEN": "your-token-here"
       }
     }
   }
 }
 ```
 
-### 3. Start Using
+### 4. Verify It Works
 
 Ask your AI assistant:
-- "List my AI Employees"
-- "Analyze the workflow for Customer Support Bot"
-- "Create a new Voice AI for appointment scheduling"
+- "List ema environments" - should show your configured environments
+- "List personas in demo" - should show AI Employees
 
 ---
 
 ## Authentication
 
-### Option 1: API Key (Recommended)
-
-API keys provide stable authentication with automatic JWT refresh:
+### Bearer Tokens (Most Common)
 
-1. Get your API key from the Ema team
-2. Set the environment variable:
-   ```bash
-   export EMA_API_KEY="your-api-key"
-   ```
+Bearer tokens are JWTs obtained from the Ema web app:
 
-The toolkit automatically:
-- Exchanges the API key for a JWT token
-- Caches the token (valid 24 hours)
-- Refreshes before expiry
+1. Each token is tied to a specific environment (prod, demo, dev, staging)
+2. Tokens expire after ~24 hours - get fresh ones when they expire
+3. The token's issuer (`iss` field) must match the API endpoint:
+   - `ema.co` token → `https://api.ema.co`
+   - `demo.ema.co` token → `https://api.demo.ema.co`
+   - etc.
 
-### Option 2: Bearer Token
+### API Keys (If Available)
 
-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)
+If you have an API key (different from bearer token):
 
 ```bash
-export EMA_BEARER_TOKEN="your-token"
+export EMA_PROD_API_KEY="your-api-key"
 ```
 
-> **Note**: Bearer tokens expire after ~1 hour. Use API keys for production.
+The toolkit will automatically exchange it for a JWT and refresh before expiry.
 
-### Multiple Environments
+### Verifying Token Environment
 
-Use environment-specific credentials:
+Check which environment a token belongs to:
 
 ```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="..."
+echo $EMA_DEMO_BEARER_TOKEN | cut -d'.' -f2 | base64 -d 2>/dev/null | jq -r .iss
+# Should output: demo.ema.co
 ```
 
 ---
@@ -152,28 +163,26 @@ export EMA_DEMO_BEARER_TOKEN="..."
 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
+# Pattern: EMA_<ENV>_BEARER_TOKEN or EMA_<ENV>_API_KEY
+export EMA_PROD_BEARER_TOKEN="..."   # → creates "prod" environment
+export EMA_DEMO_BEARER_TOKEN="..."   # → 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"`
+- Set explicitly: `export EMA_ENV_NAME="demo"`
+- Or auto-detected from available credentials
 
 **Well-known URLs** (automatic):
+
 | Environment | URL |
 |-------------|-----|
 | `prod` | `https://api.ema.co` |
 | `<env>` | `https://api.<env>.ema.co` |
 
-> For internal environments, use `EMA_<ENV>_API_KEY` or `EMA_<ENV>_BEARER_TOKEN` environment variables.
-
 ### Config File (Advanced)
 
-For complex setups, create `ema.config.yaml`:
+For custom setups, create `ema.config.yaml`:
 
 ```yaml
 environments:
@@ -182,9 +191,9 @@ environments:
     bearerTokenEnv: EMA_PROD_BEARER_TOKEN
     isMaster: true
 
-  - name: myenv
-    baseUrl: https://api.<env>.ema.co
-    bearerTokenEnv: EMA_MYENV_BEARER_TOKEN
+  - name: custom
+    baseUrl: https://api.custom.ema.co
+    bearerTokenEnv: EMA_CUSTOM_BEARER_TOKEN
 ```
 
 ---
@@ -195,7 +204,7 @@ environments:
 |------|---------|
 | `env` | List available environments |
 | `persona` | AI Employee management (get/list/create/update/compare) |
-| `workflow` | Generate/analyze/deploy/optimize/explain/extend workflows |
+| `workflow` | Generate/analyze/deploy/optimize/explain workflows |
 | `action` | Agent lookup, docs, and recommendations |
 | `template` | Patterns, widgets, qualifying questions |
 | `knowledge` | Data sources + embedding (upload/list/delete/toggle) |
@@ -232,7 +241,7 @@ ema sync status
 ## SDK
 
 ```typescript
-import { EmaClient } from "@ema.co/mcp-toolkit";
+import { EmaClient } from "@ema.co/mcp-toolkit/sdk";
 
 const client = new EmaClient({
   name: "prod",
@@ -255,64 +264,57 @@ const actions = await client.listActions();
 
 ---
 
-## Development
+## Environment Variables
 
-```bash
-# Build
-npm run build
+| Variable | Description |
+|----------|-------------|
+| `EMA_BEARER_TOKEN` | Default bearer token |
+| `EMA_<ENV>_BEARER_TOKEN` | Token for specific environment (PROD, DEMO, DEV, STAGING) |
+| `EMA_API_KEY` | API key (auto-exchanges for JWT) |
+| `EMA_<ENV>_API_KEY` | API key for specific environment |
+| `EMA_ENV_NAME` | Default environment name |
+| `EMA_AGENT_SYNC_CONFIG` | Path to config file |
 
-# Test
-npm test
+---
 
-# Type check
-npm run typecheck
-```
+## Troubleshooting
 
----
+### "Missing token for environment X"
 
-## Environment Variables
+The token isn't set or isn't being passed to the MCP server:
 
-| 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 |
+1. Check the token is set in your shell: `echo $EMA_X_BEARER_TOKEN`
+2. Ensure it's in `~/.zshrc` and you've run `source ~/.zshrc`
+3. Restart the MCP server in Cursor after config changes
+4. If `${env:...}` isn't working, paste the token directly in mcp.json
 
-*At least one credential required.
+### "Invalid API key" error
 
----
+You're using a bearer token (JWT) with an `_API_KEY` variable name:
+- Rename `EMA_X_API_KEY` to `EMA_X_BEARER_TOKEN`
 
-## Troubleshooting
+### Only some environments detected
 
-### "Missing token for environment X"
+Check each token's issuer matches its environment:
 
-Set the corresponding environment variable:
 ```bash
-export EMA_X_API_KEY="your-api-key"
-# or
-export EMA_X_BEARER_TOKEN="your-token"
+# Should show: demo.ema.co
+echo $EMA_DEMO_BEARER_TOKEN | cut -d'.' -f2 | base64 -d 2>/dev/null | jq -r .iss
 ```
 
-### "API key not yet initialized"
+### Token expired / 401 errors
 
-API keys are initialized asynchronously at startup. Either:
-- Wait a moment and retry
-- Use a bearer token instead
+Bearer tokens expire after ~24 hours. Get fresh tokens from each environment's web app.
 
-### "Token expired" / 401 errors
+### MCP server not picking up new tokens
 
-- **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.
+1. Run `source ~/.zshrc` to reload env vars
+2. Restart MCP server: `Cmd+Shift+P` → "MCP: Restart Server" → "ema"
+3. Or restart Cursor entirely
 
-### MCP server not connecting
+### Cursor `${env:...}` not expanding
 
-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
+Some Cursor versions have issues with env var expansion. Workaround: paste tokens directly in mcp.json (less secure but works).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ema.co/mcp-toolkit",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Ema AI Employee toolkit - MCP server, CLI, and SDK for managing AI Employees across environments",
   "type": "module",
   "main": "dist/index.js",