@agifyai/leadify-mcp 9.6.0 → 9.7.0

package/README.md

@@ -195,8 +195,12 @@ 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
+Une participation porte sur une entreprise ou sur une personne (PRD-2475,
+serveur PRD-2473). Un `account_id` ou le `lead_id` d’un prospect Entreprise
+écrit, comme avant, sur l’entreprise canonique (`Account`). Le `lead_id` d’un
+prospect Personne, ou un `person_id` (`canonicalIdentity.id` d’un prospect Personne, `kind: PERSON`), écrit une
+participation propre à la personne canonique : elle la suit dans tous ses
+groupes. Les outils d’events d’entreprise fonctionnent comme avant. `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
@@ -211,6 +215,31 @@ des sélecteurs courants sans effacer son historique. Les champs legacy
 restent disponibles pour compatibilité/export, mais ne sont jamais synchronisés
 depuis ce modèle.
 
+Événements d’une personne :
+
+- Rôles d’une personne : `REGISTERED` (inscrit), `ATTENDED` (présent),
+  `INVITED` (invité), `SPEAKER`, `ORGANIZER`, `OTHER`. Les trois premiers sont
+  refusés pour une entreprise. Inscrit, présent et invité sont trois faits
+  distincts : une inscription ne prouve jamais une présence.
+- Une liste d’inscrits fournie par le client est une preuve valable de
+  l’inscription, y compris pour une personne désinscrite ensuite ou inscrite
+  plusieurs fois : rôle `REGISTERED` et `client_document { file_name,
+  received_on, provided_by }`, sans adresse web. `VERIFIED` exige une adresse
+  web ou un `client_document`.
+- Un event de l’employeur n’est jamais une participation de la personne. Lue
+  avec le `lead_id` d’une personne, `list_event_participations` rend ses
+  participations propres (`origin: PERSON`) puis celles de son employeur
+  (`origin: EMPLOYER`). Sans `target`, `person_ids` ni `lead_id` de personne,
+  la liste ne rend que les entreprises, comme avant ; `target: PERSON` ou
+  `person_ids` lisent les personnes.
+- `get_leads.event_filter.subject` vaut `EMPLOYER` (défaut, comportement
+  historique) ou `PERSON` (seules les personnes qui portent elles-mêmes la
+  participation, par exemple les inscrits d’un webinar).
+- Les events ont un type facultatif `event_type` : `WEBINAR`, `CONGRESS`,
+  `TRADE_SHOW`, `OTHER` (filtre `event_types` dans `list_events`).
+  `get_event` rend `participationCounts { companies, persons }`.
+- L’absence d’enregistrement ne prouve rien.
+
 Il n’existe plus de score de confiance événementiel : le statut et ses preuves
 portent seuls la validation utile. `Event.description` explique l’audience et
 l’utilité de l’événement ; `activity_summary` explique ce que l’entreprise y
@@ -244,17 +273,17 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `preview_move_leads` | Essai à blanc du déplacement de fiches vers un autre groupe de la même organisation : sélection par identifiants, vue ou filtre (500 fiches au plus par appel, lots ensuite), refus par fiche avec motif, doublons dans le groupe cible, champs de schéma et relations à ajouter, blocages et empreinte du plan. |
 | `move_leads` | Appliquer un déplacement prévisualisé ; exige l'empreinte de la prévisualisation et une clé d'idempotence. La fiche garde son identifiant et tout son historique ; jamais de fusion. |
 | `undo_move_leads` / `get_lead_move` | Annuler ou relire une opération de déplacement par son identifiant. |
-| `get_leads` | Rechercher et lister des leads avec filtres, recherche et pagination, dont le critère composé `event_filter`. |
+| `get_leads` | Rechercher et lister des leads avec filtres, recherche et pagination, dont le critère composé `event_filter` (`subject` : employeur ou personne). |
 | `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. |
 | `clear_lead_field` | Effacer irréversiblement une valeur stockée, sans modifier le schéma du groupe. Exige la confirmation explicite `clear_lead_field`. |
-| `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. |
+| `list_events` | Lister les événements tenant-scoped, filtrables par type (`event_types`) ; les événements archivés sont masqués par défaut. |
+| `get_event` | Lire un événement partagé, son type, son état d’archivage et ses nombres d’entreprises et de personnes rattachées. |
+| `create_event` | Créer un événement partagé, avec son type facultatif, et une clé d’idempotence. |
+| `update_event` | Modifier (dont le type) ou archiver sans suppression un événement partagé, avec version attendue. |
+| `list_event_participations` | Lister les participations d’entreprise et de personne, avec leur provenance ; filtres `target`, `person_ids` ; `VERIFIED` par défaut. |
+| `get_event_participation` | Lire un snapshot courant d’entreprise ou de personne 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 d’entreprise ou de personne (inscrit, présent, invité, preuve « document du client »). |
 | `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. |

