transform-ia/clover-bridge

Clover Bridge

MCP + GraphQL server for Clover POS API integration

A dual-interface Go server that exposes Clover POS data through both MCP (Model Context Protocol) for AI agents and GraphQL for web applications.

Features

• Dual Interface: MCP JSON-RPC + GraphQL on single HTTP port
• 20 Entities: Comprehensive coverage of Clover POS API
• Simple Auth: Bearer token authentication
• Observable: Full OpenTelemetry instrumentation (metrics, traces, logs)
• Production Ready: Helm chart, health checks, graceful shutdown

Supported Entities

Core Business (3)

• Merchants
• Customers
• Employees

Inventory Management (9)

• Items
• Categories
• Modifiers & Modifier Groups
• Item Groups
• Tags
• Attributes & Options
• Tax Rates

Orders & Transactions (6)

• Orders (including atomic creation)
• Line Items
• Payments
• Refunds
• Discounts
• Service Charges

Configuration (2)

• Order Types
• Opening Hours

Quick Start

Configuration

Set environment variables:

export CLOVER_TOKEN="your-bearer-token"
export CLOVER_MERCHANT_ID="your-merchant-id"
export PORT="80"

Run Server

go run cmd/server/main.go

MCP Interface

Access MCP tools at http://localhost:80/mcp

Example tools:

• query_order - Query orders with filters
• read_item - Get single item by ID
• create_customer - Create new customer
• update_merchant - Update merchant details

GraphQL Interface

Access GraphQL playground at http://localhost:80/graphql

Example query:

query {
  orders(query: "createdTime>2024-01-01") {
    id
    total
    createdTime
    lineItems {
      name
      price
    }
  }
}

Architecture

┌─────────────┐         ┌──────────────┐
│  AI Agent   │────────▶│     MCP      │
│  (Claude)   │         │   /mcp       │
└─────────────┘         │              │
                        │              │         ┌─────────────┐
┌─────────────┐         │   Clover     │────────▶│   Clover    │
│  Web App    │────────▶│   Bridge     │         │   POS API   │
└─────────────┘         │              │         └─────────────┘
                        │              │
                        │   GraphQL    │
                        │   /graphql   │
                        └──────────────┘

Development

Project Structure

clover-bridge/
├── cmd/server/          # Main server entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── telemetry/       # OpenTelemetry setup
│   ├── mcp/             # MCP server (92 tools)
│   ├── graphql/         # GraphQL resolvers
│   └── server/          # HTTP handlers
├── pkg/clover/          # Clover API client library
│   ├── client.go        # HTTP client + interface
│   ├── *.go             # 92 CRUD methods
│   └── models/          # 20 entity models
├── chart/               # Helm chart
└── .github/workflows/   # CI/CD pipelines

Building

# Generate GraphQL code
make generate

# Build binary
make build

# Run tests
make test

# Run linter
make lint

Testing

# Run all tests
go test -v ./...

# Run with coverage
go test -v -race -coverprofile=coverage.txt ./...

Deployment

Using ArgoCD (Recommended)

The project includes an ArgoCD Application manifest:

# Apply to cluster
kubectl apply -f applications/clover-bridge.yaml

# Monitor deployment
kubectl get application clover-bridge -n argocd

Using Helm

helm install clover-bridge ./chart \
  --set clover.token="your-token" \
  --set clover.merchantID="your-merchant-id" \
  --namespace claude

Environment Variables

MCP Integration

Add to your .mcp.json:

{
  "clover-bridge": {
    "type": "http",
    "url": "http://clover-bridge.claude.svc.cluster.local/mcp"
  }
}

API Documentation

MCP Tools (92 total)

All tools follow the pattern: {operation}_{entity}

Core Business (12 tools)

• Merchants: query_merchant, read_merchant, update_merchant
• Customers: query_customer, read_customer, create_customer, update_customer, delete_customer
• Employees: query_employee, read_employee, create_employee, delete_employee

Inventory (55 tools)

• Items: Full CRUD (5 tools)
• Categories: Full CRUD (5 tools)
• Modifiers: Full CRUD (5 tools)
• Modifier Groups: Full CRUD (5 tools)
• Item Groups: Full CRUD (5 tools)
• Tags: Full CRUD (5 tools)
• Attributes: Full CRUD (5 tools)
• Options: Full CRUD (5 tools)
• Tax Rates: Full CRUD (5 tools)

Orders & Transactions (27 tools)

• Orders: query_order, read_order, create_order, create_atomic_order, update_order, delete_order
• Line Items: Full CRUD (5 tools)
• Payments: Query, Read, Create (3 tools)
• Refunds: Query, Read, Create (3 tools)
• Discounts: Full CRUD (5 tools)
• Service Charges: Full CRUD (5 tools)

Configuration (10 tools)

• Order Types: Full CRUD (5 tools)
• Opening Hours: Full CRUD (5 tools)

GraphQL Schema

See for complete schema.

Observability

The server exposes Prometheus metrics at /metrics:

• clover_api_requests_total - Total API requests (by method, status, interface)
• clover_api_request_duration_seconds - Request duration histogram
• clover_api_errors_total - Total API errors (by method, error_type, interface)

Distributed tracing via OpenTelemetry to Jaeger (configurable endpoint).

License

MIT