@agenticmail/enterprise 0.3.2 → 0.4.0

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

@@ -0,0 +1,429 @@
+/**
+ * MCP Skill Adapter — BigCommerce
+ *
+ * Maps BigCommerce REST API v3 endpoints to MCP tool handlers.
+ * BigCommerce uses a dynamic base URL: https://api.bigcommerce.com/stores/{store_hash}/v3
+ *
+ * The store hash is read from ctx.skillConfig.storeHash.
+ *
+ * BigCommerce API docs: https://developer.bigcommerce.com/docs/rest-catalog
+ *
+ * Tools:
+ *   - bc_list_products      List products in the store
+ *   - bc_create_product     Create a new product
+ *   - bc_list_orders        List orders
+ *   - bc_list_customers     List customers
+ *   - bc_get_store_info     Get store information
+ */
+
+import type {
+  SkillAdapter,
+  ToolHandler,
+  ToolResult,
+  ToolExecutionContext,
+} from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+/** Resolve the BigCommerce store base URL from skill config */
+function bcUrl(ctx: ToolExecutionContext): string {
+  const storeHash = ctx.skillConfig.storeHash;
+  if (!storeHash) {
+    throw new Error('BigCommerce store hash is required in skillConfig (e.g. { storeHash: "abc123" })');
+  }
+  return `https://api.bigcommerce.com/stores/${storeHash}/v3`;
+}
+
+/** V2 URL for orders (BigCommerce orders are still on v2) */
+function bcV2Url(ctx: ToolExecutionContext): string {
+  const storeHash = ctx.skillConfig.storeHash;
+  if (!storeHash) {
+    throw new Error('BigCommerce store hash is required in skillConfig');
+  }
+  return `https://api.bigcommerce.com/stores/${storeHash}/v2`;
+}
+
+function bcError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const title = data.title || '';
+      const detail = data.detail || data.message || err.message;
+      const errors = data.errors ? ` -- ${JSON.stringify(data.errors)}` : '';
+      return { content: `BigCommerce API error [${title}]: ${detail}${errors}`, isError: true };
+    }
+    return { content: `BigCommerce API error: ${err.message}`, isError: true };
+  }
+  return { content: `BigCommerce API error: ${String(err)}`, isError: true };
+}
+
+/** Format a BigCommerce product for display */
+function formatProduct(product: any): string {
+  const name = product.name || '(untitled)';
+  const price = product.price !== undefined ? `$${product.price}` : 'N/A';
+  const sku = product.sku || 'no sku';
+  const availability = product.availability || 'unknown';
+  const inventory = product.inventory_level !== undefined ? product.inventory_level : 'N/A';
+  return `${name} (ID: ${product.id}) -- ${price} -- SKU: ${sku} -- ${availability} -- stock: ${inventory}`;
+}
+
+/** Format a BigCommerce order for display */
+function formatOrder(order: any): string {
+  const id = order.id;
+  const status = order.status || 'unknown';
+  const total = order.total_inc_tax ? `$${order.total_inc_tax}` : 'N/A';
+  const customer = order.billing_address
+    ? `${order.billing_address.first_name || ''} ${order.billing_address.last_name || ''}`.trim()
+    : 'unknown';
+  const created = order.date_created ? order.date_created.slice(0, 10) : '';
+  return `#${id} -- ${status} -- ${total} -- ${customer} -- ${created}`;
+}
+
+/** Format a BigCommerce customer for display */
+function formatCustomer(customer: any): string {
+  const name = `${customer.first_name || ''} ${customer.last_name || ''}`.trim() || '(no name)';
+  const email = customer.email || '(no email)';
+  const orders = customer.orders_count ?? 0;
+  return `${name} <${email}> (ID: ${customer.id}) -- ${orders} orders`;
+}
+
+// ─── Tool: bc_list_products ─────────────────────────────
+
+const listProducts: ToolHandler = {
+  description:
+    'List products in the BigCommerce store. Returns product names, prices, SKUs, and availability.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      limit: {
+        type: 'number',
+        description: 'Max products to return (default 25, max 250)',
+      },
+      page: {
+        type: 'number',
+        description: 'Page number (default 1)',
+      },
+      name: {
+        type: 'string',
+        description: 'Filter by product name (partial match)',
+      },
+      keyword: {
+        type: 'string',
+        description: 'Search keyword across product fields',
+      },
+      is_visible: {
+        type: 'boolean',
+        description: 'Filter by visibility (true = visible on storefront)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = bcUrl(ctx);
+      const query: Record<string, string> = {
+        limit: String(params.limit ?? 25),
+        page: String(params.page ?? 1),
+      };
+      if (params.name) query.name = params.name;
+      if (params.keyword) query.keyword = params.keyword;
+      if (params.is_visible !== undefined) query.is_visible = String(params.is_visible);
+
+      const result = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/catalog/products`,
+        query,
+      });
+
+      const products: any[] = result.data || [];
+      if (products.length === 0) {
+        return { content: 'No products found.', metadata: { productCount: 0 } };
+      }
+
+      const lines = products.map((p: any) => formatProduct(p));
+      const total = result.meta?.pagination?.total ?? products.length;
+      return {
+        content: `${products.length} of ${total} product(s):\n${lines.join('\n')}`,
+        metadata: { productCount: products.length, total },
+      };
+    } catch (err) {
+      return bcError(err);
+    }
+  },
+};
+
+// ─── Tool: bc_create_product ────────────────────────────
+
+const createProduct: ToolHandler = {
+  description:
+    'Create a new product in the BigCommerce store. Provide a name, price, type, and weight.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'Product name',
+      },
+      price: {
+        type: 'number',
+        description: 'Product price',
+      },
+      type: {
+        type: 'string',
+        enum: ['physical', 'digital'],
+        description: 'Product type (default: "physical")',
+      },
+      weight: {
+        type: 'number',
+        description: 'Product weight (required for physical products)',
+      },
+      sku: {
+        type: 'string',
+        description: 'Stock keeping unit',
+      },
+      description: {
+        type: 'string',
+        description: 'Product description (HTML supported)',
+      },
+      categories: {
+        type: 'array',
+        items: { type: 'number' },
+        description: 'Array of category IDs',
+      },
+    },
+    required: ['name', 'price', 'weight', 'type'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = bcUrl(ctx);
+      const body: Record<string, any> = {
+        name: params.name,
+        price: params.price,
+        type: params.type || 'physical',
+        weight: params.weight,
+      };
+      if (params.sku) body.sku = params.sku;
+      if (params.description) body.description = params.description;
+      if (params.categories) body.categories = params.categories;
+
+      const result = await ctx.apiExecutor.request({
+        method: 'POST',
+        url: `${baseUrl}/catalog/products`,
+        body,
+      });
+
+      const p = result.data;
+      return {
+        content: `Product created: "${p.name}" (ID: ${p.id}) -- $${p.price} -- type: ${p.type}`,
+        metadata: {
+          productId: p.id,
+          name: p.name,
+          price: p.price,
+        },
+      };
+    } catch (err) {
+      return bcError(err);
+    }
+  },
+};
+
+// ─── Tool: bc_list_orders ───────────────────────────────
+
+const listOrders: ToolHandler = {
+  description:
+    'List orders from the BigCommerce store. Optionally filter by status or date range.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      limit: {
+        type: 'number',
+        description: 'Max orders to return (default 25, max 250)',
+      },
+      page: {
+        type: 'number',
+        description: 'Page number (default 1)',
+      },
+      status_id: {
+        type: 'number',
+        description: 'Filter by order status ID',
+      },
+      min_date_created: {
+        type: 'string',
+        description: 'Filter orders created after this date (RFC 2822 or ISO 8601)',
+      },
+      max_date_created: {
+        type: 'string',
+        description: 'Filter orders created before this date (RFC 2822 or ISO 8601)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = bcV2Url(ctx);
+      const query: Record<string, string> = {
+        limit: String(params.limit ?? 25),
+        page: String(params.page ?? 1),
+      };
+      if (params.status_id !== undefined) query.status_id = String(params.status_id);
+      if (params.min_date_created) query.min_date_created = params.min_date_created;
+      if (params.max_date_created) query.max_date_created = params.max_date_created;
+
+      const orders = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/orders`,
+        query,
+      });
+
+      const items: any[] = Array.isArray(orders) ? orders : [];
+      if (items.length === 0) {
+        return { content: 'No orders found.', metadata: { orderCount: 0 } };
+      }
+
+      const lines = items.map((o: any) => formatOrder(o));
+      return {
+        content: `${items.length} order(s):\n${lines.join('\n')}`,
+        metadata: { orderCount: items.length },
+      };
+    } catch (err) {
+      return bcError(err);
+    }
+  },
+};
+
+// ─── Tool: bc_list_customers ────────────────────────────
+
+const listCustomers: ToolHandler = {
+  description:
+    'List customers in the BigCommerce store. Optionally filter by email or name.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      limit: {
+        type: 'number',
+        description: 'Max customers to return (default 25, max 250)',
+      },
+      page: {
+        type: 'number',
+        description: 'Page number (default 1)',
+      },
+      'email:in': {
+        type: 'string',
+        description: 'Filter by email address (comma-separated for multiple)',
+      },
+      'name:like': {
+        type: 'string',
+        description: 'Filter by name (partial match)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = bcUrl(ctx);
+      const query: Record<string, string> = {
+        limit: String(params.limit ?? 25),
+        page: String(params.page ?? 1),
+      };
+      if (params['email:in']) query['email:in'] = params['email:in'];
+      if (params['name:like']) query['name:like'] = params['name:like'];
+
+      const result = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/customers`,
+        query,
+      });
+
+      const customers: any[] = result.data || [];
+      if (customers.length === 0) {
+        return { content: 'No customers found.', metadata: { customerCount: 0 } };
+      }
+
+      const lines = customers.map((c: any) => formatCustomer(c));
+      const total = result.meta?.pagination?.total ?? customers.length;
+      return {
+        content: `${customers.length} of ${total} customer(s):\n${lines.join('\n')}`,
+        metadata: { customerCount: customers.length, total },
+      };
+    } catch (err) {
+      return bcError(err);
+    }
+  },
+};
+
+// ─── Tool: bc_get_store_info ────────────────────────────
+
+const getStoreInfo: ToolHandler = {
+  description:
+    'Get general information about the BigCommerce store, including name, domain, plan, and status.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+  },
+
+  async execute(_params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = bcV2Url(ctx);
+      const result = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/store`,
+      });
+
+      const content = [
+        `Store: ${result.name || 'unknown'}`,
+        `Domain: ${result.domain || 'N/A'}`,
+        `Secure URL: ${result.secure_url || 'N/A'}`,
+        `Plan: ${result.plan_name || 'N/A'}`,
+        `Status: ${result.status || 'unknown'}`,
+        `Currency: ${result.currency || 'N/A'}`,
+        `Country: ${result.country || 'N/A'}`,
+        `Weight Units: ${result.weight_units || 'N/A'}`,
+      ].join('\n');
+
+      return {
+        content,
+        metadata: {
+          storeId: result.id,
+          name: result.name,
+          domain: result.domain,
+          plan: result.plan_name,
+        },
+      };
+    } catch (err) {
+      return bcError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const bigcommerceAdapter: SkillAdapter = {
+  skillId: 'bigcommerce',
+  name: 'BigCommerce',
+  // Base URL is dynamic based on store hash; tools use ctx.apiExecutor.request() with full URLs
+  baseUrl: 'https://api.bigcommerce.com/stores/STORE_HASH/v3',
+  auth: {
+    type: 'api_key',
+    headerName: 'X-Auth-Token',
+  },
+  tools: {
+    bc_list_products: listProducts,
+    bc_create_product: createProduct,
+    bc_list_orders: listOrders,
+    bc_list_customers: listCustomers,
+    bc_get_store_info: getStoreInfo,
+  },
+  configSchema: {
+    storeHash: {
+      type: 'string' as const,
+      label: 'Store Hash',
+      description: 'Your BigCommerce store hash (found in your API account settings)',
+      required: true,
+    },
+  },
+  rateLimits: {
+    requestsPerSecond: 5,
+    burstLimit: 15,
+  },
+};

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

@@ -0,0 +1,260 @@
+/**
+ * MCP Skill Adapter — Bitbucket
+ *
+ * Maps Bitbucket Cloud REST API 2.0 endpoints to MCP tool handlers.
+ * Bitbucket uses a paginated response envelope with `values`, `size`,
+ * `page`, and `next` fields.
+ *
+ * Bitbucket REST API docs: https://developer.atlassian.com/cloud/bitbucket/rest/
+ */
+
+import type { SkillAdapter, ToolHandler, ToolResult, ToolExecutionContext } from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+function bitbucketError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const msg = data.error?.message || data.error?.detail || data.message || err.message;
+      return { content: `Bitbucket API error: ${msg}`, isError: true };
+    }
+    return { content: `Bitbucket API error: ${err.message}`, isError: true };
+  }
+  return { content: `Bitbucket API error: ${String(err)}`, isError: true };
+}
+
+// ─── Tool: bitbucket_list_repos ─────────────────────────
+
+const listRepos: ToolHandler = {
+  description:
+    'List repositories for a Bitbucket workspace. Returns repository names, slugs, and descriptions.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      workspace: {
+        type: 'string',
+        description: 'Workspace slug or UUID',
+      },
+      role: {
+        type: 'string',
+        enum: ['admin', 'contributor', 'member', 'owner'],
+        description: 'Filter by the authenticated user\'s role (optional)',
+      },
+      pagelen: {
+        type: 'number',
+        description: 'Results per page (default 25, max 100)',
+      },
+    },
+    required: ['workspace'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        pagelen: String(params.pagelen ?? 25),
+      };
+      if (params.role) query.role = params.role;
+
+      const result = await ctx.apiExecutor.get(
+        `/repositories/${params.workspace}`,
+        query,
+      );
+
+      const repos: any[] = Array.isArray(result.values) ? result.values : [];
+      if (repos.length === 0) {
+        return { content: `No repositories found in workspace "${params.workspace}".` };
+      }
+
+      const lines = repos.map((r: any) => {
+        const desc = r.description ? ` -- ${r.description}` : '';
+        const lang = r.language || 'unknown';
+        return `${r.full_name}${desc} (${lang}, ${r.is_private ? 'private' : 'public'})`;
+      });
+
+      return {
+        content: `Found ${repos.length} repositories in ${params.workspace}:\n${lines.join('\n')}`,
+        metadata: { count: repos.length, workspace: params.workspace },
+      };
+    } catch (err) {
+      return bitbucketError(err);
+    }
+  },
+};
+
+// ─── Tool: bitbucket_create_pull_request ────────────────
+
+const createPullRequest: ToolHandler = {
+  description:
+    'Create a pull request in a Bitbucket repository. Specify source and destination branches.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      workspace: {
+        type: 'string',
+        description: 'Workspace slug or UUID',
+      },
+      repo_slug: {
+        type: 'string',
+        description: 'Repository slug',
+      },
+      title: {
+        type: 'string',
+        description: 'Pull request title',
+      },
+      description: {
+        type: 'string',
+        description: 'Pull request description (Markdown supported)',
+      },
+      source_branch: {
+        type: 'string',
+        description: 'Source branch name (contains the changes)',
+      },
+      destination_branch: {
+        type: 'string',
+        description: 'Destination branch name to merge into (e.g. "main")',
+      },
+      close_source_branch: {
+        type: 'boolean',
+        description: 'Whether to close the source branch after merge (default: false)',
+      },
+    },
+    required: ['workspace', 'repo_slug', 'title', 'source_branch', 'destination_branch'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body: Record<string, any> = {
+        title: params.title,
+        source: {
+          branch: { name: params.source_branch },
+        },
+        destination: {
+          branch: { name: params.destination_branch },
+        },
+      };
+      if (params.description) body.description = params.description;
+      if (params.close_source_branch !== undefined) {
+        body.close_source_branch = params.close_source_branch;
+      }
+
+      const result = await ctx.apiExecutor.post(
+        `/repositories/${params.workspace}/${params.repo_slug}/pullrequests`,
+        body,
+      );
+
+      return {
+        content: `PR #${result.id} created: ${result.links?.html?.href || result.links?.self?.href}\n${result.title}\n${params.source_branch} -> ${params.destination_branch}`,
+        metadata: {
+          id: result.id,
+          url: result.links?.html?.href,
+          workspace: params.workspace,
+          repo_slug: params.repo_slug,
+          source_branch: params.source_branch,
+          destination_branch: params.destination_branch,
+        },
+      };
+    } catch (err) {
+      return bitbucketError(err);
+    }
+  },
+};
+
+// ─── Tool: bitbucket_list_pull_requests ─────────────────
+
+const listPullRequests: ToolHandler = {
+  description:
+    'List pull requests in a Bitbucket repository. Filter by state (OPEN, MERGED, DECLINED, SUPERSEDED).',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      workspace: {
+        type: 'string',
+        description: 'Workspace slug or UUID',
+      },
+      repo_slug: {
+        type: 'string',
+        description: 'Repository slug',
+      },
+      state: {
+        type: 'string',
+        enum: ['OPEN', 'MERGED', 'DECLINED', 'SUPERSEDED'],
+        description: 'Filter by pull request state (default: "OPEN")',
+      },
+      pagelen: {
+        type: 'number',
+        description: 'Results per page (default 25, max 50)',
+      },
+    },
+    required: ['workspace', 'repo_slug'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        state: params.state || 'OPEN',
+        pagelen: String(params.pagelen ?? 25),
+      };
+
+      const result = await ctx.apiExecutor.get(
+        `/repositories/${params.workspace}/${params.repo_slug}/pullrequests`,
+        query,
+      );
+
+      const prs: any[] = Array.isArray(result.values) ? result.values : [];
+      if (prs.length === 0) {
+        return {
+          content: `No ${query.state} pull requests found in ${params.workspace}/${params.repo_slug}.`,
+        };
+      }
+
+      const lines = prs.map((pr: any) => {
+        const author = pr.author?.display_name || pr.author?.nickname || 'unknown';
+        const src = pr.source?.branch?.name || '?';
+        const dst = pr.destination?.branch?.name || '?';
+        return `#${pr.id} ${pr.title} (${pr.state}) -- ${src} -> ${dst} by ${author}`;
+      });
+
+      return {
+        content: `Found ${prs.length} pull requests in ${params.workspace}/${params.repo_slug}:\n${lines.join('\n')}`,
+        metadata: {
+          count: prs.length,
+          workspace: params.workspace,
+          repo_slug: params.repo_slug,
+        },
+      };
+    } catch (err) {
+      return bitbucketError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const bitbucketAdapter: SkillAdapter = {
+  skillId: 'bitbucket-repos',
+  name: 'Bitbucket',
+  baseUrl: 'https://api.bitbucket.org/2.0',
+  auth: {
+    type: 'oauth2',
+    provider: 'bitbucket',
+  },
+  tools: {
+    bitbucket_list_repos: listRepos,
+    bitbucket_create_pull_request: createPullRequest,
+    bitbucket_list_pull_requests: listPullRequests,
+  },
+  rateLimits: {
+    requestsPerSecond: 10,
+    burstLimit: 20,
+  },
+  configSchema: {
+    workspace: {
+      type: 'string' as const,
+      label: 'Bitbucket Workspace',
+      description: 'Your Bitbucket workspace slug',
+      required: true,
+      placeholder: 'my-workspace',
+    },
+  },
+};