@agifyai/leadify-mcp 9.4.0 → 9.6.0

package/README.md

@@ -121,6 +121,7 @@ src/
 └── tools/
     ├── auth.ts
     ├── leads.ts
+    ├── lead_move.ts
     ├── events.ts
     ├── campaigns.ts
     ├── context_workspace.ts
@@ -227,8 +228,11 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | Tool | Description |
 |------|-------------|
 | `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. |
-| `get_lead_group` | Consulter les métadonnées compactes d'un groupe accessible par son ID. |
+| `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. |
+| `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. |
 | `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`). |
@@ -237,6 +241,9 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `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. |
+| `preview_move_leads` | Essai à blanc du déplacement de fiches vers un autre groupe de la même organisation : sélection par identifiants, vue ou filtre (500 fiches au plus par appel, lots ensuite), refus par fiche avec motif, doublons dans le groupe cible, champs de schéma et relations à ajouter, blocages et empreinte du plan. |
+| `move_leads` | Appliquer un déplacement prévisualisé ; exige l'empreinte de la prévisualisation et une clé d'idempotence. La fiche garde son identifiant et tout son historique ; jamais de fusion. |
+| `undo_move_leads` / `get_lead_move` | Annuler ou relire une opération de déplacement par son identifiant. |
 | `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. |
@@ -402,6 +409,36 @@ de délivrabilité ni l'exclusion d'une entreprise. Chaque écriture accepte
 `get_outreach_state` relit 1 à 100 fiches. Routes serveur : `/api/outreach/*`
 (PRD-2337), auteur tracé dans Leadify : propriétaire de la clé, source Agent.
 
+### Déplacer des prospects vers un autre groupe (PRD-2478)
+
+Pour réorganiser une base, **déplacer** les fiches plutôt que les copier
+(`add_leads`) ou cloner le groupe (`clone_lead_group`). Un déplacement garde la
+même fiche : même identifiant, mêmes données, notes, activités, signaux,
+historique de campagne, identité et rattachements. Seuls changent son groupe et
+les colonnes qui recopient ce groupe. Un déplacement ne fusionne jamais deux
+fiches : un doublon déjà présent dans le groupe cible est signalé, et la fiche
+est quand même déplacée à part ; pour l'éviter, la retirer de la sélection.
+
+1. `preview_move_leads` (aucune écriture) : `target_group_id`, `organization_id`
+   facultatif (sinon celle du groupe cible) et une seule forme de `selection` :
+   `{ kind: "lead_ids", lead_ids }` (1 à 500), `{ kind: "view", view_id }` ou
+   `{ kind: "filter", group_id, filters?, or_filters?, search? }` (mêmes filtres
+   que les vues). Au-delà de 500 fiches, la vue ou le filtre est traité par lots :
+   la réponse indique `selection.remaining` et un champ `guidance`.
+2. `move_leads` : mêmes paramètres, plus `expected_plan_digest` (rendu par la
+   prévisualisation) et `idempotency_key`. Sans ces deux valeurs, le MCP n'envoie
+   rien. Si le plan a changé, le serveur refuse (`MOVE_PLAN_STALE`) : refaire la
+   prévisualisation.
+3. `undo_move_leads` et `get_lead_move` : par `operation_id` (rendu dans
+   `operation.operationId`). Une deuxième annulation rend `replayed: true`.
+
+Chaque refus (par fiche) ou blocage (global) porte un code et un message en
+français qui dit quoi faire ; il ne se contourne jamais (pas de copie, pas de
+réimport, pas de suppression puis recréation). Routes serveur :
+`/api/leads/move` (PRD-2476 : requêtes en snake_case, réponses
+`{ dry_run, preview }` ou `{ operation }`), clé `write`, refusée aux clés
+assistant. Nécessite un serveur Leadify qui contient PRD-2476.
+
 ### 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

@@ -12,10 +12,12 @@ import { registerActivityTools } from "./tools/activities.js";
 import { registerDataSourceTools } from "./tools/datasources.js";
 import { registerPersonaTools } from "./tools/personas.js";
 import { registerLeadGroupTools } from "./tools/lead_groups.js";
+import { registerLeadGroupFolderTools } from "./tools/lead_group_folders.js";
 import { registerOrganizationTools } from "./tools/organizations.js";
 import { registerPipelineTools } from "./tools/pipeline.js";
 import { registerContextWorkspaceTools } from "./tools/context_workspace.js";
 import { registerLeadViewTools } from "./tools/views.js";
+import { registerLeadMoveTools } from "./tools/lead_move.js";
 import { registerRelationshipTools } from "./tools/relationships.js";
 import { registerCanonicalBackfillTools } from "./tools/canonical_backfill.js";
 import { registerCommercialTruthTools } from "./tools/commercial_truth.js";
@@ -33,8 +35,10 @@ export function createServer() {
     registerAuthTools(server);
     registerOrganizationTools(server);
     registerLeadGroupTools(server);
+    registerLeadGroupFolderTools(server);
     registerLeadViewTools(server);
     registerLeadTools(server);
+    registerLeadMoveTools(server);
     registerRelationshipTools(server);
     registerCanonicalBackfillTools(server);
     registerClaimContradictionTools(server);

package/dist/tools/lead_group_folders.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type LeadifyClient } from "../client.js";
+/** Accepts "🇩🇪" or its code "1f1e9-1f1ea"; Leadify stores the code. */
+export declare function emojiCode(value: string): string;
+export declare function registerLeadGroupFolderTools(server: McpServer, client?: Pick<LeadifyClient, "get" | "post" | "put" | "delete">): void;

