@agifyai/leadify-mcp 8.7.3 → 8.7.5

package/README.md

@@ -229,9 +229,9 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `test_api_key` | Vérifier que la clé API configurée est valide (health check). |
 | `list_lead_groups` | Lister les groupes accessibles d'une organisation explicitement sélectionnée, en vue compacte. |
 | `get_lead_group` | Consulter les métadonnées compactes d'un groupe accessible par son ID. |
-| `create_lead_group` | Créer un groupe et choisir son type canonique optionnel (`GENERIC`, `COMPANY` ou `PERSON`) via `entity_kind`. |
-| `update_lead_group` | Modifier un groupe, y compris son `entity_kind`, avec réconciliation du schéma côté Leadify. |
-| `add_leads` | Ajouter un ou plusieurs leads à un groupe. |
+| `create_lead_group` | Créer un groupe, choisir son type canonique optionnel et rattacher atomiquement `persona_id` avec l’`offer_id` ACTIVE du même tenant. |
+| `update_lead_group` | Modifier un groupe avec réconciliation du schéma ; lorsque le serveur exige un contexte complet, transmettre ensemble `persona_id` et `offer_id` sans inférer l’offre. |
+| `add_leads` | Import plat générique vers un groupe : ne crée aucune relation d’emploi, aucun rattachement parent ni identité canonique. Ne jamais l’utiliser pour rattacher une Personne à une Company (voir `upsert_person_leads_with_employment`). |
 | `upsert_person_leads_with_employment` | Créer ou réconcilier atomiquement des Person Leads, PERSON, EMPLOYED_BY, projections et historique, sans effet commercial. |
 | `create_person_employment_evidence` / `get_person_employment_evidence` | Créer puis relire une preuve d’emploi individuelle tenant-scopée ; transmettre l’`evidence.id` retourné tel quel à l’upsert Person. |
 | `get_leads` | Rechercher et lister des leads avec filtres, recherche et pagination, dont le critère composé `event_filter`. |
@@ -325,6 +325,51 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `set_fine_tuning_output_config` | Remplacer uniquement la configuration métier de sorties d’un Fine Tuning (`linkedinConnection`, `linkedinMessage`, `email`, activations et quantités). Préserve Markdown, langues et fallback ; ne génère, ne planifie, n’active ni n’envoie aucun outreach. |
 | `pipeline_next_lead` | Sélectionner le prochain lead à traiter (score descendant, sans message). Exclusion des IDs déjà vus, limit 1-5. |
 
-### `source-icp-prospects` : preuve d’emploi
-
-Pour chaque candidat accepté, créer `create_person_employment_evidence` avec le tenant, la Company Lead, l’identité Person, la provenance et une clé idempotente. Relire si nécessaire avec `get_person_employment_evidence`, puis transmettre exclusivement l’`evidence.id` retourné dans `evidence_ids` de `upsert_person_leads_with_employment`.
+### `source-icp-prospects` : sourcing Personne rattachée à une Company
+
+`add_leads` est un import générique de leads plats et ne garantit aucune
+relation d’emploi : une Personne sourcée pour une entreprise doit toujours
+passer par `upsert_person_leads_with_employment`, seul chemin d’écriture
+Person admis pour le sourcing. Ce tool crée ou réutilise la Person Lead et la
+Person, crée ou réutilise une relation active `EMPLOYED_BY` vers la cible
+légale de la Company (Legal Entity ou Establishment compatible), maintient les
+projections `parent_lead` / `child_leads` consommées par l’interface, écrit
+uniquement les champs admis par le schéma du groupe Personne, ajoute
+l’historique sans écraser l’existant, applique l’idempotence par entrée et
+relit les objets avant de répondre. Chaque entrée est transactionnelle
+(échec = rollback complet de l’entrée) ; un batch peut mêler succès et échecs
+par entrée mais ne rend jamais un succès ambigu.
+
+Chaîne obligatoire, dans l’ordre :
+
+1. Vérifier l’identité canonique de la Company Lead. Si elle n’expose ni
+   Account ni Legal Entity / Establishment compatible, la préparer d’abord
+   avec `preview_canonical_identity_backfill` puis
+   `apply_canonical_identity_backfill` en rejouant exactement le digest
+   prévisualisé. Toute contradiction d’identité bloque proprement : jamais de
+   rapprochement au nom approximatif.
+2. Pour chaque candidat accepté, créer `create_person_employment_evidence`
+   avec le tenant, la Company Lead exacte, l’identité Person, la provenance
+   et une clé idempotente. Relire si nécessaire avec
+   `get_person_employment_evidence`, puis transmettre exclusivement
+   l’`evidence.id` retourné dans `evidence_ids` de
+   `upsert_person_leads_with_employment`.
+3. Appeler `upsert_person_leads_with_employment` avec les IDs exacts
+   (`organization_id`, `person_group_id`, `company_lead_id` identiques au
+   même tenant), les seuls champs admis par le schéma Personne,
+   `card_history_append`, et une `idempotency_key` unique par entrée.
+   Pour réparer une Person Lead orpheline exacte sans doublon, passer son
+   `person_lead_id` : la réparation suit la même transaction et les mêmes
+   contrôles, et préserve LinkedIn, sources, `card_history`,
+   `qualification_status`, `hide_from_campaign` et les champs sans lien avec
+   la relation.
+4. Vérifier dans les deux sens avant de considérer la Personne rattachée :
+   `get_lead` sur la Personne (parent résolvable) et
+   `list_canonical_relationships` filtré sur la Person puis sur la cible
+   légale (lien `EMPLOYED_BY` actif). Une relation ou projection manquante
+   est un échec explicite, jamais un succès partiel.
+
+Aucune mutation de sourcing ne qualifie le lead, n’enrichit les contacts
+(email/téléphone), ne génère de message, n’inscrit en campagne et n’active
+aucun canal externe : le readback porte `noSend: true` et
+`externalActivation: 0`.

