@seldonframe/mcp 1.55.0 → 1.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seldonframe/mcp",
-  "version": "1.55.0",
+  "version": "1.57.0",
   "mcpName": "io.github.seldonframe/seldonframe-mcp",
   "description": "Open-source GoHighLevel alternative for agencies. 146+ MCP tools that let Claude Code spin up white-labeled client workspaces — CRM, booking, intake forms, landing pages, AI chatbot, and pre-wired agent archetypes (speed-to-lead, missed-call-text-back, review-requester) — in minutes. AGPL-3.0.",
   "license": "AGPL-3.0-or-later",

package/src/finalize-summary.js

@@ -1,108 +1,157 @@
-// v1.55.0 — Standalone builder for the finalize_workspace operator summary.
-// Extracted from tools.js so we can unit-test the string-building logic
-// in isolation (no MCP server boot, no HTTP shims, no snapshot fetcher).
-//
-// The handler in tools.js fetches the snapshot, computes duration, and
-// passes the result here. This file just builds the string.
-
-/**
- * @param {object} args
- * @param {object} args.snapshot — workspace snapshot from
- *   /api/v1/workspace/<id>/snapshot. Must include: workspace.name,
- *   public_urls.{home,book,intake}, chatbot (or null), ops_stack,
- *   available_automations, tier.
- * @param {number} args.durationSec — total workspace creation time.
- * @param {string|null} args.aestheticArchetype — workspace's classified
- *   archetype (from snapshot.theme.aestheticArchetype). Used in the
- *   closing landing-page nudge.
- * @returns {string} the formatted operator summary
- */
-export function buildFinalizeSummary({ snapshot, durationSec, aestheticArchetype }) {
-  const ws = snapshot.workspace ?? {};
-  const businessName = ws.name ?? "Your workspace";
-  const chatbot = snapshot.chatbot ?? null;
-  const opsStack = snapshot.ops_stack ?? {};
-  const automations = snapshot.available_automations ?? [];
-  const tier = snapshot.tier ?? {};
-  const tierLabel = tier.current_tier_label ?? "Free";
-  const isPaid = tier.current_tier === "growth" || tier.current_tier === "scale";
-
-  // Extract client domain from the operator's input (the URL they scraped).
-  // We store it on workspace.settings.source_url upstream; fall back to
-  // the public preview URL host if unavailable.
-  const clientDomain =
-    (ws.settings && typeof ws.settings.source_url === "string"
-      ? new URL(ws.settings.source_url).host
-      : null) ?? "your client's site";
-
-  const lines = [];
-
-  // Header
-  lines.push(`✅ Client ops stack ready for ${businessName}. (${durationSec} seconds)`);
-  lines.push("");
-
-  // Chatbot embed snippet (the magic moment — paste on client's existing site)
-  if (chatbot && chatbot.embed_snippet) {
-    lines.push(`📞 AI receptionist — paste before </body> on ${clientDomain} to go live:`);
-    lines.push(chatbot.embed_snippet);
-    lines.push("");
-    lines.push(`🤖 Demo for your client: ${chatbot.preview_url ?? snapshot.public_urls?.home ?? ""}`);
-    lines.push(`   (Chatbot live in TEST mode — share so your client can try it before pasting)`);
-  } else {
-    lines.push(`🤖 AI chatbot — scaffold pending. Retry:`);
-    lines.push(`   create_agent({ archetype: "website-chatbot", channel: "web_chat" })`);
-  }
-  lines.push("");
-
-  // Ops stack URLs
-  lines.push(`📅 Booking: ${opsStack.booking_url ?? snapshot.public_urls?.book ?? ""}`);
-  lines.push(`📝 Intake:  ${opsStack.intake_url ?? snapshot.public_urls?.intake ?? ""}`);
-  lines.push(`🔧 Admin:   ${opsStack.admin_url ?? ""}`);
-  lines.push("");
-
-  // 7-automation callout
-  if (automations.length > 0) {
-    lines.push(`⚡ ${automations.length} more automations ready to deploy for this client:`);
-    const descriptions = {
-      "speed-to-lead": "text the lead within 30 sec of intake submission",
-      "missed-call-text-back": "auto-SMS when their phone goes unanswered",
-      "review-requester": "ask for a 5★ after every completed booking",
-      "appointment-confirm-sms": "reduce no-shows automatically",
-      "weather-aware-booking": "reschedule outdoor jobs when rain is forecast",
-      "daily-digest": "morning summary of yesterday's activity",
-      "win-back": "re-engage cancelled subscribers with a time-limited code",
-    };
-    for (const a of automations) {
-      const desc = descriptions[a.id] ?? "";
-      lines.push(`   • ${a.name}${desc ? " — " + desc : ""}`);
-    }
-    lines.push(`   Activate any: ${opsStack.automations_url ?? ""}`);
-    lines.push(
-      `   (Need API keys for SMS/email? Just ask — Claude will walk you through`,
-    );
-    lines.push(`    Twilio / Resend / Stripe setup when an automation needs one.)`);
-    lines.push("");
-  }
-
-  // Tier + client portal
-  const tierUpsell = isPaid
-    ? "white-label + reseller pricing on Scale ($99/mo)"
-    : "Upgrade $9/mo for unlimited workspaces";
-  const clientPortalUrl = tier.client_portal_url ?? "";
-  lines.push(
-    `💼 Tier: ${tierLabel}  ·  ${tierUpsell}` +
-      (clientPortalUrl ? `  ·  Client portal: ${clientPortalUrl}` : ""),
-  );
-  lines.push("");
-
-  // Landing-page nudge (closing)
-  const archetypeClause = aestheticArchetype ? ` in ${aestheticArchetype} style` : "";
-  lines.push(
-    `Want a landing page too? Just ask: "build a landing page for ${businessName}${archetypeClause}"`,
-  );
-  lines.push(
-    `— Claude will use the landing-page-creation skill to generate one${aestheticArchetype ? " with the archetype voice" : ""}.`,
-  );
-
-  return lines.join("\n");
-}
+// v1.55.0 — Standalone builder for the finalize_workspace operator summary.
+// Extracted from tools.js so we can unit-test the string-building logic
+// in isolation (no MCP server boot, no HTTP shims, no snapshot fetcher).
+//
+// The handler in tools.js fetches the snapshot, computes duration, and
+// passes the result here. This file just builds the string.
+
+/**
+ * @param {object} args
+ * @param {object} args.snapshot — workspace snapshot from
+ *   /api/v1/workspace/<id>/snapshot. Must include: workspace.name,
+ *   public_urls.{home,book,intake}, chatbot (or null), ops_stack,
+ *   available_automations, tier.
+ * @param {number} args.durationSec — total workspace creation time.
+ * @param {string|null} args.aestheticArchetype — workspace's classified
+ *   archetype (from snapshot.theme.aestheticArchetype). Used in the
+ *   closing landing-page nudge.
+ * @returns {string} the formatted operator summary
+ */
+export function buildFinalizeSummary({ snapshot, durationSec, aestheticArchetype }) {
+  const ws = snapshot.workspace ?? {};
+  const businessName = ws.name ?? "Your workspace";
+  const chatbot = snapshot.chatbot ?? null;
+  const opsStack = snapshot.ops_stack ?? {};
+  const automations = snapshot.available_automations ?? [];
+  const tier = snapshot.tier ?? {};
+  const tierLabel = tier.current_tier_label ?? "Free";
+  const isPaid = tier.current_tier === "growth" || tier.current_tier === "scale";
+
+  // Extract client domain from the operator's input (the URL they scraped).
+  // We store it on workspace.settings.source_url upstream; fall back to
+  // the public preview URL host if unavailable.
+  const clientDomain =
+    (ws.settings && typeof ws.settings.source_url === "string"
+      ? new URL(ws.settings.source_url).host
+      : null) ?? "your client's site";
+
+  const lines = [];
+
+  // Header
+  lines.push(`✅ Client ops stack ready for ${businessName}. (${durationSec} seconds)`);
+  lines.push("");
+
+  // Chatbot embed snippet (the magic moment — paste on client's existing site)
+  if (chatbot && chatbot.embed_snippet) {
+    lines.push(`📞 AI receptionist — paste before </body> on ${clientDomain} to go live:`);
+    lines.push(chatbot.embed_snippet);
+    lines.push("");
+    lines.push(`🤖 Demo for your client: ${chatbot.preview_url ?? snapshot.public_urls?.home ?? ""}`);
+    lines.push(`   (Chatbot is live and answering on your landing — share so your client can try it before pasting)`);
+  } else {
+    lines.push(`🤖 AI chatbot — scaffold pending. Retry:`);
+    lines.push(`   create_agent({ archetype: "website-chatbot", channel: "web_chat" })`);
+  }
+  lines.push("");
+
+  // Ops stack URLs
+  lines.push(`📅 Booking: ${opsStack.booking_url ?? snapshot.public_urls?.book ?? ""}`);
+  lines.push(`📝 Intake:  ${opsStack.intake_url ?? snapshot.public_urls?.intake ?? ""}`);
+  lines.push(`🔧 Admin:   ${opsStack.admin_url ?? ""}`);
+  lines.push("");
+
+  // 7-automation callout
+  if (automations.length > 0) {
+    lines.push(`⚡ ${automations.length} more automations ready to deploy for this client:`);
+    const descriptions = {
+      "speed-to-lead": "text the lead within 30 sec of intake submission",
+      "missed-call-text-back": "auto-SMS when their phone goes unanswered",
+      "review-requester": "ask for a 5★ after every completed booking",
+      "appointment-confirm-sms": "reduce no-shows automatically",
+      "weather-aware-booking": "reschedule outdoor jobs when rain is forecast",
+      "daily-digest": "morning summary of yesterday's activity",
+      "win-back": "re-engage cancelled subscribers with a time-limited code",
+    };
+    for (const a of automations) {
+      const desc = descriptions[a.id] ?? "";
+      lines.push(`   • ${a.name}${desc ? " — " + desc : ""}`);
+    }
+    lines.push(`   Activate any: ${opsStack.automations_url ?? ""}`);
+    lines.push(
+      `   (Need API keys for SMS/email? Just ask — Claude will walk you through`,
+    );
+    lines.push(`    Twilio / Resend / Stripe setup when an automation needs one.)`);
+    lines.push("");
+  }
+
+  // Tier + client portal
+  const tierUpsell = isPaid
+    ? "white-label + reseller pricing on Scale ($99/mo)"
+    : "Upgrade $9/mo for unlimited workspaces";
+  const clientPortalUrl = tier.client_portal_url ?? "";
+  lines.push(
+    `💼 Tier: ${tierLabel}  ·  ${tierUpsell}` +
+      (clientPortalUrl ? `  ·  Client portal: ${clientPortalUrl}` : ""),
+  );
+  lines.push("");
+
+  // v1.55.x — derive appHost for the LLM-settings + client-portal links.
+  // SELDONFRAME_APP_BASE wins when set (white-label/staging); falls back
+  // to https://app.seldonframe.com. Trailing slash stripped to match the
+  // pattern used by v2/complete when building ops_stack.automations_url.
+  const appHost = (
+    process.env.SELDONFRAME_APP_BASE ?? "https://app.seldonframe.com"
+  ).replace(/\/$/, "");
+
+  // LLM key clarity — operators kept asking "which key is the chatbot
+  // using?" + had no recovery path when llm_credit_exhausted fired.
+  lines.push(
+    `🔑 Chatbot LLM key: uses your Claude Code key by default. Change at ${appHost}/settings/integrations/llm.`,
+  );
+  lines.push(
+    `   (If you see "llm_credit_exhausted", top up at console.anthropic.com/settings/billing.)`,
+  );
+  lines.push("");
+
+  // v1.55.x — Client portal demo callout. Closes the demo loop:
+  // chatbot (above) → booking → CRM → portal demo for the client.
+  // Slug is required; skip gracefully if absent (shouldn't happen in
+  // practice but the snapshot can theoretically lack it).
+  //
+  // The /demo URL is a one-click deep link: workspace creation seeds
+  // a "Demo Customer" contact + sample upcoming appointment + welcome
+  // message, and visiting /customer/<slug>/demo auto-establishes a
+  // portal session for that contact — no email, no magic link. The
+  // operator can paste this URL to a prospect and they land directly
+  // in a populated portal instead of a magic-link form with empty
+  // tabs. Demo data is filtered out of operator-facing CRM / pipeline
+  // / analytics by tag, so it stays isolated from real customer data.
+  const slug = ws.slug ?? "";
+  if (slug) {
+    const portalUrl = `${appHost}/customer/${slug}/demo`;
+    lines.push(`🎬 Demo the client portal (one-click, no login):`);
+    lines.push(`   ${portalUrl}`);
+    lines.push(
+      `   Share this link with the prospect — opens directly as "Demo Customer" with a`,
+    );
+    lines.push(
+      `   sample appointment and welcome message. Demo data stays isolated from your`,
+    );
+    lines.push(`   real CRM and pipelines.`);
+    lines.push(
+      `   Free tier shows the portal with SeldonFrame branding. Growth ($29/mo) unlocks custom domain + the agency's logo.`,
+    );
+    lines.push("");
+  }
+
+  // Landing-page nudge (closing)
+  const archetypeClause = aestheticArchetype ? ` in ${aestheticArchetype} style` : "";
+  lines.push(
+    `Want a landing page too? Just ask: "build a landing page for ${businessName}${archetypeClause}"`,
+  );
+  lines.push(
+    `— Claude will use the landing-page-creation skill to generate one${aestheticArchetype ? " with the archetype voice" : ""}.`,
+  );
+
+  return lines.join("\n");
+}

