@agifyai/leadify-mcp 8.7.4 → 8.7.6

package/README.md

@@ -231,7 +231,7 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `get_lead_group` | Consulter les métadonnées compactes d'un groupe accessible par son ID. |
 | `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` | Ajouter un ou plusieurs leads à un groupe. |
+| `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,46 @@ 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` crée les identités minimales des fiches typées, mais aucun emploi.
+Pour sourcer une personne liée à une entreprise, utiliser
+`upsert_person_leads_with_employment` : il crée ou réutilise la Personne et
+son emploi vers l’Account exact, conserve les preuves et ajoute l’historique.
+Chaque entrée est enregistrée entièrement ou annulée. Aucun numéro légal ni
+préparation juridique de l’entreprise n’est obligatoire.
+
+1. Choisir l’organisation, les groupes et la fiche entreprise exacts.
+2. Créer la preuve avec `create_person_employment_evidence`, en conservant
+   ses dates originales. Transmettre son identifiant dans `evidence_ids`.
+3. Appeler `upsert_person_leads_with_employment` avec les champs admis par
+   le groupe, l’historique à ajouter et une clé de répétition unique.
+   `person_lead_id` permet de réconcilier une fiche existante précise.
+4. Relire les deux fiches avec `get_person_employments` et vérifier le même
+   identifiant d’emploi. Les anciens champs `parent_lead` et `child_leads`
+   ne sont plus écrits ni utilisés pour déterminer le lien.
+
+`get_lead` et `get_leads` conservent `canonicalIdentity` et
+`personAccountRelationships`, indépendamment des champs CRM demandés.
+Tous les emplois restent accessibles, avec leurs dates et leur confiance.
+Une confiance inconnue ne signifie pas une absence de lien. L’entreprise
+utilisée pour une qualification doit être choisie explicitement.
+
+Pour modifier un emploi existant, utiliser `manage_person_employment` :
+`attach` ajoute sans fermer les autres emplois ; `end` termine une période ;
+`invalidate` conserve la trace d’un lien erroné ; `replace` remplace seulement
+la relation désignée ; `evidence` actualise ses preuves et sa confiance.
+Les modifications exigent `expected_version`, relu avec
+`get_person_employments`, et une `idempotency_key` dont le contenu ne change
+pas lors d’une répétition. Les droits administrateur de l’organisation sont
+vérifiés par le serveur.
+
+Les preuves détaillées se lisent à la demande avec
+`get_person_employment_evidence_page`, pour une personne, un groupe et un
+emploi précis. Suivre `page.nextCursor` tant que `page.hasMore` vaut `true`.
+Les dates originales sont conservées ; la pagination n’efface aucune preuve.
+
+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/server.js

@@ -20,6 +20,7 @@ import { registerCommercialTruthTools } from "./tools/commercial_truth.js";
 import { registerEventTools } from "./tools/events.js";
 import { registerContextEntityTools } from "./tools/context_entities.js";
 import { registerPersonEmploymentTools } from "./tools/person_employment.js";
