@agifyai/leadify-mcp 8.3.9 → 8.4.1

package/README.md

@@ -193,6 +193,11 @@ Conséquences pratiques :
 | `get_leads` | Rechercher et lister des leads avec filtres, recherche et pagination. |
 | `get_lead` | Récupérer les détails complets d'un lead par son ID. |
 | `update_lead` | Mettre à jour un ou plusieurs champs d'un lead existant. |
+
+Pour `add_leads` et `update_lead`, `location` utilise l’objet canonique
+`{ city, region?, postalCode?, countryCode, street? }`. `city` et le code pays
+ISO-2 `countryCode` sont obligatoires. La projection `geo` est calculée par
+Leadify et ne doit jamais être envoyée par un agent MCP.
 | `delete_sequence_messages` | Supprimer uniquement les messages de séquence générés d'un lead, après confirmation explicite. |
 | `delete_leads` | Supprimer définitivement des leads par leurs IDs. |
 | `update_schema` | Ajouter ou modifier les définitions de champs d'un groupe. |
@@ -215,6 +220,13 @@ Conséquences pratiques :
 | `add_activity` | Journaliser une interaction prospect (LinkedIn, email, call) dans le feed du lead. |
 | `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. |
+| `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é. |
+| `tombstone_canonical_relationship` | Retirer réversiblement un lien sans supprimer son historique ni ses preuves. |
+| `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. |

package/dist/client.d.ts

@@ -7,6 +7,6 @@ export declare class LeadifyClient {
     post(path: string, body: unknown): Promise<unknown>;
     put(path: string, body: unknown): Promise<unknown>;
     patch(path: string, body: unknown): Promise<unknown>;
-    delete(path: string): Promise<unknown>;
+    delete(path: string, body?: unknown): Promise<unknown>;
 }
 export declare function getClient(): LeadifyClient;

package/dist/client.js

@@ -17,7 +17,7 @@ export class LeadifyClient {
         };
         const init = { method, headers };
         if (body !== undefined &&
-            (method === "POST" || method === "PUT" || method === "PATCH")) {
+            (method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE")) {
             headers["Content-Type"] = "application/json";
             init.body = JSON.stringify(body);
         }
@@ -53,9 +53,9 @@ export class LeadifyClient {
         const url = new URL(path, this.baseUrl);
         return this.request("PATCH", url, body);
     }
-    async delete(path) {
+    async delete(path, body) {
         const url = new URL(path, this.baseUrl);
-        return this.request("DELETE", url);
+        return this.request("DELETE", url, body);
     }
 }
 let _client = null;

package/dist/server.js

@@ -14,16 +14,18 @@ import { registerPipelineTools } from "./tools/pipeline.js";
 import { registerFineTuningTools } from "./tools/fine_tuning.js";
 import { registerContextWorkspaceTools } from "./tools/context_workspace.js";
 import { registerLeadViewTools } from "./tools/views.js";
+import { registerRelationshipTools } from "./tools/relationships.js";
 export function createServer() {
     const server = new McpServer({
         name: "leadify",
-        version: "8.3.8",
+        version: "8.4.0",
     });
     registerAuthTools(server);
     registerOrganizationTools(server);
     registerLeadGroupTools(server);
     registerLeadViewTools(server);
     registerLeadTools(server);
+    registerRelationshipTools(server);
     registerSchemaTools(server);
     registerLogTools(server);
     registerCampaignTools(server);

package/dist/tools/leads.js

@@ -2,6 +2,37 @@ import { z } from "zod";
 import { getClient } from "../client.js";
 import { toolResult, handleToolError } from "../types.js";
 const DEFAULT_LEAD_FIELDS = ["firstName", "lastName", "email", "company", "jobTitle", "linkedin"];
+const canonicalLocationSchema = z.object({
+    city: z.string().trim().min(1).max(200),
+    region: z.string().trim().min(1).max(500).optional(),
+    postalCode: z.string().trim().min(1).max(500).optional(),
+    countryCode: z.string().trim().regex(/^[A-Za-z]{2}$/).transform((value) => value.toUpperCase()),
+    street: z.string().trim().min(1).max(500).optional(),
+}).strict().describe("Canonical Leadify location source. city and ISO-2 countryCode are required; region, postalCode and street are optional. geo is system-owned and forbidden.");
+const leadInputSchema = z.record(z.unknown()).superRefine((lead, context) => {
+    if (!Object.hasOwn(lead, "location"))
+        return;
+    const parsed = canonicalLocationSchema.safeParse(lead.location);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            context.addIssue({ ...issue, path: ["location", ...issue.path] });
+        }
+    }
+});
+const leadUpdateSchema = z.object({
+    property_name: z.string().describe("Name of the field to update (e.g. 'email', 'status', 'card_analysis')."),
+    value: z.unknown().describe("New value for the field. location must use the canonical object; location.geo is forbidden."),
+    is_select: z.boolean().optional().describe("If true, the field is created/updated as a 'select' dropdown type. Use for categorical fields like status, source, etc."),
+}).superRefine((update, context) => {
+    if (update.property_name !== "location")
+        return;
+    const parsed = canonicalLocationSchema.safeParse(update.value);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            context.addIssue({ ...issue, path: ["value", ...issue.path] });
+        }
+    }
+});
 function projectLead(lead, fields) {
     const source = lead && typeof lead === "object" ? lead : {};
     const data = source.data && typeof source.data === "object" ? source.data : {};
@@ -24,18 +55,19 @@ export function registerLeadTools(server, client = getClient()) {
     server.tool("add_leads", "Add one or more leads to a specific lead group in Leadify. Provide the group ID " +
         "and an array of lead objects with any combination of fields (email, firstName, " +
         "lastName, company, jobTitle, phone, custom fields, card_* fields, percent_* " +
-        "fields, relation fields, etc.). Optionally specify which fields should be " +
+        "fields, etc.). Canonical relation fields are read-only here: use " +
+        "create_canonical_relationship or the migration tools instead. Optionally specify which fields should be " +
         "treated as 'select' dropdowns in the UI. Returns the count of successfully " +
         "imported leads and any errors. Use this for both bulk imports and single lead creation.", {
         lead_group_id: z
             .string()
             .describe("ID of the lead group to add leads to."),
         leads: z
-            .array(z.record(z.unknown()))
+            .array(leadInputSchema)
             .describe("Array of lead objects. Each object is a key-value map of field names to values. " +
             "Common fields: email, firstName, lastName, company, jobTitle, phone, linkedin, " +
-            "website, location, seniority, specialty, age. Also supports card_* fields, " +
-            "percent_* fields, boolean flags (decisionMaking, excluded), and relation fields."),
+            "website, seniority, specialty, age. location must be {city, region?, postalCode?, countryCode, street?}; geo is computed by Leadify. Also supports card_* fields, " +
+            "percent_* fields and boolean flags (decisionMaking, excluded). Canonical relation fields are rejected."),
         is_select_fields: z
             .array(z.string())
             .optional()
@@ -149,23 +181,13 @@ export function registerLeadTools(server, client = getClient()) {
     server.tool("update_lead", "Update one or more fields on an existing lead. Each update specifies the field " +
         "name, new value, and optionally whether the field is a 'select' dropdown type. " +
         "Supports all field types including special fields (card_*, percent_*, boolean flags " +
-        "like decisionMaking/excluded), and relation fields. Returns the updated lead. " +
+        "like decisionMaking/excluded). When a configured canonical relation field is changed, " +
+        "the backend routes it through the typed relationship service and keeps the JSON field read-only. Returns the updated lead. " +
+        "location must be the canonical object {city, region?, postalCode?, countryCode, street?}; never submit geo. " +
         "For bulk updates across many leads, call this tool once per lead.", {
         lead_id: z.string().describe("ID of the lead to update."),
         updates: z
-            .array(z.object({
-            property_name: z
-                .string()
-                .describe("Name of the field to update (e.g. 'email', 'status', 'card_analysis')."),
-            value: z
-                .unknown()
-                .describe("New value for the field. Type depends on the field."),
-            is_select: z
-                .boolean()
-                .optional()
-                .describe("If true, the field is created/updated as a 'select' dropdown type. " +
-                "Use for categorical fields like status, source, etc."),
-        }))
+            .array(leadUpdateSchema)
             .min(1)
             .describe("Array of field updates to apply."),
     }, async ({ lead_id, updates }) => {

package/dist/tools/relationships.d.ts

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

package/dist/tools/relationships.js

@@ -0,0 +1,124 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { handleToolError, toolResult } from "../types.js";
+const entityKind = z.enum(["ACCOUNT", "LEGAL_ENTITY", "ESTABLISHMENT", "PERSON", "EMPLOYMENT"]);
+const relationshipType = z.enum(["EMPLOYED_BY", "AFFILIATED_WITH", "PART_OF", "COLLEAGUE_OF"]);
+const entityRef = z.object({ kind: entityKind, id: z.string().min(1) }).strict();
+const confidence = z.object({
+    value: z.number().min(0).max(1),
+    method: z.string().min(1).max(100),
+    assessed_at: z.string().datetime(),
+}).strict();
+export function registerRelationshipTools(server, client = getClient()) {
+    server.tool("list_canonical_relationships", "List tenant-scoped canonical relationships. The response is direction-independent for consumers: filter by one entity to find both incoming and outgoing links. Legacy lead relation fields are compatibility projections, not the source of truth.", {
+        organization_id: z.string().min(1),
+        entity_kind: entityKind.optional(),
+        entity_id: z.string().min(1).optional(),
+        relationship_type: relationshipType.optional(),
+        state: z.enum(["ACTIVE", "TOMBSTONED"]).optional().default("ACTIVE"),
+        limit: z.number().int().min(1).max(500).optional().default(100),
+        cursor: z.string().optional(),
+    }, async ({ organization_id, entity_kind, entity_id, relationship_type, state, limit, cursor }) => {
+        try {
+            if (Boolean(entity_kind) !== Boolean(entity_id))
+                return toolResult({ error: "entity_kind and entity_id must be provided together" });
+            const params = new URLSearchParams({ organizationId: organization_id, state, limit: String(limit) });
+            if (entity_kind)
+                params.set("entityKind", entity_kind);
+            if (entity_id)
+                params.set("entityId", entity_id);
+            if (relationship_type)
+                params.set("relationshipType", relationship_type);
+            if (cursor)
+                params.set("cursor", cursor);
+            return toolResult(await client.get("/api/canonical-relationships", params));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("create_canonical_relationship", "Create one typed canonical relationship in a tenant. Endpoints must already be strong canonical identities in that tenant. Retries with the same idempotency key and payload are safe; a changed payload is rejected. This tool never creates placeholder identities or activates outreach.", {
+        organization_id: z.string().min(1), relationship_type: relationshipType,
+        source: entityRef, target: entityRef,
+        trust_state: z.enum(["CONFIRMED", "PROPOSED", "AMBIGUOUS", "CONFLICTED", "UNKNOWN"]).optional().default("UNKNOWN"),
+        confidence: confidence.optional(), evidence_ids: z.array(z.string()).max(100).optional().default([]),
+        valid_from: z.string().datetime().nullable().optional(), valid_to: z.string().datetime().nullable().optional(),
+        attributes: z.record(z.unknown()).optional(), idempotency_key: z.string().min(1).max(255),
+    }, async (params) => {
+        try {
+            return toolResult(await client.post("/api/canonical-relationships", {
+                organizationId: params.organization_id, relationshipType: params.relationship_type,
+                source: params.source, target: params.target, trustState: params.trust_state,
+                confidence: params.confidence ? { ...params.confidence, assessedAt: params.confidence.assessed_at, assessed_at: undefined } : undefined,
+                evidenceIds: params.evidence_ids, validFrom: params.valid_from, validTo: params.valid_to,
+                attributes: params.attributes, idempotencyKey: params.idempotency_key,
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("update_canonical_relationship", "Update, tombstone, or restore one canonical relationship through the shared transactional service. Every mutation is versioned in the immutable ledger and requires a unique idempotency key.", {
+        organization_id: z.string().min(1), relationship_id: z.string().min(1),
+        relationship_type: relationshipType.optional(), source: entityRef.optional(), target: entityRef.optional(),
+        trust_state: z.enum(["CONFIRMED", "PROPOSED", "AMBIGUOUS", "CONFLICTED", "UNKNOWN"]).optional(),
+        state: z.enum(["ACTIVE", "TOMBSTONED"]).optional(), evidence_ids: z.array(z.string()).max(100).optional(),
+        valid_from: z.string().datetime().nullable().optional(), valid_to: z.string().datetime().nullable().optional(),
+        attributes: z.record(z.unknown()).nullable().optional(), idempotency_key: z.string().min(1).max(255),
+    }, async (params) => {
+        try {
+            return toolResult(await client.patch(`/api/canonical-relationships/${encodeURIComponent(params.relationship_id)}`, {
+                organizationId: params.organization_id, relationshipType: params.relationship_type,
+                source: params.source, target: params.target, trustState: params.trust_state, state: params.state,
+                evidenceIds: params.evidence_ids, validFrom: params.valid_from, validTo: params.valid_to,
+                attributes: params.attributes, idempotencyKey: params.idempotency_key,
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("tombstone_canonical_relationship", "Soft-delete one canonical relationship while preserving its evidence and immutable history. Use this instead of deleting legacy relation fields.", { organization_id: z.string().min(1), relationship_id: z.string().min(1), idempotency_key: z.string().min(1).max(255) }, async ({ organization_id, relationship_id, idempotency_key }) => {
+        try {
+            return toolResult(await client.delete(`/api/canonical-relationships/${encodeURIComponent(relationship_id)}`, { organizationId: organization_id, idempotencyKey: idempotency_key }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    const migrationFields = {
+        organization_id: z.string().min(1), source_group_id: z.string().min(1), field: z.string().min(1),
+        relationship_type: relationshipType, endpoint_role: z.enum(["SOURCE", "TARGET"]),
+        source_label: z.string().min(1).max(120), target_label: z.string().min(1).max(120),
+        limit: z.number().int().min(1).max(500).optional().default(500),
+    };
+    const migrationBody = (params) => ({
+        organizationId: params.organization_id, sourceGroupId: params.source_group_id, field: params.field,
+        relationshipType: params.relationship_type, endpointRole: params.endpoint_role,
+        sourceLabel: params.source_label, targetLabel: params.target_label, limit: params.limit,
+    });
+    server.tool("preview_canonical_relationship_migration", "Read-only planner for a legacy LeadGroup relation. Returns the exact forward/inverse divergence matrix, unresolved identities, quarantine candidates, and a digest. It creates no identities, links, placeholders, campaigns, or outreach.", migrationFields, async (params) => {
+        try {
+            return toolResult(await client.post("/api/canonical-relationships/migration/preview", migrationBody(params)));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("apply_canonical_relationship_migration", "Apply exactly a previously reviewed canonical relationship migration plan. Requires its digest; the backend rejects drift, limits the batch, quarantines unresolved identities, and keeps external activation at zero.", { ...migrationFields, expected_plan_digest: z.string().regex(/^[a-f0-9]{64}$/) }, async (params) => {
+        try {
+            return toolResult(await client.post("/api/canonical-relationships/migration/apply", { ...migrationBody(params), expectedPlanDigest: params.expected_plan_digest }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("rollback_canonical_relationship_migration", "Tombstone every active relationship created by one migration digest. This is reversible and does not delete identities, evidence, leads, groups, or history.", { organization_id: z.string().min(1), plan_digest: z.string().regex(/^[a-f0-9]{64}$/), idempotency_key: z.string().min(1).max(200) }, async ({ organization_id, plan_digest, idempotency_key }) => {
+        try {
+            return toolResult(await client.post("/api/canonical-relationships/migration/rollback", { organizationId: organization_id, planDigest: plan_digest, idempotencyKey: idempotency_key }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/package.json

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