@sellable/mcp 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "sellable",
+  "description": "Craft personalized LinkedIn messages using Sellable campaigns and the REPLY framework. Access your campaigns, research prospects, and generate high-quality outreach messages.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Sellable",
+    "url": "https://sellable.dev"
+  },
+  "homepage": "https://app.sellable.dev",
+  "repository": "https://github.com/sellable/claude-code",
+  "keywords": ["linkedin", "outreach", "sales", "messaging", "campaigns"]
+}

package/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "sellable": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["mcp/sellable/dist/index.js"]
+    }
+  }
+}

package/README.md

@@ -0,0 +1,355 @@
+# Sellable Claude Code Plugin
+
+Craft personalized LinkedIn messages using the REPLY framework directly in Claude Code.
+
+## What It Does
+
+- Load your Sellable campaigns
+- Create campaigns headlessly with a realtime watch link
+- Research prospects (web search and LinkedIn API)
+- Apply the REPLY framework with 11 quality gates
+- Save and approve messages for sending
+
+Each message gets 5+ minutes of Claude attention with deep research - no other tool does this.
+
+## Installation
+
+### Prompt Source Of Truth
+
+There is one public create-campaign entrypoint shared across hosts:
+
+- `sellable:create-campaign`
+
+The public wrapper loads the approval-gated workflow from:
+
+- `mcp/sellable/skills/create-campaign-v2/SKILL.md`
+
+The older `mcp/sellable/skills/create-campaign/SKILL.md` prompt is kept as an
+internal legacy prompt for compatibility only. Do not advertise it as a public
+command.
+
+### 1. One-Command Agent Install
+
+For Claude Code and Codex CLI:
+
+```bash
+npx -y @sellable/install --host all --token skt_live_your_token_here --workspace-id your_workspace_id
+```
+
+Agent-readable install instructions are available at:
+
+```text
+https://app.sellable.dev/agent-install.txt
+```
+
+The reviewable curl installer is:
+
+```bash
+curl -fsSL "https://app.sellable.dev/api/v2/cli/install" -o /tmp/sellable-install.sh
+sh /tmp/sellable-install.sh
+```
+
+Phase 112 v1 uses package stdio MCP through `@sellable/mcp`. Hosted HTTP
+MCP is a future/advanced mode until the hosted endpoint exists.
+
+### 2. Generate API Token
+
+1. Go to https://app.sellable.dev/settings
+2. Click "Generate Token"
+3. Copy the token (starts with `skt_live_`)
+
+### 3. Claude Setup
+
+Install MCP server:
+
+```bash
+claude mcp add --transport stdio sellable -- npx -y @sellable/mcp
+```
+
+Create auth config at `~/.claude/sellable.json`:
+
+```json
+{
+  "token": "skt_live_your_token_here",
+  "activeWorkspaceId": "your_workspace_id"
+}
+```
+
+The token is provided when you generate it. Use `list_workspaces` +
+`set_active_workspace` to choose a workspace if you don't know the ID yet.
+
+### 4. Codex Setup
+
+For customer/package installs, use:
+
+```bash
+npx -y @sellable/install --host codex --token skt_live_your_token_here --workspace-id your_workspace_id
+```
+
+For local repo/Desktop development, run the installer from this repo:
+
+```bash
+npm run sellable:codex:install -- --token skt_live_your_token_here --workspace-id your_workspace_id
+```
+
+The installer does the full local setup:
+
+- builds the Sellable MCP server
+- uses repo-local `web` skills by default, so the Codex picker has one Sellable
+  entry per workflow
+- removes stale Personal Sellable skill copies, including
+  `sellable-create-campaign-v2`
+- writes `~/.codex/sellable.json`
+- registers the `sellable` MCP server with Codex
+- installs the local `sellable@sellable-local` Desktop plugin so Codex
+  Desktop loads the `mcp__sellable__*` tools into skill sessions
+- runs a Codex CLI smoke that must load `get_auth_status` and the
+  `create-campaign-v2` prompt
+
+If you already have `~/.codex/sellable.json`, verify the install without
+rewriting auth:
+
+```bash
+npm run sellable:codex:install -- --verify-only
+```
+
+For published-package installs instead of this local checkout:
+
+```bash
+npm run sellable:codex:install -- --server-mode package --skill-scope personal --token skt_live_your_token_here --workspace-id your_workspace_id
+```
+
+After the installer passes, fully quit and reopen Codex Desktop. Start a new
+thread from the repo and select the `web` `Sellable Create Campaign` entry. If
+the app still says `mcp__sellable__*` tools are missing after the installer
+passes, check that `~/.codex/config.toml` contains both
+`[marketplaces.sellable-local]` and `[plugins."sellable@sellable-local"]`.
+The skill being visible only proves skill discovery; the plugin is what mounts
+the Sellable MCP tools for Codex Desktop.
+
+## Usage
+
+### From Sellable UI
+
+1. Open any campaign
+2. Go to the Launch tab
+3. Click "Open in Claude Code"
+4. Copy the command shown
+
+### From Claude Code
+
+Use the create-campaign skill:
+
+```
+/sellable:create-campaign
+```
+
+Then describe intent naturally, for example:
+
+- "Let's make a campaign with sellable"
+- "Create a campaign for acme.com"
+- "Launch a LinkedIn campaign for this company"
+
+For local UAT-style runs against a company/domain:
+
+```
+npm run campaign:v2:local -- teaatshiloh.com
+```
+
+### From Codex
+
+Use the Codex skill entrypoint:
+
+```
+$sellable:create-campaign
+```
+
+Skill package path in this repo:
+
+- `.agents/skills/sellable-create-campaign/SKILL.md`
+
+## Host Parity Runbook (Codex + Claude)
+
+Use the same MCP runtime preflight in both hosts:
+
+1. `get_auth_status()`
+2. `get_campaign_framework({ flowVersion: "v2", includePlugins: true })`
+3. Optional resume branch with `get_campaign_context({ campaignId, refresh: true })`
+4. Subskill discovery and load via:
+   - `list_subskill_prompts` (catalog)
+   - `search_subskill_prompts` (lookup)
+   - `get_subskill_prompt({ subskillName: "create-campaign-v2" })` (load)
+5. Net-new sender research completion gate before create:
+   - `get_subskill_prompt({ subskillName: "research-sender" })`
+   - run sender research
+   - `complete_sender_research(...)`
+
+Canonical shortcut:
+
+- `bootstrap_create_campaign({ flowVersion: "v2", campaignId? })`
+
+If bootstrap returns blocking errors, fail fast and do not continue into provider
+search/import tools.
+
+Provider preflight contract:
+
+- Call `get_provider_prompt({ provider, campaignOfferId? })` before any provider action.
+- Provider actions (`search_apollo`, `search_sales_nav`, `search_prospeo`,
+  `search_signals`, `import_leads`) are runtime-gated until prompt preload is done.
+
+Parallel execution contract:
+
+- Claude host: use `Task` subagents for parallel research/crafting units.
+- Codex host: use `multi_tool_use.parallel` for independent tool-call batches.
+- If neither backend is available, run sequentially with the same output schema.
+
+Config path resolution (in order):
+
+1. `SELLABLE_CONFIG_PATH`
+2. `$CODEX_HOME/sellable.json`
+3. `~/.codex/sellable.json`
+4. `~/.claude/sellable.json` (compatibility fallback)
+
+## Hetzner Smoke / UAT
+
+For hosted MCP verification, keep the product MCP host separate from the
+`sellable-admin` host:
+
+- product MCP: `sellable-web-mcp`
+- admin MCP: `sellable-ops`
+
+The product MCP runtime reads auth from the normal `sellable.json` path
+resolution above. `SELLABLE_TOKEN` by itself is not the authoritative runtime
+contract for hosted smoke/UAT runs.
+
+Recommended smoke/UAT flow on the VPS:
+
+1. use the shared helper in `scripts/lib/vps-common.sh`
+2. rebuild with `npm run mcp:build`
+3. run the direct stdio MCP client in `scripts/mcp/sellable-tool-call.mjs`
+4. use `scripts/run-sellable-mcp-smoke.sh` for the baseline host proof before
+   feature-specific UAT
+
+For file-path features like CSV upload, create the fixture file on the VPS
+itself and pass the absolute host path to the tool.
+
+## Engage Memory (Learns Over Time)
+
+The `engage` skill persists user-specific, workspace-scoped memory in a separate
+JSON file so it can learn over time without editing repo or package files.
+
+Default path: next to your `sellable.json` (same directory), named:
+
+- `sellable.engage.json`
+
+Override path with:
+
+- `SELLABLE_ENGAGE_MEMORY_PATH`
+
+This file stores the commenting style guide (markdown), proven search keywords
+with outcomes, and tracked people (LinkedIn profiles), all scoped by workspace.
+
+## Config You Can Edit (Source Of Truth)
+
+- Auth + active workspace: your `sellable.json` (via `SELLABLE_CONFIG_PATH`, `$CODEX_HOME/sellable.json`, `~/.codex/sellable.json`, or `~/.claude/sellable.json`)
+- Engage memory (style guide + searches + tracked people): `sellable.engage.json` (or `SELLABLE_ENGAGE_MEMORY_PATH`)
+- Team-editable, project-local configs (recommended to edit in git):
+  - `./.sellable/configs/writing/styleguide.md`
+  - `./.sellable/configs/audience/icp-filters.md`
+  - `./.sellable/configs/proof/claims.md`
+  - `./.sellable/configs/discovery/influencers.md`
+  - `./.sellable/configs/discovery/post-filters.md`
+
+Files under `mcp/sellable/skills/**/core/*` are **package repo files**, not the intended user config surface.
+
+## Skills
+
+### /sellable:create-campaign
+
+Primary public entrypoint for the approval-gated campaign creation flow.
+
+### interview
+
+Self-interview skill to capture voice + ICP + boundaries into `./.sellable/configs/writing/styleguide.md` and persist it into MCP memory for future sessions.
+
+## Available Tools
+
+### Workspace Tools (Free)
+
+- `list_workspaces` - List accessible workspaces
+- `get_active_workspace` - Show active workspace selection
+- `set_active_workspace` - Set active workspace by ID
+- `create_workspace` - Create a new workspace
+- `add_teammate` - Invite a teammate
+
+### Campaign Tools (Free)
+
+- `get_campaigns` - List all campaigns
+- `get_campaign` - Get campaign details
+- `create_campaign` - Create a campaign offer
+- `update_campaign` - Update campaign positioning/brief/workflow
+- `get_campaign_messages_preview` - Preview campaign leads for messaging (supports filters + pagination)
+- `get_table_rows` - Get leads list
+- `get_rows_minimal` - Get minimal lead list (fast)
+- `get_rows` - Get full lead data
+- `update_cell` - Save message/approve
+- `get_message_prompt` - Get REPLY framework
+- `start_campaign` / `pause_campaign` - Control sending
+
+### Lead Tools (Free)
+
+- `search_apollo` - Apollo people search
+- `search_prospeo` - Prospeo people search
+- `search_sales_nav` - Sales Navigator search
+- `search_signals` - Signal discovery search
+- `load_csv_domains` - Preview/confirm a CSV-on-disk company-domain file and return a `domainFilterId`
+- `load_csv_linkedin_leads` - Preview/confirm a CSV-on-disk LinkedIn profile file and create a lead list
+- `import_leads` - Create a lead list and start importing leads
+- `confirm_lead_list` - Import confirmed lead list into campaign table
+
+### Processing Tools (Free)
+
+- `draft_rubrics` - Draft rubric criteria (stored in MCP state)
+- `select_necessary_rubrics` - Keep/mark required rubric checks
+- `save_rubrics` - Persist rubrics and enable ICP filtering
+- `add_rubric_item` - Add a single rubric criterion
+- `update_rubric_item` - Update a rubric criterion by ID
+- `delete_rubric_item` - Delete a rubric criterion by checkName
+- `check_rubric` - Queue enrichment + scoring sample
+- `wait_for_rubric_results` - Poll pass-rate results
+- `upsert_rubric` - Save rubric to campaign (legacy)
+
+### Readiness Tools (Free)
+
+- `wait_for_lead_list_ready` - Wait for lead list import to complete (and rows)
+- `wait_for_campaign_table_ready` - Wait for campaign table rows to appear
+
+### LinkedIn Tools (Cost Credits)
+
+- `fetch_linkedin_posts` - Recent LinkedIn posts
+- `fetch_linkedin_profile` - Full profile data
+- `fetch_company` - Company profile data
+
+## Credits
+
+- Campaign tools are free (you pay Claude tokens)
+- LinkedIn tools cost Sellable credits
+- WebSearch is free (your Claude subscription)
+
+## Troubleshooting
+
+### "Sellable not configured" Error
+
+Create `~/.claude/sellable.json` with your token. Get one at https://app.sellable.dev/settings/integrations.
+
+### Token Not Working
+
+1. Make sure token starts with `skt_`
+2. Check token is not revoked
+3. Verify activeWorkspaceId matches your workspace (or run list_workspaces + set_active_workspace)
+
+## Support
+
+- Issues: https://github.com/csreyes/sellable/issues
+- Docs: https://docs.sellable.dev
+- Email: support@sellable.dev