package/dist/tools/lead_group_folders.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { toolResult, handleToolError } from "../types.js";
+/**
+ * PRD-2480: the shared lead group folders ("sous-menus" of the Leadify
+ * sidebar, PRD-2471). One organization shares them; a group sits in one
+ * folder at most. Every change here is what the whole team sees in Leadify.
+ */
+const UNIFIED = /^[a-f0-9]{2,6}(?:-[a-f0-9]{2,6}){0,15}$/i;
+/** Accepts "🇩🇪" or its code "1f1e9-1f1ea"; Leadify stores the code. */
+export function emojiCode(value) {
+    const trimmed = value.trim();
+    if (UNIFIED.test(trimmed))
+        return trimmed.toLowerCase();
+    return Array.from(trimmed).map((char) => char.codePointAt(0).toString(16)).join("-");
+}
+const emoji = z.string().trim().min(1).max(64)
+    .describe("Emoji shown before the folder name, as the character (🇩🇪) or its code (1f1e9-1f1ea).");
+const groupIds = z.array(z.string().trim().min(1)).max(500);
+const folderId = z.string().trim().min(1).describe("Folder ID from list_lead_group_folders.");
+const path = (id) => `/api/lead-group-folders/${encodeURIComponent(id)}`;
+export function registerLeadGroupFolderTools(server, client = getClient()) {
+    server.tool("list_lead_group_folders", "List the shared folders (sidebar sub-menus such as \"🇩🇪 DACH\") of one organization, each with its " +
+        "name, emoji code, description and the ids of the lead groups it holds. The whole team sees the same " +
+        "folders in Leadify. To list the groups of one folder with their details, use list_lead_groups with folder_id.", {
+        organization_id: z.string().trim().min(1).optional()
+            .describe("Organization ID from discover_leadify_context. Required when the key reaches several organizations."),
+    }, async ({ organization_id }) => {
+        try {
+            const params = organization_id ? new URLSearchParams({ organizationId: organization_id }) : undefined;
+            return toolResult(await client.get("/api/lead-group-folders", params));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("create_lead_group_folder", "Create a shared folder in the Leadify sidebar of one organization, optionally with groups already in it. " +
+        "A group sits in one folder at most: listed groups leave their previous folder. Needs write permission. " +
+        "Visible at once to the whole team.", {
+        organization_id: z.string().trim().min(1).optional()
+            .describe("Organization ID. Required when the key reaches several organizations."),
+        name: z.string().trim().min(1).max(100).describe("Folder name, e.g. DACH."),
+        emoji: emoji.optional(),
+        description: z.string().trim().max(2000).optional(),
+        lead_group_ids: groupIds.optional().describe("Lead groups of this organization to put in the folder."),
+    }, async ({ organization_id, name, emoji: icon, description, lead_group_ids }) => {
+        try {
+            return toolResult(await client.post("/api/lead-group-folders", {
+                ...(organization_id ? { organizationId: organization_id } : {}),
+                name,
+                ...(icon ? { emoji: emojiCode(icon) } : {}),
+                ...(description !== undefined ? { description } : {}),
+                ...(lead_group_ids?.length ? { leadGroupIds: lead_group_ids } : {}),
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("update_lead_group_folder", "Change a shared folder: rename it, set or clear its emoji and description, add groups to it (they leave " +
+        "their previous folder) or take groups out of it. Only the fields given change, so a colleague's other " +
+        "edits are kept. Needs write permission.", {
+        folder_id: folderId,
+        name: z.string().trim().min(1).max(100).optional(),
+        emoji: emoji.nullable().optional().describe("New emoji, or null to remove it."),
+        description: z.string().trim().max(2000).nullable().optional().describe("New description, or null to remove it."),
+        add_lead_group_ids: groupIds.optional().describe("Groups moved into this folder."),
+        remove_lead_group_ids: groupIds.optional().describe("Groups taken out of this folder; they stay outside any folder."),
+    }, async ({ folder_id, name, emoji: icon, description, add_lead_group_ids, remove_lead_group_ids }) => {
+        try {
+            return toolResult(await client.put(path(folder_id), {
+                ...(name !== undefined ? { name } : {}),
+                ...(icon !== undefined ? { emoji: icon === null ? null : emojiCode(icon) } : {}),
+                ...(description !== undefined ? { description } : {}),
+                ...(add_lead_group_ids?.length ? { addLeadGroupIds: add_lead_group_ids } : {}),
+                ...(remove_lead_group_ids?.length ? { removeLeadGroupIds: remove_lead_group_ids } : {}),
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("delete_lead_group_folder", "Delete a shared folder. Its groups are kept and simply leave the folder; no lead or group is deleted. " +
+        "Needs write permission.", { folder_id: folderId }, async ({ folder_id }) => {
+        try {
+            return toolResult(await client.delete(path(folder_id)));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("move_lead_groups_to_folder", "Put lead groups in a shared folder, or take them out of any folder with folder_id null. All groups move " +
+        "or none does. Needs write permission.", {
+        lead_group_ids: groupIds.min(1).describe("Lead groups to file, all from the same organization."),
+        folder_id: folderId.nullable().describe("Target folder ID, or null to take the groups out of any folder."),
+    }, async ({ lead_group_ids, folder_id }) => {
+        try {
+            return toolResult(await client.put("/api/lead-group-folders/assignments", { leadGroupIds: lead_group_ids, folderId: folder_id }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/tools/lead_move.d.ts

@@ -0,0 +1,482 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { type LeadifyClient } from "../client.js";
+import { type ToolResult } from "../types.js";
+export declare const LEAD_MOVE_MAX_LEADS = 500;
+declare const selectionSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"lead_ids">;
+    lead_ids: z.ZodArray<z.ZodString, "many">;
+}, "strict", z.ZodTypeAny, {
+    lead_ids: string[];
+    kind: "lead_ids";
+}, {
+    lead_ids: string[];
+    kind: "lead_ids";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"view">;
+    view_id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    view_id: string;
+    kind: "view";
+}, {
+    view_id: string;
+    kind: "view";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"filter">;
+    group_id: z.ZodString;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        operator: z.ZodEnum<["equals", "contains", "gte", "lte", "not_equals", "not_contains", "is_true", "is_false", "is_null", "is_not_null", "activity_days_ago", "activity_count_equals", "activity_count_gte", "activity_count_lte", "bbox"]>;
+        value: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+        value?: unknown;
+    }, {
+        field: string;
+        operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+        value?: unknown;
+    }>, "many">>;
+    or_filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        operator: z.ZodEnum<["equals", "contains", "gte", "lte", "not_equals", "not_contains", "is_true", "is_false", "is_null", "is_not_null", "activity_days_ago", "activity_count_equals", "activity_count_gte", "activity_count_lte", "bbox"]>;
+        value: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+        value?: unknown;
+    }, {
+        field: string;
+        operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+        value?: unknown;
+    }>, "many">>;
+    search: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    group_id: string;
+    kind: "filter";
+    search?: string | undefined;
+    filters?: {
+        field: string;
+        operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+        value?: unknown;
+    }[] | undefined;
+    or_filters?: {
+        field: string;
+        operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+        value?: unknown;
+    }[] | undefined;
+}, {
+    group_id: string;
+    kind: "filter";
+    search?: string | undefined;
+    filters?: {
+        field: string;
+        operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+        value?: unknown;
+    }[] | undefined;
+    or_filters?: {
+        field: string;
+        operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+        value?: unknown;
+    }[] | undefined;
+}>]>, {
+    lead_ids: string[];
+    kind: "lead_ids";
+} | {
+    view_id: string;
+    kind: "view";
+} | {
+    group_id: string;
+    kind: "filter";
+    search?: string | undefined;
+    filters?: {
+        field: string;
+        operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+        value?: unknown;
+    }[] | undefined;
+    or_filters?: {
+        field: string;
+        operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+        value?: unknown;
+    }[] | undefined;
+}, {
+    lead_ids: string[];
+    kind: "lead_ids";
+} | {
+    view_id: string;
+    kind: "view";
+} | {
+    group_id: string;
+    kind: "filter";
+    search?: string | undefined;
+    filters?: {
+        field: string;
+        operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+        value?: unknown;
+    }[] | undefined;
+    or_filters?: {
+        field: string;
+        operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+        value?: unknown;
+    }[] | undefined;
+}>;
+declare const previewSchema: z.ZodObject<{
+    organization_id: z.ZodOptional<z.ZodString>;
+    target_group_id: z.ZodString;
+    selection: z.ZodEffects<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"lead_ids">;
+        lead_ids: z.ZodArray<z.ZodString, "many">;
+    }, "strict", z.ZodTypeAny, {
+        lead_ids: string[];
+        kind: "lead_ids";
+    }, {
+        lead_ids: string[];
+        kind: "lead_ids";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"view">;
+        view_id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        view_id: string;
+        kind: "view";
+    }, {
+        view_id: string;
+        kind: "view";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"filter">;
+        group_id: z.ZodString;
+        filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            operator: z.ZodEnum<["equals", "contains", "gte", "lte", "not_equals", "not_contains", "is_true", "is_false", "is_null", "is_not_null", "activity_days_ago", "activity_count_equals", "activity_count_gte", "activity_count_lte", "bbox"]>;
+            value: z.ZodOptional<z.ZodUnknown>;
+        }, "strip", z.ZodTypeAny, {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }, {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }>, "many">>;
+        or_filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            operator: z.ZodEnum<["equals", "contains", "gte", "lte", "not_equals", "not_contains", "is_true", "is_false", "is_null", "is_not_null", "activity_days_ago", "activity_count_equals", "activity_count_gte", "activity_count_lte", "bbox"]>;
+            value: z.ZodOptional<z.ZodUnknown>;
+        }, "strip", z.ZodTypeAny, {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }, {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }>, "many">>;
+        search: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        group_id: string;
+        kind: "filter";
+        search?: string | undefined;
+        filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+        or_filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+    }, {
+        group_id: string;
+        kind: "filter";
+        search?: string | undefined;
+        filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+        or_filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+    }>]>, {
+        lead_ids: string[];
+        kind: "lead_ids";
+    } | {
+        view_id: string;
+        kind: "view";
+    } | {
+        group_id: string;
+        kind: "filter";
+        search?: string | undefined;
+        filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+        or_filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+    }, {
+        lead_ids: string[];
+        kind: "lead_ids";
+    } | {
+        view_id: string;
+        kind: "view";
+    } | {
+        group_id: string;
+        kind: "filter";
+        search?: string | undefined;
+        filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+        or_filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    target_group_id: string;
+    selection: {
+        lead_ids: string[];
+        kind: "lead_ids";
+    } | {
+        view_id: string;
+        kind: "view";
+    } | {
+        group_id: string;
+        kind: "filter";
+        search?: string | undefined;
+        filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+        or_filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+    };
+    organization_id?: string | undefined;
+}, {
+    target_group_id: string;
+    selection: {
+        lead_ids: string[];
+        kind: "lead_ids";
+    } | {
+        view_id: string;
+        kind: "view";
+    } | {
+        group_id: string;
+        kind: "filter";
+        search?: string | undefined;
+        filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+        or_filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+    };
+    organization_id?: string | undefined;
+}>;
+declare const applySchema: z.ZodObject<{
+    expected_plan_digest: z.ZodString;
+    idempotency_key: z.ZodString;
+    organization_id: z.ZodOptional<z.ZodString>;
+    target_group_id: z.ZodString;
+    selection: z.ZodEffects<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"lead_ids">;
+        lead_ids: z.ZodArray<z.ZodString, "many">;
+    }, "strict", z.ZodTypeAny, {
+        lead_ids: string[];
+        kind: "lead_ids";
+    }, {
+        lead_ids: string[];
+        kind: "lead_ids";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"view">;
+        view_id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        view_id: string;
+        kind: "view";
+    }, {
+        view_id: string;
+        kind: "view";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"filter">;
+        group_id: z.ZodString;
+        filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            operator: z.ZodEnum<["equals", "contains", "gte", "lte", "not_equals", "not_contains", "is_true", "is_false", "is_null", "is_not_null", "activity_days_ago", "activity_count_equals", "activity_count_gte", "activity_count_lte", "bbox"]>;
+            value: z.ZodOptional<z.ZodUnknown>;
+        }, "strip", z.ZodTypeAny, {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }, {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }>, "many">>;
+        or_filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            operator: z.ZodEnum<["equals", "contains", "gte", "lte", "not_equals", "not_contains", "is_true", "is_false", "is_null", "is_not_null", "activity_days_ago", "activity_count_equals", "activity_count_gte", "activity_count_lte", "bbox"]>;
+            value: z.ZodOptional<z.ZodUnknown>;
+        }, "strip", z.ZodTypeAny, {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }, {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }>, "many">>;
+        search: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        group_id: string;
+        kind: "filter";
+        search?: string | undefined;
+        filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+        or_filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+    }, {
+        group_id: string;
+        kind: "filter";
+        search?: string | undefined;
+        filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+        or_filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+    }>]>, {
+        lead_ids: string[];
+        kind: "lead_ids";
+    } | {
+        view_id: string;
+        kind: "view";
+    } | {
+        group_id: string;
+        kind: "filter";
+        search?: string | undefined;
+        filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+        or_filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+    }, {
+        lead_ids: string[];
+        kind: "lead_ids";
+    } | {
+        view_id: string;
+        kind: "view";
+    } | {
+        group_id: string;
+        kind: "filter";
+        search?: string | undefined;
+        filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+        or_filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    idempotency_key: string;
+    target_group_id: string;
+    selection: {
+        lead_ids: string[];
+        kind: "lead_ids";
+    } | {
+        view_id: string;
+        kind: "view";
+    } | {
+        group_id: string;
+        kind: "filter";
+        search?: string | undefined;
+        filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+        or_filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+    };
+    expected_plan_digest: string;
+    organization_id?: string | undefined;
+}, {
+    idempotency_key: string;
+    target_group_id: string;
+    selection: {
+        lead_ids: string[];
+        kind: "lead_ids";
+    } | {
+        view_id: string;
+        kind: "view";
+    } | {
+        group_id: string;
+        kind: "filter";
+        search?: string | undefined;
+        filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+        or_filters?: {
+            field: string;
+            operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+            value?: unknown;
+        }[] | undefined;
+    };
+    expected_plan_digest: string;
+    organization_id?: string | undefined;
+}>;
+type Selection = z.infer<typeof selectionSchema>;
+type LeadMoveClient = Pick<LeadifyClient, "get" | "post">;
+export declare const leadMoveApi: {
+    movePath: string;
+    operationPath: (operationId: string) => string;
+    undoPath: (operationId: string) => string;
+    selection(selection: Selection): Record<string, unknown>;
+    previewBody(input: z.infer<typeof previewSchema>): Record<string, unknown>;
+    applyBody(input: z.infer<typeof applySchema>): Record<string, unknown>;
+    errorCode(body: unknown): string | undefined;
+    errorMessage(body: unknown): string | undefined;
+};
+export declare const LEAD_MOVE_ERRORS: Record<string, string>;
+export declare function leadMoveError(error: unknown): ToolResult;
+export declare function registerLeadMoveTools(server: McpServer, client?: LeadMoveClient): void;
+export {};

package/dist/tools/lead_move.js

@@ -0,0 +1,251 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { LeadifyApiError, handleToolError, toolError, toolResult } from "../types.js";
+import { filterSchema } from "./views.js";
+// PRD-2478 — déplacer des prospects vers un autre groupe (service PRD-2476).
+// Contrat figé le 8 octobre 2026 (LEAD_MOVE_PLAN_VERSION = '2026-10-08') :
+// la fiche garde son identifiant ; seuls changent son groupe et les colonnes
+// qui recopient le groupe de cette fiche. Rien n'est supprimé ni fusionné.
+export const LEAD_MOVE_MAX_LEADS = 500;
+const id = z.string().trim().min(1).max(200);
+const digest = z.string().trim().regex(/^[a-f0-9]{64}$/, "Empreinte SHA-256 attendue (64 caractères hexadécimaux).");
+const idempotencyKey = z.string().trim().min(8).max(200);
+const selectionSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("lead_ids"),
+        lead_ids: z.array(id).min(1).max(LEAD_MOVE_MAX_LEADS).describe(`1 to ${LEAD_MOVE_MAX_LEADS} lead ids, from one or several source groups. More than ${LEAD_MOVE_MAX_LEADS} is refused (SELECTION_TOO_LARGE): split the list into batches.`),
+    }).strict(),
+    z.object({
+        kind: z.literal("view"),
+        view_id: id.describe("Saved view whose leads are moved (see list_lead_views)."),
+    }).strict(),
+    z.object({
+        kind: z.literal("filter"),
+        group_id: id.describe("Source lead group the filter reads."),
+        filters: z.array(filterSchema).max(100).optional().describe("AND conditions, same shape as lead views."),
+        or_filters: z.array(filterSchema).max(100).optional().describe("OR conditions, same shape as lead views."),
+        search: z.string().trim().min(1).max(500).optional().describe("Full-text search, as in get_leads."),
+    }).strict(),
+]).superRefine((value, context) => {
+    if (value.kind === "lead_ids" && new Set(value.lead_ids).size !== value.lead_ids.length) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["lead_ids"], message: "lead_ids ne doit pas contenir de doublon." });
+    }
+}).describe(`Exactly one selection form. A view or a filter larger than ${LEAD_MOVE_MAX_LEADS} leads is handled in batches: the preview takes the first ${LEAD_MOVE_MAX_LEADS} leads (id order) and returns selection.totalMatching and selection.remaining.`);
+const previewShape = {
+    organization_id: id.optional().describe("Organization that owns the leads and the target group. Optional: when omitted, Leadify uses the target group's organization, if the API key can access it."),
+    target_group_id: id.describe("Lead group the leads move into. Same entity kind as the source groups (person to person, company to company)."),
+    selection: selectionSchema,
+};
+const applyShape = {
+    ...previewShape,
+    expected_plan_digest: digest.describe("expectedPlanDigest returned by preview_move_leads for this exact selection and target."),
+    idempotency_key: idempotencyKey.describe("Unique key for this move. Retrying with the same key and digest returns the operation already applied (replayed: true); the same key with another digest is refused (IDEMPOTENCY_KEY_REUSED)."),
+};
+const operationShape = {
+    operation_id: id.describe("operationId returned by move_leads (operation.operationId). Leadify checks that the API key can access its organization."),
+};
+const previewSchema = z.object(previewShape).strict();
+const applySchema = z.object(applyShape).strict();
+const operationSchema = z.object(operationShape).strict();
+// ── Correspondance avec l'API REST (PRD-2476, apps/server/src/routers/api-lead-move.ts)
+// Requêtes en snake_case, réponses en camelCase :
+//   POST /api/leads/move → { dry_run: true, preview } | { dry_run: false, operation }
+//   POST /api/leads/move/{operation_id}/undo → { operation }
+//   GET  /api/leads/move/{operation_id} → { operation }
+// Erreurs : { error: { code, message, details? } }.
+export const leadMoveApi = {
+    movePath: "/api/leads/move",
+    operationPath: (operationId) => `/api/leads/move/${encodeURIComponent(operationId)}`,
+    undoPath: (operationId) => `/api/leads/move/${encodeURIComponent(operationId)}/undo`,
+    selection(selection) {
+        if (selection.kind === "lead_ids")
+            return { kind: "lead_ids", lead_ids: selection.lead_ids };
+        if (selection.kind === "view")
+            return { kind: "view", view_id: selection.view_id };
+        return {
+            kind: "filter", group_id: selection.group_id,
+            ...(selection.filters !== undefined ? { filters: selection.filters } : {}),
+            ...(selection.or_filters !== undefined ? { or_filters: selection.or_filters } : {}),
+            ...(selection.search !== undefined ? { search: selection.search } : {}),
+        };
+    },
+    previewBody(input) {
+        return {
+            ...(input.organization_id !== undefined ? { organization_id: input.organization_id } : {}),
+            target_group_id: input.target_group_id,
+            selection: leadMoveApi.selection(input.selection),
+            dry_run: true,
+        };
+    },
+    applyBody(input) {
+        return {
+            ...leadMoveApi.previewBody(input),
+            dry_run: false,
+            expected_plan_digest: input.expected_plan_digest,
+            idempotency_key: input.idempotency_key,
+        };
+    },
+    errorCode(body) {
+        if (!body || typeof body !== "object" || Array.isArray(body))
+            return undefined;
+        const record = body;
+        const nested = record.error && typeof record.error === "object" ? record.error : undefined;
+        for (const value of [nested?.code, record.code, record.error]) {
+            if (typeof value === "string" && /^[A-Z][A-Z0-9_]+$/.test(value))
+                return value;
+        }
+        return undefined;
+    },
+    errorMessage(body) {
+        if (!body || typeof body !== "object" || Array.isArray(body))
+            return undefined;
+        const record = body;
+        const nested = record.error && typeof record.error === "object" ? record.error : undefined;
+        const value = nested?.message ?? record.message;
+        return typeof value === "string" && value.trim() ? value : undefined;
+    },
+};
+// ── Refus et blocages expliqués en français simple ─────────────────────────
+const NO_BYPASS = "Ce refus ne se contourne pas : ne copiez pas la fiche, ne la recréez pas et ne changez pas son groupe autrement.";
+export const LEAD_MOVE_ERRORS = {
+    SELECTION_TOO_LARGE: `La sélection dépasse ${LEAD_MOVE_MAX_LEADS} fiches. Découpez la liste en lots de ${LEAD_MOVE_MAX_LEADS} au plus, ou passez par une vue ou un filtre : la prévisualisation prend alors les ${LEAD_MOVE_MAX_LEADS} premières fiches et indique combien il en reste.`,
+    SELECTION_EMPTY: "La sélection ne contient aucune fiche. Vérifiez les identifiants, la vue ou le filtre.",
+    TARGET_NOT_FOUND: "Le groupe cible est introuvable dans cette organisation. Vérifiez son identifiant avec list_lead_groups.",
+    TARGET_NOT_ACTIVE: "Le groupe cible n'est plus actif (il a été fusionné). Choisissez le groupe qui l'a remplacé.",
+    TARGET_GENERIC: "Le groupe cible n'a pas de nature déclarée (personne ou établissement). Déclarez-la d'abord avec update_lead_group (entity_kind).",
+    SCHEMA_VALUE_CONFLICT: "Un champ a des valeurs qu'aucun type ne peut accepter ensemble. Rien n'est tronqué : corrigez d'abord ces valeurs, puis relancez la prévisualisation.",
+    RELATION_CONFIG_CONFLICT: "Le groupe cible a déjà un champ de relation du même nom qui pointe vers un autre groupe. Réglez d'abord ce conflit de relation.",
+    MOVE_PLAN_STALE: "Les fiches ou les groupes ont changé depuis la prévisualisation. Relancez preview_move_leads et utilisez la nouvelle empreinte.",
+    IDEMPOTENCY_KEY_REUSED: "Cette clé d'idempotence a déjà servi pour un autre déplacement. Prenez une nouvelle clé pour ce nouveau plan.",
+    UNDO_LEADS_CHANGED: "L'annulation est refusée : certaines fiches ont changé ou ne sont plus dans le groupe cible depuis le déplacement. La liste des fiches concernées est dans le détail.",
+    UNDO_SOURCE_NOT_ACTIVE: "L'annulation est refusée : un groupe d'origine n'est plus actif.",
+    MOVE_CONFIRMATION_REQUIRED: "Pour appliquer le déplacement, il faut l'empreinte rendue par preview_move_leads (expected_plan_digest) et une clé d'idempotence.",
+    MOVE_PLAN_BLOCKED: "Le déplacement est bloqué. Relancez preview_move_leads : les blocages et les refus y sont expliqués.",
+    OPERATION_NOT_FOUND: "Ce déplacement est introuvable dans les organisations de cette clé. Vérifiez operation_id.",
+    MOVE_REFUSED_BY_DATA_GUARD: "La base a refusé le déplacement pour protéger l'identité des fiches (identité incomplète ou migration des identités en cours). Rien n'a été modifié.",
+    MOVE_SAFETY_CHECK_FAILED: "Un contrôle de sécurité a échoué pendant le déplacement. Rien n'a été modifié.",
+    WRITE_FORBIDDEN: "Cette clé API ne peut que lire : le déplacement demande le droit d'écriture.",
+    ORGANIZATION_FORBIDDEN: "Cette clé API n'a pas accès à cette organisation.",
+    UNAUTHENTICATED: "La clé API est absente ou invalide. Vérifiez-la avec test_api_key.",
+    ACTIVE_ORGANIZATION_REQUIRED: "Indiquez l'organisation (organization_id).",
+    LEAD_NOT_FOUND: "Une fiche est introuvable dans cette organisation. Vérifiez la sélection.",
+    ALREADY_IN_TARGET: "La fiche est déjà dans le groupe cible : il n'y a rien à faire.",
+    ENTITY_KIND_MISMATCH: "La fiche et le groupe cible ne sont pas de même nature (personne et établissement). Choisissez un groupe de même nature.",
+    CAMPAIGN_IN_PROGRESS: "La fiche est dans une campagne en cours ou a un envoi en attente. Retirez-la de l'audience ou attendez la fin de la campagne.",
+    QUALIFICATION_IN_PROGRESS: "Une qualification est en cours sur la fiche, son établissement ou son groupe. Attendez qu'elle se termine.",
+};
+const HTTP_MESSAGES = {
+    401: "La clé API est refusée. Vérifiez la clé configurée avec test_api_key.",
+    403: "La clé API n'a pas le droit de déplacer des fiches : il faut le droit d'écriture, et les clés assistant ne peuvent pas déplacer.",
+    404: "Le déplacement demandé est introuvable dans cette organisation.",
+};
+// Refus qu'on peut simplement retenter : pas de mention « ne se contourne pas ».
+const RETRYABLE = new Set(["MOVE_BUSY", "MOVE_FAILED", "MOVE_SAFETY_CHECK_FAILED", "INVALID_INPUT"]);
+const ACCESS = new Set(["UNAUTHENTICATED", "WRITE_FORBIDDEN", "ORGANIZATION_FORBIDDEN", "OPERATION_NOT_FOUND", "ACTIVE_ORGANIZATION_REQUIRED"]);
+export function leadMoveError(error) {
+    if (!(error instanceof LeadifyApiError))
+        return handleToolError(error);
+    const code = leadMoveApi.errorCode(error.responseBody);
+    const message = (code ? LEAD_MOVE_ERRORS[code] : undefined)
+        ?? leadMoveApi.errorMessage(error.responseBody)
+        ?? HTTP_MESSAGES[error.statusCode]
+        ?? `Le serveur Leadify a répondu par une erreur (statut ${error.statusCode}).`;
+    const refusal = Boolean(code) && !RETRYABLE.has(code) && !ACCESS.has(code) && error.statusCode < 500;
+    return toolError(refusal ? `${message} ${NO_BYPASS}` : message, {
+        code, statusCode: error.statusCode, response: error.responseBody,
+    });
+}
+function invalidInput(error) {
+    return toolError("Paramètres invalides : " + error.issues.map((issue) => `${issue.path.join(".") || "(racine)"} : ${issue.message}`).join(" ; "), { issues: error.issues });
+}
+// ── Indications pour l'agent sur le résultat de la prévisualisation ───────
+function previewGuidance(data) {
+    if (!data || typeof data !== "object")
+        return undefined;
+    const envelope = data;
+    const record = envelope.preview && typeof envelope.preview === "object" ? envelope.preview : envelope;
+    if (record.status === "BLOCKED") {
+        return "Rien ne peut être déplacé : lisez blockers et les refus par fiche, réglez la cause, puis relancez la prévisualisation. Ne contournez pas un blocage.";
+    }
+    const selection = record.selection && typeof record.selection === "object" ? record.selection : {};
+    const remaining = typeof selection.remaining === "number" ? selection.remaining : 0;
+    if (remaining > 0) {
+        return `Ce lot couvre les ${LEAD_MOVE_MAX_LEADS} premières fiches ; il en reste ${remaining}. Après move_leads, relancez preview_move_leads avec la même sélection (les fiches déplacées quittent le groupe source) jusqu'à remaining = 0.`;
+    }
+    return undefined;
+}
+const CORE_RULES = "A move keeps the same lead record: same id, with all its history (data, notes, activities, signals, campaign history, " +
+    "messages, canonical identity, company links). Only its group and the columns copying that group change. A move never merges " +
+    "two records: a lead already in the target with the same email, LinkedIn URL or identity is reported in duplicates and still " +
+    "moved as a separate record; remove it from the selection to keep it out. Each refusal (per lead) or blocker (global) comes " +
+    "with a code and a message saying what to do: follow it, never bypass it (no copy, no re-import, no delete-and-recreate). " +
+    "To reorganise leads between groups, prefer moving over add_leads copies or clone_lead_group.";
+export function registerLeadMoveTools(server, client) {
+    const api = () => client ?? getClient();
+    server.tool("preview_move_leads", "Dry run (no write) of moving leads into another lead group of the same organization. Select by lead ids, by saved view or by filter; " +
+        `at most ${LEAD_MOVE_MAX_LEADS} leads per call, larger views or filters are handled in batches (selection.remaining). Returns status ` +
+        "READY or BLOCKED, target and source groups, counts (selected, movable, refused, duplicates), the decision per lead (MOVE or REFUSE " +
+        "with refusal code and message), duplicates already in the target, schema fields to add or retype in the target (the source schema " +
+        "never changes), relation settings to add, global blockers, and expectedPlanDigest to pass to move_leads. The answer is { dry_run: true, preview }. Refusal codes: " +
+        "LEAD_NOT_FOUND, ALREADY_IN_TARGET, ENTITY_KIND_MISMATCH, CAMPAIGN_IN_PROGRESS, QUALIFICATION_IN_PROGRESS. " + CORE_RULES, previewShape, { readOnlyHint: true }, async (params) => {
+        const parsed = previewSchema.safeParse(params);
+        if (!parsed.success)
+            return invalidInput(parsed.error);
+        try {
+            const data = await api().post(leadMoveApi.movePath, leadMoveApi.previewBody(parsed.data));
+            const guidance = previewGuidance(data);
+            return toolResult(guidance && data && typeof data === "object" && !Array.isArray(data) ? { ...data, guidance } : data);
+        }
+        catch (error) {
+            return leadMoveError(error);
+        }
+    });
+    server.tool("move_leads", "Apply a move reviewed with preview_move_leads. Requires that preview's expectedPlanDigest and a unique idempotency_key, with the " +
+        "same organization, target and selection. Leadify re-checks the plan in one transaction and refuses with MOVE_PLAN_STALE if " +
+        "anything changed: preview again. Only leads marked MOVE are moved; refused leads stay where they are. Returns { dry_run: false, operation } " +
+        "with operation.operationId, to read with get_lead_move or revert with undo_move_leads. Show the preview to the user before applying. " + CORE_RULES, applyShape, async (params) => {
+        const missing = ["expected_plan_digest", "idempotency_key"].filter((key) => {
+            const value = params[key];
+            return typeof value !== "string" || value.trim() === "";
+        });
+        if (missing.length > 0) {
+            return toolError(`Le déplacement n'est pas appliqué : il manque ${missing.join(" et ")}. Lancez d'abord preview_move_leads, relisez le plan, ` +
+                "puis passez son expectedPlanDigest et une clé d'idempotence unique.", { missing });
+        }
+        const parsed = applySchema.safeParse(params);
+        if (!parsed.success)
+            return invalidInput(parsed.error);
+        try {
+            return toolResult(await api().post(leadMoveApi.movePath, leadMoveApi.applyBody(parsed.data)));
+        }
+        catch (error) {
+            return leadMoveError(error);
+        }
+    });
+    server.tool("undo_move_leads", "Undo a move: puts the leads back in their source groups with the copied columns and canonical memberships, and reverts the target " +
+        "schema and relations if they did not change since (otherwise they are kept and reported). Refused with UNDO_LEADS_CHANGED when a " +
+        "lead left the target group or its data changed since the move (the list is returned), or UNDO_SOURCE_NOT_ACTIVE when a source " +
+        "group is no longer active. A second undo returns replayed: true. Nothing is deleted or merged.", operationShape, async (params) => {
+        const parsed = operationSchema.safeParse(params);
+        if (!parsed.success)
+            return invalidInput(parsed.error);
+        try {
+            return toolResult(await api().post(leadMoveApi.undoPath(parsed.data.operation_id), {}));
+        }
+        catch (error) {
+            return leadMoveError(error);
+        }
+    });
+    server.tool("get_lead_move", "Read one move operation: who and when, target group, source groups, plan digest, moved leads with their source group, and whether " +
+        "it was undone. Use it to check a move or before undo_move_leads.", operationShape, { readOnlyHint: true }, async (params) => {
+        const parsed = operationSchema.safeParse(params);
+        if (!parsed.success)
+            return invalidInput(parsed.error);
+        try {
+            return toolResult(await api().get(leadMoveApi.operationPath(parsed.data.operation_id)));
+        }
+        catch (error) {
+            return leadMoveError(error);
+        }
+    });
+}

package/dist/tools/organizations.d.ts

@@ -1,6 +1,15 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type LeadifyClient } from "../client.js";
 export declare function assertLeadGroupsBelongToOrganization(data: unknown, organizationId: string): Array<Record<string, unknown>>;
+/** PRD-2480: the shared sidebar folder of a group, or null when it sits outside any folder. */
+export declare function leadGroupFolder(group: Record<string, unknown>): {
+    folderId: string | null;
+    folder: {
+        id: unknown;
+        name: unknown;
+        emoji: unknown;
+    } | null;
+};
 /** 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

@@ -22,6 +22,26 @@ export function assertLeadGroupsBelongToOrganization(data, organizationId) {
     }
     return leadGroups;
 }
+/** PRD-2480: the shared sidebar folder of a group, or null when it sits outside any folder. */
+export function leadGroupFolder(group) {
+    const folder = group.folder && typeof group.folder === "object" ? group.folder : null;
+    return {
+        folderId: typeof group.folderId === "string" ? group.folderId : null,
+        folder: folder ? { id: folder.id, name: folder.name, emoji: folder.emoji ?? null } : null,
+    };
+}
+/** One line of a group list: navigation fields and its folder, never schema or leads. */
+function listedLeadGroup(group) {
+    return {
+        id: group.id,
+        name: group.name,
+        organizationId: group.organizationId,
+        leadCount: group._count?.leads ?? 0,
+        published: group.published ?? false,
+        refreshEnabled: group.refreshEnabled ?? false,
+        ...leadGroupFolder(group),
+    };
+}
 /** Keep group reads navigable: never return schema, profiles, or lead data. */
 export function compactLeadGroup(group) {
     const source = group && typeof group === "object" ? group : {};
@@ -42,6 +62,7 @@ export function compactLeadGroup(group) {
         refreshEnabled: source.refreshEnabled ?? false,
         refreshFrequencyDays: source.refreshFrequencyDays ?? null,
         createdAt: source.createdAt ?? null,
+        ...leadGroupFolder(source),
     };
 }
 export function registerOrganizationTools(server, client = getClient()) {
@@ -86,25 +107,22 @@ export function registerOrganizationTools(server, client = getClient()) {
         }
     });
     server.tool("list_lead_groups", "List lead groups visible in one explicitly selected organization. Returns a compact " +
-        "navigation view only: id, name, organizationId, lead count, published and refresh state. " +
+        "navigation view only: id, name, organizationId, lead count, published and refresh state, and the " +
+        "shared sidebar folder (folderId, folder { id, name, emoji }). Pass folder_id to keep exactly the " +
+        "groups of one folder (list_lead_group_folders), or \"none\" for the groups outside any folder. " +
         "Start with discover_leadify_context when no organization_id is known.", {
         organization_id: z.string().describe("Organization ID explicitly selected from list_organizations or discover_leadify_context."),
+        folder_id: z.string().trim().min(1).optional().describe("Keep only the groups of this folder, or \"none\" for groups outside any folder."),
         limit: z.number().int().min(1).max(100).optional().default(50).describe("Maximum groups returned, bounded to 100."),
-    }, async ({ organization_id, limit }) => {
+    }, async ({ organization_id, folder_id, limit }) => {
         try {
-            const params = new URLSearchParams({ organizationId: organization_id });
-            const data = await getClient().get("/api/lead-groups", params);
+            const params = new URLSearchParams({ organizationId: organization_id, ...(folder_id ? { folderId: folder_id } : {}) });
+            const data = await client.get("/api/lead-groups", params);
             const groups = assertLeadGroupsBelongToOrganization(data, organization_id);
             return toolResult({
                 organizationId: organization_id,
-                leadGroups: groups.slice(0, limit).map((group) => ({
-                    id: group.id,
-                    name: group.name,
-                    organizationId: group.organizationId,
-                    leadCount: group._count?.leads ?? 0,
-                    published: group.published ?? false,
-                    refreshEnabled: group.refreshEnabled ?? false,
-                })),
+                ...(folder_id ? { folderId: folder_id } : {}),
+                leadGroups: groups.slice(0, limit).map(listedLeadGroup),
                 total: groups.length,
                 truncated: groups.length > limit,
             });
@@ -115,12 +133,13 @@ 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) and reports inaccessible " +
+        "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.", {
         lead_group_id: z.string().describe("Lead group ID returned by Leadify discovery or another authorized Leadify response."),
     }, async ({ lead_group_id }) => {
         try {
-            const data = await getClient().get(`/api/lead-group/${encodeURIComponent(lead_group_id)}`);
+            const data = await client.get(`/api/lead-group/${encodeURIComponent(lead_group_id)}`);
             const source = data && typeof data === "object" ? data : {};
             return toolResult({ leadGroup: compactLeadGroup(source.leadGroup) });
         }
@@ -130,13 +149,14 @@ export function registerOrganizationTools(server, client = getClient()) {
     });
     server.tool("discover_leadify_context", "Safe zero-ID entry point for Leadify. With no organization_id, lists accessible organizations " +
         "and never chooses one when several are available. With an explicit organization_id, returns " +
-        "a compact list of its lead groups. Use the returned lead_group_id with lead, campaign, persona " +
+        "a compact list of its lead groups with their folder, and the organization's shared sidebar folders. " +
+        "Use the returned lead_group_id with lead, campaign, persona " +
         "and Context Workspace tools.", {
         organization_id: z.string().optional().describe("Organization selected explicitly after discovery. Omit only for the first step."),
         limit: z.number().int().min(1).max(100).optional().default(50).describe("Maximum lead groups returned after selection."),
     }, async ({ organization_id, limit }) => {
         try {
-            const orgData = await getClient().get("/api/organizations");
+            const orgData = await client.get("/api/organizations");
             const organizations = Array.isArray(orgData.organizations)
                 ? orgData.organizations.map((org) => ({ id: org.id, name: org.name ?? null, slug: org.slug ?? null }))
                 : [];
@@ -149,11 +169,28 @@ export function registerOrganizationTools(server, client = getClient()) {
             if (!organizations.some((org) => org.id === organization_id)) {
                 return toolResult({ organizations, selectionRequired: true, message: "organization_id is not accessible to this key." });
             }
-            const groupsData = await getClient().get("/api/lead-groups", new URLSearchParams({ organizationId: organization_id }));
+            const groupsData = await client.get("/api/lead-groups", new URLSearchParams({ organizationId: organization_id }));
             const groups = assertLeadGroupsBelongToOrganization(groupsData, organization_id);
+            // The folders complete the map; a failure to read them never hides the groups.
+            let folders = null;
+            let foldersError;
+            try {
+                const folderData = await client.get("/api/lead-group-folders", new URLSearchParams({ organizationId: organization_id }));
+                folders = Array.isArray(folderData?.folders)
+                    ? folderData.folders.map((folder) => ({ id: folder.id, name: folder.name, emoji: folder.emoji ?? null, leadGroupIds: folder.leadGroupIds ?? [] }))
+                    : [];
+            }
+            catch (error) {
+                foldersError = error instanceof Error ? error.message : String(error);
+            }
             return toolResult({
                 organization: organizations.find((org) => org.id === organization_id),
-                leadGroups: groups.slice(0, limit).map((group) => ({ id: group.id, name: group.name, organizationId: group.organizationId, leadCount: group._count?.leads ?? 0, published: group.published ?? false })),
+                folders,
+                ...(foldersError ? { foldersError } : {}),
+                leadGroups: groups.slice(0, limit).map((group) => {
+                    const { refreshEnabled: _refreshEnabled, ...listed } = listedLeadGroup(group);
+                    return listed;
+                }),
                 total: groups.length,
                 truncated: groups.length > limit,
                 next: "Choose a lead_group_id, then use get_leads, get_context_workspace, or list_persona_contracts.",

package/dist/tools/views.d.ts

@@ -1,2 +1,16 @@
+import { z } from "zod";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const filterSchema: z.ZodObject<{
+    field: z.ZodString;
+    operator: z.ZodEnum<["equals", "contains", "gte", "lte", "not_equals", "not_contains", "is_true", "is_false", "is_null", "is_not_null", "activity_days_ago", "activity_count_equals", "activity_count_gte", "activity_count_lte", "bbox"]>;
+    value: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    field: string;
+    operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+    value?: unknown;
+}, {
+    field: string;
+    operator: "equals" | "contains" | "gte" | "lte" | "not_equals" | "not_contains" | "is_true" | "is_false" | "is_null" | "is_not_null" | "activity_days_ago" | "activity_count_equals" | "activity_count_gte" | "activity_count_lte" | "bbox";
+    value?: unknown;
+}>;
 export declare function registerLeadViewTools(server: McpServer): void;

package/dist/tools/views.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { getClient } from "../client.js";
 import { handleToolError, toolResult } from "../types.js";
-const filterSchema = z.object({
+export const filterSchema = z.object({
     field: z.string().describe("A standard, virtual, or selected lead-group schema field."),
     operator: z.enum(["equals", "contains", "gte", "lte", "not_equals", "not_contains", "is_true", "is_false", "is_null", "is_not_null", "activity_days_ago", "activity_count_equals", "activity_count_gte", "activity_count_lte", "bbox"]),
     value: z.unknown().optional(),

package/package.json

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