# Stripe MCP Server

Model Context Protocol (MCP) server for Stripe API integration. Provides comprehensive access to Stripe's payment processing, subscription management, and customer data.

## Features

- 🔐 **Secure Authentication** - Bearer token authentication with API key
- 🔄 **Automatic Retries** - Exponential backoff with configurable retry logic
- 📊 **Pagination Support** - Cursor-based pagination with automatic iteration
- 🎯 **Idempotency** - Built-in idempotency key support for safe retries
- 🛡️ **Type Safety** - Comprehensive TypeScript types for all Stripe entities
- 🚀 **Lazy Loading** - Tool modules loaded on-demand for better performance
- 🔌 **Dual Transport** - Supports both stdio and HTTP/SSE transports
- 📦 **Resource Handlers** - Pre-built resources for common UI needs

## Installation

```bash
npm install
```

## Configuration

Create a `.env` file based on `.env.example`:

```bash
# Required
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxx

# Optional
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxx
PORT=3000
TRANSPORT_MODE=stdio  # stdio | http | dual
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `STRIPE_SECRET_KEY` | ✅ Yes | Your Stripe secret API key (starts with `sk_test_` or `sk_live_`) |
| `STRIPE_WEBHOOK_SECRET` | ❌ No | Webhook signing secret for webhook verification (starts with `whsec_`) |
| `PORT` | ❌ No | HTTP server port for SSE transport (default: 3000) |
| `TRANSPORT_MODE` | ❌ No | Transport mode: `stdio`, `http`, or `dual` (default: stdio) |

## Usage

### Development Mode

```bash
npm run dev
```

### Production Build

```bash
npm run build
npm start
```

### Transport Modes

#### stdio (Default)
Used by MCP clients like Claude Desktop:

```bash
npm start
# or
TRANSPORT_MODE=stdio npm start
```

#### HTTP/SSE
For web-based integrations:

```bash
TRANSPORT_MODE=http npm start
# Server available at http://localhost:3000
```

#### Dual Transport
Run both simultaneously:

```bash
TRANSPORT_MODE=dual npm start
```

## Tool Categories

The server provides lazy-loaded tool modules organized by functionality:

### 💳 Payments
- `charges` - Create, retrieve, update, and list charges
- `payment-intents` - Manage payment intents
- `payment-methods` - Handle payment methods
- `refunds` - Process and manage refunds
- `disputes` - Handle payment disputes

### 👥 Customers
- `customers` - Create and manage customers

### 📅 Subscriptions
- `subscriptions` - Manage recurring subscriptions
- `invoices` - Handle invoices and billing

### 🏷️ Products & Pricing
- `products` - Manage products
- `prices` - Handle pricing models

### 💰 Payouts & Balance
- `payouts` - Manage payouts to bank accounts
- `balance` - Check account balance and transactions

### 🔔 Events & Webhooks
- `events` - Retrieve and search events
- `webhooks` - Manage webhook endpoints

## Resource URIs

Pre-built resources for UI applications:

| URI | Description |
|-----|-------------|
| `stripe://dashboard` | Account overview and key metrics |
| `stripe://customers` | Customer list |
| `stripe://payments/recent` | Recent payments and charges |
| `stripe://subscriptions/active` | Active subscriptions |
| `stripe://invoices/unpaid` | Unpaid invoices |

## API Client Features

### Automatic Pagination

```typescript
// Iterate through all customers
for await (const customer of client.paginate('customers')) {
  console.log(customer.email);
}
```

### Idempotency Keys

```typescript
// Safe retry with idempotency
const result = await client.create('charges', data, {
  idempotencyKey: client.generateIdempotencyKey()
});
```

### Retry Logic

- Automatic retry on 429 (rate limit), 409 (conflict), and 5xx errors
- Exponential backoff with jitter
- Respects `Stripe-Should-Retry` and `Retry-After` headers
- Configurable retry count (default: 3)

### Form Encoding

Stripe requires `application/x-www-form-urlencoded` for POST requests. The client automatically handles:

- Nested object encoding with dot notation
- Array parameters
- Metadata fields
- Null/undefined value filtering

## Type Safety

All Stripe entities use branded ID types for additional type safety:

```typescript
type CustomerId = string & { __brand: 'CustomerId' };
type PaymentIntentId = string & { __brand: 'PaymentIntentId' };
```

This prevents accidentally mixing different ID types.

## Error Handling

The server provides structured error responses:

```json
{
  "error": {
    "type": "api_error",
    "message": "The API key provided is invalid.",
    "code": "invalid_api_key"
  }
}
```

Common error types:
- `api_error` - Stripe API errors
- `card_error` - Card-related errors
- `rate_limit_error` - Too many requests
- `invalid_request_error` - Invalid parameters
- `authentication_error` - Invalid API key

## Health Check

When running in HTTP mode, health check available at:

```bash
curl http://localhost:3000/health
```

Response:
```json
{
  "status": "healthy",
  "service": "@mcpengine/stripe",
  "version": "1.0.0",
  "timestamp": "2024-01-18T12:00:00.000Z",
  "uptime": 123.45,
  "memory": { "rss": 45678, "heapTotal": 23456, "heapUsed": 12345 },
  "node": "v22.0.0"
}
```

## Graceful Shutdown

The server handles shutdown signals gracefully:

- `SIGTERM` - Kubernetes/Docker shutdown
- `SIGINT` - Ctrl+C in terminal
- `SIGUSR2` - Nodemon restart

Cleanup process:
1. Stop accepting new connections
2. Finish processing active requests
3. Close MCP server connection
4. Exit with code 0

## Development

### Project Structure

```
stripe/
├── src/
│   ├── clients/
│   │   └── stripe.ts        # Stripe API client
│   ├── types/
│   │   └── index.ts         # TypeScript type definitions
│   ├── tools/               # Tool modules (lazy-loaded)
│   │   ├── customers.ts
│   │   ├── charges.ts
│   │   └── ...
│   ├── server.ts            # MCP server implementation
│   └── main.ts              # Entry point
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
```

### Adding New Tools

1. Create a new file in `src/tools/`
2. Export an array of `ToolModule` objects
3. Register in `TOOL_MODULES` in `src/server.ts`

### Testing

```bash
# Type check
npm run build

# Run in dev mode
npm run dev
```

## Security Considerations

- **Never commit `.env` file** - Contains sensitive API keys
- **Use test keys in development** - Keys starting with `sk_test_`
- **Rotate keys regularly** - Especially after security incidents
- **Webhook signature verification** - Use `STRIPE_WEBHOOK_SECRET` for webhooks
- **Idempotency keys** - Prevent duplicate charges on retries

## Stripe API Version

This server uses Stripe API version `2024-01-18`. The version is set in the `Stripe-Version` header for all requests.

## License

MIT

## Support

For issues and questions:
- Stripe API Docs: https://stripe.com/docs/api
- MCP Protocol: https://github.com/anthropics/model-context-protocol