@agifyai/leadify-mcp 9.2.0 → 9.3.0

package/README.md

@@ -234,6 +234,9 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `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. |
+| `exclude_account` | Exclure une entreprise (établissement) et toutes ses personnes liées : cause protégée `ACCOUNT_EXCLUDED`, motif et URL source obligatoires, `level: "establishment"`. |
+| `exclude_lead` / `reintegrate_lead` | Exclure ou réintégrer une personne avec les mêmes commandes que l'interface ; raison obligatoire, aucun motif protégé levé. |
+| `get_outreach_state` | Lire causes actives, version et date de 1 à 100 fiches. |
 | `get_leads` | Rechercher et lister des leads avec filtres, recherche et pagination, dont le critère composé `event_filter`. |
 | `get_lead` | Récupérer les détails complets d'un lead par son ID. |
 | `update_lead` | Mettre à jour un ou plusieurs champs d'un lead existant. |
@@ -375,6 +378,21 @@ Aucune mutation de sourcing ne qualifie le lead, n’enrichit les contacts
 aucun canal externe : le readback porte `noSend: true` et
 `externalActivation: 0`.
 
+### Exclusions de prospection (PRD-2404)
+
+Une exclusion ne s'écrit jamais en texte (Context Workspace, notes, persona) ni dans les
+champs `excluded`, `hide_from_campaign` ou `outreach_status` : le serveur refuse
+ces champs (409 `PROTECTED_OUTREACH_FIELD`). Utiliser `exclude_account` pour un
+client existant ou un compte à ne pas contacter : motif et `source_url` publique
+obligatoires, les personnes liées sont exclues tant que le lien existe et leurs
+campagnes s'arrêtent. Leadify ne distingue pas les services : la réponse dit
+toujours `level: "establishment"`. `exclude_lead` et `reintegrate_lead` agissent
+sur une personne ; la réintégration ne lève jamais une opposition, une protection
+de délivrabilité ni l'exclusion d'une entreprise. Chaque écriture accepte
+`idempotency_key` et `expected_version`, et rend l'état relu ;
+`get_outreach_state` relit 1 à 100 fiches. Routes serveur : `/api/outreach/*`
+(PRD-2337), auteur tracé dans Leadify : propriétaire de la clé, source Agent.
+
 ### Création d’organisation et qualification (PRD-2398)
 
 Dans Leadify, **Réglages → Clés API → Modifier** permet de changer les actions

package/dist/server.js

@@ -1,4 +1,5 @@
 import { registerQualificationRunTools } from "./tools/qualification_runs.js";
+import { registerOutreachExclusionTools } from "./tools/outreach_exclusion.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerAuthTools } from "./tools/auth.js";
 import { registerLeadTools } from "./tools/leads.js";
@@ -53,5 +54,6 @@ export function createServer() {
     registerPersonaTools(server);
     registerPipelineTools(server);
     registerQualificationRunTools(server);
+    registerOutreachExclusionTools(server);
     return server;
 }

package/dist/tools/outreach_exclusion.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type LeadifyClient } from "../client.js";
+export declare function registerOutreachExclusionTools(server: McpServer, client?: Pick<LeadifyClient, "post">): void;

package/dist/tools/outreach_exclusion.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { toolResult, handleToolError } from "../types.js";
+// PRD-2404 — vraies exclusions de prospection, branchées sur /api/outreach
+// (PRD-2337) : mêmes commandes que les boutons de l'interface Leadify.
+const NEVER_IN_TEXT = "Never write an exclusion as text (Context Workspace, company brain, notes, persona) and never write excluded, " +
+    "hide_from_campaign or outreach_status on a lead: text excludes nothing and Leadify refuses those fields (409 PROTECTED_OUTREACH_FIELD).";
+const id = z.string().trim().min(1).max(200);
+const writeShape = {
+    organization_id: id.describe("Organization that owns the lead. Must be in the API key's scope."),
+    idempotency_key: z.string().trim().min(8).max(200).optional().describe("Stable key for this decision. Retrying with the same key replays the first result; reusing it for another lead or reason returns 409 OUTREACH_IDEMPOTENCY_KEY_REUSED."),
+    expected_version: z.number().int().min(0).optional().describe("state.version read with get_outreach_state. If the state changed meanwhile, the server refuses with 409 OUTREACH_VERSION_CONFLICT: re-read, then decide again."),
+};
+const reason = z.string().trim().min(3).max(2000);
+export function registerOutreachExclusionTools(server, client = getClient()) {
+    server.tool("exclude_account", "Exclude a company (a hospital, clinic or other establishment) from all prospecting: sets the protected cause " +
+        "ACCOUNT_EXCLUDED on the company lead, and every person linked to it is excluded too (now and when linked later) and " +
+        "their running campaigns stop. Use it for existing customers, competitors or accounts the client must not contact. " +
+        "reason and source_url (the public page proving it) are required. Leadify has no department level: the response " +
+        "always says level=\"establishment\", with levelNote when service was given. Idempotent. An agent cannot lift this " +
+        "exclusion; only a human in Leadify can. " + NEVER_IN_TEXT, {
+        ...writeShape,
+        company_lead_id: id.describe("Lead id of the company (COMPANY group)."),
+        reason: reason.describe("Why the account is excluded, e.g. 'Déjà client RDS Diag'."),
+        source_url: z.string().trim().url().max(2000).refine(value => /^https?:\/\//i.test(value), "http(s) URL required")
+            .describe("Public http(s) page proving the reason."),
+        service: z.string().trim().min(1).max(200).optional().describe("Department targeted, if any. Recorded in the note; the exclusion still covers the whole establishment."),
+    }, async ({ organization_id, company_lead_id, reason, source_url, service, idempotency_key, expected_version }) => {
+        try {
+            return toolResult(await client.post("/api/outreach/accounts/exclude", {
+                organizationId: organization_id, companyLeadId: company_lead_id, reason, sourceUrl: source_url, service,
+                idempotencyKey: idempotency_key, expectedVersion: expected_version, origin: "AGENT",
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("exclude_lead", "Exclude one person from prospecting: no message is drafted, enrolled or sent, and their running campaigns stop. " +
+        "Same command as the Exclude button in Leadify; the history shows the API key owner as author. caused_by is MANUAL " +
+        "(default) or TARGET_NOT_FIT (out of target). For a company use exclude_account instead (this tool refuses company leads " +
+        "with 409 OUTREACH_COMPANY_USE_ACCOUNT_ROUTE). Returns the re-read state. " + NEVER_IN_TEXT, {
+        ...writeShape,
+        lead_id: id.describe("Lead id of the person."),
+        caused_by: z.enum(["MANUAL", "TARGET_NOT_FIT"]).default("MANUAL"),
+        reason: reason.describe("Why the person is excluded; shown in the Leadify history."),
+    }, async ({ organization_id, lead_id, caused_by, reason, idempotency_key, expected_version }) => {
+        try {
+            return toolResult(await client.post("/api/outreach/leads/exclude", {
+                organizationId: organization_id, leadId: lead_id, causedBy: caused_by, reason,
+                idempotencyKey: idempotency_key, expectedVersion: expected_version, origin: "AGENT",
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("reintegrate_lead", "Allow again a person excluded by hand (MANUAL, out of target, or a migrated historical flag). A justification is " +
+        "required. It never lifts an opt-out, a deliverability protection or a company exclusion: if one remains, state.status " +
+        "stays \"excluded\" and state.causes says why. No campaign is restarted. Returns the re-read state.", {
+        ...writeShape,
+        lead_id: id.describe("Lead id of the person."),
+        reason: reason.describe("Why the person may be contacted again; shown in the Leadify history."),
+    }, async ({ organization_id, lead_id, reason, idempotency_key, expected_version }) => {
+        try {
+            return toolResult(await client.post("/api/outreach/leads/reintegrate", {
+                organizationId: organization_id, leadId: lead_id, reason,
+                idempotencyKey: idempotency_key, expectedVersion: expected_version, origin: "AGENT",
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("get_outreach_state", "Read the prospecting state of 1 to 100 leads (people or companies): status allowed or excluded, active causes with " +
+        "their origin and note, version (pass it as expected_version to a write), lastTransitionAt and accountSources " +
+        "(companies whose exclusion the person inherits). Leads absent from the organization are listed in missingLeadIds. " +
+        "Read this before deciding, instead of looking for exclusions in text.", {
+        organization_id: id,
+        lead_ids: z.array(id).min(1).max(100),
+    }, { readOnlyHint: true }, async ({ organization_id, lead_ids }) => {
+        try {
+            return toolResult(await client.post("/api/outreach/state", { organizationId: organization_id, leadIds: lead_ids }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/package.json

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