@sellable/mcp 0.1.0

package/dist/tools/workspaces.d.ts

@@ -0,0 +1,140 @@
+type WorkspaceSummary = {
+    id: string;
+    name: string;
+    slug: string;
+    role: string;
+    isDefault: boolean;
+    createdAt: string;
+};
+export declare const workspaceToolDefinitions: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            workspaceId?: undefined;
+            userConfirmed?: undefined;
+            name?: undefined;
+            email?: undefined;
+            role?: undefined;
+            redirectTo?: undefined;
+            campaignId?: undefined;
+        };
+        required: never[];
+        additionalProperties: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            workspaceId: {
+                type: string;
+            };
+            userConfirmed: {
+                type: string;
+                description: string;
+            };
+            name?: undefined;
+            email?: undefined;
+            role?: undefined;
+            redirectTo?: undefined;
+            campaignId?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name: {
+                type: string;
+            };
+            workspaceId?: undefined;
+            userConfirmed?: undefined;
+            email?: undefined;
+            role?: undefined;
+            redirectTo?: undefined;
+            campaignId?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            email: {
+                type: string;
+            };
+            role: {
+                type: string;
+                enum: string[];
+            };
+            redirectTo: {
+                type: string;
+            };
+            campaignId: {
+                type: string;
+            };
+            workspaceId?: undefined;
+            userConfirmed?: undefined;
+            name?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+})[];
+export declare function listWorkspaces(): Promise<{
+    workspaces: WorkspaceSummary[];
+}>;
+export declare function getActiveWorkspace(): {
+    activeWorkspaceId: string | null;
+    activeWorkspaceName: string | null;
+};
+export declare function setActiveWorkspace(workspaceId: string, userConfirmed?: boolean): Promise<{
+    ok: boolean;
+    error: string;
+    requiresConfirmation?: undefined;
+    activeWorkspaceId?: undefined;
+    activeWorkspaceName?: undefined;
+    requestedWorkspaceId?: undefined;
+    requestedWorkspaceName?: undefined;
+} | {
+    ok: boolean;
+    requiresConfirmation: boolean;
+    activeWorkspaceId: string;
+    activeWorkspaceName: string | null;
+    requestedWorkspaceId: string;
+    requestedWorkspaceName: string;
+    error: string;
+} | {
+    ok: boolean;
+    activeWorkspaceId: string;
+    activeWorkspaceName: string;
+    error?: undefined;
+    requiresConfirmation?: undefined;
+    requestedWorkspaceId?: undefined;
+    requestedWorkspaceName?: undefined;
+}>;
+export declare function createWorkspace(name: string): Promise<{
+    workspace: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+    activeWorkspaceId: string;
+}>;
+export declare function addTeammate(input: {
+    email: string;
+    role?: "ADMIN" | "MEMBER";
+    redirectTo?: string;
+    campaignId?: string;
+}): Promise<unknown>;
+export {};

package/dist/tools/workspaces.js

