# corymbus-mcp

Serveur **MCP** (Model Context Protocol) non officiel pour le CRM **Corymbus**.
Interrogez et modifiez vos données Corymbus en langage naturel depuis n'importe
quel client MCP : **Claude Code**, **Claude Desktop / Cowork**, ou tout autre hôte.

> Projet communautaire, indépendant de l'éditeur de Corymbus. Fourni tel quel, sous licence MIT.
> Vous utilisez **vos propres identifiants** ; aucun secret n'est inclus dans ce dépôt.

---

## Sommaire

- [Prérequis](#prérequis)
- [Installation rapide (sans cloner, via npx)](#installation-rapide-sans-cloner-via-npx)
- [Installation en clonant le dépôt](#installation-en-clonant-le-dépôt)
- [Outils exposés](#outils-exposés)
- [Sécurité](#sécurité)
- [Documentation API](#documentation-api)

## Prérequis

- **Node.js ≥ 18** (utilise `fetch` natif). Vérifier : `node --version`.
- Un compte **Corymbus** (email + mot de passe).

---

## Installation rapide (sans cloner, via npx)

C'est la méthode recommandée : le client MCP lance le serveur directement depuis
GitHub, en passant vos identifiants par la section `env`. Rien à cloner.

### Claude Code

```bash
claude mcp add corymbus \
  -e CORYMBUS_EMAIL=email@domaine.com \
  -e CORYMBUS_PASSWORD=votre-mot-de-passe \
  -- npx -y github:laSonde/corymbus-mcp
```

### Claude Desktop / Cowork (ou tout hôte à config JSON)

Dans le fichier de configuration MCP du client :

```json
{
  "mcpServers": {
    "corymbus": {
      "command": "npx",
      "args": ["-y", "github:laSonde/corymbus-mcp"],
      "env": {
        "CORYMBUS_EMAIL": "email@domaine.com",
        "CORYMBUS_PASSWORD": "votre-mot-de-passe"
      }
    }
  }
}
```

Redémarrez le client : les outils `corymbus_*` apparaissent alors.

> 💡 npx télécharge et met en cache le dépôt au premier lancement. Pour forcer une
> mise à jour ultérieure : `npx -y github:laSonde/corymbus-mcp@main` (ou videz le cache npx).

---

## Installation en clonant le dépôt

Utile pour développer, modifier les outils, ou épingler une version.

```bash
git clone https://github.com/laSonde/corymbus-mcp.git
cd corymbus-mcp
npm install
cp .env.example .env      # puis renseignez CORYMBUS_EMAIL / CORYMBUS_PASSWORD
node scripts/smoke-test.js   # test rapide (version, whoami, quelques listes)
```

Enregistrement (le serveur lira le `.env` du dossier) :

```bash
claude mcp add corymbus -- node "/chemin/absolu/vers/corymbus-mcp/src/index.js"
```

Le client gère seul le **login** puis le **refresh** des tokens JWT. Les tokens
sont mis en cache dans `~/.corymbus-mcp/tokens.json` (permissions 600).

> 🔒 `.env` et tokens sont ignorés par git (voir `.gitignore`) — ne les committez jamais.

---

## Outils exposés

### Lecture
| Outil | Rôle |
|---|---|
| `corymbus_whoami` | Utilisateur authentifié |
| `corymbus_version` | Version du serveur |
| `corymbus_activity_types` | Énumération des types d'activité |
| `corymbus_list_accounts` | Comptes (filtres : nameContains, owner, activity) |
| `corymbus_list_contacts` | Contacts (account, opportunity, target, owner…) |
| `corymbus_list_opportunities` | Opportunités (account, contact, période de clôture…) |
| `corymbus_list_activities` | Activités (type, owner, account, contact, opportunity) |
| `corymbus_list` | Entités secondaires : campaign, target, user, subscription, filter, team, document, product, quote |

### Écriture *(déclenche une confirmation côté client MCP)*
| Outil | Rôle |
|---|---|
| `corymbus_upsert_contact` | Créer / mettre à jour un contact |
| `corymbus_upsert_account` | Créer / mettre à jour un compte |
| `corymbus_upsert_opportunity` | Créer / mettre à jour une opportunité |
| `corymbus_upsert_activity` | Créer / mettre à jour une activité |
| `corymbus_raw_request` | Appel brut (endpoints non couverts) |

Toutes les listes acceptent `size` (défaut 25, max 1000), `page` (dès 0),
`order_field` et `order_direction`. Les `upsert` acceptent un objet `extra_fields`
pour les champs personnalisés propres à votre tenant.

### Exemples en langage naturel
- « Combien de comptes contiennent "solaris" dans leur nom ? »
- « Montre-moi les 10 dernières activités de type e-mail. »
- « Liste les opportunités dont la clôture est prévue ce trimestre. »
- « Crée une tâche de relance pour le contact 12345 la semaine prochaine. »

---

## Sécurité

- Les écritures s'appliquent à un CRM de **production** : chaque `upsert_*` et
  `raw_request` déclenche une demande de permission côté client MCP.
- Vos identifiants ne quittent jamais votre machine : ils vivent dans votre `.env`
  local ou dans la section `env` de la config de votre client MCP.
- Ne committez jamais votre `.env` ni le cache de tokens.

## Documentation API

- Notes d'intégration : [`docs/API-Corymbus.md`](docs/API-Corymbus.md)
- Spec OpenAPI officielle (partielle) : [`reference/corymbus-swagger.yaml`](reference/corymbus-swagger.yaml)

## Licence

[MIT](LICENSE).