package/dist/api.d.ts

@@ -0,0 +1,21 @@
+export interface ApiResponse<T> {
+    data: T;
+    error?: string;
+}
+export declare class SellableApiError extends Error {
+    status: number;
+    body: string;
+    isAuthError: boolean;
+    guidance?: string;
+    constructor(status: number, body: string, guidance?: string);
+}
+export declare class SellableApi {
+    private request;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: object): Promise<T>;
+    put<T>(path: string, body?: object): Promise<T>;
+    patch<T>(path: string, body?: object): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+export declare function getApi(): SellableApi;
+export declare function resetApi(): void;

package/dist/api.js

@@ -0,0 +1,73 @@
+import { getConfig, getConfigPath } from "./auth.js";
+export class SellableApiError extends Error {
+    status;
+    body;
+    isAuthError;
+    guidance;
+    constructor(status, body, guidance) {
+        const prefix = status === 401 || status === 403 ? "AUTH_ERROR" : "API_ERROR";
+        super(`${prefix} ${status}: ${body}`);
+        this.status = status;
+        this.body = body;
+        this.isAuthError = status === 401 || status === 403;
+        this.guidance = guidance;
+    }
+}
+export class SellableApi {
+    async request(method, path, body) {
+        // Re-read config on every request so workspace switches take effect immediately
+        const config = getConfig();
+        const url = `${config.apiUrl}${path}`;
+        const workspaceId = config.activeWorkspaceId || config.workspaceId || null;
+        const response = await fetch(url, {
+            method,
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${config.token}`,
+                ...(workspaceId ? { "x-workspaceid": workspaceId } : {}),
+            },
+            ...(body && { body: JSON.stringify(body) }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            const isAuthError = response.status === 401 || response.status === 403;
+            const missingWorkspace = response.status === 400 && errorText.includes("Workspace");
+            const guidance = isAuthError
+                ? "Sellable authentication failed.\n\n" +
+                    `Update ${getConfigPath()} with a valid token from Sellable Settings -> Integrations, then retry.\n\n` +
+                    "NOTE: If the token was just updated via the LLM (editing the config file), " +
+                    "the change should take effect immediately. If it still fails, restart Claude Code to restart the MCP server."
+                : missingWorkspace
+                    ? "No active workspace selected.\n\n" +
+                        "Run list_workspaces then set_active_workspace to choose a workspace."
+                    : undefined;
+            throw new SellableApiError(response.status, errorText, guidance);
+        }
+        return response.json();
+    }
+    async get(path) {
+        return this.request("GET", path);
+    }
+    async post(path, body) {
+        return this.request("POST", path, body);
+    }
+    async put(path, body) {
+        return this.request("PUT", path, body);
+    }
+    async patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    async delete(path) {
+        return this.request("DELETE", path);
+    }
+}
+let apiInstance = null;
+export function getApi() {
+    if (!apiInstance) {
+        apiInstance = new SellableApi();
+    }
+    return apiInstance;
+}
+export function resetApi() {
+    apiInstance = null;
+}

package/dist/auth.d.ts

@@ -0,0 +1,60 @@
+export interface SellableEnvConfig {
+    token: string;
+    activeWorkspaceId?: string;
+    activeWorkspaceName?: string;
+    workspaceId?: string;
+    workspaceName?: string;
+    apiUrl?: string;
+    skillState?: SkillState;
+}
+export interface SellableMultiEnvConfig {
+    activeEnv: string;
+    environments: Record<string, SellableEnvConfig>;
+}
+export type SellableConfig = SellableEnvConfig & {
+    /** Name of the active environment (e.g. "local", "prod"). */
+    activeEnvName?: string;
+};
+export type EngageWorkspaceState = {
+    lastSenderId?: string;
+    lastCommentCampaignTableId?: string;
+    /** Multi-sender: array of sender IDs from last session. */
+    lastSenderIds?: string[];
+    /** Multi-sender: map of senderId → comment campaign tableId. */
+    lastCommentCampaignTableIds?: Record<string, string>;
+    /** Last session mode. */
+    lastMode?: "interactive" | "autonomous";
+    updatedAt?: string;
+};
+export type EngageSkillState = {
+    byWorkspace?: Record<string, EngageWorkspaceState>;
+};
+export type SkillState = {
+    engage?: EngageSkillState;
+};
+/**
+ * Set which config file to use. Call before getConfig().
+ * - "sellable.json" (default) - production
+ * - "sellable-dev.json" - local development
+ */
+export declare function setConfigFile(fileName: string): void;
+export declare function getConfigPath(): string;
+export declare function getConfig(): SellableConfig;
+export declare function updateActiveWorkspace(params: {
+    workspaceId: string;
+    workspaceName?: string | null;
+}): void;
+export declare function getEngageState(): {
+    activeWorkspaceId: string | null;
+    state: EngageWorkspaceState | null;
+};
+export declare function updateEngageState(patch: {
+    lastSenderId?: string;
+    lastCommentCampaignTableId?: string | null;
+    lastSenderIds?: string[];
+    lastCommentCampaignTableIds?: Record<string, string>;
+    lastMode?: "interactive" | "autonomous";
+}): {
+    activeWorkspaceId: string;
+    state: EngageWorkspaceState;
+};