@agifyai/leadify-mcp 1.4.1 → 1.5.0

package/README.md

@@ -1,18 +1,44 @@
 # Leadify MCP Server
 
-Serveur MCP (Model Context Protocol) pour l'API Leadify. Expose tous les endpoints REST de Leadify sous forme de tools MCP, utilisables depuis Claude Desktop, Claude Code ou tout client compatible MCP.
+Serveur MCP (Model Context Protocol) pour l'API Leadify. Expose les endpoints REST de Leadify sous forme de tools utilisables depuis Claude Desktop, Claude Code, Cursor ou tout client compatible MCP.
 
-## Installation
+Package npm : [`@agifyai/leadify-mcp`](https://www.npmjs.com/package/@agifyai/leadify-mcp)
 
-Le serveur est publié sur npm sous `@agifyai/leadify-mcp`. Aucun clone, aucun build local : `npx` télécharge la dernière version à chaque démarrage.
+---
+
+## 📦 Pour les utilisateurs
+
+Aucun clone, aucun build. `npx` télécharge la dernière version à chaque démarrage de session MCP.
+
+### Pré-requis
+
+- [Node.js](https://nodejs.org/) ≥ 18 (`node --version` pour vérifier)
+- Une clé API Leadify (demander à l'équipe ou la générer dans l'app)
+
+### Claude Code
+
+```bash
+claude mcp add leadify -e LEADIFY_API_KEY=votre-clé-api -- npx -y @agifyai/leadify-mcp@latest
+```
+
+> Le `--` est nécessaire pour que `claude mcp add` ne tente pas d'interpréter le `-y` de `npx` comme une de ses propres options.
+
+Vérifier que c'est bien branché :
+
+```bash
+claude mcp list
+```
+
+Tu dois voir `leadify` dans la liste. Dans une session Claude Code, demande "appelle test_api_key" pour valider.
 
 ### Claude Desktop
 
 Ouvrir le fichier de configuration :
+
 - **macOS** : `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Windows** : `%APPDATA%\Claude\claude_desktop_config.json`
 
-Ajouter une entrée `"leadify"` dans `"mcpServers"` :
+Ajouter une entrée `leadify` dans `mcpServers` :
 
 ```json
 {
@@ -28,21 +54,32 @@ Ajouter une entrée `"leadify"` dans `"mcpServers"` :
 }
 ```
 
-Redémarrer Claude Desktop. Les tools apparaissent (icône marteau).
+Redémarrer Claude Desktop. Les tools Leadify apparaissent (icône marteau dans la zone de saisie).
 
-### Claude Code
+### Mise à jour automatique
+
+Le tag `@latest` force `npx` à vérifier la dernière version publiée à chaque lancement de session. Quand un nouveau tool est mergé sur `main` et publié, il est dispo dès la **session suivante** — sans `git pull`, sans rebuild, sans rien.
+
+Pour forcer un rafraîchissement immédiat sans attendre le cache npm :
 
 ```bash
-claude mcp add leadify npx -y @agifyai/leadify-mcp@latest -e LEADIFY_API_KEY=votre-clé-api
+npm cache clean --force
 ```
 
-### Mise à jour automatique
+### Dépannage
 
-Le tag `@latest` force `npx` à vérifier la version publiée à chaque lancement de session MCP. Quand un nouveau tool est mergé sur `main` et publié, il est dispo à la session suivante — pas de `git pull`, pas de rebuild.
+| Symptôme | Cause / solution |
+|---|---|
+| `LEADIFY_API_KEY environment variable is required` | La clé n'est pas passée. Vérifier le `-e` (Claude Code) ou le bloc `env` (Claude Desktop). |
+| `401 Unauthorized` sur tous les tools | Clé API invalide ou révoquée. Tester avec `test_api_key`. |
+| Le serveur ne démarre pas | Vérifier que `npx -y @agifyai/leadify-mcp@latest` tourne en standalone. Si erreur réseau, vérifier l'accès à `registry.npmjs.org`. |
+| Tool ajouté côté équipe mais pas visible chez moi | Quitter complètement le client (Claude Desktop : ⌘Q ; Claude Code : ferme la session) et relancer. |
 
-## Développement
+---
 
-Pour bosser sur le MCP en local :
+## 🛠️ Pour les contributeurs
+
+### Setup local
 
 ```bash
 git clone git@github.com:AgifyAI/mcp_leadify.git
@@ -51,20 +88,91 @@ npm install
 npm run build
 ```
 
-Pointer Claude Code sur la build locale :
+Brancher Claude Code sur ta build locale (en plus de la version npm si tu veux comparer) :
+
+```bash
+claude mcp add leadify-dev -e LEADIFY_API_KEY=votre-clé-api -- node /chemin/absolu/vers/mcp_leadify/dist/index.js
+```
+
+Mode watch :
 
 ```bash
-claude mcp add leadify-dev node /chemin/absolu/vers/mcp_leadify/dist/index.js -e LEADIFY_API_KEY=votre-clé-api
+npm run dev
 ```
 
+### Architecture
+
+```
+src/
+├── index.ts          # entrée stdio (shebang + transport)
+├── server.ts         # création du McpServer + register* de chaque module
+├── client.ts         # LeadifyClient (singleton, lit LEADIFY_API_KEY)
+├── types.ts          # toolResult, handleToolError, LeadifyApiError
+└── tools/
+    ├── auth.ts
+    ├── leads.ts
+    ├── campaigns.ts
+    ├── dataroom.ts
+    ├── personas.ts
+    └── ...           # un fichier = un domaine fonctionnel
+```
+
+Un tool = un appel à `server.tool(name, description, zodSchema, async handler)`. Voir `src/tools/auth.ts` pour le plus simple.
+
+### Ajouter un tool
+
+1. Coder le tool dans le fichier de domaine pertinent (`src/tools/<domaine>.ts`), ou créer un nouveau fichier.
+2. Si nouveau fichier : exporter `registerXxxTools(server)` et l'appeler depuis `src/server.ts`.
+3. Vérifier que ça compile :
+   ```bash
+   npm run build
+   ```
+4. Tester en local (cf. setup ci-dessus).
+5. Bumper la version et publier (cf. section suivante).
+
 ### Publier une nouvelle version
 
+Le publish est automatique via GitHub Actions sur push `main`. Le workflow ne fait rien si la version dans `package.json` n'a pas bougé — il faut donc bumper avant de push.
+
 ```bash
-npm version patch   # ou minor / major
+npm version patch    # 1.4.2 → 1.4.3 (bug fix, ajout de tool)
+npm version minor    # 1.4.2 → 1.5.0 (changement non-breaking notable)
+npm version major    # 1.4.2 → 2.0.0 (breaking : tool renommé / supprimé / signature changée)
 git push && git push --tags
 ```
 
-GitHub Actions build et publie sur npm automatiquement (workflow `.github/workflows/publish.yml`). Si la version dans `package.json` n'a pas bougé, le workflow skip — pas de doublon.
+`npm version` crée un commit + un tag git automatiquement.
+
+Vérifier la publication :
+
+```bash
+npm view @agifyai/leadify-mcp version
+```
+
+Et le run du workflow : https://github.com/AgifyAI/mcp_leadify/actions
+
+### Comment marche la CI
+
+`.github/workflows/publish.yml` se déclenche sur push `main` :
+
+1. Checkout + install Node 20.
+2. `npm ci` pour installer les deps.
+3. Check si la version actuelle de `package.json` est déjà publiée sur npm. Si oui, skip silencieusement (on évite les doublons et on permet de push des commits non-version sur `main`).
+4. Sinon, upgrade npm vers ≥ 11.5.1 (requis pour Trusted Publishing) puis `npm publish`.
+
+L'authentification npm passe par **Trusted Publishing (OIDC)** : pas de token stocké, GitHub Actions s'authentifie directement auprès de npm via la permission `id-token: write` du workflow. La trust relation est configurée sur la [page npm du package](https://www.npmjs.com/package/@agifyai/leadify-mcp/access) (Trusted Publisher : `AgifyAI/mcp_leadify` / `publish.yml`).
+
+Conséquences pratiques :
+- Pas de secret `NPM_TOKEN` à rotater.
+- Le workflow ne peut publier que depuis ce repo + ce fichier de workflow exact. Renommer `publish.yml` casse la trust → mettre à jour côté npm si besoin.
+
+### Conventions
+
+- **Versionning** : suivre semver. Ajout de tool = `patch` (rétrocompatible). Renommage / suppression / signature breaking = `major`.
+- **Description des tools** : verbeuse et précise — c'est ce que le modèle lit pour décider d'utiliser le tool. Voir les tools `outreach_*` pour des exemples détaillés.
+- **Erreurs** : toujours wrapper le handler dans `try / catch` et retourner `handleToolError(error)` en cas d'échec — ça normalise les erreurs API en réponse MCP propre.
+
+---
 
 ## Tools disponibles
 
@@ -90,7 +198,14 @@ GitHub Actions build et publie sur npm automatiquement (workflow `.github/workfl
 | `add_signal` | Ajouter un signal de business intelligence à un lead (INFO, CRITICAL, GOLDEN). |
 | `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é, documents, personas. |
-| `update_data_room` | Mettre à jour les informations société (companyInfo) de la data room. |
+| `describe_company_info_schema` | Lire le schéma companyInfo mirroré côté MCP (enums, max-lengths, sous-objets). À appeler avant la première update pour connaître le contrat. |
+| `update_data_room` | Update full-form (escape hatch) — remplace les blocs JSON entièrement. Préférer les tools granulaires ci-dessous. |
+| `update_company_info_identity` | Patch des champs scalaires (name, sector, description, size, website, valueProposition). |
+| `update_company_info_sender` | Patch du sender (name, title, email) ou clear complet via set_to_null. |
+| `update_company_info_geo` | Patch des listes targetRegions et competitors (replace / add / remove). |
+| `update_company_info_snapshot` | Patch du bloc snapshot (stage, pitchOneLiner, constraints[]) avec validation enum + max-length. |
+| `update_company_info_product` | Add / replace / remove un seul produit dans products[], lookup par name. category strict enum. |
+| `update_company_info_constraint` | Add / replace / remove une seule contrainte dans snapshot.constraints[], lookup par index. type strict enum, note ≤150. |
 | `add_data_room_document` | Ajouter un document textuel à la data room avec catégorie. |
 | `upsert_persona` | Créer ou mettre à jour un persona (ciblage, messaging, outils actifs). |
 | `get_persona` | Récupérer un persona par son ID. |
@@ -107,11 +222,3 @@ GitHub Actions build et publie sur npm automatiquement (workflow `.github/workfl
 | `update_outreach_case_study` | Ajouter / remplacer / supprimer un case study par index, sans re-envoyer la liste. |
 | `update_outreach_urls` | Patch booking_url et/ou website_url uniquement. |
 | `set_outreach_connection_request` | Toggle du flag connectionRequestEnabled (LinkedIn invite vs cold DM). |
-
-## Développement
-
-Mode watch pour le développement :
-
-```bash
-npm run dev
-```

package/dist/tools/dataroom.js

@@ -1,6 +1,97 @@
 import { z } from "zod";
 import { getClient } from "../client.js";
-import { toolResult, handleToolError } from "../types.js";
+import { toolResult, toolError, handleToolError } from "../types.js";
+// ─── Mirrored backend constraints ──────────────────────────────────────────
+//
+// The companyInfo schema lives in the Leadify backend (apps/server/src/lib/
+// data-room-schemas.ts most likely). The MCP cannot import it directly, so
+// the constraints below are a hand-mirrored subset based on observed 422
+// responses + GET /api/data-room payload shapes. The mirror is INTENTIONALLY
+// strict on what we know and permissive (passthrough) on what we don't —
+// so callers get up-front guidance for the documented fields and the
+// backend still owns final validation for everything else.
+//
+// Known constraints (source: observed 422 path/expected pairs):
+//   - products[].category   ∈ {saas, medical_device, service, mixed}
+//   - snapshot.stage        ∈ {early, growth, scaling, enterprise}
+//   - snapshot.constraints[].type ∈ {regulatory, brand, legal}
+//   - snapshot.constraints[].note  ≤ 150 chars
+//   - snapshot.pitchOneLiner       ≤ 200 chars
+//
+// If you hit a 422 for a field/constraint not listed above, extend the
+// mirror here and republish. The asymmetric upstream Zod (.parse instead of
+// .safeParse) surfaces one error at a time — see TODO at the bottom of this
+// file re: requesting backend .safeParse cumulative errors.
+const PRODUCT_CATEGORIES = ["saas", "medical_device", "service", "mixed"];
+const STAGE_VALUES = ["early", "growth", "scaling", "enterprise"];
+const CONSTRAINT_TYPES = ["regulatory", "brand", "legal"];
+const productSchema = z
+    .object({
+    name: z.string().min(1).describe("Product name (required)."),
+    category: z
+        .enum(PRODUCT_CATEGORIES)
+        .describe("Product classification. One of: saas, medical_device, service, mixed."),
+    description: z.string().optional().describe("Short description."),
+    valueProposition: z.string().optional(),
+    targetCustomer: z.string().optional(),
+    pricing: z.string().optional(),
+})
+    .passthrough()
+    .describe("Single product entry. name + category are required (category is a strict enum).");
+const constraintSchema = z
+    .object({
+    type: z
+        .enum(CONSTRAINT_TYPES)
+        .describe("Constraint type. One of: regulatory, brand, legal."),
+    note: z
+        .string()
+        .max(150)
+        .describe("Short note describing the constraint. Max 150 chars."),
+})
+    .passthrough()
+    .describe("Single business constraint (regulatory / brand / legal). Note capped at 150 chars.");
+const snapshotSchema = z
+    .object({
+    stage: z
+        .enum(STAGE_VALUES)
+        .optional()
+        .describe("Company stage. One of: early, growth, scaling, enterprise."),
+    pitchOneLiner: z
+        .string()
+        .max(200)
+        .optional()
+        .describe("One-liner pitch. Max 200 chars."),
+    constraints: z
+        .array(constraintSchema)
+        .optional()
+        .describe("Business constraints. Each entry: {type ∈ regulatory|brand|legal, note ≤150 chars}."),
+})
+    .passthrough()
+    .describe("Snapshot block. stage + pitchOneLiner + constraints[] are validated; other keys pass through.");
+const senderSchema = z
+    .object({
+    name: z.string().describe("Default sender display name (required if sender is set)."),
+    title: z.string().optional(),
+    email: z.string().email().optional(),
+})
+    .passthrough();
+// Full companyInfo schema — exposed by describe_company_info_schema and
+// reused by the wholesale update_data_room escape hatch.
+const companyInfoSchema = z
+    .object({
+    name: z.string().optional().describe("Company name."),
+    sector: z.string().optional().describe("Sector / industry."),
+    description: z.string().optional().describe("Company description."),
+    size: z.string().optional().describe("Company size (e.g. '10-50', '200+')."),
+    website: z.string().url().optional().describe("Company website URL."),
+    valueProposition: z.string().optional().describe("Top-level value prop."),
+    competitors: z.array(z.string()).optional().describe("Competitor names."),
+    targetRegions: z.array(z.string()).optional().describe("Geographic regions."),
+    sender: senderSchema.optional().describe("Default sender identity."),
+    products: z.array(productSchema).optional(),
+    snapshot: snapshotSchema.optional(),
+})
+    .passthrough();
 const DOCUMENT_CATEGORIES = [
     "PRODUCT_CATALOG",
     "CONGRESS_LIST",
@@ -12,6 +103,52 @@ const DOCUMENT_CATEGORIES = [
 ];
 const ORG_ID_DESC = "Optional Clerk organization ID to target a specific org's data room. " +
     "Defaults to the caller's own org. Requires admin access for writes.";
+const DRY_RUN_DESC = "If true, validate the patch + return the merged preview WITHOUT writing to the API. " +
+    "Use to dry-fit a change before persisting.";
+async function fetchDataRoom(organizationId) {
+    const params = organizationId
+        ? new URLSearchParams({ organizationId })
+        : undefined;
+    const data = (await getClient().get("/api/data-room", params));
+    return data ?? {};
+}
+async function putCompanyInfo(companyInfo, organizationId) {
+    const body = { companyInfo };
+    if (organizationId)
+        body.organizationId = organizationId;
+    return getClient().put("/api/data-room", body);
+}
+function currentCompanyInfo(state) {
+    const ci = state.companyInfo;
+    return ci && typeof ci === "object" && !Array.isArray(ci)
+        ? ci
+        : {};
+}
+function dryRunResult(patch, mergedCompanyInfo) {
+    return toolResult({
+        ok: true,
+        dry_run: true,
+        patch,
+        preview_company_info: mergedCompanyInfo,
+        note: "No write performed. Re-call without dry_run to persist.",
+    });
+}
+// Validate a sub-schema MCP-side BEFORE calling the API. Returns a normalized
+// error result if invalid (collecting EVERY zod issue, not just the first),
+// or null if the value is OK to send.
+function validateOrError(schema, value, pathPrefix) {
+    const result = schema.safeParse(value);
+    if (result.success)
+        return null;
+    const issues = result.error.issues.map((i) => ({
+        path: [pathPrefix, ...i.path.map(String)].filter(Boolean).join("."),
+        message: i.message,
+        code: i.code,
+    }));
+    return toolError(`Validation failed (${issues.length} issue${issues.length === 1 ? "" : "s"}). ` +
+        "Fix all listed paths and retry — backend constraints mirrored in MCP.", { issues });
+}
+// ─── Tool registrations ────────────────────────────────────────────────────
 export function registerDataRoomTools(server) {
     // ── get_data_room ──────────────────────────────────────────────────────
     server.tool("get_data_room", "Retrieve the organization's full data room: company info, all documents, and every " +
@@ -20,32 +157,452 @@ export function registerDataRoomTools(server) {
         organization_id: z.string().optional().describe(ORG_ID_DESC),
     }, async ({ organization_id }) => {
         try {
-            const params = organization_id
-                ? new URLSearchParams({ organizationId: organization_id })
-                : undefined;
-            const data = await getClient().get("/api/data-room", params);
+            const data = await fetchDataRoom(organization_id);
             return toolResult(data);
         }
         catch (error) {
             return handleToolError(error);
         }
     });
+    // ── describe_company_info_schema ───────────────────────────────────────
+    // Read-only introspection. Lets agents fetch the contract without
+    // shooting in the dark or learning by 422.
+    server.tool("describe_company_info_schema", "Return the companyInfo schema documented at the MCP layer: known fields, enums, " +
+        "max-length constraints, and which keys pass through to the backend untouched. " +
+        "Call this BEFORE the first update of a session to know what the API will accept. " +
+        "The mirror is a subset of the backend schema — fields not listed here still pass " +
+        "through, but their constraints are enforced server-side and may surface as 422s.", {}, async () => {
+        try {
+            return toolResult({
+                source: "MCP-mirrored subset of the backend companyInfo schema.",
+                known_fields: {
+                    name: { type: "string" },
+                    sector: { type: "string" },
+                    description: { type: "string" },
+                    size: { type: "string", note: "Free-form (e.g. '10-50', '200+')." },
+                    website: { type: "string", format: "url" },
+                    valueProposition: { type: "string" },
+                    competitors: { type: "array<string>" },
+                    targetRegions: { type: "array<string>" },
+                    sender: {
+                        type: "object",
+                        shape: {
+                            name: { type: "string", required: true },
+                            title: { type: "string" },
+                            email: { type: "string", format: "email" },
+                        },
+                    },
+                    products: {
+                        type: "array<object>",
+                        item_shape: {
+                            name: { type: "string", required: true },
+                            category: {
+                                type: "enum",
+                                values: PRODUCT_CATEGORIES,
+                                required: true,
+                            },
+                            description: { type: "string" },
+                            valueProposition: { type: "string" },
+                            targetCustomer: { type: "string" },
+                            pricing: { type: "string" },
+                        },
+                        patch_tool: "update_company_info_product",
+                    },
+                    snapshot: {
+                        type: "object",
+                        shape: {
+                            stage: { type: "enum", values: STAGE_VALUES },
+                            pitchOneLiner: { type: "string", max_length: 200 },
+                            constraints: {
+                                type: "array<object>",
+                                item_shape: {
+                                    type: {
+                                        type: "enum",
+                                        values: CONSTRAINT_TYPES,
+                                        required: true,
+                                    },
+                                    note: {
+                                        type: "string",
+                                        max_length: 150,
+                                        required: true,
+                                    },
+                                },
+                                patch_tool: "update_company_info_constraint",
+                            },
+                        },
+                        patch_tool: "update_company_info_snapshot",
+                    },
+                },
+                patch_tools: [
+                    "update_company_info_identity",
+                    "update_company_info_sender",
+                    "update_company_info_geo",
+                    "update_company_info_snapshot",
+                    "update_company_info_product",
+                    "update_company_info_constraint",
+                ],
+                escape_hatch: "update_data_room",
+                notes: [
+                    "Unknown keys pass through to the backend (zod passthrough on companyInfo).",
+                    "Backend currently surfaces ONE zod issue per 422 — see TODO in MCP source.",
+                    "Prefer the granular patch tools over update_data_room to avoid wiping nested blocks.",
+                ],
+            });
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
     // ── update_data_room ───────────────────────────────────────────────────
-    server.tool("update_data_room", "Update the organization's company info in the data room. Accepts any freeform " +
-        "fields under companyInfo — common ones: name, sector, description, size, website, " +
-        "products, valueProposition, competitors, targetRegions, sender. Only the fields " +
-        "you pass are updated.", {
+    // Escape hatch: full companyInfo replacement (top-level keys you pass).
+    // Validates against the MCP-mirrored schema BEFORE hitting the API so
+    // callers don't burn round-trips on enum / max-length mistakes.
+    server.tool("update_data_room", "WHOLESALE update of companyInfo (ESCAPE HATCH). For partial edits, ALWAYS prefer the " +
+        "granular update_company_info_* tools — they do safe read-modify-write merges. Top-level " +
+        "keys you pass here REPLACE their server-side counterparts (so passing snapshot={stage:'early'} " +
+        "wipes pitchOneLiner and constraints). MCP validates the payload against the mirrored schema " +
+        "before sending; backend may still reject unknown constraints with a 422.", {
         company_info: z
             .record(z.unknown())
-            .describe("Freeform object of company details. Common fields: name, sector, description, " +
-            "size, website, products, valueProposition, competitors, targetRegions, sender."),
+            .describe("companyInfo payload. Known fields are validated against the mirrored schema " +
+            "(see describe_company_info_schema). Unknown fields pass through."),
         organization_id: z.string().optional().describe(ORG_ID_DESC),
-    }, async ({ company_info, organization_id }) => {
+        dry_run: z.boolean().optional().describe(DRY_RUN_DESC),
+    }, async ({ company_info, organization_id, dry_run }) => {
         try {
-            const body = { companyInfo: company_info };
-            if (organization_id)
-                body.organizationId = organization_id;
-            const data = await getClient().put("/api/data-room", body);
+            const validationError = validateOrError(companyInfoSchema, company_info, "company_info");
+            if (validationError)
+                return validationError;
+            if (dry_run) {
+                const current = await fetchDataRoom(organization_id);
+                const merged = { ...currentCompanyInfo(current), ...company_info };
+                return dryRunResult(company_info, merged);
+            }
+            const data = await putCompanyInfo(company_info, organization_id);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── update_company_info_identity ───────────────────────────────────────
+    server.tool("update_company_info_identity", "Patch scalar identity fields of companyInfo (name, sector, description, size, " +
+        "website, valueProposition). Only the fields you pass are updated. Other companyInfo " +
+        "blocks (sender, products, snapshot, etc.) remain intact.", {
+        name: z.string().optional().describe("Company name."),
+        sector: z.string().optional().describe("Sector / industry."),
+        description: z.string().optional().describe("Company description."),
+        size: z.string().optional().describe("Company size (e.g. '10-50', '200+')."),
+        website: z.string().url().optional().describe("Company website URL."),
+        valueProposition: z.string().optional().describe("Top-level value proposition."),
+        organization_id: z.string().optional().describe(ORG_ID_DESC),
+        dry_run: z.boolean().optional().describe(DRY_RUN_DESC),
+    }, async ({ name, sector, description, size, website, valueProposition, organization_id, dry_run, }) => {
+        try {
+            const patch = {};
+            if (name !== undefined)
+                patch.name = name;
+            if (sector !== undefined)
+                patch.sector = sector;
+            if (description !== undefined)
+                patch.description = description;
+            if (size !== undefined)
+                patch.size = size;
+            if (website !== undefined)
+                patch.website = website;
+            if (valueProposition !== undefined)
+                patch.valueProposition = valueProposition;
+            if (Object.keys(patch).length === 0) {
+                return toolError("Provide at least one of: name, sector, description, size, website, valueProposition.");
+            }
+            const current = await fetchDataRoom(organization_id);
+            const merged = { ...currentCompanyInfo(current), ...patch };
+            if (dry_run)
+                return dryRunResult(patch, merged);
+            const data = await putCompanyInfo(patch, organization_id);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── update_company_info_sender ─────────────────────────────────────────
+    server.tool("update_company_info_sender", "Patch the sender block (default SDR identity). Reads current sender, shallow-merges " +
+        "the fields you pass, writes the whole sender object back. Pass set_to_null=true to " +
+        "clear the sender entirely.", {
+        name: z.string().optional().describe("Sender display name."),
+        title: z.string().optional().describe("Sender title / role."),
+        email: z.string().email().optional().describe("Sender email address."),
+        set_to_null: z
+            .boolean()
+            .optional()
+            .describe("If true, clears the sender block entirely (mutually exclusive with name/title/email)."),
+        organization_id: z.string().optional().describe(ORG_ID_DESC),
+        dry_run: z.boolean().optional().describe(DRY_RUN_DESC),
+    }, async ({ name, title, email, set_to_null, organization_id, dry_run }) => {
+        try {
+            const hasFields = name !== undefined || title !== undefined || email !== undefined;
+            if (!hasFields && !set_to_null) {
+                return toolError("Provide at least one of: name, title, email, set_to_null.");
+            }
+            if (set_to_null && hasFields) {
+                return toolError("'set_to_null' is mutually exclusive with name/title/email.");
+            }
+            const current = await fetchDataRoom(organization_id);
+            const ci = currentCompanyInfo(current);
+            const existingSender = ci.sender && typeof ci.sender === "object" && !Array.isArray(ci.sender)
+                ? ci.sender
+                : {};
+            let nextSender;
+            if (set_to_null) {
+                nextSender = null;
+            }
+            else {
+                nextSender = { ...existingSender };
+                if (name !== undefined)
+                    nextSender.name = name;
+                if (title !== undefined)
+                    nextSender.title = title;
+                if (email !== undefined)
+                    nextSender.email = email;
+                const validationError = validateOrError(senderSchema, nextSender, "sender");
+                if (validationError)
+                    return validationError;
+            }
+            const patch = { sender: nextSender };
+            const merged = { ...ci, ...patch };
+            if (dry_run)
+                return dryRunResult(patch, merged);
+            const data = await putCompanyInfo(patch, organization_id);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── update_company_info_geo ────────────────────────────────────────────
+    server.tool("update_company_info_geo", "Patch geo / competitive lists: targetRegions, competitors. Use 'replace' to overwrite " +
+        "wholesale, or 'add'/'remove' for incremental edits (deduped). Other companyInfo " +
+        "fields remain intact.", {
+        field: z
+            .enum(["targetRegions", "competitors"])
+            .describe("Which list to patch."),
+        action: z
+            .enum(["replace", "add", "remove"])
+            .describe("replace = overwrite wholesale; add = append (deduped); remove = drop entries."),
+        values: z
+            .array(z.string())
+            .min(1)
+            .describe("Values for the action. Must be non-empty."),
+        organization_id: z.string().optional().describe(ORG_ID_DESC),
+        dry_run: z.boolean().optional().describe(DRY_RUN_DESC),
+    }, async ({ field, action, values, organization_id, dry_run }) => {
+        try {
+            const current = await fetchDataRoom(organization_id);
+            const ci = currentCompanyInfo(current);
+            const existing = Array.isArray(ci[field]) ? ci[field] : [];
+            let next;
+            if (action === "replace") {
+                next = [...new Set(values)];
+            }
+            else if (action === "add") {
+                next = [...new Set([...existing, ...values])];
+            }
+            else {
+                const removeSet = new Set(values);
+                next = existing.filter((v) => !removeSet.has(v));
+            }
+            const patch = { [field]: next };
+            const merged = { ...ci, ...patch };
+            if (dry_run)
+                return dryRunResult(patch, merged);
+            const data = await putCompanyInfo(patch, organization_id);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── update_company_info_snapshot ───────────────────────────────────────
+    server.tool("update_company_info_snapshot", "Patch the snapshot block. Reads current snapshot, shallow-merges the fields you pass, " +
+        "writes the whole snapshot back. Constraints[] is REPLACED wholesale when passed — " +
+        "use update_company_info_constraint for per-item edits. stage and pitchOneLiner are " +
+        "validated MCP-side (enum + max-length) before the API call.", {
+        stage: z
+            .enum(STAGE_VALUES)
+            .optional()
+            .describe("Company stage. One of: early, growth, scaling, enterprise."),
+        pitchOneLiner: z
+            .string()
+            .max(200)
+            .optional()
+            .describe("One-liner pitch. Max 200 chars."),
+        constraints: z
+            .array(constraintSchema)
+            .optional()
+            .describe("Full replacement of constraints[]. Use update_company_info_constraint for per-item edits."),
+        extra: z
+            .record(z.unknown())
+            .optional()
+            .describe("Escape hatch for additional snapshot keys not yet mirrored in the MCP."),
+        organization_id: z.string().optional().describe(ORG_ID_DESC),
+        dry_run: z.boolean().optional().describe(DRY_RUN_DESC),
+    }, async ({ stage, pitchOneLiner, constraints, extra, organization_id, dry_run }) => {
+        try {
+            if (stage === undefined &&
+                pitchOneLiner === undefined &&
+                constraints === undefined &&
+                (extra === undefined || Object.keys(extra).length === 0)) {
+                return toolError("Provide at least one of: stage, pitchOneLiner, constraints, extra.");
+            }
+            const current = await fetchDataRoom(organization_id);
+            const ci = currentCompanyInfo(current);
+            const existingSnapshot = ci.snapshot && typeof ci.snapshot === "object" && !Array.isArray(ci.snapshot)
+                ? ci.snapshot
+                : {};
+            const nextSnapshot = { ...existingSnapshot };
+            if (stage !== undefined)
+                nextSnapshot.stage = stage;
+            if (pitchOneLiner !== undefined)
+                nextSnapshot.pitchOneLiner = pitchOneLiner;
+            if (constraints !== undefined)
+                nextSnapshot.constraints = constraints;
+            if (extra !== undefined)
+                Object.assign(nextSnapshot, extra);
+            const patch = { snapshot: nextSnapshot };
+            const merged = { ...ci, ...patch };
+            if (dry_run)
+                return dryRunResult(patch, merged);
+            const data = await putCompanyInfo(patch, organization_id);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── update_company_info_product ────────────────────────────────────────
+    server.tool("update_company_info_product", "Add, replace, or remove a single product in companyInfo.products[] without re-sending " +
+        "the whole array. Lookups are by product `name` (case-sensitive exact match). Reads " +
+        "the current products[], mutates the matched entry, writes the full array back. " +
+        "category is a strict enum (saas|medical_device|service|mixed) — validated MCP-side.", {
+        action: z
+            .enum(["add", "replace", "remove"])
+            .describe("add = append (fails if name already exists); replace = overwrite by name; remove = delete by name."),
+        name: z
+            .string()
+            .optional()
+            .describe("Lookup key for replace/remove. Required for those actions. For 'add' the name comes from the product payload."),
+        product: productSchema
+            .optional()
+            .describe("Product payload. Required for 'add' and 'replace'. Shape: {name, category, description?, valueProposition?, targetCustomer?, pricing?}."),
+        organization_id: z.string().optional().describe(ORG_ID_DESC),
+        dry_run: z.boolean().optional().describe(DRY_RUN_DESC),
+    }, async ({ action, name, product, organization_id, dry_run }) => {
+        try {
+            if ((action === "add" || action === "replace") && !product) {
+                return toolError(`product is required for action '${action}'.`);
+            }
+            if ((action === "replace" || action === "remove") && !name) {
+                return toolError(`name is required for action '${action}'.`);
+            }
+            const current = await fetchDataRoom(organization_id);
+            const ci = currentCompanyInfo(current);
+            const list = Array.isArray(ci.products)
+                ? ci.products.map((p) => ({ ...p }))
+                : [];
+            if (action === "add") {
+                const newName = product.name;
+                if (list.some((p) => p.name === newName)) {
+                    return toolError(`A product with name "${newName}" already exists. Use action 'replace' instead.`);
+                }
+                list.push(product);
+            }
+            else if (action === "replace") {
+                const idx = list.findIndex((p) => p.name === name);
+                if (idx === -1) {
+                    return toolError(`No product found with name "${name}".`);
+                }
+                list[idx] = product;
+            }
+            else {
+                const before = list.length;
+                const filtered = list.filter((p) => p.name !== name);
+                if (filtered.length === before) {
+                    return toolError(`No product found with name "${name}".`);
+                }
+                list.length = 0;
+                list.push(...filtered);
+            }
+            const patch = { products: list };
+            const merged = { ...ci, ...patch };
+            if (dry_run)
+                return dryRunResult(patch, merged);
+            const data = await putCompanyInfo(patch, organization_id);
+            return toolResult(data);
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    // ── update_company_info_constraint ─────────────────────────────────────
+    server.tool("update_company_info_constraint", "Add, replace, or remove a single business constraint inside snapshot.constraints[] " +
+        "without re-sending the whole array. Constraints have no stable id — entries are " +
+        "addressed by zero-based index. Beware: indices shift after a remove, so re-fetch " +
+        "before chaining edits. type is a strict enum (regulatory|brand|legal), note is " +
+        "capped at 150 chars — validated MCP-side.", {
+        action: z
+            .enum(["add", "replace", "remove"])
+            .describe("add = append; replace = overwrite at index; remove = delete at index."),
+        index: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("Zero-based index. Required for 'replace' and 'remove'."),
+        constraint: constraintSchema
+            .optional()
+            .describe("Constraint payload {type ∈ regulatory|brand|legal, note ≤150 chars}. Required for 'add' and 'replace'."),
+        organization_id: z.string().optional().describe(ORG_ID_DESC),
+        dry_run: z.boolean().optional().describe(DRY_RUN_DESC),
+    }, async ({ action, index, constraint, organization_id, dry_run }) => {
+        try {
+            if ((action === "add" || action === "replace") && !constraint) {
+                return toolError(`constraint is required for action '${action}'.`);
+            }
+            if ((action === "replace" || action === "remove") && index === undefined) {
+                return toolError(`index is required for action '${action}'.`);
+            }
+            const current = await fetchDataRoom(organization_id);
+            const ci = currentCompanyInfo(current);
+            const existingSnapshot = ci.snapshot && typeof ci.snapshot === "object" && !Array.isArray(ci.snapshot)
+                ? ci.snapshot
+                : {};
+            const list = Array.isArray(existingSnapshot.constraints)
+                ? existingSnapshot.constraints.map((c) => ({
+                    ...c,
+                }))
+                : [];
+            if (action === "add") {
+                list.push(constraint);
+            }
+            else if (action === "replace") {
+                if (index < 0 || index >= list.length) {
+                    return toolError(`Index ${index} out of bounds (constraints list has ${list.length} entries).`);
+                }
+                list[index] = constraint;
+            }
+            else {
+                if (index < 0 || index >= list.length) {
+                    return toolError(`Index ${index} out of bounds (constraints list has ${list.length} entries).`);
+                }
+                list.splice(index, 1);
+            }
+            const nextSnapshot = { ...existingSnapshot, constraints: list };
+            const patch = { snapshot: nextSnapshot };
+            const merged = { ...ci, ...patch };
+            if (dry_run)
+                return dryRunResult(patch, merged);
+            const data = await putCompanyInfo(patch, organization_id);
             return toolResult(data);
         }
         catch (error) {
@@ -80,3 +637,20 @@ export function registerDataRoomTools(server) {
         }
     });
 }
+// ─── Backend TODO ──────────────────────────────────────────────────────────
+// The Leadify backend currently runs the data-room companyInfo schema with
+// .parse(), so any payload with N validation errors only surfaces the FIRST
+// one as a 422. That forces clients (and LLMs) into a death loop of
+// "fix one field, retry, discover next error, retry…".
+//
+// Fix on the backend side (apps/server most likely):
+//   const result = companyInfoSchema.safeParse(input);
+//   if (!result.success) {
+//     return res.status(422).json({
+//       error: "Validation failed",
+//       issues: result.error.issues, // ALL of them, not just the first
+//     });
+//   }
+//
+// Once that ships, the MCP can pass the full issue list through verbatim
+// instead of relying on the mirror-side validation as a fallback.

package/package.json

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