@agifyai/leadify-mcp 9.11.0 → 9.12.0

package/README.md

@@ -258,11 +258,11 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 |------|-------------|
 | `test_api_key` | Vérifier que la clé API configurée est valide (health check). |
 | `list_lead_groups` | Lister les groupes accessibles d'une organisation explicitement sélectionnée, en vue compacte, avec le sous-menu de chacun (`folderId`, `folder`). `folder_id` garde exactement les groupes d'un sous-menu, `none` ceux qui n'en ont aucun. |
-| `get_lead_group` | Consulter les métadonnées compactes d'un groupe accessible par son ID, avec son sous-menu. |
+| `get_lead_group` | Consulter les métadonnées compactes d'un groupe accessible par son ID, avec son sous-menu et `relations` : les groupes auxquels il est relié (`field`, `leadGroupId`, `canonicalType`, `canonicalEndpointRole`, `inverseField` s'il existe). |
 | `list_lead_group_folders` | Lister les sous-menus partagés de la barre latérale d'une organisation (nom, emoji, description, groupes). Toute l'équipe voit les mêmes. |
 | `create_lead_group_folder` / `update_lead_group_folder` / `delete_lead_group_folder` | Créer, renommer, changer l'emoji (caractère ou code) ou la description, ajouter ou retirer des groupes, supprimer un sous-menu. La suppression garde les groupes. Droit d'écriture requis. |
 | `move_lead_groups_to_folder` | Ranger des groupes dans un sous-menu, ou les en sortir avec `folder_id: null` ; tous bougent ou aucun. Un groupe est dans un seul sous-menu. |
-| `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. |
+| `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. Pour un groupe PERSON, `employer_lead_group_id` le relie dès la création au groupe d'entreprises (COMPANY, même organisation). |
 | `update_lead_group` | Modifier un groupe avec réconciliation du schéma ; lorsque le serveur exige un contexte complet, transmettre ensemble `persona_id` et `offer_id` sans inférer l’offre. |
 | `add_leads` | Import plat générique vers un groupe : ne crée aucune relation d’emploi, aucun rattachement parent ni identité canonique. Ne jamais l’utiliser pour rattacher une Personne à une Company (voir `upsert_person_leads_with_employment`). |
 | `upsert_person_leads_with_employment` | Créer ou réconcilier atomiquement des Person Leads, PERSON, EMPLOYED_BY, projections et historique, sans effet commercial. |
@@ -352,7 +352,7 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `preview_canonical_relationship_migration` | Prévisualiser une migration de champs historiques, divergences et quarantaines comprises, sans mutation. |
 | `apply_canonical_relationship_migration` | Appliquer exactement un plan prévisualisé et borné grâce à son digest. |
 | `rollback_canonical_relationship_migration` | Tombstoner les liens créés par un plan de migration précis. |
-| `configure_lead_group_relations` | Configurer, dans un tenant explicitement vérifié, la projection legacy relue par une migration canonique. |
+| `configure_lead_group_relations` | Relier un groupe de personnes au groupe de leurs entreprises (ou deux groupes entre eux) dans une organisation vérifiée. Appelé sur le groupe de personnes ; l'inverse est écrit seul sur le groupe d'entreprises. `relations` remplace toute la configuration du groupe : renvoyer les relations lues avec `get_lead_group`. |
 | `preview_canonical_identity_backfill` | Prévisualiser le backfill d'identité tenant-scoped d'un groupe et de ses parents Company configurés. |
 | `apply_canonical_identity_backfill` | Appliquer exactement un backfill d'identité relu par digest, sans outreach ni activation. |
 | `update_company_brain_sections` | Modifier uniquement les sections globales encore actives (`identity`, `positioning`, `allowedVocabulary`, `prohibitedVocabulary`, `legalConstraints`). Les anciennes sections Offre/Verticale sont filtrées et refusées. |
@@ -386,6 +386,9 @@ Chaque entrée est enregistrée entièrement ou annulée. Aucun numéro légal n
 préparation juridique de l’entreprise n’est obligatoire.
 
 1. Choisir l’organisation, les groupes et la fiche entreprise exacts.
+   Vérifier avec `get_lead_group` que le groupe de personnes est relié au
+   groupe d’entreprises (voir « Relier un groupe de personnes à ses
+   entreprises » ci-dessous) ; sinon, le relier avant toute écriture.
 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
@@ -401,6 +404,25 @@ 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.
 
+#### Relier un groupe de personnes à ses entreprises (PRD-2811)
+
+Un groupe de personnes (par exemple « Dirigeants ») doit être relié au
+groupe de leurs entreprises. Sans cette liaison, la qualification refuse
+les entreprises (`QUALIFICATION_EMPLOYEE_REQUIRED`) et les tableaux
+n’affichent ni l’employeur d’une personne ni les employés d’une entreprise.
+
+- À la création : `create_lead_group` avec `entity_kind: "PERSON"` et
+  `employer_lead_group_id: <groupe d’entreprises>` (groupe COMPANY de la
+  même organisation).
+- Pour un groupe existant : `configure_lead_group_relations` sur le groupe
+  de personnes, avec `{ field: "parent_lead", lead_group_id: <groupe
+  d’entreprises>, canonical_type: "EMPLOYED_BY", canonical_endpoint_role:
+  "SOURCE", inverse_field: "child_leads" }`. L’inverse est écrit seul sur le
+  groupe d’entreprises. `relations` remplace toute la configuration : lire
+  d’abord les relations existantes avec `get_lead_group` et les renvoyer
+  avec la nouvelle.
+- Vérifier ensuite avec `get_lead_group` sur les deux groupes.
+
 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
