# Chargebee MCP Server

MCP server for the Chargebee subscription billing platform, providing comprehensive tools for managing subscriptions, customers, invoices, plans, coupons, and credit notes.

## Features

- **Subscription Management** - Create, update, cancel, and reactivate subscriptions
- **Customer Database** - Manage customer records and billing information
- **Invoice Handling** - Generate invoices, track payments, and manage billing
- **Plan & Addon Management** - Browse and configure pricing plans
- **Coupon System** - Create and manage promotional discounts
- **Credit Notes** - Issue refunds and account credits

## Installation

```bash
npm install
npm run build
```

## Configuration

Set your Chargebee credentials as environment variables:

```bash
export CHARGEBEE_SITE_NAME="your-site-name"
export CHARGEBEE_API_KEY="your_api_key_here"
```

## Usage

Run the server:

```bash
npm start
# or
node dist/index.js
```

## Available Tools (24 total)

### Subscriptions (6 tools)
- `list_subscriptions` - Browse all subscriptions with pagination
- `get_subscription` - Get detailed subscription information
- `create_subscription` - Start new customer subscriptions
- `update_subscription` - Modify existing subscriptions
- `cancel_subscription` - Cancel subscriptions (immediate or end-of-term)
- `reactivate_subscription` - Restore cancelled subscriptions

### Customers (5 tools)
- `list_customers` - Browse customer database
- `get_customer` - Get detailed customer information
- `create_customer` - Add new customers
- `update_customer` - Modify customer details
- `delete_customer` - Remove customers (GDPR compliance)

### Invoices (3 tools)
- `list_invoices` - Browse invoice history
- `get_invoice` - Get detailed invoice with line items
- `create_invoice` - Generate one-time invoices

### Plans & Addons (4 tools)
- `list_plans` - Browse subscription plans
- `get_plan` - Get detailed plan configuration
- `list_addons` - Browse available add-ons
- `get_addon` - Get detailed add-on information

### Coupons (3 tools)
- `list_coupons` - Browse promotional codes
- `get_coupon` - Get coupon details and usage stats
- `create_coupon` - Create new discount coupons

### Credit Notes (3 tools)
- `list_credit_notes` - Browse refunds and credits
- `get_credit_note` - Get detailed credit note information
- `create_credit_note` - Issue refunds or account credits

## API Coverage Manifest

**Total Chargebee API Endpoints:** ~200+  
**Implemented in this server:** 24  
**Coverage:** ~12%

### Covered Areas:
- ✅ Core subscription lifecycle
- ✅ Customer management
- ✅ Invoice generation and tracking
- ✅ Plan and addon configuration
- ✅ Coupon management
- ✅ Credit note issuance

### Not Yet Implemented:
- ⏳ Payment sources and gateways
- ⏳ Hosted pages configuration
- ⏳ Quotes and estimates
- ⏳ Unbilled charges
- ⏳ Promotional credits
- ⏳ Transactions and refunds
- ⏳ Events and webhooks
- ⏳ Tax configuration
- ⏳ Dunning management
- ⏳ Reports and analytics
- ⏳ Import/export operations
- ⏳ Portal sessions
- ⏳ Gift subscriptions
- ⏳ Item prices (Product Catalog 2.0)

## Architecture

```
chargebee/
├── src/
│   ├── index.ts                    # MCP server entry point
│   ├── client/
│   │   └── chargebee-client.ts    # API client with rate limiting
│   ├── tools/
│   │   ├── subscriptions.ts       # Subscription tools
│   │   ├── customers.ts           # Customer tools
│   │   ├── invoices.ts            # Invoice tools
│   │   ├── plans.ts               # Plan & addon tools
│   │   ├── coupons.ts             # Coupon tools
│   │   └── credit_notes.ts        # Credit note tools
│   └── types/
│       └── index.ts               # TypeScript interfaces
├── package.json
├── tsconfig.json
└── README.md
```

## Rate Limiting

The client implements automatic rate limiting:
- Max 10 concurrent requests
- Minimum 100ms between requests
- Automatic retry on 429 responses

## Error Handling

The server provides detailed error messages for:
- Authentication failures (401)
- Payment required (402)
- Permission issues (403)
- Resource not found (404)
- Bad request/validation (400)
- Rate limit exceeded (429)
- Server errors (500+)

## License

MIT