@agifyai/leadify-mcp 8.5.4 → 8.6.1

package/README.md

@@ -123,7 +123,8 @@ src/
     ├── leads.ts
     ├── events.ts
     ├── campaigns.ts
-    ├── dataroom.ts
+    ├── context_workspace.ts
+    ├── context_entities.ts
     ├── personas.ts
     └── ...           # un fichier = un domaine fonctionnel
 ```
@@ -245,12 +246,12 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `get_campaign_logs` | Récupérer les logs de campagne avec filtres et pagination. |
 | `delete_campaign_log` | Supprimer une entrée de log de campagne. |
 | `update_campaign_stats` | Mettre à jour les statistiques d'email d'une campagne pour un groupe de leads. |
-| `create_campaign` | Créer une campagne DRAFT mono-canal rattachée à un groupe de leads. `channel` (`LINKEDIN` ou `EMAIL`) est obligatoire ; `start_at`, `end_at` et `timezone` configurent la fenêtre métier. À `end_at`, Leadify ferme la campagne idempotemment, annule uniquement les jobs prouvablement pré-fournisseur et préserve les autres pour réconciliation. |
-| `update_campaign_configuration` | Corriger le canal ou la fenêtre d'une campagne DRAFT encore ouverte, sans activation ni enrôlement. |
-| `list_campaigns` | Lister compactement les campagnes d'une organisation explicitement sélectionnée et leur statut courant. |
-| `get_campaign` | Récupérer les détails d'une campagne et ses KPIs temps réel. |
-| `update_campaign_status` | Changer le statut d'une campagne (DRAFT, ACTIVE, PAUSED, COMPLETED). |
-| `export_campaign` | Exporter les statistiques complètes d'une campagne en CSV. |
+| `create_campaign` | Créer une campagne DRAFT mono-canal rattachée à un Lead Group qui possède déjà sa paire Persona–Offre. Aucun `persona_id` ou contexte indépendant n’est accepté au niveau Campagne. `channel` (`LINKEDIN` ou `EMAIL`) est obligatoire ; `start_at` inclusif, `end_at` exclusif et `timezone` IANA configurent la fenêtre métier. À `end_at`, Leadify met la campagne en pause réversible (`WINDOW_END`) sans la clôturer. |
+| `update_campaign_configuration` | Modifier la fenêtre de toute campagne encore `OPEN`; le canal reste modifiable uniquement en DRAFT. Prolonger `end_at` dans le futur ou le supprimer relance automatiquement une pause `WINDOW_END` après validation du fournisseur, mais jamais une pause manuelle. La fenêtre demandée reste enregistrée si cette validation échoue. |
+| `list_campaigns` | Lister compactement les campagnes d'une organisation explicitement sélectionnée, avec état effectif, fenêtre, motif de pause et clôture. |
+| `get_campaign` | Récupérer les détails d'une campagne, son état effectif, sa clôture et son éventuel rapport final figé, ainsi que ses KPIs temps réel. |
+| `update_campaign_status` | Changer le statut d'une campagne. `PAUSED` est une pause manuelle réversible ; `COMPLETED` déclenche la clôture définitive terminale et son rapport final immuable. |
+| `export_campaign` | Exporter les statistiques en CSV ; après clôture définitive, l'export provient du rapport final figé. |
 | `signal_upsert` | Créer ou mettre à jour un signal de business intelligence (INFO, CRITICAL, GOLDEN). Remet le state à `active`. |
 | `signal_expire` | Expirer un signal (événement périmé). Flip de `state` uniquement. |
 | `signal_disable` | Désactiver un signal (faux positif / écarté manuellement). Flip de `state` uniquement. |
@@ -262,8 +263,18 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `unipile_read_messages` | Lire les messages LinkedIn Unipile bornés d'un profil explicitement sélectionné. |
 | `leadify_read_activity_feed` | Lire l'audit borné d'un lead ; le feed ne constitue jamais une preuve de réponse. |
 | `get_commercial_truth` | Réconcilier CRM, email, LinkedIn, Unipile et activité avec un statut, une fraîcheur et une action recommandée ; aucune écriture ni envoi. |
-| `compile_context_pack` | Compiler en lecture seule un Context Pack canonique depuis une cible explicite (`organization`, `lead_group`, `campaign`, `account`, `person`) ou un couple lead + campagne pour `WRITE_OUTREACH`. Retourne publications courantes, sources, freshness, contradictions et provenance. N’utilise jamais la Data Room legacy ni ne choisit de cible implicite. |
-| `get_context_workspace` | Lire le Context Workspace canonique versionné (`company_brain` ou `gtm_playbook`) d'une organisation explicitement sélectionnée. Retourne le brouillon et la dernière version publiée. |
+| `compile_context_pack` | Compiler en lecture seule un Context Pack canonique depuis une cible explicite (`organization`, `lead_group`, `campaign`, `account`, `person`) ou un couple lead + campagne pour `WRITE_OUTREACH`. Retourne publications courantes, sources, freshness, contradictions et provenance, sans choisir de cible implicite. |
+| `get_context_workspace` | Lire le seul Context Workspace encore exposé et versionné : le `company_brain` d'une organisation explicitement sélectionnée. Retourne le brouillon et la dernière version publiée ; l'historique GTM reste stocké mais n'est plus exposé. |
+| `list_verticals` / `get_vertical` | Lister ou lire les Verticales JSON simples d’une organisation explicitement sélectionnée, avec leurs Personas et Offres liées. |
+| `create_vertical` | Créer une Verticale tenant-scoped en `DRAFT`, sans activation ni sélection implicite. Son schéma JSON fermé porte les règles sectorielles et `commercialExperience` ; les métadonnées de preuve/source/provenance et les champs propres à l’Offre sont refusés. |
+| `update_vertical` | Modifier le nom et/ou des clés JSON d’une Verticale après relecture. `expected_updated_at` est obligatoire ; une révision périmée est refusée avec `409` et impose une nouvelle lecture. Une Verticale `ACTIVE` repasse en `DRAFT`. |
+| `change_vertical_status` | Passer une Verticale entre `DRAFT`, `ACTIVE` et `ARCHIVED` avec contrôle optimiste, readiness et protection des références. |
+| `list_offers` / `get_offer` | Lister ou lire les Offres JSON simples tenant-scoped, leurs Verticales et leurs Lead Groups. |
+| `create_offer` | Créer une Offre tenant-scoped en `DRAFT`, sans relation ni activation implicite. Son schéma JSON fermé est l'unique propriétaire des allégations, résultats démontrés et cas clients ; les Verticales référencent les identifiants de ces cas. |
+| `update_offer` | Modifier le nom et/ou des clés JSON d’une Offre avec `expected_updated_at` obligatoire et refus `409` de toute écriture périmée. Une Offre `ACTIVE` repasse en `DRAFT`. |
+| `change_offer_status` | Passer une Offre entre `DRAFT`, `ACTIVE` et `ARCHIVED` avec contrôle optimiste, readiness et protection des références. |
+| `link_vertical_offer` / `unlink_vertical_offer` | Créer ou retirer la relation SQL tenant-scoped. Les `updatedAt` lus pour les deux objets sont obligatoires ; aucune relation cross-tenant ou dépendance Lead Group n’est contournée. |
+| `preview_resolved_context` | Résoudre sans effet Company Brain + Verticale + Offre liée + Persona, ainsi que sender/CTA du Lead Group lorsqu'ils existent. Retourne le digest courant avec `dryRun:true`, `persisted:false`, `noSend:true`, `runtimeApplied:false` et `externalActivation:0`. |
 | `list_canonical_relationships` | Lire les liens canoniques typés d'une organisation, dans les deux directions. |
 | `create_canonical_relationship` | Créer un lien canonique tenant-scoped et idempotent entre deux identités fortes. |
 | `update_canonical_relationship` | Modifier, restaurer ou tombstoner un lien via le ledger transactionnel partagé. |
@@ -271,20 +282,12 @@ 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. |
-| `update_company_brain_sections` | Modifier uniquement les sections indiquées du Company Brain : le MCP relit le brouillon ou la dernière publication, fusionne les sections ciblées, puis sauvegarde avec révision attendue et clé d'idempotence. |
-| `update_gtm_playbook_sections` | Modifier uniquement les sections indiquées du GTM Playbook, avec la même lecture-fusion-révision atomiquement contrôlée. |
-| `publish_context_workspace` | Publier une révision prête du Context Workspace après confirmation explicite (`confirm_publish: true`). Admin de l'organisation requis ; les raisons de non-readiness sont renvoyées par le serveur. |
-| `describe_company_info_schema` | Lire le schéma companyInfo v2 mirroré côté MCP (enums, max-lengths, sections, patch tool par section). À appeler avant la première update. |
-| `update_company_info_identity` | Patch name + website. Reads + merges + PUTs le full v2 payload. |
-| `update_company_info_snapshot` | Patch du bloc snapshot (pitchOneLiner, marketSpecialty, stage, salesTeamSizeFR, geo, constraints). geo merge shallow. |
-| `update_company_info_constraint` | Add / replace / remove une seule contrainte dans snapshot.constraints[]. label + type enum + note≤150. Cap 10. |
-| `update_company_info_product` | Add / replace / remove un seul produit dans products[]. category enum strict + regulatory sub-block. Cap 5. |
-| `update_company_info_economics` | Patch du bloc economics (pricingModel, ticketRange, salesCycleMonths, triggers, defaultBaseline). |
-| `update_company_info_product_icp` | Add / replace / remove un seul ICP dans productICPs[]. Lookup par productId (must match a products[].name). Cap 5. |
-| `update_company_info_proof_wording` | Patch du bloc proofWording (keyMetrics, miniStories, forbiddenWords). |
-| `upsert_persona` | Créer ou mettre à jour atomiquement un Persona, avec `schema_packs` obligatoire à la création. |
-| `update_persona_schema_packs` | Remplacer uniquement les CRM Schema Packs d’un Persona et relire les preuves de readiness des groupes liés. |
-| `get_persona` | Récupérer un persona par son ID. |
+| `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. |
+| `publish_context_workspace` | Publier une révision prête du Company Brain après confirmation explicite (`confirm_publish: true`). Admin de l'organisation requis ; les raisons de non-readiness sont renvoyées par le serveur. |
+| `upsert_persona` | Créer ou mettre à jour un Persona strictement lié à une organisation et à une Verticale ; `schema_packs` est obligatoire à la création et `expected_updated_at` à chaque mise à jour. Les Personas globales ou orphelines ne sont jamais créées. |
+| `change_persona_status` | Passer un Persona entre `DRAFT`, `ACTIVE` et `ARCHIVED` avec le même verrou `updated_at`, readiness et protection des références. |
+| `update_persona_schema_packs` | Remplacer uniquement les CRM Schema Packs d’un Persona tenant-scoped avec `expected_updated_at`, puis relire la readiness des groupes liés. |
+| `get_persona` | Récupérer un Persona par son ID et son organisation explicite. Les anciennes Personas globales/orphelines sont exclues. |
 | `get_lead_group_persona` | Récupérer le persona assigné à un groupe de leads. |
 | `list_data_sources` | Lister toutes les sources de données configurées (par pays puis nom). |
 | `create_data_source` | Créer une nouvelle source de données (admin uniquement). |
