@agifyai/leadify-mcp 6.0.0 → 7.0.0

package/README.md

@@ -195,7 +195,10 @@ Conséquences pratiques :
 | `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. |
-| `add_signal` | Ajouter un signal de business intelligence à un lead (INFO, CRITICAL, GOLDEN). |
+| `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. |
+| `signal_delete` | Supprimer définitivement un signal (cas rare : donnée erronée, doublon). |
 | `add_activity` | Journaliser une interaction prospect (LinkedIn, email, call) dans le feed du lead. |
 | `get_data_room` | Récupérer la data room complète : infos société (v2), documents, personas. |
 | `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. |

package/dist/tools/dataroom.js

@@ -276,16 +276,17 @@ export function registerDataRoomTools(server) {
         }
     });
     // ── get_outreach_context ──────────────────────────────────────────────
-    server.tool("get_outreach_context", "Get a curated outreach context for a lead group: the outreach-relevant slice " +
-        "of companyInfo only (identity, pitch, constraints, curated products, economics " +
-        "triggers/baseline, product ICP roles, proof wording). " +
+    server.tool("get_outreach_context", "Get a lean outreach context for a lead group. Returns the shape " +
+        "`{ leadGroupId, leadGroupName, organizationId, company }` where `company` is the " +
+        "outreach-relevant slice of companyInfo (identity, pitch, constraints, curated " +
+        "products, economics triggers/baseline, product ICP roles, proof wording). " +
         "Takes a lead_group_id (NOT organization_id) — the org is resolved server-side, " +
         "eliminating the cross-org footgun of get_data_room. " +
-        "Returns a HARD error if no persona is linked to the group. " +
-        "NOTE: the `outreach` settings block is NOT returned by this tool — " +
-        "outreach configuration (positioning, tone, rules, templates, etc.) is " +
-        "managed exclusively via the Fine Tuning tools (append_fine_tuning / " +
-        "set_fine_tuning / get_fine_tuning). " +
+        "Does NOT require a persona: the group needs no linked persona and an empty data " +
+        "room returns success (not an error). No persona or outreach block is returned. " +
+        "Outreach configuration (positioning, tone, rules, templates, etc.) is managed " +
+        "exclusively via the Fine Tuning tools (append_fine_tuning / set_fine_tuning / " +
+        "get_fine_tuning). " +
         "Use this instead of get_data_room + get_lead_group_persona in the outreach " +
         "pipeline Phase 0.", {
         lead_group_id: z.string().describe("ID of the lead group to resolve context for."),

package/dist/tools/fine_tuning.js

@@ -29,7 +29,9 @@ export function registerFineTuningTools(server) {
         lead_group_id: z
             .string()
             .describe("ID of the lead group whose fine tuning configuration to fetch. " +
-            "Resolve via list_organizations + get_leads if needed."),
+            "Pass the lead_group_id directly; if you need to resolve it, use " +
+            "pipeline_next_lead (do NOT use get_leads — its payload is huge and is " +
+            "banned in the outreach pipeline)."),
     }, async ({ lead_group_id }) => {
         try {
             const data = await getClient().get(`/api/lead-group/${encodeURIComponent(lead_group_id)}/fine-tuning`);

package/dist/tools/pipeline.js

@@ -21,7 +21,13 @@ export function registerPipelineTools(server) {
         "`get_lead` call); the caller only needs `lead_id`. " +
         "The response is decorated with a Trigger.dev `traceUrl` deep-link when missing " +
         "(https://cloud.trigger.dev/runs/{runId}), so you can always jump to the trace. " +
-        "Waits up to 300s for the remote agent to complete.", {
+        "WAIT BEHAVIOR: this is a single blocking HTTP call to the backend with no " +
+        "client-side timeout — the wait is entirely server-side. The backend may return " +
+        "BEFORE the agent finishes (observed ~120s) with `status: EXECUTING` and a runId; " +
+        "this is NOT a failure — the run keeps going server-side, follow it via the " +
+        "traceUrl. In dry-run (dryrun=true) the call is safe to retry, since nothing is " +
+        "persisted; for production writes (dryrun=false) prefer following the trace over " +
+        "blindly retrying to avoid duplicate generation.", {
         lead_id: z.string().describe("ID of the lead to generate a message for."),
         dryrun: z
             .boolean()

package/dist/tools/signals.js

@@ -1,47 +1,242 @@
 import { z } from "zod";
 import { getClient } from "../client.js";
-import { toolResult, handleToolError } from "../types.js";
+import { toolResult, toolError, handleToolError } from "../types.js";
+// Anti-loop guardrail, NOT a business limit: bounds how many signal mutations
+// a single server run (= one agent session) can perform.
+const MAX_SIGNAL_MUTATIONS_PER_RUN = 20;
+let signalMutationCount = 0;
+function capExceeded() {
+    if (signalMutationCount >= MAX_SIGNAL_MUTATIONS_PER_RUN) {
+        return toolError(`Signal mutation cap reached (${MAX_SIGNAL_MUTATIONS_PER_RUN} per run). ` +
+            "This is an anti-loop guardrail, not a business limit. If you genuinely " +
+            "need more mutations, ask the user to restart the MCP session.");
+    }
+    return null;
+}
+// Best-effort: a feed failure must never fail the signal mutation itself.
+async function appendFeed(entry) {
+    try {
+        await getClient().post("/activity-feed", { mode: "agent", ...entry });
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+function mutationResult(data, feedError) {
+    if (feedError === null)
+        return toolResult(data);
+    return toolResult({
+        result: data,
+        warning: `Signal mutation succeeded but the activity-feed entry failed: ${feedError}`,
+    });
+}
+const reasonParam = z
+    .string()
+    .describe("One factual sentence explaining WHY you are performing this mutation " +
+    "(e.g. 'Tender closed on 2026-05-30, budget consumed.'). Recorded in the " +
+    "lead's append-only activity feed.");
 export function registerSignalTools(server) {
-    // ── add_signal ─────────────────────────────────────────────────────────
-    server.tool("add_signal", "Attach a business intelligence signal to a lead. Signals report key events picked " +
-        "up by external agents — budget approvals, position changes, tender publications, " +
-        "etc. Each signal has a level (INFO, CRITICAL, GOLDEN) and is shown in the lead's " +
-        "feed. Use GOLDEN sparingly for truly actionable buying-intent signals.", {
-        lead_id: z.string().describe("ID of the target lead."),
-        level: z
-            .enum(["INFO", "CRITICAL", "GOLDEN"])
-            .describe("Signal priority level."),
-        title: z
-            .string()
-            .describe("Short title of the signal (e.g. 'Budget IRM approuvé')."),
-        content: z
-            .string()
-            .describe("Detailed description of the signal."),
-        agent_source: z
-            .string()
-            .optional()
-            .describe("Short identifier of the source agent. MUST be 3 to 4 words max, " +
-            "kebab-case or space-separated (e.g. 'leadify qualification', " +
-            "'briefify research', 'dealmind coach'). Default: 'unknown'."),
-        source_url: z
-            .string()
-            .url()
-            .optional()
-            .describe("URL of the original information source."),
-    }, async ({ lead_id, level, title, content, agent_source, source_url }) => {
+    // ── signal_upsert ──────────────────────────────────────────────────────
+    server.registerTool("signal_upsert", {
+        title: "Upsert a business signal",
+        description: "Create a new business intelligence signal on a lead, or update an existing " +
+            "one's content by `id`. Signals report key events picked up by agents — budget " +
+            "approvals, position changes, tender publications, etc. — and are shown in the " +
+            "lead's feed.\n\n" +
+            "WITHOUT `id` → creates a signal (`lead_id`, `level`, `title`, `content` required).\n" +
+            "WITH `id` → PARTIAL update of the existing signal: only the fields you pass are " +
+            "modified. Ids are server-generated — never invent one; an unknown `id` returns 404. " +
+            "`lead_id` is immutable after creation.\n\n" +
+            "Every upsert (re)sets the signal's state to `active`: updating an expired or " +
+            "disabled signal reactivates it — this is also the way to reactivate a signal. To " +
+            "expire or disable a signal use `signal_expire` / `signal_disable` instead.\n\n" +
+            "Levels: GOLDEN = major actionable buying-intent (use sparingly), CRITICAL = " +
+            "important info needing attention, INFO = monitoring-grade info.\n" +
+            "Always provide `ai_summary` when `content` exceeds ~3 sentences, otherwise the UI " +
+            "truncates `content`.",
+        inputSchema: {
+            id: z
+                .string()
+                .optional()
+                .describe("ID of an existing signal to update. OMIT to create a new signal. " +
+                "Unknown id → 404 (ids are server-generated, never invent one)."),
+            lead_id: z
+                .string()
+                .optional()
+                .describe("ID of the target lead. Required when creating; immutable afterwards."),
+            level: z
+                .enum(["INFO", "CRITICAL", "GOLDEN"])
+                .optional()
+                .describe("Signal priority level. Required when creating."),
+            title: z
+                .string()
+                .optional()
+                .describe("Short one-line title (e.g. 'Budget IRM approuvé'). Required when creating."),
+            content: z
+                .string()
+                .optional()
+                .describe("Long markdown version: full details, sources, context. Required when creating."),
+            ai_summary: z
+                .string()
+                .optional()
+                .describe("3-4 sentence markdown summary, shown by default in the UI with a 'see more' " +
+                "toggle expanding `content`."),
+            date: z
+                .string()
+                .optional()
+                .describe("Date the business event actually occurred (≠ insertion date). Partial or full " +
+                "ISO 8601: 'YYYY' / 'YYYY-MM' / 'YYYY-MM-DD' / datetime. Use the finest " +
+                "precision you can reliably determine."),
+            source: z
+                .string()
+                .optional()
+                .describe("Human-readable source name ('LinkedIn', 'BOAMP', 'Les Echos'). Main badge in UI."),
+            agent_source: z
+                .string()
+                .optional()
+                .describe("Technical identifier of the producing agent, 3-4 words max, kebab-case or " +
+                "space-separated (e.g. 'leadify qualification', 'budget-monitor')."),
+            source_url: z.string().url().optional().describe("URL of the original source."),
+            reason: reasonParam,
+        },
+        annotations: { idempotentHint: true },
+    }, async ({ id, lead_id, level, title, content, ai_summary, date, source, agent_source, source_url, reason, }) => {
+        const capError = capExceeded();
+        if (capError)
+            return capError;
         try {
-            const body = {
-                leadId: lead_id,
-                level,
-                title,
-                content,
-            };
+            const body = { state: "active" };
+            if (id !== undefined)
+                body.id = id;
+            if (lead_id !== undefined)
+                body.leadId = lead_id;
+            if (level !== undefined)
+                body.level = level;
+            if (title !== undefined)
+                body.title = title;
+            if (content !== undefined)
+                body.content = content;
+            if (ai_summary !== undefined)
+                body.aiSummary = ai_summary;
+            if (date !== undefined)
+                body.date = date;
+            if (source !== undefined)
+                body.source = source;
             if (agent_source !== undefined)
                 body.agentSource = agent_source;
             if (source_url !== undefined)
                 body.sourceUrl = source_url;
-            const data = await getClient().post("/add-signal", body);
-            return toolResult(data);
+            const data = (await getClient().post("/signals", body));
+            signalMutationCount++;
+            const feedLeadId = data.signal?.leadId ?? lead_id;
+            const feedError = feedLeadId
+                ? await appendFeed({
+                    leadId: feedLeadId,
+                    action: data.created ? "signal_added" : "signal_updated",
+                    target: data.signal?.id ?? id,
+                    after: data.signal?.title ?? title,
+                    reason,
+                })
+                : "leadId missing from upsert response";
+            return mutationResult(data, feedError);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── signal_expire / signal_disable ─────────────────────────────────────
+    const stateFlips = [
+        {
+            name: "signal_expire",
+            title: "Expire a business signal",
+            state: "expired",
+            action: "signal_expired",
+            description: "Mark an existing signal as EXPIRED: the underlying business event is no longer " +
+                "current (budget consumed, tender closed, contact left the position...). The signal " +
+                "is kept for history but stops counting as active intelligence. This only flips the " +
+                "signal's lifecycle state — content is untouched. Re-upserting the signal with " +
+                "`signal_upsert` reactivates it. Do NOT use this for wrong/duplicate data — that is " +
+                "`signal_delete`.",
+        },
+        {
+            name: "signal_disable",
+            title: "Disable a business signal",
+            state: "disabled",
+            action: "signal_disabled",
+            description: "Mark an existing signal as DISABLED: the signal is set aside as a false positive " +
+                "or manually discarded (wrong interpretation, irrelevant to this lead...). The " +
+                "signal is kept for traceability but ignored by agents and the UI. This only flips " +
+                "the signal's lifecycle state — content is untouched. Re-upserting the signal with " +
+                "`signal_upsert` reactivates it. For factually wrong or duplicate data, prefer " +
+                "`signal_delete`.",
+        },
+    ];
+    for (const flip of stateFlips) {
+        server.registerTool(flip.name, {
+            title: flip.title,
+            description: flip.description,
+            inputSchema: {
+                id: z.string().describe("ID of the signal. Unknown id → 404."),
+                reason: reasonParam,
+            },
+            annotations: { idempotentHint: true },
+        }, async ({ id, reason }) => {
+            const capError = capExceeded();
+            if (capError)
+                return capError;
+            try {
+                const data = (await getClient().post("/signals", {
+                    id,
+                    state: flip.state,
+                }));
+                signalMutationCount++;
+                const feedLeadId = data.signal?.leadId;
+                const feedError = feedLeadId
+                    ? await appendFeed({
+                        leadId: feedLeadId,
+                        action: flip.action,
+                        target: id,
+                        after: flip.state.toUpperCase(),
+                        reason,
+                    })
+                    : "leadId missing from upsert response";
+                return mutationResult(data, feedError);
+            }
+            catch (error) {
+                return handleToolError(error);
+            }
+        });
+    }
+    // ── signal_delete ──────────────────────────────────────────────────────
+    server.registerTool("signal_delete", {
+        title: "Delete a business signal (rare)",
+        description: "PERMANENTLY delete a signal. RARE case reserved for factually wrong data or " +
+            "duplicates. The normal lifecycle never deletes: an outdated signal becomes " +
+            "`expired` (`signal_expire`) and a false positive becomes `disabled` " +
+            "(`signal_disable`), both keeping history. Deletion is irreversible.",
+        inputSchema: {
+            id: z.string().describe("ID of the signal to delete. Unknown id → 404."),
+            lead_id: z
+                .string()
+                .describe("ID of the lead the signal belongs to (used for the activity feed)."),
+            reason: reasonParam,
+        },
+        annotations: { destructiveHint: true, idempotentHint: false },
+    }, async ({ id, lead_id, reason }) => {
+        const capError = capExceeded();
+        if (capError)
+            return capError;
+        try {
+            const data = await getClient().delete(`/signals/${encodeURIComponent(id)}`);
+            signalMutationCount++;
+            const feedError = await appendFeed({
+                leadId: lead_id,
+                action: "signal_deleted",
+                target: id,
+                reason,
+            });
+            return mutationResult(data, feedError);
         }
         catch (error) {
             return handleToolError(error);

package/package.json

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