@agifyai/leadify-mcp 8.5.2 → 8.5.4

package/README.md

@@ -121,6 +121,7 @@ src/
 └── tools/
     ├── auth.ts
     ├── leads.ts
+    ├── events.ts
     ├── campaigns.ts
     ├── dataroom.ts
     ├── personas.ts
@@ -190,6 +191,29 @@ Conséquences pratiques :
 
 ---
 
+## Sémantique des événements
+
+Une participation est rattachée à l’entreprise canonique (`Account`), même
+lorsqu’un `lead_id` est fourni au tool. `get_leads.event_filter` et
+`list_event_participations` ajoutent explicitement `VERIFIED` lorsque le statut
+n’est pas fourni. Pour relire des faits `UNVERIFIED`, `DISPUTED` ou `REFUTED`,
+l’agent doit demander ces statuts explicitement. Une donnée incertaine ou
+l’absence d’un enregistrement ne constitue jamais une preuve de présence ou de
+non-participation.
+
+Les corrections ajoutent un fait immuable et mettent à jour le snapshot
+courant dans la même opération ; elles exigent un motif. Il n’existe aucun tool
+de suppression de participation ou de preuve. Archiver un événement le retire
+des sélecteurs courants sans effacer son historique. Les champs legacy
+`congress_presence`, `next_congress`, `next_congress_date` et `card_congress`
+restent disponibles pour compatibilité/export, mais ne sont jamais synchronisés
+depuis ce modèle.
+
+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.
+
 ## Tools disponibles
 
 | Tool | Description |
@@ -200,14 +224,16 @@ Conséquences pratiques :
 | `create_lead_group` | Créer un groupe et choisir son type canonique optionnel (`GENERIC`, `COMPANY` ou `PERSON`) via `entity_kind`. |
 | `update_lead_group` | Modifier un groupe, y compris son `entity_kind`, avec réconciliation du schéma côté Leadify. |
 | `add_leads` | Ajouter un ou plusieurs leads à un groupe. |
-| `get_leads` | Rechercher et lister des leads avec filtres, recherche et pagination. |
+| `get_leads` | Rechercher et lister des leads avec filtres, recherche et pagination, dont le critère composé `event_filter`. |
 | `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.
+| `list_events` | Lister les événements tenant-scoped ; les événements archivés sont masqués par défaut. |
+| `get_event` | Lire un événement partagé et son état d’archivage. |
+| `create_event` | Créer un événement partagé avec une clé d’idempotence. |
+| `update_event` | Modifier ou archiver sans suppression un événement partagé, avec version attendue. |
+| `list_event_participations` | Lister les participations d’entreprise ; filtre explicitement `VERIFIED` par défaut. |
+| `get_event_participation` | Lire un snapshot courant et son historique ; `VERIFIED` par défaut, statut incertain à demander explicitement. |
+| `record_event_participations` | Valider à blanc ou enregistrer un lot idempotent de 1 à 100 observations/corrections. |
 | `preview_reset_sequence_messages` / `execute_reset_sequence_messages` | Prévisualiser puis effacer irréversiblement les messages générés d'un prospect, d'une liste explicite ou d'un groupe explicite. L'exécution exige le digest de preview et une clé d'idempotence. |
 | `preview_reset_ai_fields` / `execute_reset_ai_fields` | Prévisualiser puis effacer irréversiblement les champs IA d'un prospect, d'une liste explicite ou d'un groupe explicite, sans toucher aux contacts, flags manuels, activités ou campagnes. |
 | `delete_leads` | Supprimer définitivement des leads par leurs IDs. |
@@ -219,7 +245,8 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `get_campaign_logs` | Récupérer les logs de campagne avec filtres et pagination. |
 | `delete_campaign_log` | Supprimer une entrée de log de campagne. |
 | `update_campaign_stats` | Mettre à jour les statistiques d'email d'une campagne pour un groupe de leads. |
-| `create_campaign` | Créer une campagne DRAFT mono-canal rattachée à un groupe de leads. `channel` (`LINKEDIN` ou `EMAIL`) est obligatoire : aucun défaut LinkedIn implicite. La fenêtre de campagne (`startAt`/`endAt`) et le contrat de clôture ne sont pas encore supportés par l'API Leadify ; ne pas utiliser cet outil pour une campagne bornée dans le temps avant cette livraison. |
+| `create_campaign` | Créer une campagne DRAFT mono-canal rattachée à un groupe de leads. `channel` (`LINKEDIN` ou `EMAIL`) est obligatoire ; `start_at`, `end_at` et `timezone` configurent la fenêtre métier. À `end_at`, Leadify ferme la campagne idempotemment, annule uniquement les jobs prouvablement pré-fournisseur et préserve les autres pour réconciliation. |
+| `update_campaign_configuration` | Corriger le canal ou la fenêtre d'une campagne DRAFT encore ouverte, sans activation ni enrôlement. |
 | `list_campaigns` | Lister compactement les campagnes d'une organisation explicitement sélectionnée et leur statut courant. |
 | `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). |

