Leadify MCP Server

Serveur MCP (Model Context Protocol) pour l'API Leadify. Expose les endpoints REST de Leadify sous forme de tools utilisables depuis Claude Desktop, Claude Code, Cursor ou tout client compatible MCP.

Package npm : @agifyai/leadify-mcp

📦 Pour les utilisateurs

Aucun clone, aucun build. npx télécharge la dernière version à chaque démarrage de session MCP.

Pré-requis

• Node.js ≥ 18 (node --version pour vérifier)
• Une clé API Leadify (demander à l'équipe ou la générer dans l'app)

Claude Code

claude mcp add leadify -e LEADIFY_API_KEY=votre-clé-api -- npx -y @agifyai/leadify-mcp@latest

Le -- est nécessaire pour que claude mcp add ne tente pas d'interpréter le -y de npx comme une de ses propres options.

Vérifier que c'est bien branché :

claude mcp list

Tu dois voir leadify dans la liste. Dans une session Claude Code, demande "appelle test_api_key" pour valider.

Claude Desktop

Ouvrir le fichier de configuration :

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows : %APPDATA%\Claude\claude_desktop_config.json

Ajouter une entrée leadify dans mcpServers :

{
  "mcpServers": {
    "leadify": {
      "command": "npx",
      "args": ["-y", "@agifyai/leadify-mcp@latest"],
      "env": {
        "LEADIFY_API_KEY": "votre-clé-api"
      }
    }
  }
}

Redémarrer Claude Desktop. Les tools Leadify apparaissent (icône marteau dans la zone de saisie).

Mise à jour automatique

Le tag @latest force npx à vérifier la dernière version publiée à chaque lancement de session. Quand un nouveau tool est mergé sur main et publié, il est dispo dès la session suivante — sans git pull, sans rebuild, sans rien.

Pour forcer un rafraîchissement immédiat sans attendre le cache npm :

npm cache clean --force

Dépannage

| Symptôme | Cause / solution | |---|---| | LEADIFY_API_KEY environment variable is required | La clé n'est pas passée. Vérifier le -e (Claude Code) ou le bloc env (Claude Desktop). | | 401 Unauthorized sur tous les tools | Clé API invalide ou révoquée. Tester avec test_api_key. | | Le serveur ne démarre pas | Vérifier que npx -y @agifyai/leadify-mcp@latest tourne en standalone. Si erreur réseau, vérifier l'accès à registry.npmjs.org. | | Tool ajouté côté équipe mais pas visible chez moi | Quitter complètement le client (Claude Desktop : ⌘Q ; Claude Code : ferme la session) et relancer. |

🛠️ Pour les contributeurs

Setup local

git clone [email protected]:AgifyAI/mcp_leadify.git
cd mcp_leadify
npm install
npm run build

Brancher Claude Code sur ta build locale (en plus de la version npm si tu veux comparer) :

claude mcp add leadify-dev -e LEADIFY_API_KEY=votre-clé-api -- node /chemin/absolu/vers/mcp_leadify/dist/index.js

Mode watch :

npm run dev

Architecture

src/
├── index.ts          # entrée stdio (shebang + transport)
├── server.ts         # création du McpServer + register* de chaque module
├── client.ts         # LeadifyClient (singleton, lit LEADIFY_API_KEY)
├── types.ts          # toolResult, handleToolError, LeadifyApiError
└── tools/
    ├── auth.ts
    ├── leads.ts
    ├── campaigns.ts
    ├── dataroom.ts
    ├── personas.ts
    └── ...           # un fichier = un domaine fonctionnel

Un tool = un appel à server.tool(name, description, zodSchema, async handler). Voir src/tools/auth.ts pour le plus simple.

Ajouter un tool

1. Coder le tool dans le fichier de domaine pertinent (src/tools/<domaine>.ts), ou créer un nouveau fichier.
2. Si nouveau fichier : exporter registerXxxTools(server) et l'appeler depuis src/server.ts.
3. Vérifier que ça compile :

   npm run build

