@motorical/mcp 1.0.4 → 1.1.0

package/README.md

@@ -13,7 +13,7 @@ A **Motorical SMTP Motor Block** is an isolated sending stream (similar to a per
 | `motorical_get_send_status` | none | `GET /v1/status` |
 | `motorical_mint_public_token` | `ak_live_…` | Mint Public API bearer |
 | `motorical_list_motor_blocks` | bearer (auto-mint) | List Motor Blocks |
-| `motorical_send_email` | `mk_live_…` | Transactional `POST /v1/send` (**default `dryRun: true`**) |
+| `motorical_send_email` | `mk_live_…` | Transactional `POST /v1/send` (**default `dryRun: true`**; optional **`fromName`**) |
 | `motorical_get_message` | bearer | Message by UUID |
 | `motorical_get_message_events` | bearer | Delivery lifecycle events |
 | `motorical_sandbox_status` | `MOTORICAL_JWT` | Developer sandbox status |
@@ -23,7 +23,7 @@ A **Motorical SMTP Motor Block** is an isolated sending stream (similar to a per
 **Resources:** `motorical://docs/llms.txt`, `motorical://docs/openapi.json`  
 **Prompt:** `motorical_integrate_send`
 
-Safety: real sends require `dryRun: false` **and** `confirmRealSend: true`. Sandbox outbound is allowlist-locked until convert.
+Safety: real sends require `dryRun: false` **and** `confirmRealSend: true`. Sandbox outbound is allowlist-locked until convert. Optional `fromName` sets the inbox display name (same as HTTP `/v1/send` / CLI `--from-name`); do not put `From` in custom headers.
 
 ## Environment
 
@@ -46,30 +46,25 @@ Add to MCP config (e.g. Cursor Settings → MCP):
 {
   "mcpServers": {
     "motorical": {
-      "command": "node",
-      "args": ["/root/motoric_smtp/packages/motorical-mcp/src/index.js"],
+      "command": "npx",
+      "args": ["-y", "@motorical/mcp"],
       "env": {
         "MOTORICAL_MK_API_KEY": "mk_live_…",
         "MOTORICAL_AK_API_KEY": "ak_live_…",
         "MOTORICAL_MOTOR_BLOCK_ID": "your-block-uuid",
-        "MOTORICAL_DEFAULT_FROM": "noreply@yourdomain.com"
+        "MOTORICAL_DEFAULT_FROM": "noreply@yourdomain.com",
+        "MOTORICAL_JWT": "optional-dashboard-jwt-for-sandbox-tools"
       }
     }
   }
 }
 ```
 
-On a developer Mac after cloning:
+From a clone of this repo:
 
 ```bash
 cd packages/motorical-mcp && npm ci
-# point args at the absolute path to src/index.js
-```
-
-Or via npx once published:
-
-```json
-"args": ["-y", "@motorical/mcp"]
+# point command/args at node + absolute path to src/index.js
 ```
 
 ## Develop / test

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@motorical/mcp",
-  "version": "1.0.4",
-  "description": "MCP server for Motorical transactional email API — dry-run/send, mint public tokens, list Motor Blocks, inspect delivery events",
+  "version": "1.1.0",
+  "description": "MCP server for Motorical transactional email API \u2014 dry-run/send, mint public tokens, list Motor Blocks, inspect delivery events",
   "type": "module",
   "bin": {
     "motorical-mcp": "./src/index.js"
@@ -42,6 +42,11 @@
   },
   "homepage": "https://docs.motorical.com/ai-mcp",
   "bugs": {
-    "url": "https://docs.motorical.com/ai-mcp"
+    "url": "https://github.com/motorical-smtp/motorical-packages/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/motorical-smtp/motorical-packages.git",
+    "directory": "packages/motorical-mcp"
   }
 }

package/src/client.js

@@ -24,22 +24,18 @@ export class MotoricalClient {
     this.config = config;
     /** @type {string|null} */
     this._cachedBearer = config.bearerToken || null;
+    /** @type {string|null} */
+    this._cachedMkKey = null;
   }
 
   requireMk() {
+    if (this._cachedMkKey) return this._cachedMkKey;
     if (!this.config.mkApiKey) {
       throw new Error('MOTORICAL_MK_API_KEY is required (mk_live_... Motor Block API key for POST /v1/send)');
     }
     return this.config.mkApiKey;
   }
 
-  requireAk() {
-    if (!this.config.akApiKey) {
-      throw new Error('MOTORICAL_AK_API_KEY is required (ak_live_... Account API key to mint public tokens)');
-    }
-    return this.config.akApiKey;
-  }
-
   async request(method, path, { headers = {}, body, apiKey, bearer } = {}) {
     const url = `${this.config.apiBaseUrl}${path.startsWith('/') ? path : `/${path}`}`;
     const h = { Accept: 'application/json', ...headers };
@@ -73,17 +69,28 @@ export class MotoricalClient {
 
   async mintPublicToken({ motorBlockId, scopes, ttlSeconds = 900 } = {}) {
     const blockId = motorBlockId || this.config.motorBlockId;
-    if (!blockId) {
-      throw new Error('motorBlockId is required (argument or MOTORICAL_MOTOR_BLOCK_ID)');
+    const hasAk = !!this.config.akApiKey;
+    const hasJwt = !!this.config.dashboardJwt;
+
+    const missing = [];
+    if (!blockId) missing.push('motorBlockId (argument or MOTORICAL_MOTOR_BLOCK_ID)');
+    if (!hasAk && !hasJwt) {
+      missing.push('MOTORICAL_AK_API_KEY (ak_live_... Account API key) or MOTORICAL_JWT (dashboard session)');
     }
-    const data = await this.request('POST', '/api/public/token/account-key', {
-      apiKey: this.requireAk(),
-      body: {
-        motorBlockId: blockId,
-        scopes: scopes || ['logs.read', 'analytics.read', 'webhooks.manage', 'config.read'],
-        ttlSeconds
-      }
-    });
+    if (missing.length) {
+      throw new Error(`Missing required to mint a public token: ${missing.join('; ')}`);
+    }
+
+    const body = {
+      motorBlockId: blockId,
+      scopes: scopes || ['logs.read', 'analytics.read', 'webhooks.manage', 'config.read'],
+      ttlSeconds
+    };
+
+    const data = hasAk
+      ? await this.request('POST', '/api/public/token/account-key', { apiKey: this.config.akApiKey, body })
+      : await this.request('POST', '/api/public/token', { bearer: this.config.dashboardJwt, body });
+
     const token = data?.data?.token || data?.token || data?.access_token;
     if (token) this._cachedBearer = token;
     return data;
@@ -178,14 +185,29 @@ export class MotoricalClient {
   }
 
   async sandboxStatus() {
-    return this.request('GET', '/api/developer/sandbox', { bearer: this.requireDashboardJwt() });
+    const result = await this.request('GET', '/api/developer/sandbox', {
+      bearer: this.requireDashboardJwt()
+    });
+    // A returning agent that calls status instead of re-provisioning still
+    // needs motorBlockId for mintPublicToken()/getBearer() (message lookup).
+    const blockId = result?.data?.motorBlock?.id;
+    if (blockId && !this.config.motorBlockId) this.config.motorBlockId = blockId;
+    return result;
   }
 
   async sandboxProvision({ handle, channel = 'agent' } = {}) {
-    return this.request('POST', '/api/developer/sandbox/provision', {
+    const result = await this.request('POST', '/api/developer/sandbox/provision', {
       bearer: this.requireDashboardJwt(),
       body: { handle, channel }
     });
+    const mkKey = result?.data?.credentials?.mkApiKey;
+    if (mkKey && !this.config.mkApiKey) this._cachedMkKey = mkKey;
+    // Without this a cold JWT-only agent can send but never track: getBearer()
+    // throws 'motorBlockId is required'. Same precedence rule as mkApiKey —
+    // an explicit MOTORICAL_MOTOR_BLOCK_ID always wins.
+    const blockId = result?.data?.motorBlock?.id;
+    if (blockId && !this.config.motorBlockId) this.config.motorBlockId = blockId;
+    return result;
   }
 
   async sandboxConvert({ domainId }) {
@@ -220,6 +242,23 @@ export class MotoricalClient {
     });
   }
 
+  async sandboxAllowlistRequest({ email } = {}) {
+    if (!email) throw new Error('email is required');
+    return this.request('POST', '/api/developer/sandbox/allowlist/request', {
+      bearer: this.requireDashboardJwt(),
+      body: { email }
+    });
+  }
+
+  async sandboxAllowlistConfirm({ email, code } = {}) {
+    if (!email) throw new Error('email is required');
+    if (!code) throw new Error('code is required');
+    return this.request('POST', '/api/developer/sandbox/allowlist/confirm', {
+      bearer: this.requireDashboardJwt(),
+      body: { email, code }
+    });
+  }
+
   async webHandoff({ path } = {}) {
     return this.request('POST', '/api/auth/web-handoff', {
       bearer: this.requireDashboardJwt(),

package/src/server.js

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { MotoricalClient, loadConfig } from './client.js';
 
-const PACKAGE_VERSION = '1.0.4';
+const PACKAGE_VERSION = '1.0.5';
 
 function jsonResult(data, { isError = false } = {}) {
   return {
@@ -54,7 +54,8 @@ export function createMotoricalMcpServer(options = {}) {
     'motorical_mint_public_token',
     {
       description:
-        'Mint a short-lived Public Analytics API bearer token using MOTORICAL_AK_API_KEY (ak_live_...). ' +
+        'Mint a short-lived Public Analytics API bearer token using MOTORICAL_AK_API_KEY (ak_live_...) ' +
+        'or, when none is configured, MOTORICAL_JWT. ' +
         'Use for /api/public/v1 logs, analytics, webhooks, config. Not for POST /v1/send.',
       inputSchema: {
         motorBlockId: z.string().uuid().optional().describe('Defaults to MOTORICAL_MOTOR_BLOCK_ID'),
@@ -95,7 +96,9 @@ export function createMotoricalMcpServer(options = {}) {
       description:
         'Transactional email: send or validate via POST /v1/send using MOTORICAL_MK_API_KEY (mk_live_...). ' +
         'Defaults to dryRun:true. Real sends require dryRun:false AND confirmRealSend:true. ' +
-        'Do not use OAuth access tokens or Bearer tokens here.',
+        'Do not use OAuth access tokens or Bearer tokens here. ' +
+        'For developer-sandbox accounts, a non-allowlisted recipient is redirected to the account ' +
+        'email rather than rejected — check the response\'s sandboxRedirect field.',
       inputSchema: {
         from: z.string().email().optional().describe('Defaults to MOTORICAL_DEFAULT_FROM'),
         fromName: z
@@ -179,6 +182,47 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
+  server.registerTool(
+    'motorical_sandbox_allowlist_request',
+    {
+      description:
+        'Request to add a new recipient to the developer sandbox outbound allowlist. ' +
+        'Sends a 6-digit confirmation code to that address (not the account owner) — ' +
+        'call motorical_sandbox_allowlist_confirm with the code the recipient receives. Requires MOTORICAL_JWT.',
+      inputSchema: {
+        email: z.string().email()
+      }
+    },
+    async (args) => {
+      try {
+        return jsonResult(await client.sandboxAllowlistRequest(args));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+
+  server.registerTool(
+    'motorical_sandbox_allowlist_confirm',
+    {
+      description:
+        'Confirm a sandbox allowlist recipient using the 6-digit code sent by ' +
+        'motorical_sandbox_allowlist_request. On success the address is added to the ' +
+        'allowlist and can receive real (non-dryRun) sandbox sends. Requires MOTORICAL_JWT.',
+      inputSchema: {
+        email: z.string().email(),
+        code: z.string().length(6)
+      }
+    },
+    async (args) => {
+      try {
+        return jsonResult(await client.sandboxAllowlistConfirm(args));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+
   server.registerTool(
     'motorical_sandbox_provision',
     {