@sellable/mcp 0.1.322 → 0.1.324

package/dist/server.js

@@ -41,6 +41,7 @@ import { attachRecommendedSequence, attachSequence, createWorkflowTable, } from
 import { exportTableCsv, listTables } from "./tools/tables.js";
 import { handleVerifyTableRow } from "./tools/verify-row.js";
 import { sanitizeWatchUrlsForMcpResult } from "./tools/watch-url-security.js";
+import { getCampaignWaterfall, setCampaignWaterfallOrder, } from "./tools/waterfalls.js";
 import { addTeammate, createWorkspace, getActiveWorkspace, listWorkspaces, setActiveWorkspace, } from "./tools/workspaces.js";
 import { checkForUpdates, logUpdateNotice } from "./update-check.js";
 const server = new Server({
@@ -378,6 +379,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "verify_table_row":
                 result = await handleVerifyTableRow(args);
                 break;
+            case "get_campaign_waterfall":
+                result = await getCampaignWaterfall();
+                break;
+            case "set_campaign_waterfall_order":
+                result = await setCampaignWaterfallOrder(args);
+                break;
             case "get_rows":
                 result = await getRows(args?.tableId, args?.rowIds);
                 break;

package/dist/tools/prompts.d.ts

@@ -137,7 +137,7 @@ export interface PostFindLeadsScoutRegistryResponse {
 }
 export declare const DEFAULT_SUBSKILL_PROMPT_CHUNK_CHARS = 48000;
 export declare const MAX_SUBSKILL_PROMPT_CHUNK_CHARS = 48000;
-export declare const ALLOWED_SUBSKILL_PROMPT_NAMES: readonly ["building-gtm-tables", "content", "create-ab-test", "create-campaign", "create-campaign-brief", "create-campaign-v2", "create-campaign-v2-tail", "create-campaign-v2-validation", "create-post", "create-rubric", "engage", "enrich-prospects", "fill-send-horizon", "find-leads", "foundation", "generate-messages", "interview", "load-voice", "refresh-sender-engagement", "research", "research-prospect", "research-sender", "weekly-campaign-summary", "workflow-sequences"];
+export declare const ALLOWED_SUBSKILL_PROMPT_NAMES: readonly ["building-gtm-tables", "content", "create-ab-test", "create-campaign", "create-campaign-brief", "create-campaign-v2", "create-campaign-v2-tail", "create-campaign-v2-validation", "create-evergreen-campaigns", "create-post", "create-rubric", "engage", "enrich-prospects", "fill-send-horizon", "find-leads", "foundation", "generate-messages", "interview", "load-voice", "refresh-sender-engagement", "research", "research-prospect", "research-sender", "weekly-campaign-summary", "workflow-sequences"];
 export declare const promptToolDefinitions: ({
     name: string;
     description: string;
@@ -181,7 +181,7 @@ export declare const promptToolDefinitions: ({
         properties: {
             subskillName: {
                 type: string;
-                enum: readonly ["building-gtm-tables", "content", "create-ab-test", "create-campaign", "create-campaign-brief", "create-campaign-v2", "create-campaign-v2-tail", "create-campaign-v2-validation", "create-post", "create-rubric", "engage", "enrich-prospects", "fill-send-horizon", "find-leads", "foundation", "generate-messages", "interview", "load-voice", "refresh-sender-engagement", "research", "research-prospect", "research-sender", "weekly-campaign-summary", "workflow-sequences"];
+                enum: readonly ["building-gtm-tables", "content", "create-ab-test", "create-campaign", "create-campaign-brief", "create-campaign-v2", "create-campaign-v2-tail", "create-campaign-v2-validation", "create-evergreen-campaigns", "create-post", "create-rubric", "engage", "enrich-prospects", "fill-send-horizon", "find-leads", "foundation", "generate-messages", "interview", "load-voice", "refresh-sender-engagement", "research", "research-prospect", "research-sender", "weekly-campaign-summary", "workflow-sequences"];
                 description: string;
             };
             offset: {
@@ -216,7 +216,7 @@ export declare const promptToolDefinitions: ({
         properties: {
             subskillName: {
                 type: string;
-                enum: readonly ["building-gtm-tables", "content", "create-ab-test", "create-campaign", "create-campaign-brief", "create-campaign-v2", "create-campaign-v2-tail", "create-campaign-v2-validation", "create-post", "create-rubric", "engage", "enrich-prospects", "fill-send-horizon", "find-leads", "foundation", "generate-messages", "interview", "load-voice", "refresh-sender-engagement", "research", "research-prospect", "research-sender", "weekly-campaign-summary", "workflow-sequences"];
+                enum: readonly ["building-gtm-tables", "content", "create-ab-test", "create-campaign", "create-campaign-brief", "create-campaign-v2", "create-campaign-v2-tail", "create-campaign-v2-validation", "create-evergreen-campaigns", "create-post", "create-rubric", "engage", "enrich-prospects", "fill-send-horizon", "find-leads", "foundation", "generate-messages", "interview", "load-voice", "refresh-sender-engagement", "research", "research-prospect", "research-sender", "weekly-campaign-summary", "workflow-sequences"];
                 description: string;
             };
             assetPath: {

package/dist/tools/prompts.js

@@ -25,6 +25,7 @@ export const ALLOWED_SUBSKILL_PROMPT_NAMES = [
     "create-campaign-v2",
     "create-campaign-v2-tail",
     "create-campaign-v2-validation",
+    "create-evergreen-campaigns",
     "create-post",
     "create-rubric",
     "engage",

package/dist/tools/registry.d.ts

@@ -236,7 +236,7 @@ export declare const allTools: ({
         properties: {
             subskillName: {
                 type: string;
-                enum: readonly ["building-gtm-tables", "content", "create-ab-test", "create-campaign", "create-campaign-brief", "create-campaign-v2", "create-campaign-v2-tail", "create-campaign-v2-validation", "create-post", "create-rubric", "engage", "enrich-prospects", "fill-send-horizon", "find-leads", "foundation", "generate-messages", "interview", "load-voice", "refresh-sender-engagement", "research", "research-prospect", "research-sender", "weekly-campaign-summary", "workflow-sequences"];
+                enum: readonly ["building-gtm-tables", "content", "create-ab-test", "create-campaign", "create-campaign-brief", "create-campaign-v2", "create-campaign-v2-tail", "create-campaign-v2-validation", "create-evergreen-campaigns", "create-post", "create-rubric", "engage", "enrich-prospects", "fill-send-horizon", "find-leads", "foundation", "generate-messages", "interview", "load-voice", "refresh-sender-engagement", "research", "research-prospect", "research-sender", "weekly-campaign-summary", "workflow-sequences"];
                 description: string;
             };
             offset: {
@@ -271,7 +271,7 @@ export declare const allTools: ({
         properties: {
             subskillName: {
                 type: string;
-                enum: readonly ["building-gtm-tables", "content", "create-ab-test", "create-campaign", "create-campaign-brief", "create-campaign-v2", "create-campaign-v2-tail", "create-campaign-v2-validation", "create-post", "create-rubric", "engage", "enrich-prospects", "fill-send-horizon", "find-leads", "foundation", "generate-messages", "interview", "load-voice", "refresh-sender-engagement", "research", "research-prospect", "research-sender", "weekly-campaign-summary", "workflow-sequences"];
+                enum: readonly ["building-gtm-tables", "content", "create-ab-test", "create-campaign", "create-campaign-brief", "create-campaign-v2", "create-campaign-v2-tail", "create-campaign-v2-validation", "create-evergreen-campaigns", "create-post", "create-rubric", "engage", "enrich-prospects", "fill-send-horizon", "find-leads", "foundation", "generate-messages", "interview", "load-voice", "refresh-sender-engagement", "research", "research-prospect", "research-sender", "weekly-campaign-summary", "workflow-sequences"];
                 description: string;
             };
             assetPath: {
@@ -7421,6 +7421,36 @@ export declare const allTools: ({
         };
         required: string[];
     };
+} | {
+    readonly name: "get_campaign_waterfall";
+    readonly description: "Read the active workspace's managed-campaign waterfall hierarchy: each waterfall (per sender or shared) with its campaign slots in stored priority order. Use this before fill-send-horizon runs to follow the configured lane order, or when the user asks what order their campaigns fill in. Returns empty when the workspace has no managed-campaign program (the hierarchy is created by evergreen reconcile).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly required: readonly [];
+        readonly additionalProperties: false;
+    };
+} | {
+    readonly name: "set_campaign_waterfall_order";
+    readonly description: "Reorder one waterfall's campaign slots — the stored hierarchy that decides which lane fills first (e.g. move Shared Signal Discovery above Post Engagers). Pass the waterfallKey from get_campaign_waterfall and orderedSlotKeys containing EXACTLY that waterfall's slot keys in the desired order; priorities are renumbered 10/20/30. Confirm the new order with the user before calling unless they stated it explicitly.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly waterfallKey: {
+                readonly type: "string";
+                readonly description: "Waterfall key from get_campaign_waterfall.";
+            };
+            readonly orderedSlotKeys: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "All of the waterfall's slot keys in the desired fill order (highest priority first). Must match the existing slot set exactly — no additions or omissions.";
+            };
+        };
+        readonly required: readonly ["waterfallKey", "orderedSlotKeys"];
+        readonly additionalProperties: false;
+    };
 } | {
     name: string;
     description: string;

package/dist/tools/registry.js

@@ -35,6 +35,7 @@ import { senderToolDefinitions } from "./senders.js";
 import { sequencerToolDefinitions } from "./sequencer.js";
 import { tableToolDefinitions } from "./tables.js";
 import { verifyRowToolDefinitions } from "./verify-row.js";
+import { waterfallToolDefinitions } from "./waterfalls.js";
 import { workspaceToolDefinitions } from "./workspaces.js";
 export const allTools = [
     ...campaignToolDefinitions,
@@ -76,4 +77,5 @@ export const allTools = [
     ...columnDeleteToolDefinitions,
     ...columnReorderToolDefinitions,
     ...verifyRowToolDefinitions,
+    ...waterfallToolDefinitions,
 ];

package/dist/tools/waterfalls.d.ts

@@ -0,0 +1,67 @@
+export interface WaterfallSlotEntry {
+    slotKey: string;
+    priority: number;
+    displayName: string;
+    campaignOfferId: string | null;
+    workflowTableId: string | null;
+    sourceType: string;
+    sourceScope: string;
+    slotStatus: string;
+}
+export interface WaterfallEntry {
+    programKey: string;
+    waterfallKey: string;
+    displayName: string;
+    senderRefs: string[];
+    slots: WaterfallSlotEntry[];
+}
+export interface GetCampaignWaterfallResponse {
+    waterfalls: WaterfallEntry[];
+}
+export interface SetWaterfallOrderInput {
+    waterfallKey: string;
+    orderedSlotKeys: string[];
+}
+export declare const waterfallToolDefinitions: readonly [{
+    readonly name: "get_campaign_waterfall";
+    readonly description: "Read the active workspace's managed-campaign waterfall hierarchy: each waterfall (per sender or shared) with its campaign slots in stored priority order. Use this before fill-send-horizon runs to follow the configured lane order, or when the user asks what order their campaigns fill in. Returns empty when the workspace has no managed-campaign program (the hierarchy is created by evergreen reconcile).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly required: readonly [];
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "set_campaign_waterfall_order";
+    readonly description: "Reorder one waterfall's campaign slots — the stored hierarchy that decides which lane fills first (e.g. move Shared Signal Discovery above Post Engagers). Pass the waterfallKey from get_campaign_waterfall and orderedSlotKeys containing EXACTLY that waterfall's slot keys in the desired order; priorities are renumbered 10/20/30. Confirm the new order with the user before calling unless they stated it explicitly.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly waterfallKey: {
+                readonly type: "string";
+                readonly description: "Waterfall key from get_campaign_waterfall.";
+            };
+            readonly orderedSlotKeys: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "All of the waterfall's slot keys in the desired fill order (highest priority first). Must match the existing slot set exactly — no additions or omissions.";
+            };
+        };
+        readonly required: readonly ["waterfallKey", "orderedSlotKeys"];
+        readonly additionalProperties: false;
+    };
+}];
+export declare function getCampaignWaterfall(): Promise<GetCampaignWaterfallResponse | {
+    waterfalls: never[];
+    _notice: string;
+}>;
+export declare function setCampaignWaterfallOrder(input: SetWaterfallOrderInput): Promise<{
+    waterfallKey: string;
+    slots: Array<{
+        slotKey: string;
+        priority: number;
+    }>;
+    previousOrder: string[];
+}>;

package/dist/tools/waterfalls.js

@@ -0,0 +1,51 @@
+import { getApi } from "../api.js";
+export const waterfallToolDefinitions = [
+    {
+        name: "get_campaign_waterfall",
+        description: "Read the active workspace's managed-campaign waterfall hierarchy: each waterfall (per sender or shared) with its campaign slots in stored priority order. Use this before fill-send-horizon runs to follow the configured lane order, or when the user asks what order their campaigns fill in. Returns empty when the workspace has no managed-campaign program (the hierarchy is created by evergreen reconcile).",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "set_campaign_waterfall_order",
+        description: "Reorder one waterfall's campaign slots — the stored hierarchy that decides which lane fills first (e.g. move Shared Signal Discovery above Post Engagers). Pass the waterfallKey from get_campaign_waterfall and orderedSlotKeys containing EXACTLY that waterfall's slot keys in the desired order; priorities are renumbered 10/20/30. Confirm the new order with the user before calling unless they stated it explicitly.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                waterfallKey: {
+                    type: "string",
+                    description: "Waterfall key from get_campaign_waterfall.",
+                },
+                orderedSlotKeys: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "All of the waterfall's slot keys in the desired fill order (highest priority first). Must match the existing slot set exactly — no additions or omissions.",
+                },
+            },
+            required: ["waterfallKey", "orderedSlotKeys"],
+            additionalProperties: false,
+        },
+    },
+];
+export async function getCampaignWaterfall() {
+    const api = getApi();
+    const response = await api.get("/api/v3/managed-campaigns/waterfalls");
+    if (!response.waterfalls || response.waterfalls.length === 0) {
+        return {
+            waterfalls: [],
+            _notice: "No managed-campaign waterfalls exist in this workspace yet. Run the evergreen reconcile (create-evergreen-campaigns) to materialize the hierarchy, or fall back to the per-invocation order.",
+        };
+    }
+    return response;
+}
+export async function setCampaignWaterfallOrder(input) {
+    const api = getApi();
+    return api.put("/api/v3/managed-campaigns/waterfalls", {
+        waterfallKey: input.waterfallKey,
+        orderedSlotKeys: input.orderedSlotKeys,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.322",
+  "version": "0.1.324",
   "type": "module",
   "description": "Sellable MCP server for Claude Code and Codex campaign workflows",
   "main": "dist/index.js",

package/skills/create-evergreen-campaigns/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: create-evergreen-campaigns
+description: Reconcile a sender team's evergreen campaign structure — create-or-reuse the standing campaigns (per-sender post engagers + shared fallback lanes) idempotently, with sequences attached and prospect-safe message briefs. Never duplicates, never launches. Schedule-automation friendly ("make sure evergreen campaigns exist for these users").
+visibility: internal
+---
+
+# Create Evergreen Campaigns
+
+<role>
+You are a campaign structure reconciler. Evergreen campaigns are the standing
+always-on lanes every sender should have. Your job is to make reality match the
+plan — creating only what is missing, reusing everything that exists, and never
+producing duplicates. Reconcile/create-reuse only; this skill never launches campaigns.
+</role>
+
+<inputs>
+The invoking prompt names the senders ("create evergreen campaigns for csreyes92 and thomas"). Resolve each via `list_senders`.
+
+Default evergreen plan per workspace (override only if the prompt specifies different lanes):
+
+1. **`<Sender Name> - Post Engagers`** — one per sender (warm lane, highest priority)
+2. **`<Workspace/Team> - Shared Signal Discovery`** — one shared across senders
+3. **`<Workspace/Team> - Shared Cold Fallback`** — one shared across senders
+</inputs>
+
+<objective>
+1. **Inventory first**: `get_campaigns` + `list_tables` in the active workspace. Match existing campaigns to the plan by name (case-insensitive, ignore suffixes like "(Copy)"). A matching non-archived campaign = REUSE; record it and move on. Never create a second campaign for a slot that already has one.
+2. **Create only the missing slots** with `create_on_demand_campaign({ name, senderIds, campaignBrief })`:
+   - Post Engagers lanes: that sender's ID only. Shared lanes: all the senders' IDs.
+   - The brief must include the warm post-engager first-message template style — short, casual, references the post they engaged with, closed question, **no internal vocabulary, no pitch, no meeting ask** in message one:
+
+     ```
+     {{first_name}}
+
+     Hey there
+
+     Saw you pop up on my post about {{post_topic_line}}
+     ```
+
+   - The sequence is auto-selected by sender tier; do not hand-author sequence templates here. Never select a paid-InMail template.
+3. **Verify each slot** after create/reuse: `get_campaign` shows the table exists and a sequence is attached (`list_tables({ hasSequence: true })` as a cross-check).
+4. **Report the reconcile plan and result** — every slot tagged `reused` or `created`, nothing else:
+
+```
+Evergreen Reconcile — {date}
+• Christian Reyes - Post Engagers: reused (18 rows)
+• Thomas Nobbs - Post Engagers: reused (8 rows)
+• Sellable.dev - Shared Signal Discovery: reused
+• Sellable.dev - Shared Cold Fallback: created (empty — needs leads)
+All campaigns remain unlaunched. Next: refresh-sender-engagement to supply the warm lanes, then fill-send-horizon.
+```
+</objective>
+
+<safety>
+- **Idempotent by construction**: rerunning on a schedule must produce all-`reused` and zero new campaigns. If a name matches ambiguously (two candidates), reuse the most recently updated and flag the duplicate for the operator instead of creating a third.
+- Never call `start_campaign` / `start_on_demand_campaign`. New campaigns stay in their default unlaunched state.
+- Never archive, rename, or delete existing campaigns — reconcile is additive; structural removals are operator actions.
+- Respect workspace boundaries: senders and campaigns must belong to the active workspace.
+</safety>

package/skills/fill-send-horizon/SKILL.md

@@ -17,7 +17,7 @@ The invoking prompt (often a scheduled automation) names the targets. Accept any
 - Sender names ("…for csreyes92 and thomas") — resolve via `list_senders`, then `get_campaigns` and match campaigns attached to those senders
 - Nothing specific ("fill send horizon") — operate on all non-archived campaign tables in the active workspace that have a sequence attached (`list_tables({ hasSequence: true })`), skipping ARCHIVED ones
 
-Optional inputs: `targetPreparedMessages` (default: leave unset for the adaptive default), and an explicit "approve" instruction (see safety rules).
+Optional inputs: `targetPreparedMessages` (default: leave unset for the adaptive default), an explicit "approve" instruction (see safety rules), and a **waterfall priority order** (see below).
 </inputs>
 
 <objective>
@@ -30,6 +30,27 @@ For each target campaign:
 5. Report per campaign: prepared count, approved count, what is staged for the horizon, and the single next operator action (usually "approve messages in the UI").
 </objective>
 
+<waterfall>
+## Campaign hierarchy (waterfall order)
+
+The fill order is **stored workspace state**, not something each automation restates. Resolve it in this precedence:
+
+1. **Stored hierarchy (default)**: call `get_campaign_waterfall` first. It returns each waterfall (per sender or shared) with slots in stored priority order — campaign offer IDs included. Fill in that order.
+2. **Per-invocation override**: if the invoking prompt states an explicit order ("fill in this order: Signal Discovery, Post Engagers"), use it for this run only and say in the report that the stored order was overridden. To change the order durably, use `set_campaign_waterfall_order` — but only when the user/automation explicitly asks to change the hierarchy, never as a side effect of a fill run.
+3. **No stored hierarchy** (tool returns empty — evergreen reconcile hasn't run): fall back to the conventional order `<Sender> - Post Engagers` (warmest) → `Shared Signal Discovery` → `Shared Cold Fallback` (coldest), and note that running `create-evergreen-campaigns` will materialize a stored hierarchy.
+
+Fill mechanics, whatever the source of the order:
+
+- **Fill the top lane first.** Move to the next lane ONLY when the current one stops with source exhaustion / no more eligible rows — never because it is merely slow.
+- **Stop descending once the horizon target is met.** If the warm lane alone fills the horizon, the cold lanes get nothing this run — that is correct, not a gap.
+- **Report per lane** so the operator can see the waterfall working:
+
+```
+csreyes92 waterfall (stored order): Post Engagers filled 4/4 (horizon met — lower lanes skipped)
+thomas waterfall (stored order): Post Engagers 1/4 (source thin) → Shared Signal Discovery 3/3 remaining
+```
+</waterfall>
+
 <safety>
 - **Never call `start_campaign`, `start_on_demand_campaign`, or `start_direct_campaign`.** Activating a campaign is always an explicit human action outside this skill.
 - Use `approvalMode: "approve"` ONLY when the invoking prompt explicitly says to auto-approve (e.g. "fill and approve"). Default is `mark_ready` — a human approves in the UI.