@motorical/mcp 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motorical/mcp",
-  "version": "1.3.0",
+  "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

@@ -293,6 +293,59 @@ export class MotoricalClient {
     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.

package/src/server.js

@@ -556,6 +556,63 @@ export function createMotoricalMcpServer(options = {}) {
     }
   }, 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',