@agifyai/leadify-mcp 8.7.6 → 8.8.0

package/README.md

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

package/dist/server.js

@@ -4,6 +4,7 @@ import { registerLeadTools } from "./tools/leads.js";
 import { registerSchemaTools } from "./tools/schema.js";
 import { registerLogTools } from "./tools/logs.js";
 import { registerCampaignTools } from "./tools/campaigns.js";
+import { registerCampaignWizardTools } from "./tools/campaign_wizard.js";
 import { registerSignalTools } from "./tools/signals.js";
 import { registerActivityTools } from "./tools/activities.js";
 import { registerDataSourceTools } from "./tools/datasources.js";
@@ -43,6 +44,7 @@ export function createServer() {
     registerSchemaTools(server);
     registerLogTools(server);
     registerCampaignTools(server);
+    registerCampaignWizardTools(server);
     registerSignalTools(server);
     registerActivityTools(server);
     registerContextWorkspaceTools(server);

package/dist/tools/campaign_wizard.d.ts

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

package/dist/tools/campaign_wizard.js

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

package/package.json

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