@@ -298,7 +301,7 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `update_outreach_case_study` | Ajouter / remplacer / supprimer un case study par index, sans re-envoyer la liste. |
 | `update_outreach_urls` | Patch booking_url et/ou website_url uniquement. |
 | `set_outreach_connection_request` | Toggle du flag connectionRequestEnabled (LinkedIn invite vs cold DM). |
-| `trigger_outreach` | Générer un message d'outreach via l'agent Trigger.dev (dry-run par défaut). `force=true` pour re-générer sur un lead déjà traité. |
+| `trigger_outreach` | Générer un message via le runtime Write Outreach (dry-run par défaut). Le rédacteur libre peut fournir un `context_selection` complet Verticale–Offre–Persona ; aucun objet ou défaut n’est inféré. Avant une écriture, le runtime relit le digest et refuse toute persistance si le contexte a changé. |
 | `append_fine_tuning` | Appendre du contenu à une section du Fine Tuning (nonNegotiableRules, pitfalls, structure, examples). Toujours en mode append — garantie contractuelle. |
 | `set_fine_tuning_output_config` | Remplacer uniquement la configuration métier de sorties d’un Fine Tuning (`linkedinConnection`, `linkedinMessage`, `email`, activations et quantités). Préserve Markdown, langues et fallback ; ne génère, ne planifie, n’active ni n’envoie aucun outreach. |
 | `pipeline_next_lead` | Sélectionner le prochain lead à traiter (score descendant, sans message). Exclusion des IDs déjà vus, limit 1-5. |