4. Tester en local (cf. setup ci-dessus).
5. Bumper la version et publier (cf. section suivante).

Publier une nouvelle version

Le publish est automatique via GitHub Actions sur push main. Le workflow ne fait rien si la version dans package.json n'a pas bougé — il faut donc bumper avant de push.

npm version patch    # 1.4.2 → 1.4.3 (bug fix, ajout de tool)
npm version minor    # 1.4.2 → 1.5.0 (changement non-breaking notable)
npm version major    # 1.4.2 → 2.0.0 (breaking : tool renommé / supprimé / signature changée)
git push && git push --tags

npm version crée un commit + un tag git automatiquement.

Vérifier la publication :

npm view @agifyai/leadify-mcp version

Et le run du workflow : https://github.com/AgifyAI/mcp_leadify/actions

Comment marche la CI

.github/workflows/publish.yml se déclenche sur push main :

1. Checkout + install Node 20.
2. npm ci pour installer les deps.
3. Check si la version actuelle de package.json est déjà publiée sur npm. Si oui, skip silencieusement (on évite les doublons et on permet de push des commits non-version sur main).
4. Sinon, upgrade npm vers ≥ 11.5.1 (requis pour Trusted Publishing) puis npm publish.

L'authentification npm passe par Trusted Publishing (OIDC) : pas de token stocké, GitHub Actions s'authentifie directement auprès de npm via la permission id-token: write du workflow. La trust relation est configurée sur la page npm du package (Trusted Publisher : AgifyAI/mcp_leadify / publish.yml).

Conséquences pratiques :

• Pas de secret NPM_TOKEN à rotater.
• Le workflow ne peut publier que depuis ce repo + ce fichier de workflow exact. Renommer publish.yml casse la trust → mettre à jour côté npm si besoin.

Conventions

• Versionning : suivre semver. Ajout de tool = patch (rétrocompatible). Renommage / suppression / signature breaking = major.
• Description des tools : verbeuse et précise — c'est ce que le modèle lit pour décider d'utiliser le tool. Voir les tools outreach_* pour des exemples détaillés.
• Erreurs : toujours wrapper le handler dans try / catch et retourner handleToolError(error) en cas d'échec — ça normalise les erreurs API en réponse MCP propre.

Tools disponibles

