@motorical/mcp 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motorical/mcp",
-  "version": "1.2.1",
+  "version": "1.3.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,128 @@ 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 });
+  }
+
+  // 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,155 @@ 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); } });
+
   server.registerResource(
     'motorical-llms',
     'motorical://docs/llms.txt',