package/src/tools.js

@@ -4777,6 +4777,78 @@ export const TOOLS = [
     },
   },
 
+  // ───────────────────────────────────────────────────────────────────────
+  // v1.57.0 — DEPLOY-TO-SELL. The self-serve deployment verb: take a
+  // builder-owned template (or a purchased marketplace listing) and turn
+  // it into a REAL, answering agent — one call, idempotent, resumable
+  // across the human-only connect steps (calendar OAuth / phone number).
+  // This is the money moment: a builder goes from "I built an agent" to
+  // "I'm earning from it" without leaving the IDE except for the one-time
+  // OAuth/Twilio connect screen the wizardUrl points at.
+  // ───────────────────────────────────────────────────────────────────────
+
+  {
+    name: "deploy_agent",
+    description:
+      "USE WHEN USER SAYS: 'deploy this agent', 'go live with my template', 'sell this agent — get it answering', 'launch the receptionist I built', 'turn my template into a real number', 'ship this to a client'. " +
+      "Deploys a self-built template (source.template_id) or an installed marketplace listing (source.listing_slug) into a REAL, answering agent for THIS workspace — the deploy-to-sell / earn moment, not just a build step. Idempotent: calling it again for the same source resumes the same deployment instead of creating a duplicate. " +
+      "RESUMABLE TWO-STEP FLOW — read the `status` field: " +
+      "• status='needs_connect' → NOT live yet. `requirements`/`missing` list what's unmet (calendar OAuth, another connector, a phone number, business info) and `wizardUrl` is a ONE-TIME human-only link (calendar OAuth + Twilio number can't be done by an agent). Relay it verbatim: 'Open this once to connect your calendar / phone number: <wizardUrl>' — then, once the human confirms they've done it, call deploy_agent again with the SAME source (and `phone` if the agent needs a number) to proceed. " +
+      "• status='live' → deployed and answering right now. Tell the operator the number (if any) is live and taking real calls/bookings — this is revenue-generating, not a sandbox. " +
+      "• status='disabled' → the deploy verb isn't enabled for this environment yet. " +
+      "PHONE: only required when the template needs a number and none is attached yet — pass phone={mode:'forward', number:'+1...'} to forward an existing line, or phone={mode:'provision', area_code:'512'} to buy a new Twilio number (requires the workspace's own Twilio creds — surfaced as a `telephony` requirement if missing). " +
+      "Exactly one of source.template_id / source.listing_slug is required — template_id for something you built with create_agent-style tools in THIS workspace, listing_slug for a marketplace agent you're installing to run for a client.",
+    inputSchema: obj(
+      {
+        workspace_id: str("Workspace id (bearer workspace)."),
+        source: {
+          type: "object",
+          description:
+            "Exactly one of template_id (a template this workspace built) or listing_slug (a published marketplace listing to install-and-deploy).",
+          properties: {
+            template_id: str("Id of an agent_templates row owned by this workspace."),
+            listing_slug: str("Slug of a published marketplace listing (kind='agent') to clone in and deploy."),
+          },
+        },
+        phone: {
+          type: "object",
+          description:
+            "Only needed when deploy_agent (or an earlier call) reported a 'telephony' requirement and no number is attached yet. Pass ONE mode.",
+          properties: {
+            mode: {
+              type: "string",
+              enum: ["forward", "provision"],
+              description: "'forward' = point an existing number at the agent; 'provision' = buy a new Twilio number.",
+            },
+            number: str("E.164 phone number to forward, e.g. '+15125550148'. Required when mode='forward'."),
+            area_code: str("3-digit US/NANP area code to provision a new number in, e.g. '512'. Required when mode='provision'."),
+          },
+        },
+      },
+      ["workspace_id", "source"],
+    ),
+    handler: async (args) => {
+      const ws = args.workspace_id;
+      const source = args.source ?? {};
+      const body = {
+        source: {
+          ...(source.template_id ? { templateId: source.template_id } : {}),
+          ...(source.listing_slug ? { listingSlug: source.listing_slug } : {}),
+        },
+      };
+      if (args.phone?.mode === "forward") {
+        body.phone = { mode: "forward", number: args.phone.number };
+      } else if (args.phone?.mode === "provision") {
+        body.phone = { mode: "provision", areaCode: args.phone.area_code };
+      }
+      const result = await api("POST", "/build/deploy", {
+        body,
+        workspace_id: ws,
+      });
+      return result;
+    },
+  },
+
   {
     name: "update_agent_blueprint",
     description:
@@ -5639,6 +5711,109 @@ export const TOOLS = [
       });
     },
   },
