@mentoringo/vantage-ops-mcp 1.3.0

package/dist/tools/mcp-write-tools.js

@@ -0,0 +1,1062 @@
+/**
+ * MCP write tools — thin wrappers over Vantage's /mcp/* HTTP endpoints.
+ *
+ * Each tool validates inputs with zod, delegates to the typed HTTP
+ * client in ../mcp-client, and returns the server's JSON response as
+ * both a stringified content block (for human readability) and a
+ * structured payload (typed under the writeOutput schema). Errors
+ * surface with the Vantage API's own error message so scope-check
+ * failures (403) and validation failures (400) are self-explanatory
+ * in the Claude transcript.
+ *
+ * Scopes required per tool are documented inline; the API-key has to
+ * carry the matching scope or the request is rejected at the authorizer.
+ */
+import { z } from "zod";
+import { addCampaignRecipients, addCampaignTargets, removeCampaignTarget, sourceCampaignContacts, apolloSearchContacts, apolloSearchCompanies, apolloUnlockEmail, apolloImportContacts, authConfigured, apiUrlForDiagnostics, createCampaign, createCompany, createContact, createOpportunity, createOutreach, createTemplate, deleteCampaign, deleteCompany, enrichCompany, deleteContact, deleteOpportunity, deleteTemplate, logActivity, pauseCampaign, startCampaign, updateCampaign, updateCampaignRecipient, updateCompany, updateContact, updateOpportunity, updateOutreach, updateTemplate, VantageApiError, } from "../mcp-client.js";
+import { writeOutput, healthOutput } from "../schemas.js";
+function asContent(data) {
+    const summary = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+    const record = data !== null && typeof data === "object"
+        ? data
+        : undefined;
+    return {
+        content: [{ type: "text", text: summary }],
+        structuredContent: {
+            success: true,
+            record,
+            summary,
+        },
+    };
+}
+function asError(err) {
+    if (err instanceof VantageApiError) {
+        const summary = `Vantage API error (${err.status}): ${err.message}\n\n${JSON.stringify(err.body, null, 2)}`;
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: {
+                success: false,
+                message: err.message,
+                record: err.body !== null && typeof err.body === "object"
+                    ? err.body
+                    : undefined,
+                summary,
+            },
+            isError: true,
+        };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    const summary = `Error: ${msg}`;
+    return {
+        content: [{ type: "text", text: summary }],
+        structuredContent: {
+            success: false,
+            message: msg,
+            summary,
+        },
+        isError: true,
+    };
+}
+export function registerMcpWriteTools(server) {
+    // ── Opportunities ──────────────────────────────────────────────
+    server.registerTool("vantage_opportunity_create", {
+        description: "Create a new pipeline opportunity in Vantage. Writes through the authenticated /mcp path " +
+            "so slug generation, stage history, weighted value, and audit trails follow the normal Lambda " +
+            "semantics. Idempotent when an explicit UUID id is provided — replaying the same call returns " +
+            "the existing record instead of creating a duplicate. Requires API-key scope: opportunities:write.",
+        inputSchema: {
+            id: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Optional UUID for idempotency. If provided and a record with this id already exists, " +
+                "it is returned unchanged; otherwise the new record is created with this id."),
+            name: z.string().min(1).describe("Human-readable opportunity name (required)"),
+            company_id: z
+                .string()
+                .min(1)
+                .describe("UUID of the company this opportunity is linked to (required)"),
+            stage: z
+                .enum([
+                "lead",
+                "qualified",
+                "discovery",
+                "demo",
+                "proposal",
+                "negotiation",
+                "closed_won",
+                "closed_lost",
+            ])
+                .optional()
+                .describe("Initial pipeline stage (default: qualified)"),
+            value: z.number().optional().describe("Opportunity value in the currency unit below"),
+            currency: z.string().optional().default("USD").describe("ISO currency code"),
+            probability: z
+                .number()
+                .min(0)
+                .max(100)
+                .optional()
+                .describe("Win probability 0-100. Inferred from stage if omitted."),
+            expected_close_date: z
+                .string()
+                .optional()
+                .describe("ISO 8601 date, e.g. 2026-06-30"),
+            primary_contact_id: z
+                .string()
+                .optional()
+                .describe("Primary contact UUID at the company"),
+            campaign_id: z
+                .string()
+                .optional()
+                .describe("Campaign UUID that sourced this opportunity"),
+            description: z.string().optional(),
+            notes: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+            owner_id: z
+                .string()
+                .optional()
+                .describe("Owning user UUID (defaults to the API-key's user_id)"),
+        },
+        outputSchema: writeOutput,
+    }, async (args) => {
+        try {
+            return asContent(await createOpportunity(args));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_opportunity_update_stage", {
+        description: "Advance or change an opportunity's stage. Appends a stage-history entry and recomputes " +
+            "probability + weighted_value via the API. Requires scope: opportunities:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Opportunity UUID"),
+            stage: z
+                .enum([
+                "lead",
+                "qualified",
+                "discovery",
+                "demo",
+                "proposal",
+                "negotiation",
+                "closed_won",
+                "closed_lost",
+            ])
+                .describe("Target stage"),
+            notes: z
+                .string()
+                .optional()
+                .describe("Optional note to attach to the stage change"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id, stage, notes }) => {
+        try {
+            return asContent(await updateOpportunity(id, { stage, ...(notes ? { notes } : {}) }));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    // ── Activities ─────────────────────────────────────────────────
+    server.registerTool("vantage_activity_log", {
+        description: "Log an activity / touchpoint against a company, contact, or opportunity. " +
+            "Use for deck sends, call notes, meeting summaries, follow-up reminders. " +
+            "Requires scope: activities:write.",
+        inputSchema: {
+            entity_type: z
+                .enum(["company", "contact", "opportunity"])
+                .describe("Type of entity this activity relates to"),
+            entity_id: z.string().min(1).describe("UUID of the linked entity"),
+            activity_type: z
+                .string()
+                .describe("Activity classifier: 'email_sent', 'call_logged', 'meeting', 'deck_sent', 'note', etc."),
+            summary: z.string().min(1).describe("One-line summary shown in activity lists"),
+            detail: z.string().optional().describe("Longer body / notes"),
+            occurred_at: z
+                .string()
+                .optional()
+                .describe("ISO 8601 timestamp when the activity happened (default: now)"),
+        },
+        outputSchema: writeOutput,
+    }, async (args) => {
+        try {
+            return asContent(await logActivity(args));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    // ── Contacts ───────────────────────────────────────────────────
+    server.registerTool("vantage_contact_create", {
+        description: "Create a new contact in Vantage. Links to a company by UUID. " +
+            "Idempotent when an explicit UUID id is provided — replaying the same call returns the " +
+            "existing record instead of creating a duplicate. Requires scope: contacts:write.",
+        inputSchema: {
+            id: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Optional UUID for idempotency. If provided and a record with this id already exists, " +
+                "it is returned unchanged; otherwise the new record is created with this id."),
+            first_name: z.string().min(1).describe("First name (required)"),
+            last_name: z.string().optional(),
+            email: z.string().email().optional(),
+            company_id: z
+                .string()
+                .uuid()
+                .describe("Company UUID the contact is linked to. Required — v2 contacts " +
+                "must belong to a company (the company's client_id powers the " +
+                "by-client GSI). If unknown, look up or create the company first."),
+            title: z.string().optional().describe("Job title"),
+            role: z
+                .string()
+                .optional()
+                .describe("BD role: decision_maker, champion, evaluator, etc."),
+            phone: z.string().optional(),
+            linkedin_url: z.string().optional(),
+            notes: z.string().optional(),
+        },
+        outputSchema: writeOutput,
+    }, async (args) => {
+        try {
+            return asContent(await createContact(args));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_contact_update", {
+        description: "Update an existing contact's fields. Merge-patch semantics — only the fields " +
+            "provided are changed. Requires scope: contacts:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Contact UUID"),
+            first_name: z.string().optional(),
+            last_name: z.string().optional(),
+            email: z.string().email().optional(),
+            title: z.string().optional(),
+            role: z.string().optional(),
+            phone: z.string().optional(),
+            linkedin_url: z.string().optional(),
+            notes: z.string().optional(),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id, ...updates }) => {
+        try {
+            return asContent(await updateContact(id, updates));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    // ── Companies ──────────────────────────────────────────────────
+    server.registerTool("vantage_company_create", {
+        description: "Create a new company (account) in Vantage. Links to a client tenant. " +
+            "Apollo enrichment runs automatically when domain is provided and the " +
+            "structured fields it returns (annual_revenue → estimated_revenue, " +
+            "employee_count → estimated_employees, linkedin_url) are auto-promoted " +
+            "to top-level fields when the caller doesn't supply them. " +
+            "Requires scope: companies:write.",
+        inputSchema: {
+            name: z.string().min(1).describe("Company name (required)"),
+            client_id: z
+                .string()
+                .min(1)
+                .describe("Client tenant UUID the company belongs to. Required — companies are always client-scoped."),
+            vertical: z
+                .string()
+                .optional()
+                .describe("Vertical (sort key). Defaults to 'general'."),
+            tier: z
+                .enum(["enterprise", "large", "mid-market", "smb", "emerging", "unclassified"])
+                .optional(),
+            status: z
+                .enum([
+                "new",
+                "prospect",
+                "target",
+                "active",
+                "qualified",
+                "engaged",
+                "opportunity",
+                "customer",
+                "churned",
+                "disqualified",
+            ])
+                .optional(),
+            domain: z.string().optional().describe("Primary domain; triggers Apollo enrichment"),
+            industry: z.string().optional(),
+            description: z.string().optional(),
+            website: z.string().optional(),
+            linkedin_url: z.string().optional(),
+            headquarters: z.string().optional().describe("Free-form HQ string, e.g. 'Denver, CO'"),
+            city: z.string().optional(),
+            state: z.string().optional(),
+            country: z.string().optional(),
+            estimated_revenue: z
+                .number()
+                .optional()
+                .describe("Annual revenue in USD (numeric). Apollo can fill this when domain is provided."),
+            estimated_employees: z
+                .number()
+                .optional()
+                .describe("Total employee count. Apollo can fill this when domain is provided."),
+            key_services: z.array(z.string()).optional(),
+            specializations: z.array(z.string()).optional(),
+            partner_tier: z.string().optional(),
+            verticals: z.array(z.string()).optional().describe("Multi-vertical tagging (distinct from primary `vertical` sort key)."),
+            notes: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+        },
+        outputSchema: writeOutput,
+    }, async (args) => {
+        try {
+            return asContent(await createCompany(args));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_company_update", {
+        description: "Update an existing company's fields (merge-patch). " +
+            "Lookup accepts UUID or slug. Requires scope: companies:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Company UUID or slug"),
+            name: z.string().optional(),
+            domain: z.string().optional(),
+            industry: z.string().optional(),
+            tier: z
+                .enum(["enterprise", "large", "mid-market", "smb", "emerging", "unclassified"])
+                .optional(),
+            status: z
+                .enum([
+                "new",
+                "prospect",
+                "target",
+                "active",
+                "qualified",
+                "engaged",
+                "opportunity",
+                "customer",
+                "churned",
+                "disqualified",
+            ])
+                .optional(),
+            headquarters: z.string().optional().describe("Free-form HQ string, e.g. 'Denver, CO'"),
+            estimated_revenue: z.number().optional().describe("Annual revenue in USD"),
+            estimated_employees: z.number().optional().describe("Total employee count"),
+            key_services: z.array(z.string()).optional(),
+            specializations: z.array(z.string()).optional(),
+            partner_tier: z.string().optional(),
+            verticals: z.array(z.string()).optional(),
+            lead_score: z.number().optional(),
+            fit_score: z.number().optional(),
+            tags: z.array(z.string()).optional(),
+            notes: z.string().optional(),
+            logo_url: z.string().optional(),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id, ...updates }) => {
+        try {
+            return asContent(await updateCompany(id, updates));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_company_delete", {
+        description: "Delete a company by UUID or slug. Destructive — intended for test cleanup " +
+            "or disambiguating duplicates. Requires scope: companies:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Company UUID or slug"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id }) => {
+        try {
+            return asContent(await deleteCompany(id));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_company_enrich", {
+        description: "Re-run Apollo enrichment on an existing company and promote the result " +
+            "to top-level fields (estimated_revenue, estimated_employees, linkedin_url). " +
+            "Use when the company was created without a domain (Apollo never ran), " +
+            "was created before the auto-promotion fix landed (data sits in custom_fields " +
+            "but top-level fields are blank), or when Apollo data has gone stale. " +
+            "Falls back to the cached apollo_enrichment block when Apollo returns nothing, " +
+            "so backfill works without burning credits. Caller-set values are never " +
+            "clobbered. Requires scope: companies:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Company UUID or slug"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id }) => {
+        try {
+            return asContent(await enrichCompany(id));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    // ── Contact / Opportunity deletes ──────────────────────────────
+    server.registerTool("vantage_contact_delete", {
+        description: "Delete a contact by UUID. Destructive. Requires scope: contacts:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Contact UUID"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id }) => {
+        try {
+            return asContent(await deleteContact(id));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_opportunity_update", {
+        description: "Update fields on an opportunity (merge-patch) beyond the stage. For stage " +
+            "changes use vantage_opportunity_update_stage (appends stage history). " +
+            "Requires scope: opportunities:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Opportunity UUID"),
+            name: z.string().optional(),
+            description: z.string().optional(),
+            value: z.number().optional(),
+            probability: z.number().min(0).max(100).optional(),
+            currency: z.string().optional(),
+            expected_close_date: z.string().optional().describe("ISO 8601 date"),
+            next_step: z.string().optional(),
+            next_step_date: z.string().optional().describe("ISO 8601 date"),
+            primary_contact_id: z.string().uuid().optional(),
+            owner_id: z.string().uuid().optional(),
+            notes: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id, ...updates }) => {
+        try {
+            return asContent(await updateOpportunity(id, updates));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_opportunity_delete", {
+        description: "Delete an opportunity by UUID. Destructive. Requires scope: opportunities:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Opportunity UUID"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id }) => {
+        try {
+            return asContent(await deleteOpportunity(id));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    // ── Campaigns ──────────────────────────────────────────────────
+    server.registerTool("vantage_campaign_create", {
+        description: "Create a new outreach campaign. Starts in 'draft' status; use " +
+            "vantage_campaign_start to activate. Pass `id` for idempotent " +
+            "re-runs — calling twice with the same UUID returns the existing " +
+            "record (HTTP 200) instead of creating a duplicate. " +
+            "Requires scope: campaigns:write.",
+        inputSchema: {
+            id: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Optional caller-supplied UUID. If a campaign with this id " +
+                "exists, the call is a no-op replay and returns the existing " +
+                "record. Omit to let the server generate a fresh UUID."),
+            name: z.string().min(1).describe("Campaign name"),
+            client_id: z.string().min(1).describe("Client tenant UUID"),
+            campaign_type: z
+                .enum(["email", "linkedin", "multi_channel", "multi"])
+                .optional()
+                .default("multi_channel"),
+            vertical: z.string().optional().describe("Target vertical"),
+            description: z.string().optional(),
+            goal_type: z
+                .enum(["meetings", "replies", "opens", "conversions"])
+                .optional()
+                .describe("What the campaign is optimizing for"),
+            goal_target: z
+                .number()
+                .optional()
+                .describe("Numeric target for the goal (e.g. 5 meetings)"),
+        },
+        outputSchema: writeOutput,
+    }, async (args) => {
+        try {
+            return asContent(await createCampaign(args));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_campaign_update", {
+        description: "Update campaign fields (name, description, goal, schedule, send rate, " +
+            "templates, AI flags, tags, etc). Merge-patch semantics. " +
+            "For status transitions prefer vantage_campaign_start / vantage_campaign_pause. " +
+            "For target/recipient list ops prefer vantage_campaign_add_targets / " +
+            "vantage_campaign_add_recipients. Requires scope: campaigns:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Campaign UUID or slug"),
+            name: z.string().optional(),
+            description: z.string().optional(),
+            campaign_type: z
+                .enum(["email", "linkedin", "multi_channel", "multi"])
+                .optional(),
+            vertical: z.string().optional(),
+            goal_type: z
+                .enum(["meetings", "replies", "opens", "conversions"])
+                .optional(),
+            goal_target: z.number().optional(),
+            daily_send_limit: z
+                .number()
+                .optional()
+                .describe("Max touches per day across the campaign"),
+            desired_outcome: z.string().optional(),
+            scheduled_start: z
+                .string()
+                .optional()
+                .describe("ISO 8601 timestamp when the campaign should activate"),
+            scheduled_end: z
+                .string()
+                .optional()
+                .describe("ISO 8601 timestamp when the campaign should auto-pause"),
+            ai_suggestions_enabled: z.boolean().optional(),
+            ai_auto_optimize: z.boolean().optional(),
+            tags: z.array(z.string()).optional(),
+            target_tiers: z
+                .array(z.string())
+                .optional()
+                .describe("Eligible company tiers (enterprise / large / mid-market / smb / emerging)"),
+            target_company_ids: z.array(z.string().uuid()).optional(),
+            target_contact_ids: z.array(z.string().uuid()).optional(),
+            target_criteria: z
+                .record(z.unknown())
+                .optional()
+                .describe("Free-form ICP filter criteria"),
+            primary_template_id: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Primary outreach template"),
+            template_ids: z
+                .array(z.string().uuid())
+                .optional()
+                .describe("All eligible outreach templates"),
+            follow_up_template_ids: z
+                .array(z.string().uuid())
+                .optional(),
+            sequence_steps: z
+                .array(z.record(z.unknown()))
+                .optional()
+                .describe("Multi-step outreach cadence definition"),
+            template_id: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Deprecated alias of primary_template_id; prefer primary_template_id"),
+            ab_test_template_ids: z
+                .array(z.string().uuid())
+                .optional()
+                .describe("A/B test variant template UUIDs"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id, ...updates }) => {
+        try {
+            return asContent(await updateCampaign(id, updates));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_campaign_delete", {
+        description: "Delete a campaign. Active campaigns cannot be deleted — pause first. " +
+            "Requires scope: campaigns:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Campaign UUID or slug"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id }) => {
+        try {
+            return asContent(await deleteCampaign(id));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_campaign_start", {
+        description: "Flip a draft or paused campaign to active status. Does not itself send " +
+            "messages — Vantage is a tracker, not a sender. Requires scope: campaigns:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Campaign UUID or slug"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id }) => {
+        try {
+            return asContent(await startCampaign(id));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_campaign_pause", {
+        description: "Pause an active campaign. Requires scope: campaigns:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Campaign UUID or slug"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id }) => {
+        try {
+            return asContent(await pauseCampaign(id));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_campaign_add_targets", {
+        description: "Attach one or more companies to a campaign's target list (junction table). " +
+            "Targets are the universe the campaign can draw recipients from. " +
+            "Requires scope: campaigns:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Campaign UUID or slug"),
+            company_ids: z
+                .array(z.string().uuid())
+                .min(1)
+                .describe("Company UUIDs to attach"),
+            priority: z.enum(["high", "normal", "low"]).optional().default("normal"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id, ...body }) => {
+        try {
+            return asContent(await addCampaignTargets(id, body));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_campaign_remove_target", {
+        description: "Remove a single company from a campaign's target list (junction table). " +
+            "Inverse of vantage_campaign_add_targets. Use this to clean up dangling " +
+            "junction entries after a target company is deleted, or to drop a target " +
+            "from a draft campaign before launch. Returns 404 if the (campaign, company) " +
+            "pair has no junction row. Requires scope: campaigns:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Campaign UUID or slug"),
+            company_id: z
+                .string()
+                .uuid()
+                .describe("Company UUID to detach from the campaign"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id, company_id }) => {
+        try {
+            return asContent(await removeCampaignTarget(id, company_id));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_campaign_add_recipients", {
+        description: "Add contacts to a campaign's active recipient list (engagement_status=pending). " +
+            "Recipients are the actual people messages would be addressed to. " +
+            "Requires scope: campaigns:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Campaign UUID or slug"),
+            contact_ids: z
+                .array(z.string().uuid())
+                .min(1)
+                .describe("Contact UUIDs to add as recipients"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id, ...body }) => {
+        try {
+            return asContent(await addCampaignRecipients(id, body));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_campaign_recipient_update", {
+        description: "Update a single recipient's engagement_status on a campaign. Use this to " +
+            "reflect events (invited / sent / opened / clicked / replied / bounced / " +
+            "unsubscribed) that don't auto-propagate from outreach records onto the " +
+            "campaign's embedded recipients map. Typical pattern: after " +
+            "vantage_outreach_update marks the outreach as 'replied', also call this " +
+            "tool so the campaign-recipient row in the Vantage UI reflects the same " +
+            "state. Stamps the matching timestamp (invited_at / sent_at / opened_at / " +
+            "clicked_at / replied_at / bounced_at / unsubscribed_at) automatically. " +
+            "Requires scope: campaigns:write.\n\n" +
+            "State guide:\n" +
+            "  - pending:      added to the campaign, no action yet\n" +
+            "  - invited:      connection attempt initiated (e.g. LinkedIn connect request) — no message sent yet\n" +
+            "  - sent:         outbound message sent\n" +
+            "  - opened:       target opened the message\n" +
+            "  - clicked:      target clicked a link in the message\n" +
+            "  - replied:      target responded\n" +
+            "  - bounced:      delivery failed (invalid address, etc.)\n" +
+            "  - unsubscribed: target explicitly opted out (compliance-relevant — distinct from failed)\n" +
+            "  - failed:       technical send failure (provider error, retry exhausted, etc.)",
+        inputSchema: {
+            id: z.string().min(1).describe("Campaign UUID or slug"),
+            contact_id: z.string().uuid().describe("Recipient contact UUID"),
+            engagement_status: z
+                .enum([
+                "pending",
+                "invited",
+                "sent",
+                "opened",
+                "clicked",
+                "replied",
+                "bounced",
+                "unsubscribed",
+                "failed",
+            ])
+                .describe("New engagement_status to set on the recipient row"),
+            occurred_at: z
+                .string()
+                .optional()
+                .describe("ISO 8601 timestamp for when the event occurred (default: now). " +
+                "Only stamped on the matching state transition (e.g., replied_at when " +
+                "engagement_status='replied')."),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id, contact_id, ...body }) => {
+        try {
+            return asContent(await updateCampaignRecipient(id, contact_id, body));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_campaign_source_contacts", {
+        description: "Search Apollo for contacts at each company targeted by a campaign, create them as Vantage " +
+            "contacts, and add them to the campaign's recipient list in one shot. " +
+            "Defaults to DC-ops personas (Directors/VPs of Data Center Operations, Critical Facilities, etc.) " +
+            "and manager/director/vp/c_suite seniority levels. " +
+            "Returns a per-company summary of contacts added. " +
+            "Requires scope: campaigns:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Campaign UUID or slug"),
+            titles: z
+                .array(z.string())
+                .optional()
+                .describe("Job title filters to search Apollo for (default: DC-ops personas). " +
+                "Pass an array to override the defaults."),
+            seniorities: z
+                .array(z.string())
+                .optional()
+                .describe("Seniority levels: manager, director, vp, c_suite, senior (default: all four)."),
+            limit_per_company: z
+                .number()
+                .int()
+                .min(1)
+                .max(10)
+                .optional()
+                .describe("Max contacts to add per target company (default: 3, max: 10)"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id, ...body }) => {
+        try {
+            return asContent(await sourceCampaignContacts(id, body));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    // ── Templates ──────────────────────────────────────────────────
+    server.registerTool("vantage_template_create", {
+        description: "Create a message template for campaigns. Templates can be attached to one " +
+            "or more campaigns via vantage_campaign_update (template_id field). " +
+            "Requires scope: templates:write.",
+        inputSchema: {
+            name: z.string().min(1).describe("Template name (internal reference)"),
+            body: z.string().min(1).describe("Message body (supports variables like {{first_name}})"),
+            subject: z.string().optional().describe("Subject line (for email templates)"),
+            description: z.string().optional(),
+            cta: z.string().optional().describe("Call-to-action text"),
+            campaign_type: z
+                .enum(["email", "linkedin", "multi_channel"])
+                .optional()
+                .default("email"),
+            target_vertical: z.string().optional(),
+            target_persona: z
+                .string()
+                .optional()
+                .describe("Target persona: decision_maker, champion, evaluator, etc."),
+        },
+        outputSchema: writeOutput,
+    }, async (args) => {
+        try {
+            return asContent(await createTemplate(args));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_template_update", {
+        description: "Update a template's fields. Merge-patch semantics. " +
+            "Requires scope: templates:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Template UUID"),
+            name: z.string().optional(),
+            body: z.string().optional(),
+            subject: z.string().optional(),
+            description: z.string().optional(),
+            cta: z.string().optional(),
+            target_vertical: z.string().optional(),
+            target_persona: z.string().optional(),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id, ...updates }) => {
+        try {
+            return asContent(await updateTemplate(id, updates));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_template_delete", {
+        description: "Delete a template by UUID. Requires scope: templates:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Template UUID"),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id }) => {
+        try {
+            return asContent(await deleteTemplate(id));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    // ── Outreach records ───────────────────────────────────────────
+    // Vantage is an outreach TRACKER, not a sender. These tools record
+    // that a message was sent externally (via LinkedIn, email provider,
+    // extension, etc.) so engagement can be tracked + attributed.
+    server.registerTool("vantage_outreach_record", {
+        description: "Record an outbound message that was sent externally. Vantage does not itself " +
+            "transmit messages — it tracks them. Use this to log that a campaign touch " +
+            "happened (via LinkedIn DM, email, phone, etc.) so engagement can be " +
+            "attributed downstream. Requires scope: outreach:write.",
+        inputSchema: {
+            campaign_id: z.string().uuid().describe("Campaign UUID this touch belongs to"),
+            company_id: z.string().uuid().describe("Company UUID the recipient belongs to"),
+            contact_id: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Contact UUID (the specific recipient)"),
+            channel: z
+                .enum(["email", "linkedin", "phone", "in_person", "other"])
+                .optional()
+                .default("email"),
+            status: z
+                .enum(["sent", "opened", "replied", "bounced", "failed"])
+                .optional()
+                .default("sent"),
+            subject: z.string().optional(),
+            body: z.string().optional().describe("Message body as sent"),
+            template_id: z.string().uuid().optional().describe("Template used (if any)"),
+            sent_at: z.string().optional().describe("ISO 8601 timestamp (default: now)"),
+        },
+        outputSchema: writeOutput,
+    }, async (args) => {
+        try {
+            return asContent(await createOutreach(args));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_outreach_update", {
+        description: "Update an outreach record — typically to log engagement events (opened, replied) " +
+            "or attach reply text. Requires scope: outreach:write.",
+        inputSchema: {
+            id: z.string().min(1).describe("Outreach record UUID"),
+            status: z
+                .enum(["sent", "opened", "replied", "bounced", "failed"])
+                .optional(),
+            reply_text: z.string().optional(),
+            reply_sentiment: z.enum(["positive", "neutral", "negative"]).optional(),
+            notes: z.string().optional(),
+        },
+        outputSchema: writeOutput,
+    }, async ({ id, ...updates }) => {
+        try {
+            return asContent(await updateOutreach(id, updates));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    // ── Apollo (people + company search, email reveal, bulk import) ──
+    server.registerTool("vantage_apollo_search_contacts", {
+        description: "Search Apollo for people matching the given criteria. Returns a list of " +
+            "person records (with masked emails) — pair with vantage_apollo_unlock_email " +
+            "to reveal a single email, or vantage_apollo_import_contact to bulk-import " +
+            "verified people into Vantage. Free of charge per search; only unlocks cost " +
+            "credits. Requires scope: apollo:write.",
+        inputSchema: {
+            domains: z
+                .union([z.array(z.string()), z.string()])
+                .optional()
+                .describe("Organization domain(s) to filter by, e.g. 'acme.com' or ['acme.com', 'beta.io']"),
+            q_organization_name: z
+                .string()
+                .optional()
+                .describe("Free-text organization-name match (use when domain unknown)"),
+            organization_ids: z
+                .array(z.string())
+                .optional()
+                .describe("Apollo organization IDs (from a prior search-companies call)"),
+            person_titles: z
+                .array(z.string())
+                .optional()
+                .describe("Title keywords, e.g. ['VP Supply Chain', 'Director Materials']"),
+            person_seniorities: z
+                .array(z.string())
+                .optional()
+                .describe("Seniority filters: manager, director, vp, c_suite, owner, partner"),
+            q_keywords: z.string().optional().describe("Free-text people search"),
+            page: z.number().int().min(1).optional().describe("Page (1-indexed)"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("Per-page (default 25, max 100)"),
+        },
+        outputSchema: writeOutput,
+    }, async (args) => {
+        try {
+            return asContent(await apolloSearchContacts(args));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_apollo_search_companies", {
+        description: "Search Apollo for organizations matching the given criteria. Returns Apollo " +
+            "organization records (id, name, domain, employee count, industry, etc.) " +
+            "which can then feed into vantage_apollo_search_contacts (via organization_ids) " +
+            "or vantage_company_create. Requires scope: apollo:write.",
+        inputSchema: {
+            q_organization_name: z.string().optional().describe("Free-text org-name match"),
+            q_organization_domains: z
+                .union([z.array(z.string()), z.string()])
+                .optional()
+                .describe("Specific domain(s) to look up"),
+            organization_locations: z
+                .array(z.string())
+                .optional()
+                .describe("City/state/country filters, e.g. ['Atlanta, Georgia', 'Texas']"),
+            num_employees_ranges: z
+                .array(z.string())
+                .optional()
+                .describe("Employee-count buckets, e.g. ['1,10', '11,50', '51,200']"),
+            page: z.number().int().min(1).optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+        outputSchema: writeOutput,
+    }, async (args) => {
+        try {
+            return asContent(await apolloSearchCompanies(args));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_apollo_unlock_email", {
+        description: "Reveal a verified email for a single person via Apollo's people/match endpoint. " +
+            "Requires either apollo_id (preferred — from a prior search) or linkedin_url, " +
+            "plus first_name + last_name + organization_name for higher match confidence. " +
+            "Each unlock consumes Apollo credits, so prefer to unlock only after confirming " +
+            "the person fits the campaign. Requires scope: apollo:write.",
+        inputSchema: {
+            apollo_id: z
+                .string()
+                .optional()
+                .describe("Apollo person ID (from search-contacts results) — strongest signal"),
+            first_name: z.string().optional(),
+            last_name: z.string().optional(),
+            linkedin_url: z
+                .string()
+                .optional()
+                .describe("LinkedIn profile URL — fallback when apollo_id is unknown"),
+            organization_name: z
+                .string()
+                .optional()
+                .describe("Current employer name — improves match confidence"),
+        },
+        outputSchema: writeOutput,
+    }, async (args) => {
+        try {
+            return asContent(await apolloUnlockEmail(args));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    server.registerTool("vantage_apollo_import_contact", {
+        description: "Bulk-import a list of Apollo person records into Vantage. Each record is " +
+            "matched to (or creates, if create_missing_companies is true) a Vantage " +
+            "company by domain, then written to vantage-contacts-v2-prod with an " +
+            "apollo_id link for future enrichment. Use after vantage_apollo_search_contacts " +
+            "+ vantage_apollo_unlock_email when you have a verified shortlist. " +
+            "Requires scope: apollo:write.",
+        inputSchema: {
+            client_id: z.string().min(1).describe("Vantage client tenant ID"),
+            contacts: z
+                .array(z.record(z.string(), z.unknown()))
+                .min(1)
+                .describe("Array of Apollo person records (typically from search-contacts results)"),
+            create_missing_companies: z
+                .boolean()
+                .optional()
+                .describe("Create companies for unknown domains (default: true)"),
+            default_company_id: z
+                .string()
+                .optional()
+                .describe("Fallback company UUID for contacts with no resolvable organization"),
+        },
+        outputSchema: writeOutput,
+    }, async (args) => {
+        try {
+            return asContent(await apolloImportContacts(args));
+        }
+        catch (err) {
+            return asError(err);
+        }
+    });
+    // ── Diagnostics ────────────────────────────────────────────────
+    server.registerTool("vantage_mcp_health", {
+        description: "Diagnostic for the MCP write surface. Reports whether VANTAGE_MCP_KEY is configured " +
+            "and the API URL the tools will call. Does not make any API request.",
+        inputSchema: {},
+        outputSchema: healthOutput,
+    }, async () => {
+        const keyConfigured = authConfigured();
+        const apiUrl = apiUrlForDiagnostics();
+        const hint = keyConfigured
+            ? "Ready. Provision a key at <dashboard>/api-keys with the scopes you need."
+            : "Set VANTAGE_MCP_KEY in ~/repo/.env or the mcp.json env block.";
+        const summary = JSON.stringify({ api_url: apiUrl, key_configured: keyConfigured, hint }, null, 2);
+        return {
+            content: [{ type: "text", text: summary }],
+            structuredContent: {
+                healthy: keyConfigured,
+                details: { api_url: apiUrl, key_configured: keyConfigured, hint },
+                summary,
+            },
+        };
+    });
+}
+//# sourceMappingURL=mcp-write-tools.js.map