mcpengine/servers/square/README.md

# Square MCP Server

A comprehensive Model Context Protocol (MCP) server for Square, providing AI assistants with complete access to payment processing, point-of-sale operations, and business management. This server delivers 80 tools across payments, inventory, customers, and e-commerce workflows, plus 18 React-based UI applications.

## Features

- **Payment Processing**: Create, capture, void, and refund payments with support for all payment methods
- **Order Management**: Create orders, manage line items, apply discounts, calculate taxes, and track fulfillment
- **Customer Management**: Full CRM with customer profiles, groups, segments, and marketing preferences
- **Catalog & Inventory**: Manage products, variations, modifiers, categories, and real-time inventory tracking
- **Invoicing**: Create, send, update, and track invoices with payment reminders
- **Subscriptions**: Manage recurring billing, subscription plans, and customer subscriptions
- **Loyalty Programs**: Create loyalty programs, track points, and manage rewards
- **Team Management**: Manage team members, roles, wage settings, and permissions
- **Location Management**: Handle multiple business locations and location-specific settings
- **Booking & Appointments**: Manage appointment calendars, bookings, and service catalog
- **Dispute Handling**: Track payment disputes, submit evidence, and manage chargebacks
- **Refund Operations**: Process full and partial refunds with automatic inventory adjustment
- **18 React Apps**: Pre-built UI components for POS, inventory management, customer dashboards, and more
- **Multi-Currency Support**: Process payments in multiple currencies with automatic conversion
- **Sandbox Testing**: Full sandbox environment support for development and testing

## Installation

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

## Environment Variables

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `SQUARE_ACCESS_TOKEN` | Yes | Your Square access token (sandbox or production) | `EAAAEOuLQPTO1Z4...` |
| `SQUARE_ENVIRONMENT` | No | Environment: `sandbox` or `production` (default: `production`) | `sandbox` |

## Getting Your Access Token

### Production Token (Live Payments)