package/dist/tools/events.d.ts

@@ -1,2 +1,8 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+export declare const COMPANY_EVENT_ROLES: readonly ["EXHIBITOR", "SPONSOR", "SPEAKER", "PARTNER", "ORGANIZER", "CONTRIBUTOR", "PARTICIPANT", "UNKNOWN", "OTHER"];
+export declare const PERSON_ONLY_EVENT_ROLES: readonly ["REGISTERED", "ATTENDED", "INVITED"];
+export declare const PERSON_EVENT_ROLES: readonly ["REGISTERED", "ATTENDED", "INVITED", "SPEAKER", "ORGANIZER", "OTHER"];
+export declare const eventRole: z.ZodEnum<["EXHIBITOR", "SPONSOR", "SPEAKER", "PARTNER", "ORGANIZER", "CONTRIBUTOR", "PARTICIPANT", "UNKNOWN", "OTHER", "REGISTERED", "ATTENDED", "INVITED"]>;
+export declare const eventType: z.ZodEnum<["WEBINAR", "CONGRESS", "TRADE_SHOW", "OTHER"]>;
 export declare function registerEventTools(server: McpServer, client?: import("../client.js").LeadifyClient): void;

package/dist/tools/events.js

@@ -7,7 +7,10 @@ const dateOnly = z.string()
     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([
+// Company roles are the nine historical ones. REGISTERED, ATTENDED and
+// INVITED are three distinct facts about a person (PRD-2473 contract):
+// a registration never proves attendance, an invitation proves neither.
+export const COMPANY_EVENT_ROLES = [
     "EXHIBITOR",
     "SPONSOR",
     "SPEAKER",
@@ -17,7 +20,13 @@ const role = z.enum([
     "PARTICIPANT",
     "UNKNOWN",
     "OTHER",
-]);
+];
+export const PERSON_ONLY_EVENT_ROLES = ["REGISTERED", "ATTENDED", "INVITED"];
+export const PERSON_EVENT_ROLES = ["REGISTERED", "ATTENDED", "INVITED", "SPEAKER", "ORGANIZER", "OTHER"];
+export const eventRole = z.enum([...COMPANY_EVENT_ROLES, ...PERSON_ONLY_EVENT_ROLES]);
+const role = eventRole;
+export const eventType = z.enum(["WEBINAR", "CONGRESS", "TRADE_SHOW", "OTHER"]);
+const target = z.enum(["COMPANY", "PERSON"]);
 const status = z.enum(["UNVERIFIED", "VERIFIED", "DISPUTED", "REFUTED"]);
 const nullableLabel = z.string().trim().min(1).max(500).nullable().optional();
 const nullableNarrative = z.string().trim().min(1).max(5_000).nullable().optional();
@@ -35,10 +44,12 @@ const eventFields = {
     official_url: nullableUrl,
     last_verified_on: dateOnly.nullable().optional(),
 };
+const eventTypeDescription = "Event type: WEBINAR, CONGRESS, TRADE_SHOW or OTHER. Omitted means not specified.";
 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,
+    event_type: eventType.optional().describe(eventTypeDescription),
     idempotency_key: idempotencyKey,
 };
 const createEventInput = z.object(createEventShape).strict().superRefine((value, context) => {
@@ -59,12 +70,13 @@ const updateEventShape = {
     venue: eventFields.venue,
     official_url: eventFields.official_url,
     last_verified_on: eventFields.last_verified_on,
+    event_type: eventType.nullable().optional().describe("New event type (WEBINAR, CONGRESS, TRADE_SHOW, OTHER), or null to mark it as not specified."),
     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", "description", "starts_on", "ends_on", "city", "country_code", "venue", "official_url", "last_verified_on"];
+    const mutable = ["name", "edition", "description", "starts_on", "ends_on", "city", "country_code", "venue", "official_url", "last_verified_on", "event_type"];
     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." });
@@ -76,16 +88,23 @@ const updateEventInput = z.object(updateEventShape).strict().superRefine((value,
         context.addIssue({ code: z.ZodIssueCode.custom, path: ["ends_on"], message: "ends_on must be on or after starts_on." });
     }
 });
+const clientDocument = z.object({
+    file_name: z.string().trim().min(1).max(300).describe("Name of the file the client sent, e.g. the registrants spreadsheet."),
+    received_on: dateOnly.describe("Date the file was received, YYYY-MM-DD."),
+    provided_by: z.string().trim().min(1).max(300).describe("Who provided the file (client organization or contact)."),
+}).strict().describe("Proof by a document provided by the client, without a web address. A client's registrants list is valid proof of registration (role REGISTERED), including for a person who later unsubscribed or registered several times. It is not proof of attendance.");
 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),
+    account_id: z.string().trim().min(1).optional().describe("Company target: canonical account id."),
+    lead_id: z.string().trim().min(1).optional().describe("Company lead (writes on its account) or Person lead (writes a personal participation on its canonical person)."),
+    person_id: z.string().trim().min(1).optional().describe("Person target: canonical person id: canonicalIdentity.id of a Person lead (canonicalIdentity.kind PERSON), as returned by get_lead."),
+    roles: z.array(role).min(1).max(20).describe("Company roles: EXHIBITOR, SPONSOR, SPEAKER, PARTNER, ORGANIZER, CONTRIBUTOR, PARTICIPANT, UNKNOWN, OTHER. Person roles: REGISTERED, ATTENDED, INVITED, SPEAKER, ORGANIZER, OTHER. REGISTERED, ATTENDED and INVITED are reserved to persons and are three distinct facts."),
     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([]),
+    client_document: clientDocument.optional(),
     source_provider: nullableLabel,
-    activity_summary: nullableNarrative.describe("Readable summary of what the company does, presents or targets at this event."),
+    activity_summary: nullableNarrative.describe("Readable summary of what the company or person does, presents or targets at this event."),
     proof_excerpt: z.string().trim().min(1).max(20_000),
     observed_on: dateOnly,
     verified_on: dateOnly.nullable().optional(),
@@ -93,11 +112,24 @@ const participationItem = z.object({
     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." });
+    const targets = [value.account_id, value.lead_id, value.person_id].filter(Boolean).length;
+    if (targets !== 1) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "Provide exactly one account_id, lead_id or person_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.account_id) {
+        const refused = value.roles.filter((item) => PERSON_ONLY_EVENT_ROLES.includes(item));
+        if (refused.length) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["roles"], message: `Roles reserved to a person cannot be recorded on a company: ${refused.join(", ")}.` });
+        }
+    }
+    if (value.person_id) {
+        const refused = value.roles.filter((item) => !PERSON_EVENT_ROLES.includes(item));
+        if (refused.length) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["roles"], message: `Roles not accepted for a person: ${refused.join(", ")}. Use REGISTERED, ATTENDED, INVITED, SPEAKER, ORGANIZER or OTHER.` });
+        }
+    }
+    if (value.status === "VERIFIED" && value.source_urls.length === 0 && !value.client_document) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["source_urls"], message: "VERIFIED requires at least one source URL or a client_document." });
     }
     if (value.status === "VERIFIED" && !value.verified_on) {
         context.addIssue({ code: z.ZodIssueCode.custom, path: ["verified_on"], message: "VERIFIED requires verified_on." });
@@ -118,10 +150,18 @@ function participationPayload(item) {
         eventId: item.event_id,
         accountId: item.account_id,
         leadId: item.lead_id,
+        personId: item.person_id,
         roles: item.roles,
         roleDetails: item.role_details,
         stands: item.stands,
         sourceUrls: item.source_urls,
+        clientDocument: item.client_document
+            ? {
+                fileName: item.client_document.file_name,
+                receivedOn: item.client_document.received_on,
+                providedBy: item.client_document.provided_by,
+            }
+            : undefined,
         sourceProvider: item.source_provider,
         activitySummary: item.activity_summary,
         proofExcerpt: item.proof_excerpt,
@@ -160,16 +200,17 @@ function filterFactHistory(data, acceptedStatuses) {
     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.", {
+    server.tool("list_events", "List tenant-scoped events. Archived events are hidden unless include_archived=true. Filter by event_types (WEBINAR, CONGRESS, TRADE_SHOW, OTHER). An event alone is not evidence that a company or a person took part; 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(),
+        event_types: z.array(eventType).min(1).max(4).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 }) => {
+    }, async ({ organization_id, include_archived, search, editions, event_types, starts_on_from, starts_on_to, limit, cursor }) => {
         try {
             const params = new URLSearchParams({
                 organizationId: organization_id,
@@ -179,6 +220,7 @@ export function registerEventTools(server, client = getClient()) {
             if (search)
                 params.set("search", search);
             setCsv(params, "editions", editions);
+            setCsv(params, "eventTypes", event_types);
             if (starts_on_from)
                 params.set("startsOnFrom", starts_on_from);
             if (starts_on_to)
@@ -191,7 +233,7 @@ export function registerEventTools(server, client = getClient()) {
             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.", {
+    server.tool("get_event", "Get one tenant-scoped event, including its type, archive state and participationCounts { companies, persons }: the number of companies and of persons that carry a participation themselves. A count does not establish that any particular company or person attended, and a person is never counted through their employer.", {
         organization_id: z.string().trim().min(1),
         event_id: z.string().trim().min(1),
     }, async ({ organization_id, event_id }) => {
@@ -202,7 +244,7 @@ export function registerEventTools(server, client = getClient()) {
             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) => {
+    server.tool("create_event", "Create one reusable tenant-scoped event, optionally typed with event_type (WEBINAR, CONGRESS, TRADE_SHOW, OTHER). The idempotency key makes an identical retry safe; changing the payload under the same key is rejected. Creating an event does not create any company or person participation evidence.", createEventShape, async (params) => {
         try {
             const input = createEventInput.parse(params);
             return toolResult(await client.post("/api/events", compact({
@@ -218,6 +260,7 @@ export function registerEventTools(server, client = getClient()) {
                 venue: input.venue,
                 officialUrl: input.official_url,
                 lastVerifiedOn: input.last_verified_on,
+                eventType: input.event_type,
                 idempotencyKey: input.idempotency_key,
             })));
         }
@@ -225,7 +268,7 @@ export function registerEventTools(server, client = getClient()) {
             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) => {
+    server.tool("update_event", "Update or archive one shared event with optimistic versioning and idempotency, including its event_type (WEBINAR, CONGRESS, TRADE_SHOW, OTHER, or null for not specified). Set archive=true as a separate operation with no field changes. This affects every company and person 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
@@ -247,6 +290,7 @@ export function registerEventTools(server, client = getClient()) {
                     venue: input.venue,
                     officialUrl: input.official_url,
                     lastVerifiedOn: input.last_verified_on,
+                    eventType: input.event_type,
                     expectedVersion: input.expected_version,
                     idempotencyKey: input.idempotency_key,
                 });
@@ -256,11 +300,13 @@ export function registerEventTools(server, client = getClient()) {
             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.", {
+    server.tool("list_event_participations", "List current event participation snapshots of companies and persons in one tenant. Without target, person_ids or a Person lead_id, only company participations are returned (historical behavior); pass target=PERSON, person_ids or the lead_id of a Person lead to read persons. Each item carries target (COMPANY or PERSON), accountId, personId, clientDocument and, for a person, personLeads. With the lead_id of a Person lead, the result holds the person's own participations (origin PERSON) and those of their employer (origin EMPLOYER): an employer's event is never a participation of the person. REGISTERED (registered), ATTENDED (attended) and INVITED (invited) are distinct facts: a registration never proves attendance. 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(),
+        person_ids: z.array(z.string().trim().min(1)).max(100).optional().describe("Canonical person ids: canonicalIdentity.id of Person leads (kind PERSON)."),
+        target: target.optional().describe("COMPANY or PERSON. Omitted: companies only, unless person_ids or a Person lead_id is given."),
+        lead_id: z.string().trim().min(1).optional().describe("Company lead: its account's participations. Person lead: its own participations (origin PERSON) and its employer's (origin EMPLOYER)."),
         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"]),
@@ -268,8 +314,8 @@ export function registerEventTools(server, client = getClient()) {
         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, starts_on_from, starts_on_to, include_facts, limit, cursor }) => {
+        cursor: z.string().trim().min(1).optional().describe("Opaque cursor returned by the previous page; pass it back unchanged."),
+    }, async ({ organization_id, event_ids, account_ids, person_ids, target, lead_id, editions, roles, statuses, starts_on_from, starts_on_to, include_facts, limit, cursor }) => {
         try {
             const params = new URLSearchParams({
                 organizationId: organization_id,
@@ -279,6 +325,9 @@ export function registerEventTools(server, client = getClient()) {
             });
             setCsv(params, "eventIds", event_ids);
             setCsv(params, "accountIds", account_ids);
+            setCsv(params, "personIds", person_ids);
+            if (target)
+                params.set("target", target);
             if (lead_id)
                 params.set("leadId", lead_id);
             setCsv(params, "editions", editions);
@@ -296,7 +345,7 @@ export function registerEventTools(server, client = getClient()) {
             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.", {
+    server.tool("get_event_participation", "Get one explicitly selected current participation of a company or a person and its immutable fact history, with target, accountId, personId, clientDocument and, for a person, personLeads. Access defaults to VERIFIED only; pass statuses explicitly to review UNVERIFIED, DISPUTED or REFUTED facts. REGISTERED is not ATTENDED. 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"]),
@@ -320,7 +369,7 @@ export function registerEventTools(server, client = getClient()) {
             return handleToolError(error);
         }
     });
-    server.tool("record_event_participations", "Create participation evidence, add a corroborating source, or correct 1-100 company-event observations. Set validate_only=true for a no-write dry-run. activity_summary is the readable account of what the company does at the event; proof_excerpt remains the exact agent/audit evidence. 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.", {
+    server.tool("record_event_participations", "Create participation evidence, add a corroborating source, or correct 1-100 event observations of companies or persons. Set validate_only=true for a no-write dry-run. Each item targets exactly one account_id, lead_id or person_id and has its own idempotency key. A Company lead or account_id writes a company participation, exactly as before. The lead_id of a Person lead, or a person_id, writes a personal participation on the canonical person: it follows that person across every group. Person roles: REGISTERED, ATTENDED, INVITED, SPEAKER, ORGANIZER, OTHER; REGISTERED, ATTENDED and INVITED are refused for a company. Registered, attended and invited are three distinct facts: a registration never proves attendance. A registrants list provided by the client is valid proof of registration: record role REGISTERED with client_document { file_name, received_on, provided_by } and no URL, including for a person who later unsubscribed or registered several times. An employer's event is never a participation of the person: never record a person from their company's participation. activity_summary is the readable account of what the company or person does at the event; proof_excerpt remains the exact agent/audit evidence. Corrections append an immutable fact and require correction_reason; there is no delete operation. VERIFIED requires a source URL or a client_document, a proof excerpt and a verification date. Uncertain or absent data cannot be cited as attendance, and the absence of a record proves nothing.", {
         organization_id: z.string().trim().min(1),
         batch_id: z.string().trim().min(1).max(255),
         validate_only: z.boolean().optional().default(false),

package/dist/tools/leads.js

@@ -1,17 +1,16 @@
 import { z } from "zod";
 import { getClient } from "../client.js";
 import { toolResult, handleToolError } from "../types.js";
+import { eventRole } from "./events.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(),
+    roles: z.array(eventRole).max(20).optional(),
     statuses: z.array(z.enum(["UNVERIFIED", "VERIFIED", "DISPUTED", "REFUTED"])).min(1).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(),
+    subject: z.enum(["EMPLOYER", "PERSON"]).optional().describe("EMPLOYER (default, historical behavior): leads whose company carries the participation. PERSON: only Person leads that carry the participation themselves, e.g. the registrants of a webinar. An employer's event is never a participation of the person."),
 }).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." });
@@ -169,7 +168,9 @@ export function registerLeadTools(server, client = getClient()) {
         "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. event_filter " +
-        "uses one correlated company participation and defaults explicitly to VERIFIED; " +
+        "uses one correlated participation and defaults explicitly to VERIFIED; subject=PERSON " +
+        "keeps only persons who carry the participation themselves, subject=EMPLOYER (default) " +
+        "matches through the company. A registration (REGISTERED) is not attendance (ATTENDED); " +
         "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
@@ -202,7 +203,7 @@ 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"}}'),
-        event_filter: eventFilterSchema.optional().describe("Structured company-event participation filter. Values within one list use OR; event, edition, role, status and date dimensions use AND against the same participation. statuses defaults to [VERIFIED]. Pass uncertain statuses explicitly for review. There is no confidence score, negative operator or absence filter."),
+        event_filter: eventFilterSchema.optional().describe("Structured event participation filter. subject chooses whose participation counts: EMPLOYER (default, the company's) or PERSON (the person's own). Values within one list use OR; event, edition, role, status and date dimensions use AND against the same participation. statuses defaults to [VERIFIED]. Pass uncertain statuses explicitly for review. There is no confidence score, negative operator or absence filter: the absence of a record proves nothing."),
     }, async ({ group_id, view_id, page, limit, search, fields, include_schema, filters, event_filter }) => {
         try {
             const params = new URLSearchParams();
@@ -231,6 +232,7 @@ export function registerLeadTools(server, client = getClient()) {
                     statuses: checked.statuses ?? ["VERIFIED"],
                     ...(checked.starts_on_from ? { startsOnFrom: checked.starts_on_from } : {}),
                     ...(checked.starts_on_to ? { startsOnTo: checked.starts_on_to } : {}),
+                    ...(checked.subject ? { subject: checked.subject } : {}),
                 }));
             }
             const data = await client.get("/get-leads", params);

package/package.json

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