@sellable/mcp 0.1.0

package/dist/tools/prompts.js

@@ -0,0 +1,210 @@
+import { getApi } from "../api.js";
+import { getSkillByName, listSkills, stripFrontmatter } from "../skills.js";
+import { markCreateCampaignPromptLoaded, markResearchPromptLoaded, markSenderResearchCompleted, } from "./flow-preflight.js";
+export const promptToolDefinitions = [
+    {
+        name: "get_message_prompt",
+        description: "Get the REPLY framework prompt for crafting LinkedIn messages. Returns the full prompt with 11 quality gates inline. Load this when actively crafting to ensure quality standards.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: "list_subskill_prompts",
+        description: "List available Sellable subskill prompts with visibility controls. Use this when the host does not expose prompts/list.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Max matches to return (default: 25, max: 100)",
+                },
+                includePublic: {
+                    type: "boolean",
+                    description: "Include public skills in results (default: false). Internal skills are included by default.",
+                },
+                includeInternal: {
+                    type: "boolean",
+                    description: "Include internal skills in results (default: true). Set false to return only public skills.",
+                },
+            },
+            required: [],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_subskill_prompt",
+        description: "Load a Sellable subskill prompt by name. Internal subskills are not listed in prompts/list; use search_subskill_prompts when you are unsure of the exact name.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                subskillName: {
+                    type: "string",
+                    description: "Subskill prompt name (e.g., create-rubric, find-leads)",
+                },
+                offset: {
+                    type: "number",
+                    description: "Optional character offset for chunked prompt reads. Use for very large prompts.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Optional max characters to return for chunked prompt reads. Use a bounded value for very large prompts.",
+                },
+            },
+            required: ["subskillName"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "search_subskill_prompts",
+        description: "Search Sellable subskills by name/description. Use this before get_subskill_prompt if you are unsure which prompt to load.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query (name, task, or keyword)",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max matches to return (default: 5, max: 10)",
+                },
+                includePublic: {
+                    type: "boolean",
+                    description: "Include public skills in results (default: false). Internal skills are included by default.",
+                },
+                includeInternal: {
+                    type: "boolean",
+                    description: "Include internal skills in results (default: true). Set false to search only public skills.",
+                },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "complete_sender_research",
+        description: "Mark sender research as completed for create-campaign preflight. Call this after research-sender synthesis and before create_campaign.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                depth: {
+                    type: "string",
+                    enum: ["minimal-verification", "deep-proof"],
+                    description: "Research depth used: minimal verification or deeper proof-focused pass.",
+                },
+                proofItemsFound: {
+                    type: "number",
+                    description: "Count of concrete proof items found (named customers, quantified outcomes, etc.).",
+                },
+                caseStudyItemsFound: {
+                    type: "number",
+                    description: "Count of usable case study items found for messaging/brief context.",
+                },
+                credibilitySignalsFound: {
+                    type: "number",
+                    description: "Count of credibility signals found (reviews, ratings, hiring/funding/press, etc.).",
+                },
+                notes: {
+                    type: "string",
+                    description: "Optional one-line summary of what was verified or still missing.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+];
+export async function getMessagePrompt() {
+    const api = getApi();
+    return api.get("/api/v3/prompts/edit-message");
+}
+function filterSubskills(includePublic = false, includeInternal = true) {
+    return listSkills().filter((skill) => {
+        if (skill.visibility === "public")
+            return includePublic;
+        if (skill.visibility === "internal")
+            return includeInternal;
+        return false;
+    });
+}
+export function listSubskillPrompts(limit, includePublic, includeInternal) {
+    const safeLimit = Math.min(Math.max(limit ?? 25, 1), 100);
+    const filtered = filterSubskills(includePublic, includeInternal).sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        total: filtered.length,
+        matches: filtered.slice(0, safeLimit).map((skill) => ({
+            name: skill.name,
+            description: skill.description,
+            visibility: skill.visibility,
+        })),
+    };
+}
+export function getSubskillPrompt(subskillName, offset, limit) {
+    const skill = getSkillByName(subskillName);
+    if (!skill) {
+        throw new Error(`Unknown subskill prompt: ${subskillName}`);
+    }
+    if (subskillName === "create-campaign") {
+        markCreateCampaignPromptLoaded();
+    }
+    if (subskillName === "research") {
+        markResearchPromptLoaded("generic", "research");
+    }
+    if (subskillName === "research-sender") {
+        markResearchPromptLoaded("sender", "research-sender");
+    }
+    if (subskillName === "research-prospect") {
+        markResearchPromptLoaded("prospect", "research-prospect");
+    }
+    const fullPrompt = stripFrontmatter(skill.content);
+    const safeOffset = Math.min(Math.max(Number.isFinite(offset) ? Math.floor(offset ?? 0) : 0, 0), fullPrompt.length);
+    const safeLimit = Number.isFinite(limit) && limit !== undefined
+        ? Math.max(Math.floor(limit), 1)
+        : null;
+    const prompt = safeLimit === null
+        ? fullPrompt
+        : fullPrompt.slice(safeOffset, safeOffset + safeLimit);
+    const nextOffset = safeLimit === null
+        ? null
+        : Math.min(safeOffset + safeLimit, fullPrompt.length);
+    return {
+        name: skill.name,
+        description: skill.description,
+        visibility: skill.visibility,
+        prompt,
+        promptLength: fullPrompt.length,
+        offset: safeOffset,
+        limit: safeLimit ?? undefined,
+        hasMore: nextOffset !== null && nextOffset < fullPrompt.length,
+        nextOffset: nextOffset !== null && nextOffset < fullPrompt.length ? nextOffset : null,
+    };
+}
+export function completeSenderResearch(input) {
+    return markSenderResearchCompleted(input);
+}
+export function searchSubskillPrompts(query, limit, includePublic, includeInternal) {
+    const safeLimit = Math.min(Math.max(limit ?? 5, 1), 10);
+    const queryLower = query.trim().toLowerCase();
+    const matches = filterSubskills(includePublic, includeInternal)
+        .filter((skill) => {
+        const name = skill.name.toLowerCase();
+        const description = skill.description.toLowerCase();
+        return name.includes(queryLower) || description.includes(queryLower);
+    })
+        .sort((a, b) => {
+        const aName = a.name.toLowerCase().includes(queryLower) ? 0 : 1;
+        const bName = b.name.toLowerCase().includes(queryLower) ? 0 : 1;
+        if (aName !== bName)
+            return aName - bName;
+        return a.name.localeCompare(b.name);
+    })
+        .slice(0, safeLimit)
+        .map((skill) => ({
+        name: skill.name,
+        description: skill.description,
+        visibility: skill.visibility,
+    }));
+    return { query, matches };
+}

