@agifyai/leadify-mcp 8.7.5 → 8.7.6

package/README.md

@@ -327,47 +327,42 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 
 ### `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.
+`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

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) {
@@ -117,14 +122,14 @@ export function registerLeadTools(server, client = getClient()) {
     }
     // ── add_leads ──────────────────────────────────────────────────────────
     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 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, and preview_canonical_identity_backfill plus " +
-        "apply_canonical_identity_backfill when the Company lacks canonical identity). Provide the group ID " +
+        "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
@@ -265,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, 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.", {
+    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),

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.5",
+  "version": "8.7.6",
   "description": "MCP server for Leadify lead management API",
   "type": "module",
   "main": "dist/index.js",