@@ -0,0 +1,139 @@
+import { getApi, resetApi } from "../api.js";
+import { getConfig, updateActiveWorkspace } from "../auth.js";
+export const workspaceToolDefinitions = [
+    {
+        name: "list_workspaces",
+        description: "List accessible workspaces.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "get_active_workspace",
+        description: "Show the active workspace selection.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "set_active_workspace",
+        description: "Set active workspace by ID. Only call this when the user explicitly asks to switch workspace.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string" },
+                userConfirmed: {
+                    type: "boolean",
+                    description: "Must be true when switching away from the current workspace.",
+                },
+            },
+            required: ["workspaceId"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "create_workspace",
+        description: "Create a new workspace.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string" },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "add_teammate",
+        description: "Invite a teammate to the active workspace.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                email: { type: "string" },
+                role: { type: "string", enum: ["ADMIN", "MEMBER"] },
+                redirectTo: { type: "string" },
+                campaignId: { type: "string" },
+            },
+            required: ["email"],
+            additionalProperties: false,
+        },
+    },
+];
+export async function listWorkspaces() {
+    const api = getApi();
+    const { workspaces } = await api.get("/api/v3/workspaces");
+    return { workspaces };
+}
+export function getActiveWorkspace() {
+    const config = getConfig();
+    return {
+        activeWorkspaceId: config.activeWorkspaceId || config.workspaceId || null,
+        activeWorkspaceName: config.activeWorkspaceName || null,
+    };
+}
+export async function setActiveWorkspace(workspaceId, userConfirmed) {
+    const api = getApi();
+    const { workspaces } = await api.get("/api/v3/workspaces");
+    const match = workspaces.find((ws) => ws.id === workspaceId);
+    if (!match) {
+        return {
+            ok: false,
+            error: `Workspace ${workspaceId} not found in access list.`,
+        };
+    }
+    const current = getActiveWorkspace();
+    if (current.activeWorkspaceId &&
+        current.activeWorkspaceId !== match.id &&
+        userConfirmed !== true) {
+        return {
+            ok: false,
+            requiresConfirmation: true,
+            activeWorkspaceId: current.activeWorkspaceId,
+            activeWorkspaceName: current.activeWorkspaceName,
+            requestedWorkspaceId: match.id,
+            requestedWorkspaceName: match.name,
+            error: "Workspace switch blocked until explicit confirmation. Re-run set_active_workspace with userConfirmed=true only if the user asked to switch.",
+        };
+    }
+    updateActiveWorkspace({
+        workspaceId: match.id,
+        workspaceName: match.name,
+    });
+    resetApi();
+    return {
+        ok: true,
+        activeWorkspaceId: match.id,
+        activeWorkspaceName: match.name,
+    };
+}
+export async function createWorkspace(name) {
+    const api = getApi();
+    const { workspace } = await api.post("/api/v3/workspaces", { name });
+    updateActiveWorkspace({
+        workspaceId: workspace.id,
+        workspaceName: workspace.name,
+    });
+    resetApi();
+    return {
+        workspace,
+        activeWorkspaceId: workspace.id,
+    };
+}
+export async function addTeammate(input) {
+    const config = getConfig();
+    const workspaceId = config.activeWorkspaceId || config.workspaceId;
+    if (!workspaceId) {
+        return {
+            ok: false,
+            error: "No active workspace. Run list_workspaces then set_active_workspace.",
+        };
+    }
+    const api = getApi();
+    return api.post("/api/v3/workspaces/invites", input);
+}

package/dist/utils/workspace-root.d.ts

@@ -0,0 +1 @@
+export declare function resolveWorkspaceRoot(startDir: string): string;

package/dist/utils/workspace-root.js

