@agifyai/leadify-mcp 1.4.1

package/dist/tools/logs.js

@@ -0,0 +1,181 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { toolResult, handleToolError } from "../types.js";
+// ─── Shared log-input schema ───────────────────────────────────────────────
+const logLevelEnum = z.enum(["INFO", "WARNING", "ERROR"]);
+const campaignLogInput = z.object({
+    campaign_slug: z.string().describe("Campaign identifier slug (e.g. 'campaign-2024-q1')."),
+    campaign_name: z
+        .string()
+        .describe("Human-readable campaign name (required by the API)."),
+    lead_id: z.string().describe("ID of the lead this log entry is about."),
+    action: z.string().describe("Action performed (e.g. 'Email sent', 'Call made')."),
+    message: z.string().describe("Human-readable description of what happened."),
+    execution_id: z.number().int().describe("n8n execution ID that triggered this action."),
+    workflow_id: z.number().int().describe("n8n workflow ID that triggered this action."),
+    workflow: z.string().describe("Name of the n8n workflow."),
+    workflow_url: z.string().describe("Full URL to the n8n workflow."),
+    execution_url: z.string().describe("Full URL to the n8n execution."),
+    level: logLevelEnum.describe("Log severity level."),
+    lemlist_activity_id: z
+        .string()
+        .optional()
+        .describe("Lemlist activity ID, if this log originates from a Lemlist event."),
+    error_code: z
+        .string()
+        .optional()
+        .describe("Error code if the action failed (e.g. 'SMTP_TIMEOUT', 'RATE_LIMITED')."),
+    retry_count: z.number().int().optional().describe("Number of retry attempts. Defaults to 0."),
+});
+function mapLog(log) {
+    const body = {
+        campaignSlug: log.campaign_slug,
+        campaignName: log.campaign_name,
+        leadId: log.lead_id,
+        action: log.action,
+        message: log.message,
+        executionId: log.execution_id,
+        workflowId: log.workflow_id,
+        workflow: log.workflow,
+        workflowUrl: log.workflow_url,
+        executionUrl: log.execution_url,
+        level: log.level,
+    };
+    if (log.lemlist_activity_id !== undefined)
+        body.lemlistActivityId = log.lemlist_activity_id;
+    if (log.error_code !== undefined)
+        body.errorCode = log.error_code;
+    if (log.retry_count !== undefined)
+        body.retryCount = log.retry_count;
+    return body;
+}
+// ─── Tool registrations ────────────────────────────────────────────────────
+export function registerLogTools(server) {
+    // ── add_campaign_log ───────────────────────────────────────────────────
+    server.tool("add_campaign_log", "Record a single campaign activity log entry for a specific lead. Logs track actions " +
+        "like emails sent, calls made, or workflow executions, linking them to a campaign " +
+        "slug and n8n workflow/execution metadata. Each log has a severity level " +
+        "(INFO, WARNING, ERROR). Requires admin permissions. Use this to build an audit " +
+        "trail of campaign interactions with leads. For bulk log ingestion, use " +
+        "add_campaign_logs instead.", campaignLogInput.shape, async (params) => {
+        try {
+            const data = await getClient().post("/add-lead-log", mapLog(params));
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── add_campaign_logs ──────────────────────────────────────────────────
+    server.tool("add_campaign_logs", "Record multiple campaign log entries in a single call. Same schema as add_campaign_log, " +
+        "but accepts an array of logs for efficient bulk ingestion (e.g. when replaying " +
+        "a batch of n8n workflow events). Requires admin permissions.", {
+        logs: z
+            .array(campaignLogInput)
+            .min(1)
+            .describe("Array of campaign log entries to create (minimum 1)."),
+    }, async ({ logs }) => {
+        try {
+            const data = await getClient().post("/add-lead-log", logs.map(mapLog));
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── get_campaign_logs ──────────────────────────────────────────────────
+    server.tool("get_campaign_logs", "Retrieve campaign activity logs with flexible filtering by campaign slug, lead ID, " +
+        "lead group, action type, severity level, and date range. Supports pagination and " +
+        "sorting by createdAt, level, action, or campaignSlug. Returns log entries enriched " +
+        "with basic lead data. Requires admin permissions. Use this to audit campaign " +
+        "activity, investigate errors, or review a specific lead's interaction history.", {
+        campaign_slug: z.string().optional().describe("Filter by campaign slug."),
+        lead_id: z
+            .string()
+            .optional()
+            .describe("Filter by lead ID — returns all logs for that lead."),
+        leadgroup_id: z
+            .string()
+            .optional()
+            .describe("Filter by lead group ID — returns logs for all leads in the group."),
+        action: z
+            .string()
+            .optional()
+            .describe("Filter by action (partial match). E.g. 'Email' matches 'Email sent'."),
+        level: logLevelEnum.optional().describe("Filter by severity level."),
+        date_from: z
+            .string()
+            .optional()
+            .describe("Start date filter in ISO 8601 format (e.g. '2024-01-01T00:00:00Z')."),
+        date_to: z
+            .string()
+            .optional()
+            .describe("End date filter in ISO 8601 format."),
+        page: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Page number (1-based). Defaults to 1."),
+        limit: z
+            .number()
+            .int()
+            .positive()
+            .max(100)
+            .optional()
+            .describe("Results per page. Defaults to 50, max 100."),
+        sort_by: z
+            .enum(["createdAt", "level", "action", "campaignSlug"])
+            .optional()
+            .describe("Field to sort by. Defaults to 'createdAt'."),
+        sort_order: z
+            .enum(["asc", "desc"])
+            .optional()
+            .describe("Sort direction. Defaults to 'desc'."),
+    }, async (params) => {
+        try {
+            const qp = new URLSearchParams();
+            if (params.campaign_slug)
+                qp.set("campaign_slug", params.campaign_slug);
+            if (params.lead_id)
+                qp.set("lead_id", params.lead_id);
+            if (params.leadgroup_id)
+                qp.set("leadgroup_id", params.leadgroup_id);
+            if (params.action)
+                qp.set("action", params.action);
+            if (params.level)
+                qp.set("level", params.level);
+            if (params.date_from)
+                qp.set("date_from", params.date_from);
+            if (params.date_to)
+                qp.set("date_to", params.date_to);
+            if (params.page !== undefined)
+                qp.set("page", String(params.page));
+            if (params.limit !== undefined)
+                qp.set("limit", String(params.limit));
+            if (params.sort_by)
+                qp.set("sort_by", params.sort_by);
+            if (params.sort_order)
+                qp.set("sort_order", params.sort_order);
+            const data = await getClient().get("/get-lead-logs", qp);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── delete_campaign_log ────────────────────────────────────────────────
+    server.tool("delete_campaign_log", "Delete a single campaign log entry by its ID. This action is irreversible. " +
+        "Requires admin permissions. Use get_campaign_logs first to find the log ID. " +
+        "Always confirm with the user before calling this tool.", {
+        id: z.string().describe("ID of the campaign log entry to delete."),
+    }, async ({ id }) => {
+        try {
+            const data = await getClient().post("/delete-lead-log", { id });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/tools/organizations.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerOrganizationTools(server: McpServer): void;

package/dist/tools/organizations.js

@@ -0,0 +1,17 @@
+import { getClient } from "../client.js";
+import { toolResult, handleToolError } from "../types.js";
+export function registerOrganizationTools(server) {
+    // ── list_organizations ─────────────────────────────────────────────────
+    server.tool("list_organizations", "List every organization accessible to the caller, returning each with id, name, and " +
+        "optional slug. Use this as the starting point when you need an organization_id — " +
+        "e.g. before create_lead_group, clone_lead_group, upsert_persona (org-scoped), " +
+        "or move_persona.", {}, async () => {
+        try {
+            const data = await getClient().get("/api/organizations");
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/tools/outreach_settings.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerOutreachSettingsTools(server: McpServer): void;

package/dist/tools/outreach_settings.js

@@ -0,0 +1,397 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { toolResult, toolError, handleToolError } from "../types.js";
+// ── Schemas mirror apps/server/src/lib/outreach-settings-schemas.ts ────────
+const sequenceBlock = z
+    .object({
+    goal: z.string().optional(),
+    coreElements: z.array(z.string()).optional(),
+})
+    .passthrough();
+const positioning = z
+    .object({
+    dream: z.string().max(200).optional(),
+    fear: z.string().max(200).optional(),
+    whyNow: z.string().max(200).optional(),
+})
+    .passthrough();
+const sequenceDesign = z
+    .object({
+    connexion: sequenceBlock.optional(),
+    linkedin: z
+        .object({
+        one: sequenceBlock.optional(),
+        two: sequenceBlock.optional(),
+        three: sequenceBlock.optional(),
+    })
+        .partial()
+        .passthrough()
+        .optional(),
+    email: z
+        .object({
+        one: sequenceBlock.optional(),
+        two: sequenceBlock.optional(),
+        three: sequenceBlock.optional(),
+    })
+        .partial()
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+const rules = z
+    .object({
+    forbidden: z.array(z.string()).optional(),
+    priority: z.array(z.string()).optional(),
+    format: z
+        .object({
+        signatureEmail: z.string().optional(),
+        signatureLinkedin: z.string().optional(),
+        vouvoiement: z.boolean().optional(),
+        bannedChars: z.array(z.string()).optional(),
+        bannedStyles: z.array(z.string()).optional(),
+        maxWordsPerSentence: z.number().int().positive().optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+const caseStudy = z
+    .object({
+    title: z.string().min(1),
+    summary: z.string().max(200),
+    idealFor: z.string().optional(),
+    proofPoints: z.array(z.string()).optional(),
+})
+    .passthrough();
+const urlValue = z
+    .union([z.literal(""), z.string().url()])
+    .nullable()
+    .optional();
+async function fetchCurrentSettings(leadGroupId) {
+    const data = await getClient().get(`/api/lead-group/${encodeURIComponent(leadGroupId)}/outreach-settings`);
+    return data;
+}
+async function putPartial(leadGroupId, body) {
+    return getClient().put(`/api/lead-group/${encodeURIComponent(leadGroupId)}/outreach-settings`, body);
+}
+export function registerOutreachSettingsTools(server) {
+    // ── get_outreach_settings ──────────────────────────────────────────────
+    server.tool("get_outreach_settings", "Get the outreach settings (positioning, sequence design, rules, URLs, case studies) " +
+        "for a specific lead group / campaign. The settings drive the [Leadify] Outreach agent " +
+        "preflight. GET auto-creates a row with defaults on first read.", {
+        lead_group_id: z.string().describe("Lead group ID."),
+    }, async ({ lead_group_id }) => {
+        try {
+            const data = await getClient().get(`/api/lead-group/${encodeURIComponent(lead_group_id)}/outreach-settings`);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── update_outreach_settings ───────────────────────────────────────────
+    // Full-form escape hatch: set the whole block at once. Prefer the
+    // granular tools below when you only want to touch a single slot / field.
+    server.tool("update_outreach_settings", "Full-form update (escape hatch). Replaces JSON blocks wholesale when " +
+        "provided — if you only want to tweak a single slot or sub-field, prefer " +
+        "update_outreach_positioning / update_outreach_sequence_slot / " +
+        "update_outreach_rules / update_outreach_case_study / update_outreach_urls / " +
+        "set_outreach_connection_request, which do safe read-modify-write merges.", {
+        lead_group_id: z.string().describe("Lead group ID."),
+        connection_request_enabled: z
+            .boolean()
+            .optional()
+            .describe("If true, first touchpoint is a LinkedIn connection request; if false, " +
+            "card_linkedin_one is written as a cold message."),
+        positioning: positioning.optional().describe("Value Equation — 3 short phrases (200 chars max each): dream (what this lead " +
+            "group wants), fear (what they dread), whyNow (why act now rather than later)."),
+        sequence_design: sequenceDesign
+            .optional()
+            .describe("Per-message blueprints keyed by channel/slot (connexion, linkedin.one/two/three, " +
+            "email.one/two/three). Each block = {goal, coreElements[]}."),
+        rules: rules
+            .optional()
+            .describe("Formatting/content rules: forbidden phrases, priority points, and format " +
+            "(signatures, vouvoiement, bannedChars, bannedStyles, maxWordsPerSentence)."),
+        booking_url: urlValue.describe("Booking URL (e.g. Cal.com). Empty string or null clears it."),
+        website_url: urlValue.describe("Website URL. Empty string or null clears it."),
+        case_studies: z
+            .array(caseStudy)
+            .max(5)
+            .optional()
+            .describe("Up to 5 case studies used as proof (title, summary ≤200 chars, idealFor, proofPoints[])."),
+    }, async ({ lead_group_id, connection_request_enabled, positioning: pos, sequence_design, rules: rls, booking_url, website_url, case_studies, }) => {
+        try {
+            const body = {};
+            if (connection_request_enabled !== undefined)
+                body.connectionRequestEnabled = connection_request_enabled;
+            if (pos !== undefined)
+                body.positioning = pos;
+            if (sequence_design !== undefined)
+                body.sequenceDesign = sequence_design;
+            if (rls !== undefined)
+                body.rules = rls;
+            if (booking_url !== undefined)
+                body.bookingUrl = booking_url;
+            if (website_url !== undefined)
+                body.websiteUrl = website_url;
+            if (case_studies !== undefined)
+                body.caseStudies = case_studies;
+            const data = await putPartial(lead_group_id, body);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── update_outreach_positioning ────────────────────────────────────────
+    server.tool("update_outreach_positioning", "Patch only the positioning block (dream/fear/whyNow). Reads the current " +
+        "positioning, merges the fields you pass, and writes it back. Pass any " +
+        "subset of dream/fear/whyNow — unspecified fields stay intact.", {
+        lead_group_id: z.string().describe("Lead group ID."),
+        dream: z
+            .string()
+            .max(200)
+            .optional()
+            .describe("What this lead group wants (≤200 chars)."),
+        fear: z
+            .string()
+            .max(200)
+            .optional()
+            .describe("What they dread (≤200 chars)."),
+        whyNow: z
+            .string()
+            .max(200)
+            .optional()
+            .describe("Why act now rather than later (≤200 chars)."),
+    }, async ({ lead_group_id, dream, fear, whyNow }) => {
+        try {
+            if (dream === undefined && fear === undefined && whyNow === undefined) {
+                return toolError("Provide at least one of: dream, fear, whyNow.");
+            }
+            const current = await fetchCurrentSettings(lead_group_id);
+            const merged = {
+                ...(current.positioning ?? {}),
+                ...(dream !== undefined && { dream }),
+                ...(fear !== undefined && { fear }),
+                ...(whyNow !== undefined && { whyNow }),
+            };
+            const data = await putPartial(lead_group_id, { positioning: merged });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── update_outreach_sequence_slot ──────────────────────────────────────
+    server.tool("update_outreach_sequence_slot", "Patch a single sequence slot (connexion, linkedin.one/two/three, or " +
+        "email.one/two/three). Reads the current sequenceDesign, mutates just the " +
+        "target slot, and writes the whole block back so other slots are untouched. " +
+        "goal and coreElements within the slot are each replaced wholesale when passed.", {
+        lead_group_id: z.string().describe("Lead group ID."),
+        channel: z
+            .enum(["connexion", "linkedin", "email"])
+            .describe("Channel: 'connexion' (single slot, LinkedIn invite note), 'linkedin' " +
+            "(slots one/two/three), or 'email' (slots one/two/three)."),
+        slot: z
+            .enum(["one", "two", "three"])
+            .optional()
+            .describe("Slot index. Required when channel is 'linkedin' or 'email'. Ignored for 'connexion'."),
+        goal: z
+            .string()
+            .optional()
+            .describe("The message goal (one sentence)."),
+        core_elements: z
+            .array(z.string())
+            .optional()
+            .describe("List of elements the message must include (short bullet points). Replaces the array wholesale."),
+    }, async ({ lead_group_id, channel, slot, goal, core_elements }) => {
+        try {
+            if (goal === undefined && core_elements === undefined) {
+                return toolError("Provide at least one of: goal, core_elements.");
+            }
+            if (channel !== "connexion" && !slot) {
+                return toolError(`slot is required when channel is '${channel}'.`);
+            }
+            const current = await fetchCurrentSettings(lead_group_id);
+            const next = { ...(current.sequenceDesign ?? {}) };
+            if (channel === "connexion") {
+                const existing = (next.connexion ?? {});
+                next.connexion = {
+                    ...existing,
+                    ...(goal !== undefined && { goal }),
+                    ...(core_elements !== undefined && { coreElements: core_elements }),
+                };
+            }
+            else {
+                const channelExisting = {
+                    ...(next[channel] ?? {}),
+                };
+                const slotExisting = (channelExisting[slot] ??
+                    {});
+                channelExisting[slot] = {
+                    ...slotExisting,
+                    ...(goal !== undefined && { goal }),
+                    ...(core_elements !== undefined && { coreElements: core_elements }),
+                };
+                next[channel] = channelExisting;
+            }
+            const data = await putPartial(lead_group_id, { sequenceDesign: next });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── update_outreach_rules ──────────────────────────────────────────────
+    server.tool("update_outreach_rules", "Patch only the rules block. forbidden and priority arrays are replaced " +
+        "wholesale when passed. format.* sub-fields are deep-merged individually " +
+        "(signatureEmail/signatureLinkedin/vouvoiement/bannedChars/bannedStyles/" +
+        "maxWordsPerSentence) — pass only what you want to change.", {
+        lead_group_id: z.string().describe("Lead group ID."),
+        forbidden: z
+            .array(z.string())
+            .optional()
+            .describe("Forbidden phrases (replaces the array when passed)."),
+        priority: z
+            .array(z.string())
+            .optional()
+            .describe("Priority points (replaces the array when passed)."),
+        format: z
+            .object({
+            signatureEmail: z.string().optional(),
+            signatureLinkedin: z.string().optional(),
+            vouvoiement: z.boolean().optional(),
+            bannedChars: z.array(z.string()).optional(),
+            bannedStyles: z.array(z.string()).optional(),
+            maxWordsPerSentence: z.number().int().positive().optional(),
+        })
+            .passthrough()
+            .optional()
+            .describe("Format sub-fields: only fields passed are updated. Arrays (bannedChars/bannedStyles) are replaced wholesale."),
+    }, async ({ lead_group_id, forbidden, priority, format }) => {
+        try {
+            if (forbidden === undefined &&
+                priority === undefined &&
+                format === undefined) {
+                return toolError("Provide at least one of: forbidden, priority, format.");
+            }
+            const current = await fetchCurrentSettings(lead_group_id);
+            const currentRules = (current.rules ?? {});
+            const next = { ...currentRules };
+            if (forbidden !== undefined)
+                next.forbidden = forbidden;
+            if (priority !== undefined)
+                next.priority = priority;
+            if (format !== undefined) {
+                next.format = {
+                    ...(currentRules.format ?? {}),
+                    ...format,
+                };
+            }
+            const data = await putPartial(lead_group_id, { rules: next });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── update_outreach_case_study ─────────────────────────────────────────
+    server.tool("update_outreach_case_study", "Add, replace, or remove a single case study without re-sending the whole " +
+        "list. Reads the current caseStudies array, mutates the target entry, " +
+        "and writes the full list back. Cap is 5 entries.", {
+        lead_group_id: z.string().describe("Lead group ID."),
+        action: z
+            .enum(["add", "replace", "remove"])
+            .describe("add = append (fails if list is at cap 5); replace = overwrite at index; remove = delete at index."),
+        index: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("Zero-based index. Required for 'replace' and 'remove'. Ignored for 'add'."),
+        case_study: caseStudy
+            .optional()
+            .describe("Case study payload (title, summary ≤200 chars, idealFor, proofPoints[]). Required for 'add' and 'replace'."),
+    }, async ({ lead_group_id, action, index, case_study }) => {
+        try {
+            if ((action === "add" || action === "replace") && !case_study) {
+                return toolError(`case_study is required for action '${action}'.`);
+            }
+            if ((action === "replace" || action === "remove") &&
+                index === undefined) {
+                return toolError(`index is required for action '${action}'.`);
+            }
+            const current = await fetchCurrentSettings(lead_group_id);
+            const list = Array.isArray(current.caseStudies)
+                ? [...current.caseStudies]
+                : [];
+            if (action === "add") {
+                if (list.length >= 5) {
+                    return toolError("Cannot add — case studies list is at cap (5). Use 'replace' or 'remove' first.");
+                }
+                list.push(case_study);
+            }
+            else if (action === "replace") {
+                if (index < 0 || index >= list.length) {
+                    return toolError(`Index ${index} out of bounds (list has ${list.length} entries).`);
+                }
+                list[index] = case_study;
+            }
+            else {
+                if (index < 0 || index >= list.length) {
+                    return toolError(`Index ${index} out of bounds (list has ${list.length} entries).`);
+                }
+                list.splice(index, 1);
+            }
+            const data = await putPartial(lead_group_id, { caseStudies: list });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── update_outreach_urls ───────────────────────────────────────────────
+    server.tool("update_outreach_urls", "Patch bookingUrl and/or websiteUrl only. Empty string or null clears a " +
+        "field. Other outreach settings are untouched.", {
+        lead_group_id: z.string().describe("Lead group ID."),
+        booking_url: urlValue.describe("Booking URL (e.g. Cal.com). Empty string or null clears it."),
+        website_url: urlValue.describe("Website URL. Empty string or null clears it."),
+    }, async ({ lead_group_id, booking_url, website_url }) => {
+        try {
+            if (booking_url === undefined && website_url === undefined) {
+                return toolError("Provide at least one of: booking_url, website_url.");
+            }
+            const body = {};
+            if (booking_url !== undefined)
+                body.bookingUrl = booking_url;
+            if (website_url !== undefined)
+                body.websiteUrl = website_url;
+            const data = await putPartial(lead_group_id, body);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── set_outreach_connection_request ────────────────────────────────────
+    server.tool("set_outreach_connection_request", "Toggle whether the first LinkedIn touchpoint is a connection request " +
+        "(true) or a cold direct message (false). When false, card_linkedin_one " +
+        "is written as a cold first-contact message and the update_lead handler " +
+        "rejects any write to card_connexion.", {
+        lead_group_id: z.string().describe("Lead group ID."),
+        enabled: z
+            .boolean()
+            .describe("true = connection request first; false = cold DM."),
+    }, async ({ lead_group_id, enabled }) => {
+        try {
+            const data = await putPartial(lead_group_id, {
+                connectionRequestEnabled: enabled,
+            });
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/tools/personas.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPersonaTools(server: McpServer): void;