@@ -518,7 +540,9 @@ de 1 à 20 entreprises et un `request_id` UUID. Commencer avec `dry_run: true`
 (valeur par défaut), puis transmettre le `expectedSchemaHash` retourné dans
 `expected_schema_hash` avec `dry_run: false`. La clé doit avoir les droits
 `write` et `start_qualification`, et son propriétaire doit administrer
-l’organisation. Chaque entreprise doit avoir un employé vérifié et relié.
+l’organisation. Le groupe d’entreprises doit être relié à un groupe de
+personnes (`configure_lead_group_relations`), et chaque entreprise doit avoir
+un employé vérifié et relié.
 Avant l’accord du pilote dans les réglages du groupe, deux entreprises distinctes
 au plus sont admises, même avec plusieurs appels. Une répétition conserve le
 même `request_id` et la même sélection. Aucun groupe entier n’est déduit.

package/dist/tools/canonical_backfill.js

@@ -34,7 +34,14 @@ const backfillScope = {
     lead_ids: z.array(z.string().trim().min(1)).min(1).max(100),
 };
 export function registerCanonicalBackfillTools(server, client = getClient()) {
-    server.tool("configure_lead_group_relations", "Configure the legacy projection that a canonical migration reads. The organization is mandatory and verified against both groups; canonical_type and canonical_endpoint_role must be specified together. This changes no lead, identity, canonical relationship, campaign, or outreach.", { organization_id: z.string().trim().min(1), lead_group_id: z.string().trim().min(1), relations: z.array(relation).max(100) }, async ({ organization_id, lead_group_id, relations }) => {
+    server.tool("configure_lead_group_relations", "Link (connect, pair) a person group to the company group of their employers, or set any other relation between two lead groups of the same organization. " +
+        "Common use: link a person group (for example \"Dirigeants\") to its company group. Call it on the person group with " +
+        "relations: [{ field: \"parent_lead\", lead_group_id: <company group id>, canonical_type: \"EMPLOYED_BY\", canonical_endpoint_role: \"SOURCE\", inverse_field: \"child_leads\" }]. " +
+        "Leadify writes the inverse relation on the company group by itself: do not call it again on the company group. " +
+        "Without this link, qualification refuses the companies (QUALIFICATION_EMPLOYEE_REQUIRED) and the tables show neither the employer of a person nor the employees of a company. " +
+        "relations replaces the whole relation configuration of the group: first read the existing relations with get_lead_group, then send them back together with the new one; a relation left out is removed. " +
+        "The organization is mandatory and verified against both groups; canonical_type and canonical_endpoint_role must be specified together. " +
+        "The same configuration is read by canonical relationship migrations. It changes no lead, identity, canonical relationship, campaign, or outreach.", { organization_id: z.string().trim().min(1), lead_group_id: z.string().trim().min(1), relations: z.array(relation).max(100) }, async ({ organization_id, lead_group_id, relations }) => {
         try {
             return toolResult(await client.put(`/api/lead-group/${encodeURIComponent(lead_group_id)}/relations`, {
                 organizationId: organization_id,

package/dist/tools/lead_groups.js

@@ -15,7 +15,9 @@ export function registerLeadGroupTools(server, writeClient) {
     server.tool("create_lead_group", "Create a new lead group in the specified organization. A lead group holds leads, a " +
         "schema, and an optional persona assignment. Use list_organizations first to find the " +
         "organization_id if you don't have it. Assigning a persona at creation time scopes " +
-        "scoring/messaging immediately.", {
+        "scoring/messaging immediately. For a PERSON group, pass employer_lead_group_id to link it at " +
+        "creation to the company group of their employers (otherwise link it afterwards with " +
+        "configure_lead_group_relations).", {
         name: z.string().describe("Group name."),
         organization_id: z
             .string()
@@ -53,6 +55,14 @@ export function registerLeadGroupTools(server, writeClient) {
             .nullable()
             .optional()
             .describe("Active offer ID to assign with persona_id. Must belong to the same organization."),
+        employer_lead_group_id: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe("For a PERSON group: ID of the COMPANY group of the same organization that holds their employers. " +
+            "Links the new person group to that company group at creation, the same link as " +
+            "configure_lead_group_relations (parent_lead / child_leads, EMPLOYED_BY). Check it with get_lead_group."),
     }, async (params) => {
         try {
             const body = {
@@ -73,6 +83,8 @@ export function registerLeadGroupTools(server, writeClient) {
                 body.personaId = params.persona_id;
             if (params.offer_id !== undefined)
                 body.offerId = params.offer_id;
+            if (params.employer_lead_group_id !== undefined)
+                body.employerLeadGroupId = params.employer_lead_group_id;
             const data = await (writeClient ?? getClient()).post("/api/lead-group", body);
             return toolResult(data);
         }

package/dist/tools/organizations.d.ts

@@ -10,6 +10,12 @@ export declare function leadGroupFolder(group: Record<string, unknown>): {
         emoji: unknown;
     } | null;
 };
+/**
+ * Compact view of the groups this group is linked to (for example a person
+ * group linked to the company group of its employers). Display mapping
+ * details (targetField, displayField, canonicalLabel) stay out of the read.
+ */
+export declare function compactLeadGroupRelations(relations: unknown): Record<string, unknown>[];
 /** Keep group reads navigable: never return schema, profiles, or lead data. */
 export declare function compactLeadGroup(group: unknown): Record<string, unknown>;
 export declare function registerOrganizationTools(server: McpServer, client?: Pick<LeadifyClient, "get" | "post" | "put">): void;

package/dist/tools/organizations.js

@@ -42,6 +42,24 @@ function listedLeadGroup(group) {
         ...leadGroupFolder(group),
     };
 }
+/**
+ * Compact view of the groups this group is linked to (for example a person
+ * group linked to the company group of its employers). Display mapping
+ * details (targetField, displayField, canonicalLabel) stay out of the read.
+ */
+export function compactLeadGroupRelations(relations) {
+    if (!Array.isArray(relations))
+        return [];
+    return relations
+        .filter((relation) => Boolean(relation) && typeof relation === "object")
+        .map((relation) => ({
+        field: relation.field,
+        leadGroupId: relation.leadGroupId,
+        canonicalType: relation.canonicalType ?? null,
+        canonicalEndpointRole: relation.canonicalEndpointRole ?? null,
+        ...(typeof relation.inverseField === "string" && relation.inverseField ? { inverseField: relation.inverseField } : {}),
+    }));
+}
 /** Keep group reads navigable: never return schema, profiles, or lead data. */
 export function compactLeadGroup(group) {
     const source = group && typeof group === "object" ? group : {};
@@ -62,6 +80,7 @@ export function compactLeadGroup(group) {
         refreshEnabled: source.refreshEnabled ?? false,
         refreshFrequencyDays: source.refreshFrequencyDays ?? null,
         createdAt: source.createdAt ?? null,
+        relations: compactLeadGroupRelations(source.relations),
         ...leadGroupFolder(source),
     };
 }
@@ -132,10 +151,14 @@ export function registerOrganizationTools(server, client = getClient()) {
         }
     });
     server.tool("get_lead_group", "Read the compact metadata of one accessible lead group by ID. Use this after list_lead_groups " +
-        "or discover_leadify_context to confirm its type and operational state. Returns only navigation " +
-        "metadata (no lead records, schema, company profile, or persona payload), with its shared sidebar " +
-        "folder (folderId, folder), and reports inaccessible " +
-        "groups as not found, without revealing their organization.", {
+        "or discover_leadify_context to confirm its type and operational state, and to see which other groups " +
+        "this group is linked to: relations lists each link as { field, leadGroupId, canonicalType, " +
+        "canonicalEndpointRole, inverseField when present } (for example a person group linked to the company " +
+        "group of their employers with field parent_lead and canonicalType EMPLOYED_BY). An empty relations " +
+        "array means the group is linked to no other group; link it with configure_lead_group_relations, after " +
+        "reading these relations, since that tool replaces the whole list. Returns no lead records, schema, " +
+        "company profile, or persona payload; includes its shared sidebar folder (folderId, folder), and reports " +
+        "inaccessible groups as not found, without revealing their organization.", {
         lead_group_id: z.string().describe("Lead group ID returned by Leadify discovery or another authorized Leadify response."),
     }, async ({ lead_group_id }) => {
         try {

package/dist/tools/qualification_runs.js

@@ -5,6 +5,8 @@ export function registerQualificationRunTools(server, client = getClient()) {
     server.tool("start_qualification_run", "Validate or start qualification of an explicit list of 1 to 20 companies in one organization and group, " +
         "then their linked people. dry_run defaults to true: read preflight.snapshot.expectedSchemaHash, then " +
         "send it as expected_schema_hash with dry_run=false and the same request_id to launch. " +
+        "The company group must be linked to a person group (configure_lead_group_relations on the person group, " +
+        "checked with get_lead_group): without that link the server refuses with QUALIFICATION_EMPLOYEE_REQUIRED. " +
         "The server refuses companies without a verified employee and more than two distinct pilot companies " +
         "until a human approves the pilot for this group in Leadify. No outreach or campaign activation. " +
         "Keep request_id unchanged when retrying the same selection. Read the returned runId with get_qualification_run.", { organization_id: z.string().trim().min(1), lead_group_id: z.string().trim().min(1),

package/package.json

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