@agifyai/leadify-mcp 6.0.1 → 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/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.1",
+  "version": "7.0.0",
   "description": "MCP server for Leadify lead management API",
   "type": "module",
   "main": "dist/index.js",