1. **Create a Square Developer Account**:
   - Go to [developer.squareup.com](https://developer.squareup.com)
   - Click **Sign Up** or log in with your Square account
   - Complete the developer registration

2. **Create an Application**:
   - Go to [Square Developer Dashboard](https://developer.squareup.com/apps)
   - Click **+ Create App** or **New Application**
   - Enter application name (e.g., "MCP Integration")
   - Select your Square account to associate with the app

3. **Get Production Access Token**:
   - In your application dashboard, click **Production** tab
   - Under **Credentials**, find **Access Token**
   - Click **Show** to reveal the token
   - Copy the entire token (starts with `EAA...`)

4. **Set Environment Variables**:
   ```bash
   export SQUARE_ACCESS_TOKEN="your_production_token_here"
   export SQUARE_ENVIRONMENT="production"
   ```

### Sandbox Token (Testing)

1. **Access Sandbox Credentials**:
   - In your [application dashboard](https://developer.squareup.com/apps)
   - Click the **Sandbox** tab (not Production)
   - Under **Credentials**, find **Sandbox Access Token**
   - Click **Show** to reveal the token

2. **Set Environment Variables**:
   ```bash
   export SQUARE_ACCESS_TOKEN="your_sandbox_token_here"
   export SQUARE_ENVIRONMENT="sandbox"
   ```

3. **Test Data**:
   - Sandbox uses fake credit cards: `4111 1111 1111 1111` (Visa)
   - CVV: any 3 digits, Expiry: any future date
   - Postal code: any 5-digit ZIP
   - [Full test card list](https://developer.squareup.com/docs/testing/test-values)

### OAuth 2.0 (For Third-Party Apps)

If building an app for other Square merchants:

1. **Enable OAuth**: In app settings, enable OAuth
2. **Set Redirect URL**: Add your OAuth callback URL
3. **Authorization Flow**:
   - Direct user to: `https://connect.squareup.com/oauth2/authorize?client_id={APP_ID}&scope={SCOPES}`
   - User authorizes and redirects back with code
   - Exchange code for access token at `/oauth2/token` endpoint

**Security Notes**:
- Never commit access tokens to version control
- Production tokens have full access to real payment data
- Rotate tokens regularly and use OAuth for third-party integrations
- Sandbox and production tokens are completely separate

## Required API Scopes

Square access tokens automatically include these permissions:

**Payment Scopes**:
- `PAYMENTS_READ` - View payment history and details
- `PAYMENTS_WRITE` - Process payments, refunds, and voids
- `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` - Split payments to multiple recipients

**Order & Catalog Scopes**:
- `ORDERS_READ` - View orders
- `ORDERS_WRITE` - Create and update orders
- `ITEMS_READ` - View catalog items and inventory
- `ITEMS_WRITE` - Manage products, variations, and inventory

**Customer Scopes**:
- `CUSTOMERS_READ` - View customer data
- `CUSTOMERS_WRITE` - Create and update customers
- `MERCHANT_PROFILE_READ` - View business information
- `MERCHANT_PROFILE_WRITE` - Update business settings

**Additional Scopes**:
- `INVOICES_READ` / `INVOICES_WRITE` - Manage invoices
- `SUBSCRIPTIONS_READ` / `SUBSCRIPTIONS_WRITE` - Manage subscriptions
- `APPOINTMENTS_READ` / `APPOINTMENTS_WRITE` - Manage bookings
- `LOYALTY_READ` / `LOYALTY_WRITE` - Manage loyalty programs
- `TIMECARDS_READ` / `TIMECARDS_WRITE` - Manage team time tracking
- `DISPUTES_READ` / `DISPUTES_WRITE` - Handle payment disputes
- `GIFTCARDS_READ` / `GIFTCARDS_WRITE` - Manage gift cards

**OAuth Scope Format**: When using OAuth, request specific scopes in the authorization URL (space-separated list).

## Usage

### stdio Mode (Default)

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "square": {
      "command": "node",
      "args": [
        "/path/to/mcpengine-repo/servers/square/dist/index.js"
      ],
      "env": {
        "SQUARE_ACCESS_TOKEN": "your_token_here",
        "SQUARE_ENVIRONMENT": "sandbox"
      }
    }
  }
}
```

### HTTP Mode

The server can also run as an HTTP endpoint:

```bash
export SQUARE_ACCESS_TOKEN="your_token_here"
export SQUARE_ENVIRONMENT="sandbox"
npm start -- --http --port 3000
```

Then configure your MCP client to connect to `http://localhost:3000`.

## Coverage Manifest

```
Total API endpoints: ~150 (Square API v2)
Tools implemented: 80
Intentionally skipped: ~40 (gift cards, cash drawer, labor, terminal, devices, deprecated v1 endpoints)
Not yet covered: ~30 (bank accounts, payouts, cards on file, snippets, sites, mobile auth)
Coverage: 80/150 = 53%
```

**Coverage Notes**:
- ✅ **Complete**: Payments (8 tools), Orders (10 tools), Customers (9 tools), Catalog (9 tools), Inventory (7 tools), Invoices (8 tools), Subscriptions (7 tools), Locations (4 tools), Team Members (6 tools), Bookings (6 tools), Disputes (3 tools), Refunds (3 tools), Loyalty (8+ tools)
- ⏭️ **Skipped**: Gift cards (separate activation flow), cash drawer management, labor/shift tracking, terminal device pairing, deprecated v1 APIs, snippets/embeds
- 🚧 **Planned**: Bank account verification, payout schedules, saved payment methods (cards on file), marketing snippets, Square Sites integration, mobile authorization

## Example Use Cases

- "Process a $49.99 payment for customer john@example.com"
- "Create a new product 'Organic Coffee Beans' with price $24.99"
- "List all orders from the last 7 days"
- "Add customer Sarah Johnson with email sarah@example.com"
- "Refund payment #xyz123 for $10.00"
- "Update inventory count for product SKU 'BEANS-001' to 50 units"
- "Create an invoice for $500 due in 30 days"
- "List all team members at the Downtown location"
- "Get today's payment summary across all locations"
- "Create a subscription plan for $29.99/month"

## Architecture

The server uses Square API v2 (2024-12-18) with Bearer token authentication:
- **Client**: `SquareClient` with automatic idempotency key generation
- **Tools**: 13 tool modules with 80 total tools
- **Apps**: 18 React-based UI components
- **Auth**: HTTP Bearer Authentication (`Authorization: Bearer {token}`)
- **Pagination**: Automatic cursor-based pagination
- **Idempotency**: Automatic UUID generation for idempotent operations
- **Retry Logic**: Built-in retry with exponential backoff (3 attempts, 1s delay)
- **Rate Limits**: Respects Square rate limits (varies by endpoint, typically 10-500 req/sec)
- **API Version**: `2024-12-18` (updates quarterly)

## Links

- [Square Developer Portal](https://developer.squareup.com)
- [Square API Reference](https://developer.squareup.com/reference/square)
- [API Explorer](https://developer.squareup.com/explorer/square)
- [OAuth Guide](https://developer.squareup.com/docs/oauth-api/overview)
- [Testing Guide](https://developer.squareup.com/docs/testing/test-values)
- [Sandbox Dashboard](https://developer.squareup.com/apps)
- [API Changelog](https://developer.squareup.com/docs/changelog)
- [Square Support](https://squareup.com/help)