+
+  // Phase T — natural-language R1 landing-page editor.
+  //
+  // Wraps POST /api/v1/landing/r1/customize. Same handler as the in-app
+  // editor at /clients/<slug>/landing/edit. Auth flows through the workspace
+  // bearer stored in ~/.seldonframe/device.json.
+  //
+  // IMPORTANT: The target workspace MUST already have an R1 landing page
+  // (generated by create_full_workspace or create_workspace_from_url with
+  // the R-framework pipeline). If no R1 page exists, the tool returns
+  // { ok: false, error: "no_landing_exists" }.
+  {
+    name: "customize_landing",
+    description:
+      "Apply a natural-language instruction to the current R1 landing page for a workspace. " +
+      "The LLM rewrites only the parts of the payload touched by the instruction, preserving " +
+      "everything else. Each call creates an immutable version snapshot so the operator can " +
+      "undo any change. Edits go live immediately (no publish step). " +
+      "Examples:\n" +
+      "  • customize_landing({ workspace_id: '...', instruction: 'Change the hero tagline to focus on 24/7 emergency service' })\n" +
+      "  • customize_landing({ workspace_id: '...', instruction: 'Replace the hero photo with https://example.com/photo.jpg' })\n" +
+      "  • customize_landing({ workspace_id: '...', instruction: 'Make the FAQ more local-flavored for Phoenix residents' })\n" +
+      "  • customize_landing({ workspace_id: '...', instruction: 'Add a question about financing options to the FAQ' })\n" +
+      "Requires: the workspace must have an R1 landing page (auto-generated during workspace creation). " +
+      "Requires: an Anthropic API key configured for the workspace (BYOK via /settings/integrations or platform fallback). " +
+      "Returns: { ok: true, summary, version_id } on success. " +
+      "Returns: { ok: false, error: 'no_landing_exists' } if the workspace has no R1 landing yet.",
+    inputSchema: obj(
+      {
+        workspace_id: str("UUID of the workspace whose landing page to edit."),
+        instruction: str(
+          "Natural-language description of what to change. Be specific. " +
+          "Include image URLs verbatim if swapping a photo. " +
+          "Example: 'Change the hero tagline to: Fast. Local. Trusted.' or " +
+          "'Replace the hero photo with https://images.unsplash.com/photo-...'",
+        ),
+      },
+      ["workspace_id", "instruction"],
+    ),
+    handler: async (a) => {
+      const ws = wsOrDefault(a.workspace_id);
+      if (typeof a.instruction !== "string" || !a.instruction.trim()) {
+        throw new Error("instruction must be a non-empty string.");
+      }
+      return api("POST", "/landing/r1/customize", {
+        body: { instruction: a.instruction },
+        workspace_id: ws,
+      });
+    },
+  },
+
+  // Phase T — list R1 landing version history.
+  {
+    name: "list_landing_versions",
+    description:
+      "Return the edit history for a workspace's R1 landing page, newest first. " +
+      "Each row has: id, instruction, summary, createdAt. Pass a version id to " +
+      "customize_landing_revert to undo to that point. " +
+      "Example: list_landing_versions({ workspace_id: '...' })",
+    inputSchema: obj(
+      {
+        workspace_id: str("UUID of the workspace."),
+        limit: {
+          type: "number",
+          description: "Optional. Max rows to return (default 20, max 100).",
+        },
+      },
+      ["workspace_id"],
+    ),
+    handler: async (a) => {
+      const ws = wsOrDefault(a.workspace_id);
+      const qs = a.limit ? `?limit=${encodeURIComponent(String(a.limit))}` : "";
+      return api("GET", `/landing/r1/versions${qs}`, { workspace_id: ws });
+    },
+  },
+
+  // Phase T — revert R1 landing to a prior version.
+  {
+    name: "revert_landing",
+    description:
+      "Revert the R1 landing page to a prior version's payload snapshot. " +
+      "Creates a new immutable version row (never deletes history). " +
+      "The page goes live immediately with the reverted content. " +
+      "Get version IDs from list_landing_versions. " +
+      "Example: revert_landing({ workspace_id: '...', version_id: '<uuid>' })",
+    inputSchema: obj(
+      {
+        workspace_id: str("UUID of the workspace."),
+        version_id: str("UUID of the version to revert to (from list_landing_versions)."),
+      },
+      ["workspace_id", "version_id"],
+    ),
+    handler: async (a) => {
+      const ws = wsOrDefault(a.workspace_id);
+      if (typeof a.version_id !== "string" || !a.version_id.trim()) {
+        throw new Error("version_id must be a non-empty string.");
+      }
+      return api("POST", "/landing/r1/revert", {
+        body: { version_id: a.version_id },
+        workspace_id: ws,
+      });
+    },
+  },
 ];
 
 export const TOOL_MAP = Object.fromEntries(TOOLS.map((t) => [t.name, t]));