<p align="center">
  <a href="https://shotgun.live">
    <img src="https://www.google.com/s2/favicons?domain=shotgun.live&sz=128" alt="Shotgun" width="72" height="72">
  </a>
</p>

<h1 align="center">🎟️ Shotgun MCP</h1>

<p align="center">
  Serveur <b>MCP</b> (Model Context Protocol) <b>non officiel</b> qui expose les
  ventes de tes événements <a href="https://shotgun.live">Shotgun</a> à un assistant
  IA : billets, revenu net, remboursement potentiel, quotas par tarif et audience —
  le tout en <b>données agrégées</b>.
</p>

<p align="center">
  <a href="https://modelcontextprotocol.io">🔌 Model Context Protocol</a> ·
  <a href="https://shotgun.live">🌐 Shotgun</a>
</p>

---

## ✨ Ce que ça fait

Un serveur MCP en **HTTP streamable** que tu ajoutes comme connecteur dans un
client compatible (Claude, etc.). L'assistant peut alors interroger tes ventes
en langage naturel : « où en sont les ventes de ce soir ? », « quel est mon CA
net ? », « combien de filles/gars ? ».

### 🛠️ Outils exposés

| Outil | Description |
| --- | --- |
| `list_events` | Événements `active` (à venir / en cours), `past` (terminés) ou `all` |
| `event_report` | Rapport de ventes complet d'un événement (accepte un **id, slug ou nom**) |
| `dashboard` | Vue agrégée de tous les événements actifs (ventes, CA, CA net, restants) |

### 📊 `event_report` renvoie

- **Ventes** : vendus, valides, **scannés** (détectés via `ticket_scanned_at`), annulés, restants, taux de remplissage
- **Revenu** : brut, frais Shotgun, **net**, **remboursement potentiel ce soir** (payés non scannés)
- **Rythme** : ventes sur la dernière heure / 24 h
- **Tarifs** : vendus **/ quota** par type de billet, avec statut sold-out
- **Audience** (agrégée) : répartition filles/gars, top villes

> ⚠️ Aucune donnée personnelle n'est renvoyée — tout est agrégé (compteurs, pourcentages).

## 🚀 Installation

```bash
python3 -m venv venv
./venv/bin/pip install -r requirements.txt
cp .env.example .env   # puis renseigne tes identifiants
```

### Configuration (`.env`)

```env
SHOTGUN_TOKEN=ton_token_shotgun
SHOTGUN_ORGANIZER_ID=ton_id_organisateur
# Jeton d'authentification exigé des clients (Authorization: Bearer <token>)
MCP_AUTH_TOKEN=un_secret_long_et_aleatoire
MCP_HOST=127.0.0.1
MCP_PORT=8790
# Hôte public derrière le reverse proxy (anti-DNS-rebinding)
MCP_PUBLIC_HOST=shotgun-mcp.exemple.tld
```

Où trouver le `SHOTGUN_TOKEN` / `SHOTGUN_ORGANIZER_ID` : dans ton
[dashboard organisateur](https://organizer.shotgun.live) → intégration > API.

## ▶️ Lancer

```bash
./venv/bin/python server.py
# → http://127.0.0.1:8790/mcp
```

En production (PM2) :

```bash
pm2 start ecosystem.config.js
pm2 save
```

## 🌐 Exposition HTTPS (reverse proxy)

Le serveur écoute en local ; place un reverse proxy HTTPS devant (nginx/Caddy).
Points importants pour le transport **SSE** du MCP :

```nginx
location / {
    proxy_pass http://127.0.0.1:8790;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_buffering off;          # SSE : pas de buffering
    proxy_read_timeout 3600s;     # connexions longues
    chunked_transfer_encoding on;
}
```

Renseigne l'hôte public dans `MCP_PUBLIC_HOST` (sinon la protection
anti-DNS-rebinding du MCP rejette les requêtes proxifiées).

## 🔌 Ajouter le connecteur

Endpoint : `https://<ton-hôte>/mcp`
En-tête d'authentification : `Authorization: Bearer <MCP_AUTH_TOKEN>`

## 🔒 Sécurité

- **Auth par jeton** : si `MCP_AUTH_TOKEN` est défini, toute requête sans le bon
  `Authorization: Bearer` reçoit `401`. Laisse-le vide **uniquement** en local.
- **Anti-DNS-rebinding** : seuls les hôtes listés (`MCP_PUBLIC_HOST` + localhost)
  sont acceptés.
- Les secrets vivent dans `.env` (non versionné). Aucune donnée personnelle des
  acheteurs n'est exposée.

## 🧱 Structure

```
shotgun-mcp/
├── server.py           # Serveur MCP (outils + auth + app HTTP)
├── shotgun_client.py   # Client async de l'API Shotgun (agrégation des stats)
├── requirements.txt
├── .env.example
├── ecosystem.config.js # PM2
└── README.md
```

---

## ⚠️ Avertissement / Mentions légales

Projet **personnel et non officiel**, **en aucun cas affilié, associé, autorisé
ni soutenu par Shotgun** (Shotgun Live SAS). « Shotgun », le logo et les marques
associées sont la propriété exclusive de leurs détenteurs respectifs, utilisés
ici à des fins d'identification uniquement. Tu es responsable du respect des
conditions d'utilisation de Shotgun. Utilisation à tes risques, sans garantie.

## 📄 Licence

[MIT](LICENSE).