+import { registerPersonAccountTools } from "./tools/person_account.js";
 import { registerClaimContradictionTools } from "./tools/claim_contradictions.js";
 import { MCP_SERVER_NAME, MCP_VERSION } from "./version.js";
 export function createServer() {
@@ -36,6 +37,7 @@ export function createServer() {
     registerCanonicalBackfillTools(server);
     registerClaimContradictionTools(server);
     registerPersonEmploymentTools(server);
+    registerPersonAccountTools(server);
     registerEventTools(server);
     registerCommercialTruthTools(server);
     registerSchemaTools(server);

package/dist/tools/leads.js

@@ -80,6 +80,11 @@ function projectLead(lead, fields) {
     for (const field of fields)
         if (data[field] !== undefined)
             projected[field] = data[field];
+    // Relationship metadata belongs to the server contract, not selectable CRM fields.
+    for (const key of ["canonicalIdentity", "personAccountRelationships"]) {
+        if (source[key] !== undefined)
+            projected[key] = source[key];
+    }
     return projected;
 }
 function compactLeadsResponse(data, fields, includeSchema) {
@@ -116,11 +121,15 @@ 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 creates each typed lead with its minimal Person or Account identity, but creates no employment relationship. " +
+        "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; no legal identity backfill is required). " +
+        "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 " +
-        "create_canonical_relationship or the migration tools instead. Optionally specify which fields should be " +
+        "manage_person_employment for employment links instead. Optionally specify which fields should be " +
         "treated as 'select' dropdowns in the UI. Returns the count of successfully " +
         "imported leads and any errors. Use this for both bulk imports and single lead creation.", {
         lead_group_id: z
@@ -130,7 +139,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())
@@ -260,7 +270,7 @@ export function registerLeadTools(server, client = getClient()) {
         "name, new value, and optionally whether the field is a 'select' dropdown type. " +
         "Supports all field types including special fields (card_*, percent_*, boolean flags " +
         "like decisionMaking/excluded). When a configured canonical relation field is changed, " +
-        "the backend routes it through the typed relationship service and keeps the JSON field read-only. Returns the updated lead. " +
+        "employment fields are refused: use manage_person_employment. Other relationship types retain their own service. Returns the updated lead. " +
         "location must be the canonical object {city, region?, postalCode?, countryCode, street?}; never submit geo. " +
         "For bulk updates across many leads, call this tool once per lead.", {
         lead_id: z.string().describe("ID of the lead to update."),

package/dist/tools/person_account.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPersonAccountTools(server: McpServer, client?: import("../client.js").LeadifyClient): void;

package/dist/tools/person_account.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { handleToolError, toolResult } from "../types.js";
+const id = z.string().trim().min(1);
+const instant = z.string().datetime({ offset: true });
+const trust = z.enum(["CONFIRMED", "PROPOSED", "AMBIGUOUS", "CONFLICTED", "UNKNOWN"]);
+const existing = { relationship_id: id, expected_version: z.number().int().positive() };
+const link = { person_lead_id: id, company_lead_id: id, trust_state: trust.optional(),
+    evidence_ids: z.array(id).max(100).optional(), role_title: id.nullable().optional() };
+const command = z.discriminatedUnion("operation", [
+    z.object({ operation: z.literal("attach"), ...link, valid_from: instant.nullable().optional() }).strict(),
+    z.object({ operation: z.literal("end"), ...existing, ended_at: instant }).strict(),
+    z.object({ operation: z.literal("invalidate"), ...existing, reason: id }).strict(),
+    z.object({ operation: z.literal("evidence"), ...existing, evidence_ids: z.array(id).min(1).max(100), trust_state: trust }).strict(),
+    z.object({ operation: z.literal("replace"), ...existing, ...link, effective_at: instant }).strict(),
+]);
+const commandKeys = {
+    operation: "operation", relationship_id: "relationshipId", expected_version: "expectedVersion",
+    person_lead_id: "personLeadId", company_lead_id: "companyLeadId", trust_state: "trustState",
+    evidence_ids: "evidenceIds", role_title: "roleTitle", valid_from: "validFrom", ended_at: "endedAt",
+    reason: "reason", effective_at: "effectiveAt",
+};
+export function registerPersonAccountTools(server, client = getClient()) {
+    server.tool("get_person_employments", "Read all employment periods for one exact Person or Company lead in its organization, including historical and invalidated links. Both directions use the same Person Account registry. Preserve trust and dates; UNKNOWN or stale evidence does not erase a link. Read relationship version before updating it; never choose the first employer implicitly.", { organization_id: id, lead_id: id }, async ({ organization_id, lead_id }) => {
+        try {
+            return toolResult(await client.get(`/api/person-employment/links/${encodeURIComponent(lead_id)}`, new URLSearchParams({ organizationId: organization_id })));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("manage_person_employment", "Attach, end, invalidate, replace one exact employment, or update its evidence through the shared Person Account command. Requires organization admin access. Minimal Person and Account identities are ensured without SIREN or legal identity prerequisites. attach preserves other jobs; replace ends only the named relationship and preserves other simultaneous jobs. end preserves history; invalidate records an erroneous link and cannot be automatically reversed. Existing links require their latest expected_version from get_person_employments. Retries require the same idempotency key and unchanged payload. This never sends messages, qualifies a lead or activates a campaign.", { organization_id: id, idempotency_key: id.max(180), command }, async ({ organization_id, idempotency_key, command: input }) => {
+        try {
+            const checked = command.parse(input);
+            const body = Object.fromEntries(Object.entries(checked).map(([key, value]) => [commandKeys[key], value]));
+            return toolResult(await client.post("/api/person-employment/command", {
+                organizationId: organization_id, idempotencyKey: idempotency_key, ...body,
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("get_person_employment_evidence_page", "Read detailed evidence on demand for one employment belonging to the exact Person lead, group and organization. Follow page.nextCursor while page.hasMore is true. Original observation and collection dates are preserved; an empty page is not a claim that another employment has no evidence.", { organization_id: id.max(200), lead_id: id.max(200), lead_group_id: id.max(200), relationship_id: id.max(200),
+        cursor: id.max(200).optional(), limit: z.number().int().min(1).max(5).optional().default(5) }, async ({ organization_id, lead_id, lead_group_id, relationship_id, cursor, limit }) => {
+        try {
+            return toolResult(await client.post("/api/qualify-lead/employment-evidence", {
+                organizationId: organization_id, leadId: lead_id, leadGroupId: lead_group_id,
+                relationshipId: relationship_id, cursor, limit,
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

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 minimal PERSON identity and an active EMPLOYED_BY relationship to the exact Company ACCOUNT, evidence and append-only card_history. company_lead_id must identify an existing Company lead in the same organization; no legal identity, SIREN or prior backfill is required. Never fuzzy-match identity. Pass person_lead_id to reconcile one exact existing Person Lead without creating a duplicate. fields must only contain keys admitted by the Person group schema; card_history_append preserves existing history. Each entry is independently transactional and idempotent by idempotency_key; changed payloads under the same key are refused. Other simultaneous jobs are preserved. Verify the returned personId, accountId and relationshipId through get_person_employments on both lead IDs. No parent_lead or child_leads values are written. This is the only supported Person write path for sourcing; never fall back to add_leads or legal backfill to attach a sourced person. For explicit changes to existing jobs, use manage_person_employment. It never qualifies a lead, enriches contacts, generates messages, enrolls in a campaign or activates an 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/dist/tools/relationships.js

@@ -10,7 +10,7 @@ const confidence = z.object({
     assessed_at: z.string().datetime(),
 }).strict();
 export function registerRelationshipTools(server, client = getClient()) {
-    server.tool("list_canonical_relationships", "List tenant-scoped canonical relationships. The response is direction-independent for consumers: filter by one entity to find both incoming and outgoing links. Legacy lead relation fields are compatibility projections, not the source of truth.", {
+    server.tool("list_canonical_relationships", "List tenant-scoped canonical relationships. The response is direction-independent for consumers: filter by one entity to find both incoming and outgoing links. Employment links are PERSON EMPLOYED_BY ACCOUNT. Use get_person_employments to read them from lead IDs; stored parent_lead and child_leads are retired.", {
         organization_id: z.string().min(1),
         entity_kind: entityKind.optional(),
         entity_id: z.string().min(1).optional(),
@@ -37,7 +37,7 @@ export function registerRelationshipTools(server, client = getClient()) {
             return handleToolError(error);
         }
     });
-    server.tool("create_canonical_relationship", "Create one typed canonical relationship in a tenant. Endpoints must already be strong canonical identities in that tenant. Retries with the same idempotency key and payload are safe; a changed payload is rejected. This tool never creates placeholder identities or activates outreach.", {
+    server.tool("create_canonical_relationship", "Create one typed canonical relationship in a tenant. Endpoints must already be strong canonical identities in that tenant. Retries with the same idempotency key and payload are safe; a changed payload is rejected. For EMPLOYED_BY use manage_person_employment instead; this generic write route rejects employment changes. This tool never creates placeholder identities or activates outreach.", {
         organization_id: z.string().min(1), relationship_type: relationshipType,
         source: entityRef, target: entityRef,
         trust_state: z.enum(["CONFIRMED", "PROPOSED", "AMBIGUOUS", "CONFLICTED", "UNKNOWN"]).optional().default("UNKNOWN"),
@@ -58,7 +58,7 @@ export function registerRelationshipTools(server, client = getClient()) {
             return handleToolError(error);
         }
     });
-    server.tool("update_canonical_relationship", "Update, tombstone, or restore one canonical relationship through the shared transactional service. Every mutation is versioned in the immutable ledger and requires a unique idempotency key.", {
+    server.tool("update_canonical_relationship", "Update, tombstone, or restore one canonical relationship through the shared transactional service. Every mutation is versioned in the immutable ledger and requires a unique idempotency key. EMPLOYED_BY changes are refused here; use manage_person_employment with the current relationship version.", {
         organization_id: z.string().min(1), relationship_id: z.string().min(1),
         relationship_type: relationshipType.optional(), source: entityRef.optional(), target: entityRef.optional(),
         trust_state: z.enum(["CONFIRMED", "PROPOSED", "AMBIGUOUS", "CONFLICTED", "UNKNOWN"]).optional(),
@@ -78,7 +78,7 @@ export function registerRelationshipTools(server, client = getClient()) {
             return handleToolError(error);
         }
     });
-    server.tool("tombstone_canonical_relationship", "Soft-delete one canonical relationship while preserving its evidence and immutable history. Use this instead of deleting legacy relation fields.", { organization_id: z.string().min(1), relationship_id: z.string().min(1), idempotency_key: z.string().min(1).max(255) }, async ({ organization_id, relationship_id, idempotency_key }) => {
+    server.tool("tombstone_canonical_relationship", "Soft-delete one canonical relationship while preserving its evidence and immutable history. For employment use manage_person_employment with operation invalidate or end; this generic route rejects EMPLOYED_BY.", { organization_id: z.string().min(1), relationship_id: z.string().min(1), idempotency_key: z.string().min(1).max(255) }, async ({ organization_id, relationship_id, idempotency_key }) => {
         try {
             return toolResult(await client.delete(`/api/canonical-relationships/${encodeURIComponent(relationship_id)}`, { organizationId: organization_id, idempotencyKey: idempotency_key }));
         }

package/package.json

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