Metadata-Version: 2.5
Name: loyaltydog-mcp
Version: 0.1.0
Summary: MCP server for the LoyaltyDog loyalty, wallet pass, and gift card API.
Project-URL: Homepage, https://loyaltydog.ai
Project-URL: Documentation, https://docs.loyalty.dog/mcp/overview
Author-email: LoyaltyDog <support@loyalty.dog>
License-Expression: MIT
License-File: LICENSE
Keywords: gift-cards,loyalty,loyaltydog,mcp,model-context-protocol,wallet-passes
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: pydantic-settings>=2.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: respx>=0.21; extra == 'test'
Description-Content-Type: text/markdown

# loyaltydog-mcp

MCP server for the [LoyaltyDog](https://loyaltydog.ai) loyalty, wallet pass, and gift card API. It speaks the [Model Context Protocol](https://modelcontextprotocol.io/) over stdio, so Claude, Cursor, and any other MCP client can list programs, look up customers, and — when you allow it — issue gift cards or update records through a bearer API key.

The server is a thin client of the public REST API. It does not talk to a database. Tool calls send `Authorization: Bearer <your key>` to `https://api.loyalty.dog/v2`.

Documentation: https://docs.loyalty.dog/mcp/overview

## Requirements

- Python 3.10 or newer. [uv](https://docs.astral.sh/uv/) is the easiest way to run the server without a manual install.
- A LoyaltyDog API key from your dashboard. Live keys look like `ld_live_...` and test keys look like `ld_test_...`.
- An account on a plan that includes API access. Plans are listed at https://loyaltydog.ai/pricing/.

## Quick start

Run without installing, using uv:

```bash
uvx loyaltydog-mcp
```

Or with pipx:

```bash
pipx run loyaltydog-mcp
```

Or install into the current environment:

```bash
pip install loyaltydog-mcp
loyaltydog-mcp
```

The process speaks MCP on stdin/stdout and waits for a client. Configure the client with your API key as shown below. `loyaltydog-mcp --version` prints the installed version and exits.

## Configuration

Set variables in the MCP client's `env` block. The installed command does not read a `.env` file from the working directory.

| Variable | Required | Description |
| --- | --- | --- |
| `LOYALTYDOG_API_KEY` | Yes | Bearer API key (`ld_live_...` or `ld_test_...`). |
| `LOYALTYDOG_API_URL` | No | API base URL. Default `https://api.loyalty.dog/v2`. A trailing slash is stripped. |
| `LOYALTYDOG_API_TOKEN` | No | Legacy alias for the API key. Used only when `LOYALTYDOG_API_KEY` is unset. If both are set, `LOYALTYDOG_API_KEY` wins. |

The server starts and lists its tools even when the key is missing. The first tool call then returns an error telling you to set `LOYALTYDOG_API_KEY`. The key is sent only as the bearer token and is never logged.

## Client setup

Use a placeholder here, then replace it with your own key. Prefer an `ld_test_...` key until you trust the assistant with live data.

### Claude Desktop

Add this to `claude_desktop_config.json` (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "loyaltydog": {
      "command": "uvx",
      "args": ["loyaltydog-mcp"],
      "env": {
        "LOYALTYDOG_API_KEY": "ld_live_your_key_here"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add loyaltydog --env LOYALTYDOG_API_KEY=ld_live_xxx -- uvx loyaltydog-mcp
```

### Cursor

Add this to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "loyaltydog": {
      "command": "uvx",
      "args": ["loyaltydog-mcp"],
      "env": {
        "LOYALTYDOG_API_KEY": "ld_live_your_key_here"
      }
    }
  }
}
```

### Generic MCP client

Any client that launches a stdio server can use the same shape:

```json
{
  "command": "uvx",
  "args": ["loyaltydog-mcp"],
  "env": {
    "LOYALTYDOG_API_KEY": "ld_live_your_key_here",
    "LOYALTYDOG_API_URL": "https://api.loyalty.dog/v2"
  }
}
```

`pipx run loyaltydog-mcp` or an installed `loyaltydog-mcp` work as the command in place of `uvx`.

## Tools

The server exposes 17 tools.

### Read

| Tool | What it does |
| --- | --- |
| `list_programs` | List loyalty programs with names and IDs. |
| `get_program` | Program details. Requires `program_id`. |
| `search_customers` | Search customers in a program by `email` or `name`. Requires `program_id`. |
| `get_customer` | One customer's details and points. Requires `program_id` and `customer_id`. |
| `get_customer_transactions` | Points history. Requires `program_id` and `customer_id`. Optional `limit` (default 20), `start`, `end`. |
| `list_passes` | Wallet passes visible to the authenticated merchant. |
| `get_pass` | Passes for a pass type identifier (`pass_id`). |
| `list_gift_cards` | Gift cards for a program. Requires `program_id`. Optional `status`, `positive_balance`. |
| `get_gift_card` | One gift card. Requires `program_id` and `card_id`. |
| `get_gift_card_transactions` | Gift card ledger. Requires `program_id` and `card_id`. Optional `limit` (default 20). |
| `get_gift_card_business_report` | Read-only gift card totals for a program. Requires `program_id`. |
| `get_system_health` | API health and version. |

### Writes

These five tools change data. There is no undo inside the server.

| Tool | Effect |
| --- | --- |
| `issue_gift_card` | **Mutating.** Issues a new gift card with real value. Requires `program_id`, `merchant_id`, and `initial_value` (0.01–10000, no default). |
| `redeem_gift_card` | **Mutating.** Spends value from a gift card. Requires `program_id`, `card_id`, and `amount` (at least 0.01, no default). |
| `update_customer` | **Mutating.** Updates a customer, including PII. If `points` is set, it overwrites the balance. Requires `program_id`, `customer_id`, and at least one field. |
| `update_program` | **Mutating.** Updates program-wide settings that apply to every customer. Requires `program_id` and at least one field. |
| `regenerate_pass` | **Mutating, low risk.** Pushes a wallet pass update so the device re-fetches it. Does not change balances, points, or customer data. Requires `pass_type_identifier` and `serial_number`. |

**Safety.** Use an `ld_test_...` key while you are trying the server out. In your MCP client, approve each tool call yourself instead of granting blanket permission, especially for the five tools above. Amounts are required and have no default. The server checks that they are positive before it calls the API.

## Troubleshooting

**`uvx` is not found.** Install uv, then open a new terminal:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

See https://docs.astral.sh/uv/getting-started/installation/ if you would rather use a package manager.

**Tool calls say `LOYALTYDOG_API_KEY is not set`.** Create a key in the LoyaltyDog dashboard and set `LOYALTYDOG_API_KEY` in the MCP client config (the `env` block above). A key exported only in some other shell, or written only in a `.env` file, is not visible to the server. `LOYALTYDOG_API_TOKEN` still works as a legacy name.

**`401` or `403` from a tool.** The key is present but was rejected. Confirm it is an `ld_live_...` or `ld_test_...` key for the right account, and that the account's plan includes API access (https://loyaltydog.ai/pricing/).

## Development

From a checkout of this package:

```bash
pip install -e ".[test]"
pytest
```

Tests use a dummy key and mock HTTP. They do not call the live API.

## License

MIT. Copyright (c) 2026 LoyaltyDog.

- Homepage: https://loyaltydog.ai
- Documentation: https://docs.loyalty.dog/mcp/overview
