# chateapro-mcp

An MCP server that exposes a curated, safety-gated subset of the [Chatea Pro](https://chateapro.app) REST API as tools for Claude Code and Claude Desktop.

It is meant for order-ops automation: read data (contacts, orders, tags, flows, agents) and act on a single contact (tag, set fields, move chat, assign agent, trigger a flow, send a message). Bulk and order-state writes are opt-in behind environment flags.

## Requirements

- Python 3.11+
- A Chatea Pro API token with **both** scopes: *Gestionar equipo* (Manage Team) and *Gestionar el flujo* (Manage Flow).

## Get a token

Chatea Pro → profile menu (top right) → **API Keys** → *Crear token API*. Name it, tick **Asignar todas las habilidades** (or at least *Gestionar equipo* + *Gestionar el flujo*), pick the workspace and bot, **Crear**. Copy the token.

## Install

```bash
git clone https://github.com/Anthonygp21/chateapro-mcp
cd chateapro-mcp
uv sync --extra dev
```

## Configure Claude Code

```bash
claude mcp add chateapro \
  -e CHATEAPRO_API_TOKEN=YOUR_TOKEN \
  -e CHATEAPRO_DRY_RUN=true \
  -- uv run --directory /abs/path/to/chateapro-mcp chateapro-mcp
```

Start in dry-run: every write tool returns the request it *would* send and makes no call. Once you've seen what the write tools do, drop `-e CHATEAPRO_DRY_RUN=true` (or set it to `false`) to let writes through.

## Configure Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "chateapro": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/to/chateapro-mcp", "chateapro-mcp"],
      "env": { "CHATEAPRO_API_TOKEN": "YOUR_TOKEN" }
    }
  }
}
```

## Environment variables

| Var | Default | Meaning |
|---|---|---|
| `CHATEAPRO_API_TOKEN` | — | **Required.** Bearer token. |
| `CHATEAPRO_BASE_URL` | `https://chateapro.app/api` | API base. |
| `CHATEAPRO_DRY_RUN` | `false` | When `true`, every write tool returns the request it *would* send and makes no call. |
| `CHATEAPRO_ENABLE_ORDER_WRITE` | `false` | Register `update_order_status`. |
| `CHATEAPRO_ENABLE_BROADCAST` | `false` | Register `broadcast_whatsapp_template_by_tag` (messages many customers). |
| `CHATEAPRO_REQUEST_TIMEOUT` | `30` | Per-request timeout (seconds). |
| `CHATEAPRO_MAX_RETRIES` | `3` | Retries on HTTP 429/5xx (exponential backoff). |

## Tools

**Read:** `find_contact`, `get_contact`, `list_contacts`, `list_contact_fields`, `list_tags`, `list_flows`, `list_whatsapp_templates`, `list_orders`, `get_order`, `list_agents`, `list_agent_groups`, `list_ticket_lists`, `get_ticket_list_items`.

**Write (one contact; honor `CHATEAPRO_DRY_RUN`):** `set_contact_field`, `add_contact_tag`, `remove_contact_tag`, `move_chat` (`open`/`pending`/`spam`/`done`), `assign_agent`, `assign_agent_group`, `unassign_agent`, `pause_bot`, `resume_bot`, `trigger_flow`, `send_text`, `send_whatsapp_template`.

**Opt-in write (flag-gated):** `update_order_status`, `broadcast_whatsapp_template_by_tag`.

`find_contact` joins external data (e.g. from Dropi) to a Chatea Pro conversation by phone number (Ecuador `+593` normalization). If more than one contact matches, it returns them all and does not guess.

## Safety

- The token is read only from the environment and never logged or returned.
- Start with `CHATEAPRO_DRY_RUN=true` to see exactly what each write would do.
- `broadcast_whatsapp_template_by_tag` and `update_order_status` are not even registered unless you opt in.

## Development

```bash
uv run pytest
```

The live smoke test (`tests/test_smoke_live.py`) runs only when `CHATEAPRO_API_TOKEN` is set and is read-only.

## License

MIT