mcpengine/servers/chargebee/src/tools/customers.ts

/**
 * Chargebee Customer Tools
 */

import type { Tool } from '@modelcontextprotocol/sdk/types.js';

export const listCustomersTool: Tool = {
  name: 'list_customers',
  description: 'Lists customers from Chargebee with pagination support. Use when the user wants to browse their customer database, export customer records, or analyze customer segments. Returns paginated results showing customer details, billing info, payment status, and account balances. Up to 100 customers per page.',
  inputSchema: {
    type: 'object',
    properties: {
      limit: {
        type: 'number',
        description: 'Number of customers per page (max 100)',
        default: 100,
      },
      offset: {
        type: 'string',
        description: 'Pagination offset from previous response',
      },
    },
  },
  _meta: {
    category: 'customers',
    access_level: 'read',
    complexity: 'low',
  },
};

export const getCustomerTool: Tool = {
  name: 'get_customer',
  description: 'Retrieves a single customer by ID from Chargebee. Use when the user asks for detailed customer information including contact details, billing address, payment methods, credit balances, and account status. Returns complete customer record with all metadata and financial information.',
  inputSchema: {
    type: 'object',
    properties: {
      id: {
        type: 'string',
        description: 'The unique ID of the customer to retrieve',
      },
    },
    required: ['id'],
  },
  _meta: {
    category: 'customers',
    access_level: 'read',
    complexity: 'low',
  },
};

export const createCustomerTool: Tool = {
  name: 'create_customer',
  description: 'Creates a new customer in Chargebee. Use when onboarding a new customer, importing customer data, or setting up an account before subscription creation. Accepts contact information, billing preferences, and payment settings. Returns the newly created customer with assigned ID.',
  inputSchema: {
    type: 'object',
    properties: {
      id: {
        type: 'string',
        description: 'Optional custom customer ID (auto-generated if not provided)',
      },
      email: {
        type: 'string',
        description: 'Customer email address',
      },
      first_name: {
        type: 'string',
        description: 'First name',
      },
      last_name: {
        type: 'string',
        description: 'Last name',
      },
      phone: {
        type: 'string',
        description: 'Phone number',
      },
      company: {
        type: 'string',
        description: 'Company name',
      },
      auto_collection: {
        type: 'string',
        enum: ['on', 'off'],
        description: 'Enable automatic payment collection (default: on)',
      },
      net_term_days: {
        type: 'number',
        description: 'Net payment term in days',
      },
      vat_number: {
        type: 'string',
        description: 'VAT/tax number',
      },
    },
  },
  _meta: {
    category: 'customers',
    access_level: 'write',
    complexity: 'medium',
  },
};

export const updateCustomerTool: Tool = {
  name: 'update_customer',
  description: 'Updates an existing customer in Chargebee. Use when the user needs to modify customer details, update contact information, change billing settings, or adjust payment preferences. Only specified fields will be updated. Returns the updated customer record.',
  inputSchema: {
    type: 'object',
    properties: {
      id: {
        type: 'string',
        description: 'The customer ID to update',
      },
      email: {
        type: 'string',
        description: 'Updated email address',
      },
      first_name: {
        type: 'string',
        description: 'Updated first name',
      },
      last_name: {
        type: 'string',
        description: 'Updated last name',
      },
      phone: {
        type: 'string',
        description: 'Updated phone number',
      },
      company: {
        type: 'string',
        description: 'Updated company name',
      },
      auto_collection: {
        type: 'string',
        enum: ['on', 'off'],
        description: 'Updated auto-collection setting',
      },
      net_term_days: {
        type: 'number',
        description: 'Updated net term days',
      },
    },
    required: ['id'],
  },
  _meta: {
    category: 'customers',
    access_level: 'write',
    complexity: 'medium',
  },
};

export const deleteCustomerTool: Tool = {
  name: 'delete_customer',
  description: 'Permanently deletes a customer from Chargebee. Use with caution when the user explicitly requests customer deletion for GDPR compliance or data cleanup. Customer must have no active subscriptions. This action cannot be undone. Returns confirmation of deletion.',
  inputSchema: {
    type: 'object',
    properties: {
      id: {
        type: 'string',
        description: 'The customer ID to delete',
      },
    },
    required: ['id'],
  },
  _meta: {
    category: 'customers',
    access_level: 'delete',
    complexity: 'low',
  },
};