@agenticmail/enterprise 0.3.2 → 0.4.0

package/src/mcp/adapters/stripe.adapter.ts

@@ -0,0 +1,380 @@
+/**
+ * MCP Skill Adapter — Stripe
+ *
+ * Maps Stripe REST API endpoints to MCP tool handlers.
+ * API reference: https://stripe.com/docs/api
+ *
+ * Important: Stripe uses application/x-www-form-urlencoded for POST bodies.
+ * We use ctx.apiExecutor.request({ formEncoded: true }) for all write operations.
+ *
+ * Tools:
+ *   - stripe_list_customers      List customers with optional email filter
+ *   - stripe_create_customer     Create a new customer
+ *   - stripe_create_invoice      Create a draft invoice for a customer
+ *   - stripe_list_subscriptions  List subscriptions with optional filters
+ *   - stripe_create_payment_link Create a payment link for one or more line items
+ */
+
+import type {
+  SkillAdapter,
+  ToolHandler,
+  ToolResult,
+} from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+/** Format a Stripe amount (in cents) as a currency string. */
+function formatAmount(amountCents: number | undefined, currency: string | undefined): string {
+  if (amountCents === undefined || amountCents === null) return 'N/A';
+  const cur = (currency ?? 'usd').toUpperCase();
+  const amount = (amountCents / 100).toFixed(2);
+  return `${amount} ${cur}`;
+}
+
+/** Format a Unix timestamp into a readable date. */
+function fromUnix(ts: number | undefined): string {
+  if (!ts) return 'unknown';
+  return new Date(ts * 1000).toLocaleString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+/**
+ * Flatten line_items array into Stripe's form-encoded nested param format.
+ * e.g. [{ price: "price_xxx", quantity: 1 }] becomes:
+ *   { "line_items[0][price]": "price_xxx", "line_items[0][quantity]": "1" }
+ */
+function flattenLineItems(items: Array<{ price: string; quantity: number }>): Record<string, string> {
+  const result: Record<string, string> = {};
+  items.forEach((item, i) => {
+    result[`line_items[${i}][price]`] = item.price;
+    result[`line_items[${i}][quantity]`] = String(item.quantity);
+  });
+  return result;
+}
+
+// ─── Tool Handlers ──────────────────────────────────────
+
+const stripeListCustomers: ToolHandler = {
+  description:
+    'List Stripe customers, optionally filtered by email. Returns customer names, IDs, and balances.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      limit: {
+        type: 'number',
+        description: 'Max customers to return (default 10, max 100)',
+      },
+      email: {
+        type: 'string',
+        description: 'Filter by exact email address',
+      },
+      starting_after: {
+        type: 'string',
+        description: 'Cursor for pagination — customer ID to start after',
+      },
+    },
+    additionalProperties: false,
+  },
+
+  async execute(params, ctx): Promise<ToolResult> {
+    const query: Record<string, string> = {
+      limit: String(params.limit ?? 10),
+    };
+    if (params.email) query.email = params.email;
+    if (params.starting_after) query.starting_after = params.starting_after;
+
+    const data = await ctx.apiExecutor.get('/v1/customers', query);
+
+    const customers: any[] = data.data ?? [];
+    if (customers.length === 0) {
+      return {
+        content: 'No customers found.',
+        metadata: { customerCount: 0, hasMore: false },
+      };
+    }
+
+    const lines = customers.map((c: any) => {
+      const label = c.name || c.email || '(no name)';
+      const balance = formatAmount(c.balance, c.currency);
+      return `\u2022 ${label} (ID: ${c.id}) \u2014 balance: ${balance}`;
+    });
+
+    return {
+      content: `${customers.length} customer(s):\n\n${lines.join('\n')}`,
+      metadata: {
+        customerCount: customers.length,
+        hasMore: data.has_more ?? false,
+      },
+    };
+  },
+};
+
+const stripeCreateCustomer: ToolHandler = {
+  description:
+    'Create a new Stripe customer with an email and optional name, description, and metadata.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      email: {
+        type: 'string',
+        description: 'Customer email address',
+      },
+      name: {
+        type: 'string',
+        description: 'Customer full name',
+      },
+      description: {
+        type: 'string',
+        description: 'Internal description for this customer',
+      },
+      metadata: {
+        type: 'object',
+        description: 'Key-value metadata pairs to attach to the customer',
+        additionalProperties: { type: 'string' },
+      },
+    },
+    required: ['email'],
+    additionalProperties: false,
+  },
+
+  async execute(params, ctx): Promise<ToolResult> {
+    const body: Record<string, any> = { email: params.email };
+    if (params.name) body.name = params.name;
+    if (params.description) body.description = params.description;
+    if (params.metadata) body.metadata = params.metadata;
+
+    const customer = await ctx.apiExecutor.request({
+      method: 'POST',
+      path: '/v1/customers',
+      body,
+      formEncoded: true,
+    });
+
+    const displayName = customer.name || customer.email;
+    return {
+      content: `Customer created: ${displayName} (${customer.id}) \u2014 ${customer.email}`,
+      metadata: {
+        customerId: customer.id,
+        email: customer.email,
+        name: customer.name,
+      },
+    };
+  },
+};
+
+const stripeCreateInvoice: ToolHandler = {
+  description:
+    'Create a draft invoice for an existing Stripe customer. The invoice can be finalized and sent later.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      customer: {
+        type: 'string',
+        description: 'Stripe customer ID (e.g. cus_xxxxx)',
+      },
+      description: {
+        type: 'string',
+        description: 'Invoice description / memo',
+      },
+      auto_advance: {
+        type: 'boolean',
+        description:
+          'Whether the invoice should auto-finalize and attempt payment (default true)',
+      },
+      collection_method: {
+        type: 'string',
+        enum: ['charge_automatically', 'send_invoice'],
+        description: 'How to collect payment (default: charge_automatically)',
+      },
+    },
+    required: ['customer'],
+    additionalProperties: false,
+  },
+
+  async execute(params, ctx): Promise<ToolResult> {
+    const body: Record<string, any> = {
+      customer: params.customer,
+      auto_advance: params.auto_advance ?? true,
+      collection_method: params.collection_method ?? 'charge_automatically',
+    };
+    if (params.description) body.description = params.description;
+
+    // send_invoice requires days_until_due
+    if (body.collection_method === 'send_invoice' && !body.days_until_due) {
+      body.days_until_due = 30;
+    }
+
+    const invoice = await ctx.apiExecutor.request({
+      method: 'POST',
+      path: '/v1/invoices',
+      body,
+      formEncoded: true,
+    });
+
+    return {
+      content: `Invoice ${invoice.id} created for customer ${invoice.customer} \u2014 status: ${invoice.status}`,
+      metadata: {
+        invoiceId: invoice.id,
+        customerId: invoice.customer,
+        status: invoice.status,
+        amountDue: invoice.amount_due,
+        currency: invoice.currency,
+      },
+    };
+  },
+};
+
+const stripeListSubscriptions: ToolHandler = {
+  description:
+    'List Stripe subscriptions, optionally filtered by customer or status.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      customer: {
+        type: 'string',
+        description: 'Filter by customer ID',
+      },
+      status: {
+        type: 'string',
+        enum: ['active', 'past_due', 'canceled', 'all'],
+        description: 'Filter by subscription status (default: active)',
+      },
+      limit: {
+        type: 'number',
+        description: 'Max subscriptions to return (default 10, max 100)',
+      },
+    },
+    additionalProperties: false,
+  },
+
+  async execute(params, ctx): Promise<ToolResult> {
+    const query: Record<string, string> = {
+      limit: String(params.limit ?? 10),
+      status: params.status ?? 'active',
+    };
+    if (params.customer) query.customer = params.customer;
+
+    const data = await ctx.apiExecutor.get('/v1/subscriptions', query);
+
+    const subscriptions: any[] = data.data ?? [];
+    if (subscriptions.length === 0) {
+      return {
+        content: 'No subscriptions found.',
+        metadata: { subscriptionCount: 0, hasMore: false },
+      };
+    }
+
+    const lines = subscriptions.map((sub: any) => {
+      const status = sub.status ?? 'unknown';
+
+      // Extract pricing from the first item in the subscription
+      let pricing = 'N/A';
+      const items: any[] = sub.items?.data ?? [];
+      if (items.length > 0) {
+        const plan = items[0].plan ?? items[0].price;
+        if (plan) {
+          const amount = formatAmount(plan.amount ?? plan.unit_amount, plan.currency);
+          const interval = plan.interval ?? 'period';
+          pricing = `${amount}/${interval}`;
+        }
+      }
+
+      return `\u2022 ${sub.id} \u2014 ${status} \u2014 ${pricing} \u2014 customer: ${sub.customer}`;
+    });
+
+    return {
+      content: `${subscriptions.length} subscription(s):\n\n${lines.join('\n')}`,
+      metadata: {
+        subscriptionCount: subscriptions.length,
+        hasMore: data.has_more ?? false,
+      },
+    };
+  },
+};
+
+const stripeCreatePaymentLink: ToolHandler = {
+  description:
+    'Create a Stripe payment link for one or more priced line items. Returns a shareable URL.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      line_items: {
+        type: 'array',
+        description: 'Array of line items, each with a Stripe price ID and quantity',
+        items: {
+          type: 'object',
+          properties: {
+            price: {
+              type: 'string',
+              description: 'Stripe price ID (e.g. price_xxxxx)',
+            },
+            quantity: {
+              type: 'number',
+              description: 'Quantity (must be >= 1)',
+            },
+          },
+          required: ['price', 'quantity'],
+        },
+        minItems: 1,
+      },
+    },
+    required: ['line_items'],
+    additionalProperties: false,
+  },
+
+  async execute(params, ctx): Promise<ToolResult> {
+    const { line_items } = params;
+
+    if (!Array.isArray(line_items) || line_items.length === 0) {
+      return {
+        content: 'Error: line_items must be a non-empty array of { price, quantity } objects.',
+        isError: true,
+      };
+    }
+
+    // Build the form body with Stripe's nested array syntax
+    const formBody = flattenLineItems(line_items);
+
+    const paymentLink = await ctx.apiExecutor.request({
+      method: 'POST',
+      path: '/v1/payment_links',
+      body: formBody,
+      formEncoded: true,
+    });
+
+    return {
+      content: `Payment link created: ${paymentLink.url}`,
+      metadata: {
+        paymentLinkId: paymentLink.id,
+        url: paymentLink.url,
+        active: paymentLink.active,
+        lineItemCount: line_items.length,
+      },
+    };
+  },
+};
+
+// ─── Adapter ────────────────────────────────────────────
+
+export const stripeAdapter: SkillAdapter = {
+  skillId: 'stripe',
+  name: 'Stripe',
+  baseUrl: 'https://api.stripe.com',
+  auth: {
+    type: 'api_key',
+    headerPrefix: 'Bearer',
+  },
+  tools: {
+    stripe_list_customers: stripeListCustomers,
+    stripe_create_customer: stripeCreateCustomer,
+    stripe_create_invoice: stripeCreateInvoice,
+    stripe_list_subscriptions: stripeListSubscriptions,
+    stripe_create_payment_link: stripeCreatePaymentLink,
+  },
+  rateLimits: { requestsPerSecond: 25, burstLimit: 50 },
+};

