@motorical/mcp 1.2.1 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motorical/mcp",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "MCP server for Motorical transactional email API — dry-run/send, mint public tokens, list Motor Blocks, inspect delivery events",
   "type": "module",
   "bin": {

package/src/client.js

@@ -208,6 +208,181 @@ export class MotoricalClient {
     return `${path}${sep}motorBlockId=${encodeURIComponent(id)}`;
   }
 
+  /**
+   * Query string from a params object, skipping anything the caller didn't
+   * supply. Returns '' when nothing survives, so it composes with _scoped()
+   * and _accountPath() — both of which detect an existing '?' and switch to
+   * '&' when appending motorBlockId.
+   */
+  _qs(params = {}) {
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+      if (v === undefined || v === null || v === '') continue;
+      q.set(k, String(v));
+    }
+    const s = q.toString();
+    return s ? `?${s}` : '';
+  }
+
+  async getOverview({ motorBlockId, from, to } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/overview`;
+    return this.request('GET', this._scoped(path + this._qs({ from, to }), motorBlockId), { bearer });
+  }
+
+  async getDailySummary({ motorBlockId, days } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/daily-summary`;
+    return this.request('GET', this._scoped(path + this._qs({ days }), motorBlockId), { bearer });
+  }
+
+  async getMetrics({ motorBlockId, from, to, interval } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/metrics`;
+    return this.request('GET', this._scoped(path + this._qs({ from, to, interval }), motorBlockId), { bearer });
+  }
+
+  async getDeliverability({ motorBlockId, from, to, limit } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/deliverability`;
+    return this.request('GET', this._scoped(path + this._qs({ from, to, limit }), motorBlockId), { bearer });
+  }
+
+  async getReputation({ motorBlockId } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/reputation`;
+    return this.request('GET', this._scoped(path, motorBlockId), { bearer });
+  }
+
+  async getAnomalies({ motorBlockId } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/anomalies`;
+    return this.request('GET', this._scoped(path, motorBlockId), { bearer });
+  }
+
+  async getProviders({ motorBlockId, from, to, limit } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/providers`;
+    return this.request('GET', this._scoped(path + this._qs({ from, to, limit }), motorBlockId), { bearer });
+  }
+
+  async getErrorCodes({ motorBlockId, from, to, limit } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/error-codes`;
+    return this.request('GET', this._scoped(path + this._qs({ from, to, limit }), motorBlockId), { bearer });
+  }
+
+  async getRateLimits({ motorBlockId } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/rate-limits`;
+    return this.request('GET', this._scoped(path, motorBlockId), { bearer });
+  }
+
+  async getConfig({ motorBlockId } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/config`;
+    return this.request('GET', this._scoped(path, motorBlockId), { bearer });
+  }
+
+  // refresh is sent only when true: the route reads it as "re-run the live DNS
+  // check now", so refresh=false is not the same request as omitting it.
+  async getDomainHealth({ motorBlockId, refresh } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/domain-health`;
+    const qs = this._qs({ refresh: refresh === true ? 'true' : undefined });
+    return this.request('GET', this._scoped(path + qs, motorBlockId), { bearer });
+  }
+
+  async webhookList({ motorBlockId } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/webhooks`;
+    return this.request('GET', this._scoped(path, motorBlockId), { bearer });
+  }
+
+  async webhookCreate({ motorBlockId, url, events } = {}) {
+    if (!url) throw new Error('url is required');
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/webhooks`;
+    const body = events !== undefined ? { url, events } : { url };
+    return this.request('POST', this._scoped(path, motorBlockId), { bearer, body });
+  }
+
+  async webhookUpdate({ motorBlockId, webhookId, url, events, enabled } = {}) {
+    if (!webhookId) throw new Error('webhookId is required');
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/webhooks/${encodeURIComponent(webhookId)}`;
+    const body = {};
+    if (url !== undefined) body.url = url;
+    if (events !== undefined) body.events = events;
+    if (enabled !== undefined) body.enabled = enabled;
+    return this.request('PUT', this._scoped(path, motorBlockId), { bearer, body });
+  }
+
+  async webhookDelete({ motorBlockId, webhookId } = {}) {
+    if (!webhookId) throw new Error('webhookId is required');
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/webhooks/${encodeURIComponent(webhookId)}`;
+    return this.request('DELETE', this._scoped(path, motorBlockId), { bearer });
+  }
+
+  async webhookTest({ motorBlockId, webhookId } = {}) {
+    if (!webhookId) throw new Error('webhookId is required');
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/webhooks/${encodeURIComponent(webhookId)}/test`;
+    return this.request('POST', this._scoped(path, motorBlockId), { bearer });
+  }
+
+  async webhookGetDeliveries({ motorBlockId, webhookId, limit } = {}) {
+    if (!webhookId) throw new Error('webhookId is required');
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/webhooks/${encodeURIComponent(webhookId)}/deliveries`;
+    return this.request('GET', this._scoped(path + this._qs({ limit }), motorBlockId), { bearer });
+  }
+
+  async webhookGetStats({ motorBlockId, webhookId, hours } = {}) {
+    if (!webhookId) throw new Error('webhookId is required');
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/webhooks/${encodeURIComponent(webhookId)}/stats`;
+    return this.request('GET', this._scoped(path + this._qs({ hours }), motorBlockId), { bearer });
+  }
+
+  // Account-wide: the route is mounted { accountScoped: true } and reads only
+  // the token's user, so _accountPath omits the block rather than throwing.
+  // Using _scoped() here would demand a Motor Block for an account-wide route.
+  async getAccountRateLimits({ motorBlockId } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    return this.request(
+      'GET',
+      this._accountPath('/api/public/v1/account/rate-limits', motorBlockId),
+      { bearer }
+    );
+  }
+
+  async getLogs({
+    motorBlockId, from, to, currentOutcome, query, limit, cursor, includePII,
+  } = {}) {
+    const bearer = await this.getBearer({ motorBlockId });
+    const path = `/api/public/v1/motor-blocks/${encodeURIComponent(motorBlockId)}/logs`;
+    const qs = this._qs({
+      from, to, currentOutcome, query, limit, cursor,
+      includePII: includePII === true ? 'true' : undefined,
+    });
+    return this.request('GET', this._scoped(path + qs, motorBlockId), { bearer });
+  }
+
+  // GET /messages is a LOOKUP, not a listing: it 400s without an exact
+  // smtpMessageId and resolves at most one match. This is a second lookup key
+  // alongside getMessage()'s internal UUID, never a way to browse.
+  async getMessageBySmtpId({ smtpMessageId, motorBlockId, includePII } = {}) {
+    if (!smtpMessageId) throw new Error('smtpMessageId is required');
+    const bearer = await this.getBearer({ motorBlockId });
+    const qs = this._qs({
+      smtpMessageId,
+      includePII: includePII === true ? 'true' : undefined,
+    });
+    return this.request('GET', this._scoped(`/api/public/v1/messages${qs}`, motorBlockId), { bearer });
+  }
+
   async getBearer({ motorBlockId, forceRefresh = false } = {}) {
     // An OAuth grant supersedes minted public tokens entirely — no ak_live_ key
     // and no dashboard JWT needed.

package/src/server.js

@@ -1,8 +1,11 @@
+import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { MotoricalClient, loadConfig } from './client.js';
 
-const PACKAGE_VERSION = '1.1.3';
+const PACKAGE_VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url))
+).version;
 
 function jsonResult(data, { isError = false } = {}) {
   return {
@@ -404,6 +407,212 @@ export function createMotoricalMcpServer(options = {}) {
     }
   );
 
+  // ---- Analytics & health tools ----
+  // Each wraps one existing Public API route one-to-one. See
+  // motorical-docs/plans/2026-09-02-mcp-analytics-health-tools-implementation.md.
+  // .optional() on purpose, matching every pre-existing block-scoped tool: a
+  // grant covering exactly one Motor Block resolves it automatically, so the
+  // caller only has to name one when the grant covers several. Making it
+  // required forces single-block users to supply an id they should never need,
+  // and turns the multi-block case into a Zod type error instead of
+  // resolveBlock's actionable message.
+  const blockSelector = z.string().uuid().optional()
+    .describe('Required when the authorization covers more than one Motor Block');
+  const isoDate = (bound) => z.string().optional().describe(`ISO date or datetime, ${bound}`);
+
+  registerTool(
+    'motorical_get_overview',
+    {
+      description:
+        'Sending overview for one Motor Block over a date range — volume, delivery and bounce '
+        + 'rates, and current usage against plan limits (GET /api/public/v1/motor-blocks/{id}/overview).',
+      inputSchema: {
+        motorBlockId: blockSelector,
+        from: isoDate('inclusive'),
+        to: isoDate('inclusive')
+      }
+    },
+    async (args) => {
+      try {
+        return jsonResult(await client.getOverview(args));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+
+  registerTool('motorical_get_daily_summary', {
+    description: 'Per-day send counts and outcomes for one Motor Block (GET /api/public/v1/motor-blocks/{id}/daily-summary).',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      days: z.number().int().positive().optional().describe('How many days back, counting today')
+    }
+  }, async (args) => { try { return jsonResult(await client.getDailySummary(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_metrics', {
+    description: 'Time-series send metrics for one Motor Block, bucketed by hour or day (GET /api/public/v1/motor-blocks/{id}/metrics).',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      from: isoDate('inclusive'),
+      to: isoDate('inclusive'),
+      interval: z.enum(['hour', 'day']).optional().describe('Bucket size; defaults to the API default')
+    }
+  }, async (args) => { try { return jsonResult(await client.getMetrics(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_deliverability', {
+    description: 'Deliverability broken down by recipient domain (GET /api/public/v1/motor-blocks/{id}/deliverability).',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      from: isoDate('inclusive'),
+      to: isoDate('inclusive'),
+      limit: z.number().int().positive().optional().describe('Max recipient domains returned')
+    }
+  }, async (args) => { try { return jsonResult(await client.getDeliverability(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_reputation', {
+    description: 'Current sending reputation for one Motor Block (GET /api/public/v1/motor-blocks/{id}/reputation).',
+    inputSchema: { motorBlockId: blockSelector }
+  }, async (args) => { try { return jsonResult(await client.getReputation(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_anomalies', {
+    description: 'Detected sending anomalies for one Motor Block — volume spikes, bounce surges, unusual patterns (GET /api/public/v1/motor-blocks/{id}/anomalies).',
+    inputSchema: { motorBlockId: blockSelector }
+  }, async (args) => { try { return jsonResult(await client.getAnomalies(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_providers', {
+    description: 'Send outcomes grouped by receiving mailbox provider (GET /api/public/v1/motor-blocks/{id}/providers).',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      from: isoDate('inclusive'),
+      to: isoDate('inclusive'),
+      limit: z.number().int().positive().optional().describe('Max providers returned')
+    }
+  }, async (args) => { try { return jsonResult(await client.getProviders(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_error_codes', {
+    description: 'SMTP error codes seen for one Motor Block, with counts and diagnostics (GET /api/public/v1/motor-blocks/{id}/error-codes).',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      from: isoDate('inclusive'),
+      to: isoDate('inclusive'),
+      limit: z.number().int().positive().optional().describe('Max distinct error codes returned')
+    }
+  }, async (args) => { try { return jsonResult(await client.getErrorCodes(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_rate_limits', {
+    description: "Current hourly and daily send usage against this Motor Block's limits (GET /api/public/v1/motor-blocks/{id}/rate-limits).",
+    inputSchema: { motorBlockId: blockSelector }
+  }, async (args) => { try { return jsonResult(await client.getRateLimits(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_account_rate_limits', {
+    description:
+      'Account-wide send ceiling and current usage across every Motor Block '
+      + '(GET /api/public/v1/account/rate-limits). Account-scoped: no Motor Block needed.',
+    inputSchema: {
+      motorBlockId: z.string().uuid().optional()
+        .describe('Optional. This operation acts on the whole account, so a Motor Block is never needed; pass one only to record which block the call was made on behalf of.')
+    }
+  }, async (args) => { try { return jsonResult(await client.getAccountRateLimits(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_logs', {
+    description:
+      'Search send logs for one Motor Block (GET /api/public/v1/motor-blocks/{id}/logs). '
+      + 'Paginate with cursor. Recipient addresses are masked unless the token carries logs.pii, '
+      + 'which OAuth tokens never do.',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      from: isoDate('inclusive'),
+      to: isoDate('inclusive'),
+      currentOutcome: z.string().optional().describe('Filter to one delivery outcome, e.g. delivered, bounced, deferred'),
+      query: z.string().optional().describe('Free-text match against recipient, subject or message id'),
+      limit: z.number().int().positive().optional().describe('Page size'),
+      cursor: z.string().optional().describe('Opaque cursor from a previous page'),
+      includePII: z.boolean().optional().describe('Unmask recipient addresses. Requires the logs.pii scope, which is never granted to OAuth tokens — the API returns 403.')
+    }
+  }, async (args) => { try { return jsonResult(await client.getLogs(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_message_by_smtp_id', {
+    description:
+      'Look up one message by its SMTP Message-ID header (GET /api/public/v1/messages?smtpMessageId=). '
+      + 'This is a lookup, not a listing: an exact id is required and at most one message is returned. '
+      + 'Use motorical_get_message when you have the internal send UUID instead.',
+    inputSchema: {
+      smtpMessageId: z.string().describe('The exact SMTP Message-ID, angle brackets included'),
+      motorBlockId: blockSelector,
+      includePII: z.boolean().optional().describe('Unmask the recipient address. Requires the logs.pii scope, which is never granted to OAuth tokens — the API returns 403.')
+    }
+  }, async (args) => { try { return jsonResult(await client.getMessageBySmtpId(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_config', {
+    description: "Configuration of one Motor Block — its sending domain, limits and delivery settings (GET /api/public/v1/motor-blocks/{id}/config).",
+    inputSchema: { motorBlockId: blockSelector }
+  }, async (args) => { try { return jsonResult(await client.getConfig(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_get_domain_health', {
+    description: "DNS and email-authentication health for the Motor Block's sending domain — SPF, DKIM, DMARC, MX (GET /api/public/v1/motor-blocks/{id}/domain-health).",
+    inputSchema: {
+      motorBlockId: blockSelector,
+      refresh: z.boolean().optional().describe('Re-run the live DNS checks now instead of returning the last cached result')
+    }
+  }, async (args) => { try { return jsonResult(await client.getDomainHealth(args)); } catch (err) { return errorResult(err); } });
+
+  const webhookIdArg = z.string().describe('The webhook endpoint id, from motorical_webhook_list or the create response');
+
+  registerTool('motorical_webhook_list', {
+    description: 'List webhook endpoints registered on one Motor Block (GET /api/public/v1/motor-blocks/{id}/webhooks).',
+    inputSchema: { motorBlockId: blockSelector }
+  }, async (args) => { try { return jsonResult(await client.webhookList(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_webhook_create', {
+    description:
+      'Register a new webhook endpoint on one Motor Block (POST /api/public/v1/motor-blocks/{id}/webhooks). '
+      + 'The response includes the full signing secret exactly once — store it immediately, it is only masked on every later read.',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      url: z.string().url().describe('HTTPS endpoint that will receive webhook deliveries'),
+      events: z.array(z.string()).optional().describe('Event types to subscribe to; defaults to all event types when omitted')
+    }
+  }, async (args) => { try { return jsonResult(await client.webhookCreate(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_webhook_update', {
+    description: 'Update a webhook endpoint\'s url, events, or enabled state (PUT /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}). Only the fields you pass are changed.',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      webhookId: webhookIdArg,
+      url: z.string().url().optional(),
+      events: z.array(z.string()).optional(),
+      enabled: z.boolean().optional()
+    }
+  }, async (args) => { try { return jsonResult(await client.webhookUpdate(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_webhook_delete', {
+    description: 'Delete a webhook endpoint (DELETE /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}).',
+    inputSchema: { motorBlockId: blockSelector, webhookId: webhookIdArg }
+  }, async (args) => { try { return jsonResult(await client.webhookDelete(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_webhook_test', {
+    description: 'Send a synthetic test delivery to a webhook endpoint (POST /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/test).',
+    inputSchema: { motorBlockId: blockSelector, webhookId: webhookIdArg }
+  }, async (args) => { try { return jsonResult(await client.webhookTest(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_webhook_get_deliveries', {
+    description: 'Recent delivery attempts for one webhook endpoint (GET /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/deliveries).',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      webhookId: webhookIdArg,
+      limit: z.number().int().positive().max(200).optional().describe('Default 50, max 200')
+    }
+  }, async (args) => { try { return jsonResult(await client.webhookGetDeliveries(args)); } catch (err) { return errorResult(err); } });
+
+  registerTool('motorical_webhook_get_stats', {
+    description: 'Delivery success/failure counts and average latency for one webhook endpoint over a time window (GET /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/stats).',
+    inputSchema: {
+      motorBlockId: blockSelector,
+      webhookId: webhookIdArg,
+      hours: z.number().int().positive().max(168).optional().describe('Default 24, max 168 (7 days)')
+    }
+  }, async (args) => { try { return jsonResult(await client.webhookGetStats(args)); } catch (err) { return errorResult(err); } });
+
   server.registerResource(
     'motorical-llms',
     'motorical://docs/llms.txt',