package/dist/server.js

@@ -16,6 +16,7 @@ import { registerContextWorkspaceTools } from "./tools/context_workspace.js";
 import { registerLeadViewTools } from "./tools/views.js";
 import { registerRelationshipTools } from "./tools/relationships.js";
 import { registerCommercialTruthTools } from "./tools/commercial_truth.js";
+import { registerEventTools } from "./tools/events.js";
 import { MCP_SERVER_NAME, MCP_VERSION } from "./version.js";
 export function createServer() {
     const server = new McpServer({
@@ -28,6 +29,7 @@ export function createServer() {
     registerLeadViewTools(server);
     registerLeadTools(server);
     registerRelationshipTools(server);
+    registerEventTools(server);
     registerCommercialTruthTools(server);
     registerSchemaTools(server);
     registerLogTools(server);

package/dist/tools/campaigns.d.ts

@@ -2,5 +2,6 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type LeadifyClient } from "../client.js";
 type CampaignReadClient = Pick<LeadifyClient, "get">;
 type CampaignWriteClient = Pick<LeadifyClient, "post">;
-export declare function registerCampaignTools(server: McpServer, readClient?: CampaignReadClient, writeClient?: CampaignWriteClient): void;
+type CampaignMutationClient = Pick<LeadifyClient, "put">;
+export declare function registerCampaignTools(server: McpServer, readClient?: CampaignReadClient, writeClient?: CampaignWriteClient, mutationClient?: CampaignMutationClient): void;
 export {};

package/dist/tools/campaigns.js

@@ -19,7 +19,7 @@ function assertCampaignBelongsToOrganization(data, organizationId) {
     }
     return campaign;
 }
-export function registerCampaignTools(server, readClient, writeClient) {
+export function registerCampaignTools(server, readClient, writeClient, mutationClient) {
     // ── update_campaign_stats ──────────────────────────────────────────────
     server.tool("update_campaign_stats", "Update email campaign statistics for a lead group. If the given campaignSlug " +
         "doesn't exist in the group's stats yet, it is created; otherwise provided fields " +
@@ -88,26 +88,33 @@ export function registerCampaignTools(server, readClient, writeClient) {
         }
     });
     // ── create_campaign ────────────────────────────────────────────────────
-    server.tool("create_campaign", "Create a mono-channel DRAFT campaign linked to an existing lead group. channel is required " +
-        "so no campaign silently defaults to LinkedIn. The current Leadify API does not yet persist " +
-        "a campaign start/end window or closure contract: do not use this tool for a time-bounded " +
-        "campaign until that API support is released. Returns the new campaign ID; use " +
-        "update_campaign_status only after the campaign is fully configured and explicitly approved.", {
+    server.tool("create_campaign", "Create a mono-channel DRAFT campaign with an explicit channel, optional ISO-8601 start/end " +
+        "window, and IANA timezone. At endAt Leadify closes the campaign idempotently, cancels only " +
+        "pre-provider jobs, and preserves any provider-barrier job for reconciliation.", {
         name: z.string().describe("Campaign name."),
         lead_group_id: z.string().describe("ID of the lead group to associate."),
         channel: z.enum(["LINKEDIN", "EMAIL"]).describe("Required effective delivery channel. Create separate campaigns for LinkedIn and email."),
+        start_at: z.string().datetime().optional().describe("Optional inclusive campaign start timestamp in ISO-8601 UTC."),
+        end_at: z.string().datetime().optional().describe("Optional exclusive campaign end timestamp in ISO-8601 UTC; must be after start_at."),
+        timezone: z.string().min(1).optional().describe("IANA timezone used for the campaign business window, for example Europe/Paris."),
         description: z.string().optional().describe("Optional description."),
         persona_id: z
             .string()
             .optional()
             .describe("ID of the persona to assign (optional)."),
-    }, async ({ name, lead_group_id, channel, description, persona_id }) => {
+    }, async ({ name, lead_group_id, channel, start_at, end_at, timezone, description, persona_id }) => {
         try {
             const body = {
                 name,
                 leadGroupId: lead_group_id,
                 channel,
             };
+            if (start_at !== undefined)
+                body.startAt = start_at;
+            if (end_at !== undefined)
+                body.endAt = end_at;
+            if (timezone !== undefined)
+                body.timezone = timezone;
             if (description !== undefined)
                 body.description = description;
             if (persona_id !== undefined)
@@ -119,6 +126,29 @@ export function registerCampaignTools(server, readClient, writeClient) {
             return handleToolError(error);
         }
     });
+    server.tool("update_campaign_configuration", "Correct an open DRAFT campaign's channel or lifecycle window before activation. This tool refuses ACTIVE, PAUSED, COMPLETED, or closed campaigns and never activates or enrolls prospects.", {
+        id: z.string().describe("Campaign ID."),
+        channel: z.enum(["LINKEDIN", "EMAIL"]).optional(),
+        start_at: z.string().datetime().nullable().optional(),
+        end_at: z.string().datetime().nullable().optional(),
+        timezone: z.string().min(1).optional(),
+    }, async ({ id, channel, start_at, end_at, timezone }) => {
+        try {
+            const body = {};
+            if (channel !== undefined)
+                body.channel = channel;
+            if (start_at !== undefined)
+                body.startAt = start_at;
+            if (end_at !== undefined)
+                body.endAt = end_at;
+            if (timezone !== undefined)
+                body.timezone = timezone;
+            return toolResult(await (mutationClient ?? getClient()).put(`/api/campaign/${encodeURIComponent(id)}/configuration`, body));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
     // ── get_campaign ───────────────────────────────────────────────────────
     server.tool("get_campaign", "Retrieve a campaign chosen from list_campaigns, scoped to the explicitly selected " +
         "organization. Includes its normalized current status (DRAFT, ACTIVE, PAUSED, or COMPLETED) " +

package/dist/tools/events.d.ts

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

package/dist/tools/events.js

@@ -0,0 +1,340 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { handleToolError, toolError, toolResult } from "../types.js";
+const dateOnly = z.string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, "Use an ISO date in YYYY-MM-DD format.")
+    .refine((value) => {
+    const parsed = new Date(`${value}T00:00:00.000Z`);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}, "Use a real calendar date in YYYY-MM-DD format.");
+const role = z.enum([
+    "EXHIBITOR",
+    "SPONSOR",
+    "SPEAKER",
+    "PARTNER",
+    "ORGANIZER",
+    "CONTRIBUTOR",
+    "PARTICIPANT",
+    "UNKNOWN",
+    "OTHER",
+]);
+const status = z.enum(["UNVERIFIED", "VERIFIED", "DISPUTED", "REFUTED"]);
+const confidence = z.enum(["LOW", "MEDIUM", "HIGH"]);
+const nullableLabel = z.string().trim().min(1).max(500).nullable().optional();
+const nullableUrl = z.string().trim().url().max(2048).nullable().optional();
+const idempotencyKey = z.string().trim().min(1).max(255);
+const eventFields = {
+    name: z.string().trim().min(1).max(300),
+    edition: z.string().trim().min(1).max(200),
+    starts_on: dateOnly,
+    ends_on: dateOnly,
+    city: nullableLabel,
+    country_code: z.string().trim().regex(/^[A-Za-z]{2}$/).transform((value) => value.toUpperCase()).nullable().optional(),
+    venue: nullableLabel,
+    official_url: nullableUrl,
+    last_verified_on: dateOnly.nullable().optional(),
+};
+const createEventShape = {
+    organization_id: z.string().trim().min(1),
+    slug: z.string().trim().min(1).max(160).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+    ...eventFields,
+    idempotency_key: idempotencyKey,
+};
+const createEventInput = z.object(createEventShape).strict().superRefine((value, context) => {
+    if (value.ends_on < value.starts_on) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["ends_on"], message: "ends_on must be on or after starts_on." });
+    }
+});
+const updateEventShape = {
+    organization_id: z.string().trim().min(1),
+    event_id: z.string().trim().min(1),
+    name: eventFields.name.optional(),
+    edition: eventFields.edition.optional(),
+    starts_on: eventFields.starts_on.optional(),
+    ends_on: eventFields.ends_on.optional(),
+    city: eventFields.city,
+    country_code: eventFields.country_code,
+    venue: eventFields.venue,
+    official_url: eventFields.official_url,
+    last_verified_on: eventFields.last_verified_on,
+    archive: z.boolean().optional().default(false),
+    expected_version: z.number().int().positive(),
+    idempotency_key: idempotencyKey,
+};
+const updateEventInput = z.object(updateEventShape).strict().superRefine((value, context) => {
+    const mutable = ["name", "edition", "starts_on", "ends_on", "city", "country_code", "venue", "official_url", "last_verified_on"];
+    const supplied = mutable.filter((key) => value[key] !== undefined);
+    if (value.archive && supplied.length > 0) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["archive"], message: "Archive and field updates must be separate idempotent operations." });
+    }
+    if (!value.archive && supplied.length === 0) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "Provide at least one field to update, or set archive=true." });
+    }
+    if (value.starts_on && value.ends_on && value.ends_on < value.starts_on) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["ends_on"], message: "ends_on must be on or after starts_on." });
+    }
+});
+const participationItem = z.object({
+    event_id: z.string().trim().min(1),
+    account_id: z.string().trim().min(1).optional(),
+    lead_id: z.string().trim().min(1).optional(),
+    roles: z.array(role).min(1).max(20),
+    role_details: z.array(z.string().trim().min(1).max(500)).max(50).optional().default([]),
+    stands: z.array(z.string().trim().min(1).max(200)).max(50).optional().default([]),
+    source_urls: z.array(z.string().trim().url().max(2048)).max(50).optional().default([]),
+    source_provider: nullableLabel,
+    proof_excerpt: z.string().trim().min(1).max(20_000),
+    observed_on: dateOnly,
+    verified_on: dateOnly.nullable().optional(),
+    confidence,
+    status,
+    correction_reason: z.string().trim().min(1).max(5_000).optional(),
+    idempotency_key: idempotencyKey,
+}).strict().superRefine((value, context) => {
+    if (Number(Boolean(value.account_id)) + Number(Boolean(value.lead_id)) !== 1) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "Provide exactly one account_id or lead_id." });
+    }
+    if (value.status === "VERIFIED" && value.source_urls.length === 0) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["source_urls"], message: "VERIFIED requires at least one source URL." });
+    }
+    if (value.status === "VERIFIED" && !value.verified_on) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["verified_on"], message: "VERIFIED requires verified_on." });
+    }
+    if (value.verified_on && value.verified_on < value.observed_on) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["verified_on"], message: "verified_on must be on or after observed_on." });
+    }
+});
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, child]) => child !== undefined));
+}
+function setCsv(params, key, values) {
+    if (values?.length)
+        params.set(key, values.join(","));
+}
+function participationPayload(item) {
+    return compact({
+        eventId: item.event_id,
+        accountId: item.account_id,
+        leadId: item.lead_id,
+        roles: item.roles,
+        roleDetails: item.role_details,
+        stands: item.stands,
+        sourceUrls: item.source_urls,
+        sourceProvider: item.source_provider,
+        proofExcerpt: item.proof_excerpt,
+        observedOn: item.observed_on,
+        verifiedOn: item.verified_on,
+        confidence: item.confidence,
+        status: item.status,
+        correctionReason: item.correction_reason,
+        idempotencyKey: item.idempotency_key,
+    });
+}
+function filterFactHistory(data, acceptedStatuses) {
+    const projectParticipation = (value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return value;
+        const participation = value;
+        if (!Array.isArray(participation.facts))
+            return participation;
+        const facts = participation.facts.filter((fact) => (fact && typeof fact === "object" && !Array.isArray(fact)
+            && typeof fact.status === "string"
+            && acceptedStatuses.includes(fact.status)));
+        return {
+            ...participation,
+            facts,
+            hiddenFactCount: participation.facts.length - facts.length,
+        };
+    };
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return data;
+    const source = data;
+    if (Array.isArray(source.items)) {
+        return { ...source, items: source.items.map(projectParticipation) };
+    }
+    if (source.participation) {
+        return { ...source, participation: projectParticipation(source.participation) };
+    }
+    return source;
+}
+export function registerEventTools(server, client = getClient()) {
+    server.tool("list_events", "List tenant-scoped events. Archived events are hidden unless include_archived=true. An event alone is not evidence that a company attended; cite participation only from a matching VERIFIED participation.", {
+        organization_id: z.string().trim().min(1),
+        include_archived: z.boolean().optional().default(false),
+        search: z.string().trim().min(1).max(200).optional(),
+        editions: z.array(z.string().trim().min(1).max(200)).max(100).optional(),
+        starts_on_from: dateOnly.optional(),
+        starts_on_to: dateOnly.optional(),
+        limit: z.number().int().min(1).max(100).optional().default(50),
+        cursor: z.string().trim().min(1).optional(),
+    }, async ({ organization_id, include_archived, search, editions, starts_on_from, starts_on_to, limit, cursor }) => {
+        try {
+            const params = new URLSearchParams({
+                organizationId: organization_id,
+                includeArchived: String(include_archived ?? false),
+                limit: String(limit ?? 50),
+            });
+            if (search)
+                params.set("search", search);
+            setCsv(params, "editions", editions);
+            if (starts_on_from)
+                params.set("startsOnFrom", starts_on_from);
+            if (starts_on_to)
+                params.set("startsOnTo", starts_on_to);
+            if (cursor)
+                params.set("cursor", cursor);
+            return toolResult(await client.get("/api/events", params));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("get_event", "Get one tenant-scoped event, including its archive state and current participation count. This does not establish that any particular company attended.", {
+        organization_id: z.string().trim().min(1),
+        event_id: z.string().trim().min(1),
+    }, async ({ organization_id, event_id }) => {
+        try {
+            return toolResult(await client.get(`/api/events/${encodeURIComponent(event_id)}`, new URLSearchParams({ organizationId: organization_id })));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("create_event", "Create one reusable tenant-scoped event. The idempotency key makes an identical retry safe; changing the payload under the same key is rejected. Creating an event does not create company participation evidence.", createEventShape, async (params) => {
+        try {
+            const input = createEventInput.parse(params);
+            return toolResult(await client.post("/api/events", compact({
+                organizationId: input.organization_id,
+                slug: input.slug,
+                name: input.name,
+                edition: input.edition,
+                startsOn: input.starts_on,
+                endsOn: input.ends_on,
+                city: input.city,
+                countryCode: input.country_code,
+                venue: input.venue,
+                officialUrl: input.official_url,
+                lastVerifiedOn: input.last_verified_on,
+                idempotencyKey: input.idempotency_key,
+            })));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("update_event", "Update or archive one shared event with optimistic versioning and idempotency. Set archive=true as a separate operation with no field changes. This affects every company view that references the event; archiving is non-destructive and keeps all participation evidence.", updateEventShape, async (params) => {
+        try {
+            const input = updateEventInput.parse(params);
+            const body = input.archive
+                ? {
+                    organizationId: input.organization_id,
+                    archive: true,
+                    expectedVersion: input.expected_version,
+                    idempotencyKey: input.idempotency_key,
+                }
+                : compact({
+                    organizationId: input.organization_id,
+                    name: input.name,
+                    edition: input.edition,
+                    startsOn: input.starts_on,
+                    endsOn: input.ends_on,
+                    city: input.city,
+                    countryCode: input.country_code,
+                    venue: input.venue,
+                    officialUrl: input.official_url,
+                    lastVerifiedOn: input.last_verified_on,
+                    expectedVersion: input.expected_version,
+                    idempotencyKey: input.idempotency_key,
+                });
+            return toolResult(await client.patch(`/api/events/${encodeURIComponent(input.event_id)}`, body));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("list_event_participations", "List current company-event participation snapshots in one tenant. Defaults explicitly to VERIFIED only. To review uncertain evidence or uncertain historical facts, pass statuses containing UNVERIFIED, DISPUTED or REFUTED; unrequested fact statuses are hidden and counted. Never cite uncertain data, or the absence of a record, as proof of attendance or non-attendance.", {
+        organization_id: z.string().trim().min(1),
+        event_ids: z.array(z.string().trim().min(1)).max(100).optional(),
+        account_ids: z.array(z.string().trim().min(1)).max(100).optional(),
+        lead_id: z.string().trim().min(1).optional(),
+        editions: z.array(z.string().trim().min(1).max(200)).max(100).optional(),
+        roles: z.array(role).max(20).optional(),
+        statuses: z.array(status).min(1).max(10).optional().default(["VERIFIED"]),
+        confidences: z.array(confidence).max(10).optional(),
+        starts_on_from: dateOnly.optional(),
+        starts_on_to: dateOnly.optional(),
+        include_facts: z.boolean().optional().default(false),
+        limit: z.number().int().min(1).max(100).optional().default(50),
+        cursor: z.string().trim().min(1).optional(),
+    }, async ({ organization_id, event_ids, account_ids, lead_id, editions, roles, statuses, confidences, starts_on_from, starts_on_to, include_facts, limit, cursor }) => {
+        try {
+            const params = new URLSearchParams({
+                organizationId: organization_id,
+                statuses: (statuses ?? ["VERIFIED"]).join(","),
+                includeFacts: String(include_facts ?? false),
+                limit: String(limit ?? 50),
+            });
+            setCsv(params, "eventIds", event_ids);
+            setCsv(params, "accountIds", account_ids);
+            if (lead_id)
+                params.set("leadId", lead_id);
+            setCsv(params, "editions", editions);
+            setCsv(params, "roles", roles);
+            setCsv(params, "confidences", confidences);
+            if (starts_on_from)
+                params.set("startsOnFrom", starts_on_from);
+            if (starts_on_to)
+                params.set("startsOnTo", starts_on_to);
+            if (cursor)
+                params.set("cursor", cursor);
+            const acceptedStatuses = statuses ?? ["VERIFIED"];
+            return toolResult(filterFactHistory(await client.get("/api/event-participations", params), acceptedStatuses));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("get_event_participation", "Get one explicitly selected current participation and its immutable fact history. Access defaults to VERIFIED only; pass statuses explicitly to review UNVERIFIED, DISPUTED or REFUTED facts. Uncertain evidence is not verified attendance, and missing data never means non-participation.", {
+        organization_id: z.string().trim().min(1),
+        participation_id: z.string().trim().min(1),
+        statuses: z.array(status).min(1).max(10).optional().default(["VERIFIED"]),
+    }, async ({ organization_id, participation_id, statuses }) => {
+        try {
+            const data = await client.get(`/api/event-participations/${encodeURIComponent(participation_id)}`, new URLSearchParams({ organizationId: organization_id }));
+            const source = data && typeof data === "object" ? data : {};
+            const participation = source.participation && typeof source.participation === "object"
+                ? source.participation
+                : null;
+            const accepted = statuses ?? ["VERIFIED"];
+            if (!participation || typeof participation.status !== "string") {
+                return toolError("Leadify returned an invalid event participation response.");
+            }
+            if (!accepted.includes(participation.status)) {
+                return toolError(`Participation status ${participation.status} was not explicitly requested. Pass statuses including ${participation.status} to review this uncertain fact.`);
+            }
+            return toolResult(filterFactHistory(data, accepted));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.tool("record_event_participations", "Validate or record 1-100 company-event participation observations. Set validate_only=true for a no-write dry-run. Each item targets exactly one account_id or resolvable lead_id and has its own idempotency key. Corrections append an immutable fact and require correction_reason; there is no delete operation. VERIFIED requires a source URL, proof excerpt and verification date. Uncertain or absent data cannot be cited as attendance.", {
+        organization_id: z.string().trim().min(1),
+        batch_id: z.string().trim().min(1).max(255),
+        validate_only: z.boolean().optional().default(false),
+        items: z.array(participationItem).min(1).max(100),
+    }, async ({ organization_id, batch_id, validate_only, items }) => {
+        try {
+            const parsedItems = z.array(participationItem).min(1).max(100).parse(items);
+            return toolResult(await client.post("/api/event-participations/batch", {
+                organizationId: organization_id,
+                batchId: batch_id,
+                validateOnly: validate_only ?? false,
+                items: parsedItems.map(participationPayload),
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/tools/leads.js

@@ -2,6 +2,22 @@ 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 eventFilterSchema = z.object({
+    event_ids: z.array(z.string().trim().min(1)).max(100).optional(),
+    editions: z.array(z.string().trim().min(1).max(200)).max(100).optional(),
+    roles: z.array(z.enum([
+        "EXHIBITOR", "SPONSOR", "SPEAKER", "PARTNER", "ORGANIZER",
+        "CONTRIBUTOR", "PARTICIPANT", "UNKNOWN", "OTHER",
+    ])).max(20).optional(),
+    statuses: z.array(z.enum(["UNVERIFIED", "VERIFIED", "DISPUTED", "REFUTED"])).min(1).max(10).optional(),
+    confidences: z.array(z.enum(["LOW", "MEDIUM", "HIGH"])).max(10).optional(),
+    starts_on_from: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+    starts_on_to: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+}).strict().superRefine((value, context) => {
+    if (value.starts_on_from && value.starts_on_to && value.starts_on_to < value.starts_on_from) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["starts_on_to"], message: "starts_on_to must be on or after starts_on_from." });
+    }
+});
 const canonicalLocationSchema = z.object({
     city: z.string().trim().min(1).max(200),
     region: z.string().trim().min(1).max(500).optional(),
@@ -143,7 +159,9 @@ export function registerLeadTools(server, client = getClient()) {
     server.tool("get_leads", "Search and list leads from a Leadify lead group with optional filtering, search, " +
         "full-text search, saved views, and compact field projections. Returns lead ID plus " +
         "common identity fields by default. Pass `fields` for a workflow-specific projection " +
-        "and `include_schema=true` only when the schema is explicitly needed.", {
+        "and `include_schema=true` only when the schema is explicitly needed. event_filter " +
+        "uses one correlated company participation and defaults explicitly to VERIFIED; " +
+        "uncertain or absent data must never be cited as attendance or non-attendance.", {
         group_id: z.string().describe("ID of the lead group to query."),
         view_id: z
             .string()
@@ -175,7 +193,8 @@ export function registerLeadTools(server, client = getClient()) {
             "operator to value. Operators: equals, not_equals, contains, not_contains, " +
             "gte, lte, is_true, is_false, is_null, is_not_null. " +
             'Example: {"industry": {"contains": "tech"}, "company": {"is_not_null": "true"}}'),
-    }, async ({ group_id, view_id, page, limit, search, fields, include_schema, filters }) => {
+        event_filter: eventFilterSchema.optional().describe("Structured company-event participation filter. Values within one list use OR; event, edition, role, status, confidence and date dimensions use AND against the same participation. statuses defaults to [VERIFIED]. Pass uncertain statuses explicitly for review. There is no negative or absence filter."),
+    }, async ({ group_id, view_id, page, limit, search, fields, include_schema, filters, event_filter }) => {
         try {
             const params = new URLSearchParams();
             params.set("groupId", group_id);
@@ -194,6 +213,18 @@ export function registerLeadTools(server, client = getClient()) {
                     }
                 }
             }
+            if (event_filter) {
+                const checked = eventFilterSchema.parse(event_filter);
+                params.set("eventFilter", JSON.stringify({
+                    ...(checked.event_ids ? { eventIds: checked.event_ids } : {}),
+                    ...(checked.editions ? { editions: checked.editions } : {}),
+                    ...(checked.roles ? { roles: checked.roles } : {}),
+                    statuses: checked.statuses ?? ["VERIFIED"],
+                    ...(checked.confidences ? { confidences: checked.confidences } : {}),
+                    ...(checked.starts_on_from ? { startsOnFrom: checked.starts_on_from } : {}),
+                    ...(checked.starts_on_to ? { startsOnTo: checked.starts_on_to } : {}),
+                }));
+            }
             const data = await client.get("/get-leads", params);
             return toolResult(compactLeadsResponse(data, fields ?? DEFAULT_LEAD_FIELDS, include_schema));
         }

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const MCP_PACKAGE_NAME = "@agifyai/leadify-mcp";
 export declare const MCP_SERVER_NAME = "leadify";
-export declare const MCP_VERSION = "8.5.2";
+export declare const MCP_VERSION = "8.5.4";

package/dist/version.js

@@ -1,3 +1,3 @@
 export const MCP_PACKAGE_NAME = "@agifyai/leadify-mcp";
 export const MCP_SERVER_NAME = "leadify";
-export const MCP_VERSION = "8.5.2";
+export const MCP_VERSION = "8.5.4";

package/package.json

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