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
• Installation rapide (sans cloner, via npx)
• Installation en clonant le dépôt
• Outils exposés
• Sécurité
• 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

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 :

{
  "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.

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) :

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
• Spec OpenAPI officielle (partielle) : reference/corymbus-swagger.yaml

Licence

MIT.