package/dist/tools/provider-preflight.d.ts

@@ -0,0 +1,21 @@
+export type ProviderId = "apollo" | "sales-nav" | "prospeo" | "signal-discovery";
+export declare function markProviderPromptLoaded(params: {
+    provider: ProviderId;
+    campaignOfferId?: string | null;
+}): {
+    readonly scope: "campaign" | "provider";
+    readonly provider: ProviderId;
+    readonly campaignOfferId: string | null;
+    readonly loadedAt: string;
+};
+export declare function assertProviderPromptLoaded(params: {
+    provider: ProviderId;
+    campaignOfferId?: string | null;
+}): {
+    readonly ok: true;
+    readonly provider: ProviderId;
+    readonly campaignOfferId: string | null;
+    readonly loadedAt: string;
+    readonly scope: "campaign" | "provider";
+};
+export declare function resetProviderPromptPreflightState(): void;

package/dist/tools/provider-preflight.js

@@ -0,0 +1,59 @@
+const providerPromptLoadedState = new Map();
+function scopedKey(provider, campaignOfferId) {
+    return `${campaignOfferId ?? "*"}::${provider}`;
+}
+function resolveLoadedState(provider, campaignOfferId) {
+    if (campaignOfferId) {
+        const campaignScoped = providerPromptLoadedState.get(scopedKey(provider, campaignOfferId));
+        if (campaignScoped)
+            return campaignScoped;
+    }
+    const providerScoped = providerPromptLoadedState.get(scopedKey(provider));
+    return providerScoped ?? null;
+}
+export function markProviderPromptLoaded(params) {
+    const entry = {
+        provider: params.provider,
+        campaignOfferId: params.campaignOfferId ?? null,
+        loadedAt: new Date().toISOString(),
+    };
+    providerPromptLoadedState.set(scopedKey(params.provider, params.campaignOfferId), entry);
+    return {
+        ...entry,
+        scope: entry.campaignOfferId ? "campaign" : "provider",
+    };
+}
+export function assertProviderPromptLoaded(params) {
+    const loadedState = resolveLoadedState(params.provider, params.campaignOfferId);
+    if (loadedState) {
+        return {
+            ok: true,
+            provider: params.provider,
+            campaignOfferId: params.campaignOfferId ?? null,
+            loadedAt: loadedState.loadedAt,
+            scope: loadedState.campaignOfferId ? "campaign" : "provider",
+        };
+    }
+    const scopeText = params.campaignOfferId
+        ? `campaign ${params.campaignOfferId}`
+        : "this run";
+    const blockingMessage = `Provider prompt preflight missing for ${params.provider} (${scopeText}).`;
+    const diagnostics = {
+        provider: params.provider,
+        campaignOfferId: params.campaignOfferId ?? null,
+        safeToProceed: false,
+        blockingErrors: [
+            `${blockingMessage} Call get_provider_prompt({ provider: "${params.provider}"${params.campaignOfferId
+                ? `, campaignOfferId: "${params.campaignOfferId}"`
+                : ""} }) before search/import.`,
+        ],
+        nextStep: `Call get_provider_prompt for ${params.provider}, then retry the provider tool.`,
+    };
+    const error = new Error(`${diagnostics.blockingErrors[0]} Next step: ${diagnostics.nextStep}`);
+    error.diagnostics =
+        diagnostics;
+    throw error;
+}
+export function resetProviderPromptPreflightState() {
+    providerPromptLoadedState.clear();
+}

