# KiezelPay Sales MCP

An [MCP](https://modelcontextprotocol.io) client + server that lets you talk to your
[KiezelPay](https://kiezelpay.com) merchant **sales data** in natural language. Claude
picks which reporting call to make, your **products** become attachable context, and
common analyses are one-word commands.

The read-only KiezelPay merchant reporting API is wrapped as:

- **Tools** (Claude calls these autonomously)
  - `get_sales_summary` - balance, totals, active trials, next/previous payout
  - `get_sales_today` / `get_sales_yesterday` - your sales vs. the best merchant + your rank (optional `platform`)
  - `get_purchase_history` - recent individual purchases (`limit`, `platform`, `sort`)
  - `list_products` - distinct product names, derived from history
  - `get_product_sales` - aggregated stats for one product
- **Resources** - your products (derived by aggregating the `product` field across purchase history)
  - `kpay://products` - list of product names
  - `kpay://products/{product}` - one product's aggregate (count, revenue*, countries, platforms, first/last sale)
- **Prompts** - one-word analyses
  - `/analyze-product <product>` - performance deep-dive
  - `/trend-product <product>` - trajectory over the available history window
  - `/predict-product <product>` - near-term estimate (a heuristic extrapolation, **not** a statistical forecast)
  - `/sales-report` - overall executive summary

\* revenue is included only if the history records carry a price field.

## Prerequisites

- Python 3.10+
- An Anthropic API key (for the chat host)
- A KiezelPay merchant API key - get it at <https://kiezelpay.com/account/api>
  - The public test key `0123456789abcdef0123456789abcdef` works for summary/today/yesterday,
    but **not** `/history`, so products and the product prompts need a real key.

## Setup

### 1. Configure environment variables

Copy `.env.example` to `.env` and fill in the values:

```bash
ANTHROPIC_API_KEY=""          # your Anthropic API key
CLAUDE_MODEL="claude-sonnet-5"
KIEZELPAY_API_KEY=""          # your KiezelPay merchant key
USE_UV="1"
```

The KiezelPay key is used **only** by the MCP server, is read from the environment, and is
never returned to the model or printed. `.env` is gitignored.

### 2. Install dependencies

Using [uv](https://github.com/astral-sh/uv) (recommended):

```bash
uv venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -e .
```

Or without uv:

```bash
python -m venv .venv
source .venv/bin/activate
pip install anthropic python-dotenv prompt-toolkit "mcp[cli]>=1.8.0" "httpx>=0.27.0"
```

### 3. Run the chat host

```bash
uv run main.py     # or: python main.py
```

## Usage

Chat naturally - Claude will call the right tools:

```text
> How did sales go today, and what's my current balance?
> Which products sold the most in the last 200 purchases?
```

Attach a product as context with `@` (Tab to autocomplete):

```text
> How is @RadPro doing lately?
```

Run an analysis prompt with `/` (Tab to autocomplete):

```text
> /analyze-product RadPro
> /trend-product RadPro
> /predict-product RadPro
> /sales-report
```

## Use from Claude Desktop / Claude Code

The server speaks stdio, so any MCP host can run it. Example Claude Desktop entry:

```json
{
  "mcpServers": {
    "kiezelpay": {
      "command": "uv",
      "args": ["run", "mcp_server.py"],
      "cwd": "/absolute/path/to/kiezelpay-mcp",
      "env": { "KIEZELPAY_API_KEY": "your_key_here" }
    }
  }
}
```

## Project layout

| File | Role |
|---|---|
| `mcp_server.py` | KiezelPay Sales MCP server (tools, product resources, prompts) |
| `kpay_api.py` | Thin async HTTP client for the KiezelPay merchant API + product aggregation |
| `mcp_client.py` | Generic MCP client + a small test harness (`uv run mcp_client.py`) |
| `main.py` | CLI chat host entry point |
| `core/` | Chat host internals (Claude wrapper, chat loop, tool manager, CLI I/O) |

## Notes & caveats

- The API is **read-only**; this MCP never mutates anything.
- Products are **derived from history**, so the catalog only reflects the fetched window
  (`CATALOG_LIMIT` in `mcp_server.py`, default 200). Raise it for a longer catalog.
- `/predict-product` is a reasoning-based estimate over past patterns, not a real forecast.
- If `today`/`yesterday` day boundaries look off, adjust the timezone `offset` in `kpay_api.py`
  (`tz_offset_minutes()`).