# QuickBooks Online MCP Server

Model Context Protocol (MCP) server for QuickBooks Online integration.

## Features

- **Full QBO API Coverage**: Invoices, Customers, Vendors, Bills, Payments, Estimates, Items, Accounts, Reports, and more
- **SQL-like Queries**: Native support for QBO's query language
- **Rate Limiting**: Respects QBO's 500 req/min throttle with automatic retry
- **Optimistic Locking**: SyncToken support for safe updates
- **Sandbox Support**: Test against QBO Sandbox environment
- **Type Safety**: Comprehensive TypeScript types for all QBO entities
- **Pagination**: Automatic handling of large result sets
- **Token Refresh**: Built-in OAuth2 token refresh support

## Installation

```bash
npm install
```

## Configuration

Create a `.env` file (see `.env.example`):

```bash
# Required
QBO_ACCESS_TOKEN=your_access_token
QBO_REALM_ID=your_realm_id

# Optional
QBO_REFRESH_TOKEN=your_refresh_token
QBO_SANDBOX=false
QBO_MINOR_VERSION=73
```

### Getting OAuth Credentials

1. Create an app at [Intuit Developer Portal](https://developer.intuit.com)
2. Configure OAuth2 redirect URIs
3. Obtain access token and realm ID via OAuth flow
4. Store refresh token for automatic renewal

## Usage

### Development

```bash
npm run dev
```

### Production

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

## Architecture

### Foundation Components

- **`src/types/index.ts`**: Comprehensive TypeScript interfaces for all QBO entities
- **`src/clients/quickbooks.ts`**: Full-featured QBO API client with retry, rate limiting, and pagination
- **`src/server.ts`**: MCP server with lazy-loaded tool modules
- **`src/main.ts`**: Entry point with environment validation and dual transport

### QuickBooks Client Features

- OAuth2 Bearer authentication
- Automatic retry with exponential backoff (3 retries)
- Rate limit handling (500 req/min)
- Pagination support (startPosition + maxResults)
- SQL-like query execution
- Batch operations (up to 30 per batch)
- Token refresh helper
- Sandbox/production environment switching

### Tool Categories (Lazy-Loaded)

Tool implementations will be added in:
- `src/tools/invoices.ts` - Create, read, update, send invoices
- `src/tools/customers.ts` - Customer management
- `src/tools/payments.ts` - Payment processing
- `src/tools/estimates.ts` - Estimate creation and conversion
- `src/tools/bills.ts` - Bill management
- `src/tools/vendors.ts` - Vendor operations
- `src/tools/items.ts` - Inventory and service items
- `src/tools/accounts.ts` - Chart of accounts
- `src/tools/reports.ts` - P&L, Balance Sheet, Cash Flow, etc.
- `src/tools/employees.ts` - Employee management
- `src/tools/time-activities.ts` - Time tracking
- `src/tools/taxes.ts` - Tax codes and rates
- `src/tools/purchases.ts` - Purchase orders and expenses
- `src/tools/journal-entries.ts` - Manual journal entries

## API Examples

### Query Invoices

```typescript
const result = await client.query(
  'SELECT * FROM Invoice WHERE TotalAmt > 1000',
  { startPosition: 1, maxResults: 100 }
);
```

### Create Customer

```typescript
const customer = await client.create('Customer', {
  DisplayName: 'Acme Corp',
  PrimaryEmailAddr: { Address: 'billing@acme.com' },
});
```

### Update Invoice (with SyncToken)

```typescript
const invoice = await client.update('Invoice', {
  Id: '123',
  SyncToken: '0',
  TotalAmt: 5000,
});
```

### Get Reports

```typescript
const profitLoss = await client.getReport('ProfitAndLoss', {
  start_date: '2024-01-01',
  end_date: '2024-12-31',
  accounting_method: 'Accrual',
});
```

## QuickBooks Online API Reference

- [API Documentation](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/invoice)
- [Query Language](https://developer.intuit.com/app/developer/qbo/docs/develop/explore-the-quickbooks-online-api/data-queries)
- [OAuth Guide](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization)

## Type Safety

All QBO entities use:
- Branded types for IDs (prevents mixing Customer/Vendor/etc. IDs)
- Discriminated unions for entity types and statuses
- SyncToken for optimistic locking on all entities
- Strict TypeScript mode for compile-time safety

## Rate Limiting

QBO enforces 500 requests/minute:
- Client tracks requests per rolling window
- Automatically throttles when approaching limit
- Retries 429 responses with exponential backoff

## Error Handling

QBO errors include:
- Error code
- Message
- Detail
- Element (field causing error)

The client wraps these in structured MCP errors.

## License

MIT

## Contributing

This is the foundation layer. Tool implementations and UI apps will be added separately.