package/dist/server.js

@@ -17,6 +17,7 @@ import { registerLeadViewTools } from "./tools/views.js";
 import { registerRelationshipTools } from "./tools/relationships.js";
 import { registerCommercialTruthTools } from "./tools/commercial_truth.js";
 import { registerEventTools } from "./tools/events.js";
+import { registerContextEntityTools } from "./tools/context_entities.js";
 import { MCP_SERVER_NAME, MCP_VERSION } from "./version.js";
 export function createServer() {
     const server = new McpServer({
@@ -37,6 +38,7 @@ export function createServer() {
     registerSignalTools(server);
     registerActivityTools(server);
     registerContextWorkspaceTools(server);
+    registerContextEntityTools(server);
     registerDataSourceTools(server);
     registerPersonaTools(server);
     registerPipelineTools(server);

package/dist/tools/campaigns.js

@@ -2,6 +2,14 @@ import { z } from "zod";
 import { getClient } from "../client.js";
 import { toolResult, handleToolError } from "../types.js";
 const CAMPAIGN_STATUSES = ["DRAFT", "ACTIVE", "PAUSED", "COMPLETED"];
+const CAMPAIGN_EFFECTIVE_STATES = [
+    "DRAFT",
+    "SCHEDULED",
+    "ACTIVE",
+    "PAUSED_MANUAL",
+    "PAUSED_WINDOW_END",
+    "CLOSED",
+];
 function assertCampaignBelongsToOrganization(data, organizationId) {
     if (!data || typeof data !== "object") {
         throw new Error("Leadify returned an invalid campaign response");
@@ -89,20 +97,18 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
     });
     // ── create_campaign ────────────────────────────────────────────────────
     server.tool("create_campaign", "Create a mono-channel DRAFT campaign with an explicit channel, optional ISO-8601 start/end " +
-        "window, and IANA timezone. At endAt Leadify closes the campaign idempotently, cancels only " +
-        "pre-provider jobs, and preserves any provider-barrier job for reconciliation.", {
+        "window, and IANA timezone. startAt is inclusive and endAt is exclusive. Reaching endAt " +
+        "reversibly pauses the campaign with reason WINDOW_END while closure remains OPEN; it never " +
+        "creates the permanent closure report. The selected Lead Group already owns the Persona and " +
+        "Offer; Campaign never accepts an independent context selection.", {
         name: z.string().describe("Campaign name."),
         lead_group_id: z.string().describe("ID of the lead group to associate."),
         channel: z.enum(["LINKEDIN", "EMAIL"]).describe("Required effective delivery channel. Create separate campaigns for LinkedIn and email."),
         start_at: z.string().datetime().optional().describe("Optional inclusive campaign start timestamp in ISO-8601 UTC."),
-        end_at: z.string().datetime().optional().describe("Optional exclusive campaign end timestamp in ISO-8601 UTC; must be after start_at."),
+        end_at: z.string().datetime().optional().describe("Optional exclusive campaign end timestamp in ISO-8601 UTC; must be after start_at. Reaching it pauses, but does not close, the campaign."),
         timezone: z.string().min(1).optional().describe("IANA timezone used for the campaign business window, for example Europe/Paris."),
         description: z.string().optional().describe("Optional description."),
-        persona_id: z
-            .string()
-            .optional()
-            .describe("ID of the persona to assign (optional)."),
-    }, async ({ name, lead_group_id, channel, start_at, end_at, timezone, description, persona_id }) => {
+    }, async ({ name, lead_group_id, channel, start_at, end_at, timezone, description }) => {
         try {
             const body = {
                 name,
@@ -117,8 +123,6 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
                 body.timezone = timezone;
             if (description !== undefined)
                 body.description = description;
-            if (persona_id !== undefined)
-                body.personaId = persona_id;
             const data = await (writeClient ?? getClient()).post("/api/campaign", body);
             return toolResult(data);
         }
@@ -126,12 +130,16 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
             return handleToolError(error);
         }
     });
-    server.tool("update_campaign_configuration", "Correct an open DRAFT campaign's channel or lifecycle window before activation. This tool refuses ACTIVE, PAUSED, COMPLETED, or closed campaigns and never activates or enrolls prospects.", {
+    server.tool("update_campaign_configuration", "Edit the lifecycle window of any OPEN campaign; changing channel remains limited to DRAFT. " +
+        "Extending endAt into the future or removing it automatically resumes only a campaign paused " +
+        "because WINDOW_END, after provider validation and immediate replanning. A MANUAL pause never " +
+        "auto-resumes. The requested window remains saved when provider validation fails, and a CLOSED " +
+        "campaign is terminal.", {
         id: z.string().describe("Campaign ID."),
-        channel: z.enum(["LINKEDIN", "EMAIL"]).optional(),
-        start_at: z.string().datetime().nullable().optional(),
-        end_at: z.string().datetime().nullable().optional(),
-        timezone: z.string().min(1).optional(),
+        channel: z.enum(["LINKEDIN", "EMAIL"]).optional().describe("Delivery channel; mutable only while status is DRAFT."),
+        start_at: z.string().datetime().nullable().optional().describe("Inclusive UTC start timestamp, or null to remove the lower bound."),
+        end_at: z.string().datetime().nullable().optional().describe("Exclusive UTC end timestamp, or null to remove the upper bound. A future value or null can auto-resume only a WINDOW_END pause."),
+        timezone: z.string().min(1).optional().describe("IANA timezone used for the business window, for example Europe/Paris."),
     }, async ({ id, channel, start_at, end_at, timezone }) => {
         try {
             const body = {};
@@ -151,8 +159,9 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
     });
     // ── get_campaign ───────────────────────────────────────────────────────
     server.tool("get_campaign", "Retrieve a campaign chosen from list_campaigns, scoped to the explicitly selected " +
-        "organization. Includes its normalized current status (DRAFT, ACTIVE, PAUSED, or COMPLETED) " +
-        "and real-time KPIs. Never use campaign logs as the source of status.", {
+        "organization. Includes status, effectiveState, pauseReason, pausedAt, window, terminal " +
+        "closure metadata, immutable final report when present, and real-time KPIs. Never use " +
+        "campaign logs as the source of lifecycle state.", {
         id: z.string().describe("Campaign ID."),
         organization_id: z.string().describe("Organization selected explicitly via discover_leadify_context or list_organizations."),
     }, async ({ id, organization_id }) => {
@@ -165,9 +174,10 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
         }
     });
     // ── list_campaigns ─────────────────────────────────────────────────────
-    server.tool("list_campaigns", "List campaigns in one explicitly selected organization with compact current status metadata. " +
-        "Use this after discover_leadify_context to identify ACTIVE, DRAFT, PAUSED, or COMPLETED " +
-        "campaigns without reading historical logs.", {
+    server.tool("list_campaigns", "List campaigns in one explicitly selected organization with compact persisted and effective " +
+        "lifecycle metadata. Use effectiveState to distinguish SCHEDULED, ACTIVE, a manual pause, an " +
+        "end-of-window pause, and permanent closure without reading historical logs. Fetch get_campaign " +
+        "for the immutable final report.", {
         organization_id: z.string().describe("Organization selected explicitly via discover_leadify_context or list_organizations."),
         status: z.enum(CAMPAIGN_STATUSES).optional().describe("Optional current-status filter."),
         limit: z.number().int().min(1).max(100).optional().default(50).describe("Maximum campaigns returned, bounded to 100."),
@@ -188,24 +198,46 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
                 if (!CAMPAIGN_STATUSES.includes(campaign.status)) {
                     throw new Error("Leadify returned a campaign with an invalid current status");
                 }
+                if (!CAMPAIGN_EFFECTIVE_STATES.includes(campaign.effectiveState)) {
+                    throw new Error("Leadify returned a campaign with an invalid effective state");
+                }
+                const closure = campaign.closure;
+                if (!closure || typeof closure !== "object") {
+                    throw new Error("Leadify returned a campaign without closure metadata");
+                }
+                const closureRecord = closure;
                 return {
                     id: campaign.id,
                     name: campaign.name,
                     status: campaign.status,
+                    effectiveState: campaign.effectiveState,
                     channel: campaign.channel,
                     leadGroupId: campaign.leadGroupId,
+                    startAt: campaign.startAt,
+                    endAt: campaign.endAt,
+                    timezone: campaign.timezone,
+                    pauseReason: campaign.pauseReason,
+                    pausedAt: campaign.pausedAt,
+                    closure: {
+                        state: closureRecord.state,
+                        closedAt: closureRecord.closedAt,
+                        terminal: closureRecord.terminal,
+                        reportAvailable: closureRecord.report !== null && closureRecord.report !== undefined,
+                    },
                     createdAt: campaign.createdAt,
                     updatedAt: campaign.updatedAt,
                 };
             });
             const filtered = status ? campaigns.filter((campaign) => campaign.status === status) : campaigns;
             const statusCounts = Object.fromEntries(CAMPAIGN_STATUSES.map((value) => [value, campaigns.filter((campaign) => campaign.status === value).length]));
+            const effectiveStateCounts = Object.fromEntries(CAMPAIGN_EFFECTIVE_STATES.map((value) => [value, campaigns.filter((campaign) => campaign.effectiveState === value).length]));
             return toolResult({
                 organizationId: organization_id,
                 campaigns: filtered.slice(0, limit),
                 total: filtered.length,
                 truncated: filtered.length > limit,
                 statusCounts,
+                effectiveStateCounts,
             });
         }
         catch (error) {
@@ -214,8 +246,9 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
     });
     // ── update_campaign_status ─────────────────────────────────────────────
     server.tool("update_campaign_status", "Change a campaign's workflow status. Allowed values: DRAFT, ACTIVE, PAUSED, COMPLETED. " +
-        "Moving to ACTIVE starts outbound execution; PAUSED halts it; COMPLETED marks the " +
-        "campaign as finished. Always confirm with the user before calling this tool.", {
+        "Moving to ACTIVE starts outbound execution; PAUSED is a reversible manual pause; COMPLETED " +
+        "means explicit permanent closure and creates the immutable final report. Permanent closure is " +
+        "terminal and cannot be reopened. Always confirm with the user before calling this tool.", {
         id: z.string().describe("Campaign ID."),
         status: z
             .enum(["DRAFT", "ACTIVE", "PAUSED", "COMPLETED"])
@@ -230,8 +263,9 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
         }
     });
     // ── export_campaign ────────────────────────────────────────────────────
-    server.tool("export_campaign", "Export a campaign's full statistics and metrics as CSV. Returns the raw CSV text. " +
-        "Use this for external analysis or reporting.", {
+    server.tool("export_campaign", "Export a campaign's statistics and metrics as CSV. A permanently closed campaign is exported " +
+        "from its immutable final report, so late replies remain visible in current activity without " +
+        "rewriting the export. Returns the raw CSV text.", {
         id: z.string().describe("Campaign ID."),
     }, async ({ id }) => {
         try {