package/src/mcp/adapters/supabase.adapter.ts

@@ -0,0 +1,334 @@
+/**
+ * MCP Skill Adapter — Supabase
+ *
+ * Maps Supabase PostgREST and RPC endpoints to MCP tool handlers.
+ * Provides access to querying, inserting, updating, and deleting rows,
+ * as well as invoking custom database functions via RPC.
+ *
+ * Supabase API docs: https://supabase.com/docs/guides/api
+ */
+
+import type {
+  SkillAdapter,
+  ToolHandler,
+  ToolResult,
+  ToolExecutionContext,
+  ResolvedCredentials,
+} from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+function supabaseError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const msg = data.message || data.hint || data.details || err.message;
+      const code = data.code || '';
+      const detail = code ? `${msg} (code: ${code})` : msg;
+      return { content: `Supabase API error: ${detail}`, isError: true };
+    }
+    return { content: `Supabase API error: ${err.message}`, isError: true };
+  }
+  return { content: `Supabase API error: ${String(err)}`, isError: true };
+}
+
+// ─── Tool: supabase_query ───────────────────────────────
+
+const query: ToolHandler = {
+  description:
+    'Query rows from a Supabase table using PostgREST syntax. Supports select, filtering, ordering, and pagination.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      table: {
+        type: 'string',
+        description: 'Table name to query',
+      },
+      select: {
+        type: 'string',
+        description: 'Columns to select (e.g. "id,name,email" or "*"). Default: "*"',
+      },
+      filter: {
+        type: 'string',
+        description: 'PostgREST filter string (e.g. "status=eq.active&age=gt.18")',
+      },
+      order: {
+        type: 'string',
+        description: 'Order by clause (e.g. "created_at.desc")',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of rows to return (default 50)',
+      },
+      offset: {
+        type: 'number',
+        description: 'Number of rows to skip (default 0)',
+      },
+    },
+    required: ['table'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        select: params.select || '*',
+      };
+      if (params.order) query.order = params.order;
+      if (params.limit) query.limit = String(params.limit);
+      if (params.offset) query.offset = String(params.offset);
+
+      // Parse filter string into query params
+      if (params.filter) {
+        const filterParts = params.filter.split('&');
+        for (const part of filterParts) {
+          const [key, ...rest] = part.split('=');
+          if (key && rest.length > 0) {
+            query[key] = rest.join('=');
+          }
+        }
+      }
+
+      const result = await ctx.apiExecutor.get(`/${params.table}`, query);
+
+      const rows: any[] = Array.isArray(result) ? result : [];
+      if (rows.length === 0) {
+        return { content: `No rows found in table "${params.table}".` };
+      }
+
+      return {
+        content: `Found ${rows.length} row(s) in "${params.table}":\n${JSON.stringify(rows, null, 2)}`,
+        metadata: { count: rows.length, table: params.table },
+      };
+    } catch (err) {
+      return supabaseError(err);
+    }
+  },
+};
+
+// ─── Tool: supabase_insert ──────────────────────────────
+
+const insert: ToolHandler = {
+  description:
+    'Insert one or more rows into a Supabase table. Returns the inserted rows.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      table: {
+        type: 'string',
+        description: 'Table name to insert into',
+      },
+      rows: {
+        type: 'array',
+        items: { type: 'object' },
+        description: 'Array of row objects to insert (e.g. [{"name": "Alice", "email": "a@b.com"}])',
+      },
+      upsert: {
+        type: 'boolean',
+        description: 'If true, perform an upsert (insert or update on conflict). Default: false',
+      },
+    },
+    required: ['table', 'rows'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const headers: Record<string, string> = {
+        'Prefer': 'return=representation',
+      };
+      if (params.upsert) {
+        headers['Prefer'] = 'return=representation,resolution=merge-duplicates';
+      }
+
+      const result = await ctx.apiExecutor.request({
+        method: 'POST',
+        path: `/${params.table}`,
+        headers,
+        body: params.rows,
+      });
+
+      const inserted: any[] = Array.isArray(result) ? result : [result];
+      return {
+        content: `Inserted ${inserted.length} row(s) into "${params.table}":\n${JSON.stringify(inserted, null, 2)}`,
+        metadata: { count: inserted.length, table: params.table },
+      };
+    } catch (err) {
+      return supabaseError(err);
+    }
+  },
+};
+
+// ─── Tool: supabase_update ──────────────────────────────
+
+const update: ToolHandler = {
+  description:
+    'Update rows in a Supabase table matching a filter. Returns the updated rows.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      table: {
+        type: 'string',
+        description: 'Table name to update',
+      },
+      filter: {
+        type: 'string',
+        description: 'PostgREST filter to identify rows (e.g. "id=eq.123"). Required to prevent accidental full-table updates.',
+      },
+      data: {
+        type: 'object',
+        description: 'Object with column values to update (e.g. {"status": "active"})',
+      },
+    },
+    required: ['table', 'filter', 'data'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const queryParams: Record<string, string> = {};
+      const filterParts = params.filter.split('&');
+      for (const part of filterParts) {
+        const [key, ...rest] = part.split('=');
+        if (key && rest.length > 0) {
+          queryParams[key] = rest.join('=');
+        }
+      }
+
+      const result = await ctx.apiExecutor.request({
+        method: 'PATCH',
+        path: `/${params.table}`,
+        query: queryParams,
+        headers: { 'Prefer': 'return=representation' },
+        body: params.data,
+      });
+
+      const updated: any[] = Array.isArray(result) ? result : [result];
+      return {
+        content: `Updated ${updated.length} row(s) in "${params.table}":\n${JSON.stringify(updated, null, 2)}`,
+        metadata: { count: updated.length, table: params.table },
+      };
+    } catch (err) {
+      return supabaseError(err);
+    }
+  },
+};
+
+// ─── Tool: supabase_delete ──────────────────────────────
+
+const deleteRows: ToolHandler = {
+  description:
+    'Delete rows from a Supabase table matching a filter. Returns the deleted rows.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      table: {
+        type: 'string',
+        description: 'Table name to delete from',
+      },
+      filter: {
+        type: 'string',
+        description: 'PostgREST filter to identify rows to delete (e.g. "id=eq.123"). Required to prevent accidental full-table deletion.',
+      },
+    },
+    required: ['table', 'filter'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const queryParams: Record<string, string> = {};
+      const filterParts = params.filter.split('&');
+      for (const part of filterParts) {
+        const [key, ...rest] = part.split('=');
+        if (key && rest.length > 0) {
+          queryParams[key] = rest.join('=');
+        }
+      }
+
+      const result = await ctx.apiExecutor.request({
+        method: 'DELETE',
+        path: `/${params.table}`,
+        query: queryParams,
+        headers: { 'Prefer': 'return=representation' },
+      });
+
+      const deleted: any[] = Array.isArray(result) ? result : [result];
+      return {
+        content: `Deleted ${deleted.length} row(s) from "${params.table}":\n${JSON.stringify(deleted, null, 2)}`,
+        metadata: { count: deleted.length, table: params.table },
+      };
+    } catch (err) {
+      return supabaseError(err);
+    }
+  },
+};
+
+// ─── Tool: supabase_rpc ─────────────────────────────────
+
+const rpc: ToolHandler = {
+  description:
+    'Call a Supabase database function (RPC). Pass the function name and an optional parameter object.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      functionName: {
+        type: 'string',
+        description: 'Name of the database function to invoke',
+      },
+      params: {
+        type: 'object',
+        description: 'Parameters to pass to the function (optional)',
+      },
+    },
+    required: ['functionName'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const result = await ctx.apiExecutor.post(
+        `/rpc/${params.functionName}`,
+        params.params || {},
+      );
+
+      const formatted = typeof result === 'object'
+        ? JSON.stringify(result, null, 2)
+        : String(result);
+
+      return {
+        content: `RPC "${params.functionName}" result:\n${formatted}`,
+        metadata: { functionName: params.functionName },
+      };
+    } catch (err) {
+      return supabaseError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const supabaseAdapter: SkillAdapter = {
+  skillId: 'supabase',
+  name: 'Supabase',
+  baseUrl: 'https://REFERENCE.supabase.co/rest/v1',
+  auth: {
+    type: 'api_key',
+    headerName: 'apikey',
+  },
+  tools: {
+    supabase_query: query,
+    supabase_insert: insert,
+    supabase_update: update,
+    supabase_delete: deleteRows,
+    supabase_rpc: rpc,
+  },
+  rateLimits: { requestsPerSecond: 10, burstLimit: 30 },
+  configSchema: {
+    projectRef: {
+      type: 'string' as const,
+      label: 'Project Reference',
+      description: 'Supabase project reference ID (found in project URL)',
+      required: true,
+      placeholder: 'abcdefghijklmnop',
+    },
+  },
+  async initialize(credentials: ResolvedCredentials) {
+    // Dynamic base URL will be set by the framework using projectRef from config
+  },
+};