package/dist/tools/lead_groups.js

@@ -48,6 +48,11 @@ export function registerLeadGroupTools(server, writeClient) {
             .optional()
             .describe("ICP persona ID to assign. Must belong to the same org or be global. " +
             "Omit to create the group without a persona."),
+        offer_id: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Active offer ID to assign with persona_id. Must belong to the same organization."),
     }, async (params) => {
         try {
             const body = {
@@ -66,6 +71,8 @@ export function registerLeadGroupTools(server, writeClient) {
                 body.disabledTools = params.disabled_tools;
             if (params.persona_id !== undefined)
                 body.personaId = params.persona_id;
+            if (params.offer_id !== undefined)
+                body.offerId = params.offer_id;
             const data = await (writeClient ?? getClient()).post("/api/lead-group", body);
             return toolResult(data);
         }
@@ -91,6 +98,11 @@ export function registerLeadGroupTools(server, writeClient) {
             .nullable()
             .optional()
             .describe("New ICP persona ID. Pass null to unassign. Must belong to the same org or be global."),
+        offer_id: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Active offer ID to assign with persona_id. Pass null only when removing the binding."),
         persona_types: z
             .array(z.string())
             .optional()
@@ -116,6 +128,8 @@ export function registerLeadGroupTools(server, writeClient) {
                 body.entityKind = params.entity_kind;
             if (params.persona_id !== undefined)
                 body.personaId = params.persona_id;
+            if (params.offer_id !== undefined)
+                body.offerId = params.offer_id;
             if (params.persona_types !== undefined)
                 body.personaTypes = params.persona_types;
             if (params.company_profile !== undefined)

package/dist/tools/leads.js

@@ -116,7 +116,11 @@ export function registerLeadTools(server, client = getClient()) {
         });
     }
     // ── add_leads ──────────────────────────────────────────────────────────
-    server.tool("add_leads", "Add one or more leads to a specific lead group in Leadify. Provide the group ID " +
+    server.tool("add_leads", "Flat generic lead import only: add one or more leads to a specific lead group in Leadify. " +
+        "It stores plain field values and guarantees NO employment relationship, NO parent link and NO canonical identity. " +
+        "It must never be used to attach a Person to a Company: Person sourcing attached to a Company must use " +
+        "upsert_person_leads_with_employment (after create_person_employment_evidence, and preview_canonical_identity_backfill plus " +
+        "apply_canonical_identity_backfill when the Company lacks canonical identity). Provide the group ID " +
         "and an array of lead objects with any combination of fields (email, firstName, " +
         "lastName, company, jobTitle, phone, custom fields, card_* fields, percent_* " +
         "fields, etc.). Canonical relation fields are read-only here: use " +
@@ -130,7 +134,8 @@ export function registerLeadTools(server, client = getClient()) {
             .array(leadInputSchema)
             .describe("Array of lead objects. Each object is a key-value map of field names to values. " +
             "Common fields: email, firstName, lastName, company, jobTitle, phone, linkedin, " +
-            "website, seniority, specialty, age. location must be {city, region?, postalCode?, countryCode, street?}; geo is computed by Leadify. Also supports card_* fields, " +
+            "website, seniority, specialty, age. The company field is flat display text only and never creates an employment relationship or parent link. " +
+            "location must be {city, region?, postalCode?, countryCode, street?}; geo is computed by Leadify. Also supports card_* fields, " +
             "percent_* fields and boolean flags (decisionMaking, excluded). Canonical relation fields are rejected."),
         is_select_fields: z
             .array(z.string())

package/dist/tools/person_employment.js

@@ -44,7 +44,7 @@ export function registerPersonEmploymentTools(server, client = getClient()) {
             return handleToolError(error);
         }
     });
-    server.tool("upsert_person_leads_with_employment", "Atomically create or reconcile Person Leads with their canonical PERSON identity, EMPLOYED_BY relationship, parent_lead/child_leads projections, evidence and append-only card_history. company_lead_id must be exact and already project an Account plus Legal Entity or compatible Establishment. Each batch entry is independently transactional and idempotent. This is the only supported Person write path for sourcing; never fall back to add_leads, canonical backfill, or separate relationship writes. It never qualifies, enriches contact details, sends outreach, creates campaigns, or activates anything.", {
+    server.tool("upsert_person_leads_with_employment", "Atomically create or reconcile Person Leads with their canonical PERSON identity, an active EMPLOYED_BY relationship to the Company legal target, parent_lead/child_leads projections, evidence and append-only card_history. company_lead_id must be exact and already project an Account plus Legal Entity or compatible Establishment: when it does not, prepare it first with preview_canonical_identity_backfill then apply_canonical_identity_backfill using the returned digest, and never fuzzy-match identity. Pass person_lead_id to repair one exact orphan Person Lead without creating a duplicate; otherwise a new Person Lead is created. fields must only contain keys admitted by the Person group schema and are forwarded verbatim so the backend rejects unknown keys; history is append-only via card_history_append and existing card_history is never overwritten. Each batch entry is independently transactional (a failure rolls that entry back entirely) and idempotent by idempotency_key; a changed payload under the same key is rejected, never merged. The success readback carries personLeadId, personId, companyLeadId, legalTarget, relationshipId, relationship, projections, cardHistory, noSend and externalActivation: verify the EMPLOYED_BY link in both directions (get_lead plus list_canonical_relationships) before treating the Person as attached. This is the only supported Person write path for sourcing; never fall back to add_leads, direct canonical backfill writes, or separate relationship writes. It never creates emails or phones, never qualifies the lead, never generates messages, never enrolls in a campaign and never activates any external channel.", {
         people: z.array(z.object({
             organization_id: z.string().trim().min(1),
             person_group_id: z.string().trim().min(1),
@@ -52,7 +52,7 @@ export function registerPersonEmploymentTools(server, client = getClient()) {
             person_lead_id: z.string().trim().min(1).optional(),
             fields: z.record(z.unknown()),
             card_history_append: z.string().trim().min(1).max(100_000),
-            evidence_ids: z.array(z.string().trim().min(1)).min(1).max(100),
+            evidence_ids: z.array(z.string().trim().min(1)).min(1).max(100).optional(),
             idempotency_key: z.string().trim().min(1).max(220),
         }).strict()).min(1).max(100),
     }, async ({ people }) => {
@@ -65,7 +65,7 @@ export function registerPersonEmploymentTools(server, client = getClient()) {
                     personLeadId: person.person_lead_id,
                     fields: person.fields,
                     cardHistoryAppend: person.card_history_append,
-                    evidenceIds: person.evidence_ids,
+                    ...(person.evidence_ids !== undefined ? { evidenceIds: person.evidence_ids } : {}),
                     idempotencyKey: person.idempotency_key,
                 })),
             }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agifyai/leadify-mcp",
-  "version": "8.7.3",
+  "version": "8.7.5",
   "description": "MCP server for Leadify lead management API",
   "type": "module",
   "main": "dist/index.js",