@agifyai/leadify-mcp 8.7.5 → 8.8.0

package/README.md

@@ -266,6 +266,14 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `preview_unenroll_campaign_audience` | Prévisualiser de façon déterministe les membres explicites sans message pour le canal de leur campagne ou sans aucun canal de contact. Retourne les `lead_ids` exacts, sans mutation. |
 | `unenroll_campaign_audience` | Désenrôler uniquement la liste complète de `lead_ids` renvoyée par le preview courant. Relit et refuse toute sélection partielle, étendue ou périmée ; aucun envoi. |
 | `export_campaign` | Exporter les statistiques en CSV ; après clôture définitive, l'export provient du rapport final figé. |
+| `list_playbooks` / `get_playbook` | Lister et lire les « Messages types » (playbooks du rédacteur) d’une organisation, avec leur contenu complet à la dernière version. |
+| `publish_playbook` | Publier un message type : création, duplication ou nouvelle version (avec la version relue). Les refus du contrat du rédacteur sont rendus avec leur chemin. |
+| `list_campaign_senders` | Lister les comptes d’envoi (LinkedIn, boîtes mail) de la personne qui porte la clé : les messages partent à son nom. |
+| `get_campaign_audience_options` | Compter les personnes d’un groupe et de chacun de ses segments pour choisir l’audience d’une campagne. |
+| `get_contact_policy` | Lire la politique de contact effective de l’organisation ou d’une campagne, en lecture seule. |
+| `save_campaign_draft` / `get_campaign_draft` | Créer, modifier et relire un brouillon par l’assistant de campagne : audience, messages types jamais épinglés, expéditeur, fenêtre, jours, horaires et plafond quotidien. Toujours en mode `REVIEW` : chaque message attend une validation humaine. |
+| `preview_campaign_draft` | Évaluer l’audience avec le moteur d’éligibilité (personnes par message type, raisons de non-contact), sans rien écrire. |
+| `launch_campaign` | Lancer un brouillon comme le bouton « Lancer la campagne » (inscription, activation, rédaction immédiate), avec la confirmation explicite `launch_campaign`. Les messages attendent dans la file « À valider ». |
 | `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. |
@@ -327,47 +335,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

@@ -4,6 +4,7 @@ import { registerLeadTools } from "./tools/leads.js";
 import { registerSchemaTools } from "./tools/schema.js";
 import { registerLogTools } from "./tools/logs.js";
 import { registerCampaignTools } from "./tools/campaigns.js";
+import { registerCampaignWizardTools } from "./tools/campaign_wizard.js";
 import { registerSignalTools } from "./tools/signals.js";
 import { registerActivityTools } from "./tools/activities.js";
 import { registerDataSourceTools } from "./tools/datasources.js";
@@ -20,6 +21,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,11 +38,13 @@ export function createServer() {
     registerCanonicalBackfillTools(server);
     registerClaimContradictionTools(server);
     registerPersonEmploymentTools(server);
+    registerPersonAccountTools(server);
     registerEventTools(server);
     registerCommercialTruthTools(server);
     registerSchemaTools(server);
     registerLogTools(server);
     registerCampaignTools(server);
+    registerCampaignWizardTools(server);
     registerSignalTools(server);
     registerActivityTools(server);
     registerContextWorkspaceTools(server);

package/dist/tools/campaign_wizard.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type LeadifyClient } from "../client.js";
+type WizardClient = Pick<LeadifyClient, "get" | "post">;
+export declare function registerCampaignWizardTools(server: McpServer, injectedClient?: WizardClient): void;
+export {};

package/dist/tools/campaign_wizard.js

@@ -0,0 +1,204 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { toolResult, handleToolError } from "../types.js";
+const organizationId = z.string().min(1).describe("Organization selected explicitly via discover_leadify_context or list_organizations.");
+const time = z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/);
+function scoped(params) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(params))
+        if (value !== undefined)
+            query.set(key, value);
+    return query;
+}
+/** The server always stores REVIEW; refuse to report success if that ever changes. */
+function assertReviewMode(data) {
+    const campaign = data && typeof data === "object" ? data.campaign : undefined;
+    const mode = campaign && typeof campaign === "object" ? campaign.autonomyMode : undefined;
+    if (mode !== "REVIEW") {
+        throw new Error(`Leadify returned a campaign whose autonomy mode is not REVIEW (${String(mode)}); stop and check the campaign in Leadify.`);
+    }
+    return data;
+}
+export function registerCampaignWizardTools(server, injectedClient) {
+    const client = () => injectedClient ?? getClient();
+    // ── Messages types (playbooks) ─────────────────────────────────────────
+    server.tool("list_playbooks", "List the organization's 'Messages types' (outreach playbooks) used by the outreach writer: id, name, kind " +
+        "(EVENT or GENERIC), latest version, validity window, linked event, channels with steps, and campaign usage.", {
+        organization_id: organizationId,
+        include_archived: z.boolean().optional().default(false).describe("Include archived playbooks."),
+    }, async ({ organization_id, include_archived }) => {
+        try {
+            return toolResult(await client().get("/api/playbooks", scoped({ organizationId: organization_id, includeArchived: include_archived ? "true" : undefined })));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("get_playbook", "Read one 'Message type' at its latest version, with its full editable content (intent, eligibility, " +
+        "judgment guidance, promise, proofs, CTA, sequences and examples). Use it before publishing a new version.", {
+        organization_id: organizationId,
+        playbook_id: z.string().min(1).describe("Playbook ID from list_playbooks."),
+    }, async ({ organization_id, playbook_id }) => {
+        try {
+            return toolResult(await client().get(`/api/playbooks/${encodeURIComponent(playbook_id)}`, scoped({ organizationId: organization_id })));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("publish_playbook", "Publish a 'Message type' (outreach playbook): create one (no playbook_id), duplicate one (duplicated_from_id), " +
+        "or publish a new version of an existing one (playbook_id plus the expected_version read by get_playbook). " +
+        "content follows the outreach contract without key, version, exclusivityKey and kind: name, intent, validity " +
+        "{startsAt?, endsAt?}, eligibility {all: [...]}, judgmentGuidance, promise, proofs [{id, statement, sourceUrl?}], " +
+        "cta {description, url?}, sequences [{channel: EMAIL|LINKEDIN, steps: [{step, kind: EMAIL|LINKEDIN_INVITE|LINKEDIN_MESSAGE, delayDays, purpose}]}], " +
+        "examples [{channel, step, subject?, body, commentary?}]. An EVENT playbook requires an eligibility condition " +
+        "{type: 'event_participation', eventId, status: 'VERIFIED'}. Contract refusals are returned with their JSON path.", {
+        organization_id: organizationId,
+        kind: z.enum(["EVENT", "GENERIC"]).describe("EVENT requires a verified event participation; GENERIC does not. Fixed after creation."),
+        content: z.record(z.unknown()).describe("Playbook content (see the tool description)."),
+        playbook_id: z.string().min(1).optional().describe("Existing playbook to publish a new version of."),
+        expected_version: z.number().int().min(1).optional().describe("Latest version read by get_playbook; required with playbook_id."),
+        duplicated_from_id: z.string().min(1).optional().describe("Playbook duplicated into a new one."),
+    }, async ({ organization_id, kind, content, playbook_id, expected_version, duplicated_from_id }) => {
+        try {
+            const body = { organizationId: organization_id, kind, content };
+            if (playbook_id !== undefined)
+                body.playbookId = playbook_id;
+            if (expected_version !== undefined)
+                body.expectedVersion = expected_version;
+            if (duplicated_from_id !== undefined)
+                body.duplicatedFromId = duplicated_from_id;
+            return toolResult(await client().post("/api/playbooks", body));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── Campaign wizard ────────────────────────────────────────────────────
+    server.tool("list_campaign_senders", "List the sending accounts of the person who owns the API key in this organization (connected LinkedIn " +
+        "accounts and mailboxes). Messages are sent in that person's name, so a campaign can only use these senders.", { organization_id: organizationId }, async ({ organization_id }) => {
+        try {
+            return toolResult(await client().get("/api/campaign-wizard/senders", scoped({ organizationId: organization_id })));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("get_campaign_audience_options", "Count the people of a lead group and of each saved view (segment), to choose a campaign audience. " +
+        "A campaign audience is the whole group or one saved view; create a view with create_lead_view to target a subset " +
+        "(for example an __event_participation filter for one event).", {
+        organization_id: organizationId,
+        lead_group_id: z.string().min(1).describe("Person lead group ID."),
+    }, async ({ organization_id, lead_group_id }) => {
+        try {
+            return toolResult(await client().get("/api/campaign-wizard/audience-options", scoped({ organizationId: organization_id, leadGroupId: lead_group_id })));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("get_contact_policy", "Read the effective contact policy (cooldown days, maximum people per account and window, maximum qualification age) " +
+        "of the organization, or of one campaign when campaign_id is given. Read-only.", {
+        organization_id: organizationId,
+        campaign_id: z.string().min(1).optional().describe("Optional campaign ID for its effective policy."),
+    }, async ({ organization_id, campaign_id }) => {
+        try {
+            return toolResult(await client().get("/api/campaign-wizard/contact-policy", scoped({ organizationId: organization_id, campaignId: campaign_id })));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("save_campaign_draft", "Create or update a DRAFT campaign through the Leadify campaign wizard: audience (group or saved view), " +
+        "'Messages types' (never pinned to a version), sender, window, send days, hours and daily limit. The campaign " +
+        "is always in REVIEW mode: every written message waits for a human validation before sending. Nothing is " +
+        "written or sent before launch_campaign. Pass campaign_id to update an existing draft.", {
+        organization_id: organizationId,
+        campaign_id: z.string().min(1).optional().describe("Existing DRAFT campaign to update."),
+        name: z.string().min(1).max(200).describe("Campaign name."),
+        lead_group_id: z.string().min(1).describe("Person lead group ID."),
+        audience_view_id: z.string().min(1).nullable().describe("Saved view used as audience, or null for the whole group."),
+        primary_playbook_ids: z.array(z.string().min(1)).max(20).describe("Primary 'Messages types', in priority order."),
+        fallback_playbook_id: z.string().min(1).nullable().optional().describe("Optional fallback 'Message type'."),
+        channel: z.enum(["LINKEDIN", "EMAIL"]).describe("Delivery channel."),
+        unipile_account_id: z.string().min(1).nullable().optional().describe("LinkedIn sender from list_campaign_senders."),
+        mailbox_provider: z.enum(["OUTLOOK", "GMAIL", "SMTP"]).nullable().optional().describe("Email sender provider from list_campaign_senders."),
+        mailbox_owner_user_id: z.string().min(1).nullable().optional().describe("Email sender owner from list_campaign_senders."),
+        start_at: z.string().datetime().nullable().describe("Inclusive start (ISO-8601 UTC); required before launch."),
+        end_at: z.string().datetime().nullable().describe("Exclusive end (ISO-8601 UTC); required before launch."),
+        timezone: z.string().min(1).describe("IANA timezone, for example Europe/Paris."),
+        workday_start: time.describe("Sending window start, HH:MM."),
+        workday_end: time.describe("Sending window end, HH:MM."),
+        send_days: z
+            .object({ monday: z.boolean(), tuesday: z.boolean(), wednesday: z.boolean(), thursday: z.boolean(), friday: z.boolean(), saturday: z.boolean(), sunday: z.boolean() })
+            .describe("Allowed sending days."),
+        daily_limit: z.number().int().min(1).describe("Daily sending limit for the channel."),
+    }, async (input) => {
+        try {
+            const linkedin = input.channel === "LINKEDIN";
+            const body = {
+                organizationId: input.organization_id,
+                ...(input.campaign_id ? { campaignId: input.campaign_id } : {}),
+                name: input.name,
+                leadGroupId: input.lead_group_id,
+                audienceViewId: input.audience_view_id,
+                primaryPlaybookIds: input.primary_playbook_ids,
+                fallbackEnabled: Boolean(input.fallback_playbook_id),
+                fallbackPlaybookId: input.fallback_playbook_id ?? null,
+                channel: input.channel,
+                unipileAccountId: linkedin ? input.unipile_account_id ?? null : null,
+                mailboxProvider: linkedin ? null : input.mailbox_provider ?? null,
+                mailboxOwnerUserId: linkedin ? null : input.mailbox_owner_user_id ?? null,
+                startAt: input.start_at,
+                endAt: input.end_at,
+                defaultTimezone: input.timezone,
+                workdayStart: input.workday_start,
+                workdayEnd: input.workday_end,
+                sendDays: input.send_days,
+                dailyLimit: input.daily_limit,
+            };
+            return toolResult(assertReviewMode(await client().post("/api/campaign-wizard", body)));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("get_campaign_draft", "Read a campaign as the wizard sees it: audience, 'Messages types', sender, window, days, daily limit, " +
+        "autonomyMode (always REVIEW) and the launch blockers still missing.", {
+        organization_id: organizationId,
+        campaign_id: z.string().min(1).describe("Campaign ID."),
+    }, async ({ organization_id, campaign_id }) => {
+        try {
+            return toolResult(await client().get(`/api/campaign-wizard/${encodeURIComponent(campaign_id)}`, scoped({ organizationId: organization_id })));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("preview_campaign_draft", "Dry-run the eligibility engine on the campaign audience: people per 'Message type' and people not contacted " +
+        "with their reasons. Nothing is written or sent.", {
+        organization_id: organizationId,
+        campaign_id: z.string().min(1).describe("Campaign ID."),
+    }, async ({ organization_id, campaign_id }) => {
+        try {
+            return toolResult(await client().get(`/api/campaign-wizard/${encodeURIComponent(campaign_id)}/preview`, scoped({ organizationId: organization_id })));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("launch_campaign", "Launch a DRAFT campaign exactly like the 'Lancer la campagne' button: enroll the audience, activate the campaign " +
+        "and start the outreach writer immediately. In REVIEW mode every written message waits in the 'À valider' queue " +
+        "for a human validation before anything is sent. Confirm with the user before calling this tool.", {
+        organization_id: organizationId,
+        campaign_id: z.string().min(1).describe("DRAFT campaign ID."),
+        confirmation: z.literal("launch_campaign").describe("Exact acknowledgement required before launching."),
+    }, async ({ organization_id, campaign_id }) => {
+        try {
+            return toolResult(assertReviewMode(await client().post(`/api/campaign-wizard/${encodeURIComponent(campaign_id)}/launch`, { organizationId: organization_id })));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

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