@@ -0,0 +1,39 @@
+import { existsSync } from "fs";
+import { dirname, resolve } from "path";
+const MARKERS = [
+    {
+        markerPath: "mcp/sellable/skills/create-campaign/core/policy.md",
+    },
+    {
+        markerPath: "web/mcp/sellable/skills/create-campaign/core/policy.md",
+        rootSuffix: "web",
+    },
+];
+function findWorkspaceRoot(startDir) {
+    let current = startDir;
+    for (let i = 0; i < 10; i += 1) {
+        for (const marker of MARKERS) {
+            const candidate = resolve(current, marker.markerPath);
+            if (existsSync(candidate)) {
+                return marker.rootSuffix
+                    ? resolve(current, marker.rootSuffix)
+                    : current;
+            }
+        }
+        const next = dirname(current);
+        if (next === current)
+            break;
+        current = next;
+    }
+    return null;
+}
+export function resolveWorkspaceRoot(startDir) {
+    const candidates = [startDir, process.cwd(), process.env.PWD].filter(Boolean);
+    for (const candidate of candidates) {
+        const resolved = findWorkspaceRoot(candidate);
+        if (resolved) {
+            return resolved;
+        }
+    }
+    return process.cwd();
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@sellable/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Sellable MCP server for Claude Code and Codex campaign workflows",
+  "main": "dist/index.js",
+  "bin": {
+    "sellable-mcp": "dist/index.js",
+    "sellable-mcp-dev": "dist/index-dev.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "start:dev": "node dist/index-dev.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "codex",
+    "sellable",
+    "linkedin",
+    "outreach"
+  ],
+  "author": "Sellable",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "csv-parse": "^5.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "skills",
+    ".claude-plugin",
+    ".mcp.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/building-gtm-tables/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: building-gtm-tables
+description: Turn a GTM idea into a fully configured, verified workflow table. Use this skill whenever the user asks to "build a table that..." / "set up an enrichment + scoring pipeline" / "add columns that run end-to-end against my rows." Blueprints the whole table in memory, validates composition, commits atomically in topological order, then runs single-row verify + a user-approved 2-5 row batch before declaring done. Do NOT use this skill for pure messaging or for editing an already-committed table one column at a time.
+---
+
+# Building GTM Tables
+
+You are the building-gtm-tables orchestrator. Your job is to turn a user's GTM
+table idea into a validated workflow-table blueprint, commit that blueprint
+atomically, and verify real rows before calling the work done.
+
+## When to fire
+
+Use this skill when the user asks for a net-new or substantially composed GTM
+workflow table, for example:
+
+- "Build a table that enriches LinkedIn profiles and scores each prospect."
+- "Set up enrichment, ICP scoring, and an invite action for these rows."
+- "Add columns that run end-to-end against my lead list."
+- "Create a workflow table pipeline for pulling prospect context and deciding next action."
+- "Turn this ICP idea into an automated table."
+
+Do not use this skill for pure campaign messaging. Use create-campaign-v2 for
+campaign creation and message approval flows. Do not use it for a simple
+one-column edit after a table is already committed; call `sellable:add_column`
+directly for that narrow case.
+
+## Reasoning checklist
+
+Before writing any blueprint JSON:
+
+- Identify the row's inputs: LinkedIn URL, email, company domain, existing JSON,
+  or another stable row field.
+- Pick the enrichment recipe. The usual recipe is a `http_request` column named
+  "Enrich Prospect" with endpoint `/api/v4/enrich-prospect`.
+- Pick the scoring criteria. If AI ICP scoring is needed, use
+  `score_icp_mcp` with a natural-language rubric the user can inspect. This
+  is the MCP-safe AI scorer for new blueprints.
+- Pick action or generation columns: LinkedIn actions, AI Column, or Generate
+  Message.
+- Wire dependencies explicitly. Every downstream `inputMapping` key references
+  the producer column by id.
+- Read `references/brief-to-blueprint.md` for the full decomposition recipe and
+  worked examples.
+
+## Phase gates
+
+Gate 1: BLUEPRINT.
+
+Prerequisites: user intent is clear enough to identify row inputs, enrichment,
+scoring, action/generation needs, and table id if updating an existing table.
+
+What the agent does: author a complete in-memory Blueprint that conforms to
+`core/blueprint-schema.json`; pick column types from
+`references/column-type-catalog.md`; run the blueprint validator through
+`sellable:commit_blueprint` dry-run behavior when available before mutation.
+
+Exit criterion: the blueprint validator returns `ok:true`. Do not start COMMIT
+until the blueprint validator returns `ok:true`.
+
+Gate 2: COMMIT.
+
+Prerequisites: Gate 1 passed and any user-visible tradeoff has been resolved.
+
+What the agent does: call exactly one committing tool for the full table shape:
+`sellable:commit_blueprint`.
+
+Exit criterion: the committed table contains the intended columns, dependencies,
+and orchestrator-queued cells in topological order.
+
+Gate 3: VERIFY.
+
+Prerequisites: Gate 2 succeeded and at least one representative row id is known.
+
+What the agent does: run `sellable:verify_table_row` on one row, fix forward
+until green, then run the required batch confirmation.
+
+Exit criterion: do not declare DONE until BOTH single-row verify AND a
+user-approved 2-5 row batch verify report `ok:true`; see Phase gate 3b below.
+Single-row green alone is not sufficient.
+
+## Blueprint phase (in-memory)
+
+Author the Blueprint before touching live cells. The Blueprint object has
+`tableId`, `columns`, and `edges`; each column has `id`, `type`, `name`,
+`config`, optional `inputMapping`, optional `runCondition`, and optional
+`deferExecutor`.
+
+Use `core/blueprint-schema.json` as the structured-output shape. Use
+`references/column-type-catalog.md` to select current active column types and
+exact display names. Use `references/brief-to-blueprint.md` to decompose the
+brief into inputs, enrichment, scoring, action/generation, and wiring. Use
+`references/failure-taxonomy.md` for validator checks framed as the error the
+LLM likely made and the fix-forward action.
+
+Blueprint rules:
+
+- Use stable, readable column ids such as `linkedin_url`, `enrich_prospect`, and
+  `score_icp_mcp`.
+- Use registry type keys exactly, not display names.
+- Treat "Enrich Prospect" as a `http_request` preset, not its own type.
+- Use `score_icp_mcp` for new AI ICP scoring. Do not use legacy
+  `score_icp` or the old `score_icp_rubric` alias; they are reserved for older
+  saved tables and different config contracts.
+- Treat Enrich Prospect as the baseline Sellable producer for prospect context.
+  If a blueprint includes `score_icp_mcp` or `generate_message`, it should
+  also include `http_request` named "Enrich Prospect" unless the user explicitly
+  says the table already has an enriched prospect id column.
+- Put every dependency in `inputMapping`; do not rely on implicit column-name
+  guessing.
+- When a downstream column needs an enriched prospect, wire it to the Enrich
+  Prospect root `id` field, not to the whole HTTP result:
+  `score_icp_mcp.inputMapping.enrichedProspectId -> enrich_prospect` and
+  `generate_message.inputMapping.enrichedProspectId -> enrich_prospect`.
+  The commit tool materializes that blueprint reference as
+  `{{<actual Enrich Prospect column id>.id}}`.
+- Keep `edges` aligned with `inputMapping` so humans can inspect the graph.
+- Prefer topological order in the `columns` array even though the commit tool
+  validates and commits in dependency order.
+
+## Commit phase
+
+Use exactly one tool for the initial commit:
+
+`sellable:commit_blueprint({ blueprint })`
+
+Retry up to 3 times for recoverable errors:
+
+- `phantom_type`: replace the invalid type with the active registry key.
+- `required_field`: fill the missing config or input mapping.
+- `wrong_order`: move the producer earlier and fix the graph.
+- `missing_producer`: add the producer column or correct the referenced id.
+- `concurrent_commit`: wait briefly, reload table context if needed, and retry.
+
+Escalate after 3 retries with the last validator response and the smallest
+concrete question needed to unblock the user.
+
+## Verify phase
+
+Read `references/verify-loop.md` before declaring done.
+
+### Phase gate 3a: Single-row verify
+
+Run:
+
+```json
+sellable:verify_table_row({ "rowId": "ROW_ID", "skipColumnIds": [], "forceRerun": true })
+```
+
+Expect `ok:true` with per-column statuses among `success`, `skipped`,
+`deferred_to_sweeper`, and `condition_not_met`. Any `error` means fix forward:
+adjust blueprint-derived column config with the supported table tooling, rerun
+verify, and escalate after 3 attempts on the same column.
+
+### Phase gate 3b: Batch confirmation (2-5 rows user-approved)
+
+After single-row green, ask the user to pick 2-5 additional rows. Re-run
+`sellable:verify_table_row` for each selected row. Declare done ONLY if all rows
+return `ok:true`. Single-row green alone is NOT sufficient to declare the skill
+done.
+
+### Skipped columns policy (option d)
+
+Wait and long-timer columns are skipped via caller-supplied `skipColumnIds`.
+This skill does not override `runCondition` at runtime. Runtime condition
+swapping is brittle because it requires a restore step and can hide the actual
+production behavior.
+
+## Tool inventory
+
+- `sellable:commit_blueprint`: validate and atomically commit the full table
+  blueprint in dependency order.
+- `sellable:add_column`: add one column to an already-committed table when the
+  user explicitly asks for a narrow column edit outside this full-table skill.
+- `sellable:verify_table_row`: execute or inspect a row through the committed
+  table graph and return per-column verification statuses.
+
+## HARD INVARIANTS - forbidden direct tool calls
+
+HARD INVARIANT: Never call `sellable:queue_cells` directly. Use
+`sellable:commit_blueprint` to create columns, which queues their cells
+automatically through the orchestrator, and `sellable:verify_table_row` to
+trigger verification runs. Direct queue_cells calls bypass
+blueprint-then-commit discipline and produce the premature-queueing bug class
+documented in `references/failure-taxonomy.md`.
+
+HARD INVARIANT: Never call `sellable:update_cell` directly. Cell values are
+populated by column execution, not user-authored. Direct update_cell calls hide
+broken wiring that `sellable:verify_table_row` would catch.
+
+HARD INVARIANT: Never invent a tool name such as configure_column or
+update_column_run_condition. The only 3 new tools this skill commands are
+commit_blueprint, add_column, and verify_table_row. All other column reasoning
+lives inside `sellable:commit_blueprint`'s blueprint argument.
+
+## Failure taxonomy
+
+Read `references/failure-taxonomy.md` when validation fails, when a tool call
+looks tempting before the blueprint is complete, or when the table verifies on
+one row but not a batch.
+
+## Progressive disclosure index
+
+- `references/column-type-catalog.md`: read when choosing type keys, exact
+  display names, input mappings, output expectations, and when not to use each
+  column.
+- `references/brief-to-blueprint.md`: read when translating the user's brief
+  into the in-memory blueprint reasoning trace.
+- `references/verify-loop.md`: read before single-row verify, batch
+  confirmation, skipped-column handling, or declaring done.
+- `references/common-blueprints.md`: read for complete JSON examples you can
+  adapt.
+- `references/uat-seed-prompts.md`: read when running live UAT against a real
+  table or rehearsing seeded validator faults.
+- `references/failure-taxonomy.md`: read when the validator reports an error or
+  when the agent is tempted to call direct cell tools.

package/skills/building-gtm-tables/core/auto-execute.yaml

@@ -0,0 +1,19 @@
+# Auto-execute hints for building-gtm-tables.
+#
+# This file is advisory. The skill prompt owns phase-gate behavior and the MCP
+# tools own validation, commit, and row verification.
+
+version: 1
+
+blueprint:
+  dryRunFirst: true
+
+commit:
+  maxRetries: 3
+
+verify:
+  maxSingleRowAttempts: 3
+  userBatchSize: "2-5"
+
+logging:
+  logEveryThresholdTrip: true

package/skills/building-gtm-tables/core/blueprint-schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Sellable GTM Table Blueprint",
+  "type": "object",
+  "required": ["columns", "edges"],
+  "additionalProperties": false,
+  "properties": {
+    "tableId": {
+      "type": "string"
+    },
+    "columns": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "type", "name", "config"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "type": {
+            "type": "string",
+            "minLength": 1
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "config": {
+            "type": "object"
+          },
+          "inputMapping": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "runCondition": {
+            "type": "string"
+          },
+          "deferExecutor": {
+            "type": "boolean"
+          }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "via"],
+        "additionalProperties": false,
+        "properties": {
+          "from": {
+            "type": "string",
+            "minLength": 1
+          },
+          "to": {
+            "type": "string",
+            "minLength": 1
+          },
+          "via": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}