| Tool | Description | |------|-------------| | test_api_key | Vérifier que la clé API configurée est valide (health check). | | add_leads | Ajouter un ou plusieurs leads à un groupe. | | get_leads | Rechercher et lister des leads avec filtres, recherche et pagination. | | get_lead | Récupérer les détails complets d'un lead par son ID. | | update_lead | Mettre à jour un ou plusieurs champs d'un lead existant. | | delete_leads | Supprimer définitivement des leads par leurs IDs. | | update_schema | Ajouter ou modifier les définitions de champs d'un groupe. | | delete_columns | Supprimer des colonnes du schéma et des données d'un groupe. | | update_hidden_columns | Afficher ou masquer des colonnes dans la vue tableau (réversible). | | add_campaign_log | Enregistrer une entrée de log de campagne pour un lead. | | get_campaign_logs | Récupérer les logs de campagne avec filtres et pagination. | | delete_campaign_log | Supprimer une entrée de log de campagne. | | update_campaign_stats | Mettre à jour les statistiques d'email d'une campagne pour un groupe de leads. | | create_campaign | Créer une nouvelle campagne rattachée à un groupe de leads (statut DRAFT). | | get_campaign | Récupérer les détails d'une campagne et ses KPIs temps réel. | | update_campaign_status | Changer le statut d'une campagne (DRAFT, ACTIVE, PAUSED, COMPLETED). | | export_campaign | Exporter les statistiques complètes d'une campagne en CSV. | | signal_upsert | Créer ou mettre à jour un signal de business intelligence (INFO, CRITICAL, GOLDEN). Remet le state à active. | | signal_expire | Expirer un signal (événement périmé). Flip de state uniquement. | | signal_disable | Désactiver un signal (faux positif / écarté manuellement). Flip de state uniquement. | | signal_delete | Supprimer définitivement un signal (cas rare : donnée erronée, doublon). | | add_activity | Journaliser une interaction prospect (LinkedIn, email, call) dans le feed du lead. | | get_data_room | Récupérer la data room complète : infos société (v2), documents, personas. | | describe_company_info_schema | Lire le schéma companyInfo v2 mirroré côté MCP (enums, max-lengths, sections, patch tool par section). À appeler avant la première update. | | update_data_room | Update WHOLESALE (escape hatch) — remplace l'intégralité de companyInfo. Requis pour le bootstrap initial. Préférer les tools granulaires pour l'incrémental. | | update_company_info_identity | Patch name + website. Reads + merges + PUTs le full v2 payload. | | update_company_info_snapshot | Patch du bloc snapshot (pitchOneLiner, marketSpecialty, stage, salesTeamSizeFR, geo, constraints). geo merge shallow. | | update_company_info_constraint | Add / replace / remove une seule contrainte dans snapshot.constraints[]. label + type enum + note≤150. Cap 10. | | update_company_info_product | Add / replace / remove un seul produit dans products[]. category enum strict + regulatory sub-block. Cap 5. | | update_company_info_economics | Patch du bloc economics (pricingModel, ticketRange, salesCycleMonths, triggers, defaultBaseline). | | update_company_info_product_icp | Add / replace / remove un seul ICP dans productICPs[]. Lookup par productId (must match a products[].name). Cap 5. | | update_company_info_proof_wording | Patch du bloc proofWording (keyMetrics, miniStories, forbiddenWords). | | add_data_room_document | Ajouter un document textuel à la data room avec catégorie. | | upsert_persona | Créer ou mettre à jour un persona (ciblage, messaging, outils actifs). | | get_persona | Récupérer un persona par son ID. | | get_lead_group_persona | Récupérer le persona assigné à un groupe de leads. | | list_data_sources | Lister toutes les sources de données configurées (par pays puis nom). | | create_data_source | Créer une nouvelle source de données (admin uniquement). | | update_data_source | Modifier une source de données existante (admin uniquement). | | delete_data_source | Supprimer définitivement une source de données (admin uniquement). | | get_outreach_settings | Récupérer la config outreach d'un lead group (positioning, sequence, rules, URLs, case studies). | | update_outreach_settings | Update full-form (escape hatch) — remplace les blocs JSON entièrement. Préférer les tools granulaires ci-dessous. | | update_outreach_positioning | Patch partiel du positioning (dream / fear / whyNow individuellement). | | update_outreach_sequence_slot | Patch d'un seul slot de séquence (connexion, linkedin.one/two/three, email.one/two/three) sans toucher les autres. | | update_outreach_rules | Patch du bloc rules : forbidden/priority (replace), format.* (deep-merge). | | update_outreach_case_study | Ajouter / remplacer / supprimer un case study par index, sans re-envoyer la liste. | | update_outreach_urls | Patch booking_url et/ou website_url uniquement. | | set_outreach_connection_request | Toggle du flag connectionRequestEnabled (LinkedIn invite vs cold DM). | | trigger_outreach | Générer un message d'outreach via l'agent Trigger.dev (dry-run par défaut). force=true pour re-générer sur un lead déjà traité. | | append_fine_tuning | Appendre du contenu à une section du Fine Tuning (nonNegotiableRules, pitfalls, structure, examples). Toujours en mode append — garantie contractuelle. | | pipeline_next_lead | Sélectionner le prochain lead à traiter (score descendant, sans message). Exclusion des IDs déjà vus, limit 1-5. |