package/dist/tools/readiness.d.ts

@@ -0,0 +1,261 @@
+type WaitForCampaignTableReadyInput = {
+    campaignId: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+    requireRows?: boolean;
+};
+type WaitForLeadListReadyInput = {
+    leadListId?: string;
+    campaignOfferId?: string;
+    provider?: "apollo" | "sales-nav" | "prospeo" | "signal-discovery" | "csv-linkedin";
+    jobId?: string;
+    targetLeadCount?: number;
+    timeoutMs?: number;
+    intervalMs?: number;
+    requireRows?: boolean;
+    requireComplete?: boolean;
+};
+export declare function resolveWaitTimeout(timeoutMs?: number): {
+    requestedTimeoutMs: number;
+    effectiveTimeoutMs: number;
+    guardApplied: boolean;
+};
+export declare const readinessToolDefinitions: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            campaignId: {
+                type: string;
+                description: string;
+            };
+            timeoutMs: {
+                type: string;
+                description: string;
+            };
+            intervalMs: {
+                type: string;
+                description: string;
+            };
+            requireRows: {
+                type: string;
+                description: string;
+            };
+            leadListId?: undefined;
+            campaignOfferId?: undefined;
+            provider?: undefined;
+            jobId?: undefined;
+            targetLeadCount?: undefined;
+            requireComplete?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            leadListId: {
+                type: string;
+                description: string;
+            };
+            campaignOfferId: {
+                type: string;
+                description: string;
+            };
+            provider: {
+                type: string;
+                description: string;
+            };
+            jobId: {
+                type: string;
+                description: string;
+            };
+            targetLeadCount: {
+                type: string;
+                description: string;
+            };
+            timeoutMs: {
+                type: string;
+                description: string;
+            };
+            intervalMs: {
+                type: string;
+                description: string;
+            };
+            requireRows: {
+                type: string;
+                description: string;
+            };
+            requireComplete: {
+                type: string;
+                description: string;
+            };
+            campaignId?: undefined;
+        };
+        required: never[];
+        additionalProperties: boolean;
+    };
+})[];
+export declare function waitForCampaignTableReady(input: WaitForCampaignTableReadyInput): Promise<{
+    ready: boolean;
+    reason: string;
+    attempts: number;
+    elapsedMs: number;
+    navigation: {
+        campaignId: string;
+        computedStep: "campaign-created" | "pick-provider" | "provider-search" | "confirm-lead-list";
+        blockedAt: ("campaign-created" | "pick-provider" | "provider-search" | "confirm-lead-list") | null;
+        missing: string[];
+        expectedHeadlessStep: string | null;
+        headlessCurrentStep: string | null;
+        uiStep: string | null;
+        table: {
+            workflowTableId: string | null;
+            checked: boolean;
+            rowCount: number | null;
+            hasRows: boolean | null;
+        };
+        context: {
+            leadSourceType: string | null;
+            leadSourceProvider: string | null;
+            selectedLeadListId: string | null;
+            providerCurrentStep: string | null;
+        };
+        warnings: string[];
+    };
+    warning?: undefined;
+} | {
+    ready: boolean;
+    attempts: number;
+    elapsedMs: number;
+    navigation: {
+        campaignId: string;
+        computedStep: "campaign-created" | "pick-provider" | "provider-search" | "confirm-lead-list";
+        blockedAt: ("campaign-created" | "pick-provider" | "provider-search" | "confirm-lead-list") | null;
+        missing: string[];
+        expectedHeadlessStep: string | null;
+        headlessCurrentStep: string | null;
+        uiStep: string | null;
+        table: {
+            workflowTableId: string | null;
+            checked: boolean;
+            rowCount: number | null;
+            hasRows: boolean | null;
+        };
+        context: {
+            leadSourceType: string | null;
+            leadSourceProvider: string | null;
+            selectedLeadListId: string | null;
+            providerCurrentStep: string | null;
+        };
+        warnings: string[];
+    };
+    reason?: undefined;
+    warning?: undefined;
+} | {
+    ready: boolean;
+    reason: string;
+    attempts: number;
+    elapsedMs: number;
+    navigation: {
+        campaignId: string;
+        computedStep: "campaign-created" | "pick-provider" | "provider-search" | "confirm-lead-list";
+        blockedAt: ("campaign-created" | "pick-provider" | "provider-search" | "confirm-lead-list") | null;
+        missing: string[];
+        expectedHeadlessStep: string | null;
+        headlessCurrentStep: string | null;
+        uiStep: string | null;
+        table: {
+            workflowTableId: string | null;
+            checked: boolean;
+            rowCount: number | null;
+            hasRows: boolean | null;
+        };
+        context: {
+            leadSourceType: string | null;
+            leadSourceProvider: string | null;
+            selectedLeadListId: string | null;
+            providerCurrentStep: string | null;
+        };
+        warnings: string[];
+    } | null;
+    warning: string | undefined;
+}>;
+export declare function waitForLeadListReady(input: WaitForLeadListReadyInput): Promise<{
+    ready: boolean;
+    reason: string;
+    attempts: number;
+    elapsedMs: number;
+    leadListId: null;
+    provider?: undefined;
+    rowCount?: undefined;
+    status?: undefined;
+    targetLeadCount?: undefined;
+    error?: undefined;
+    warning?: undefined;
+} | {
+    ready: boolean;
+    reason: string;
+    leadListId: string;
+    provider: "signal-discovery" | "apollo" | "sales-nav" | "prospeo" | "csv-linkedin" | null;
+    attempts: number;
+    elapsedMs: number;
+    rowCount: number;
+    status: string;
+    targetLeadCount: number | undefined;
+    error?: undefined;
+    warning?: undefined;
+} | {
+    ready: boolean;
+    reason: string;
+    leadListId: string;
+    provider: "signal-discovery" | "apollo" | "sales-nav" | "prospeo" | "csv-linkedin" | null;
+    attempts: number;
+    elapsedMs: number;
+    rowCount: number;
+    status: string | null;
+    targetLeadCount: number | undefined;
+    error: string;
+    warning?: undefined;
+} | {
+    ready: boolean;
+    reason: string;
+    leadListId: string;
+    provider: "signal-discovery" | "apollo" | "sales-nav" | "prospeo" | "csv-linkedin" | null;
+    attempts: number;
+    elapsedMs: number;
+    rowCount: number;
+    status: string;
+    targetLeadCount: number | undefined;
+    error: string | null;
+    warning?: undefined;
+} | {
+    ready: boolean;
+    leadListId: string;
+    provider: "signal-discovery" | "apollo" | "sales-nav" | "prospeo" | "csv-linkedin" | null;
+    attempts: number;
+    elapsedMs: number;
+    rowCount: number;
+    status: string | null;
+    targetLeadCount: number | null;
+    reason?: undefined;
+    error?: undefined;
+    warning?: undefined;
+} | {
+    ready: boolean;
+    reason: string;
+    leadListId: string;
+    provider: "signal-discovery" | "apollo" | "sales-nav" | "prospeo" | "csv-linkedin" | null;
+    attempts: number;
+    elapsedMs: number;
+    rowCount: number | null;
+    status: string | undefined;
+    targetLeadCount: number | undefined;
+    warning: string | undefined;
+    error: string | undefined;
+}>;
+export {};