@seldonframe/mcp 1.53.0 → 1.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seldonframe/mcp",
-  "version": "1.53.0",
+  "version": "1.56.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

@@ -0,0 +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("");
+
+  // 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

@@ -20,6 +20,10 @@ import {
 // drafts assumed VERSION leaked in via client.js's transitive import;
 // it doesn't. Direct import = no runtime "VERSION is not defined".
 import { FIRST_CALL_BANNER, VERSION } from "./welcome.js";
+// v1.55.0 — finalize_workspace summary builder extracted into its own
+// module so it can be unit-tested in isolation. See
+// packages/crm/tests/unit/finalize-summary-v1-55.spec.ts.
+import { buildFinalizeSummary } from "./finalize-summary.js";
 // v1.10.1 — upload_workspace_image local_file_path branch reads the file
 // directly in the MCP-client process (which runs on the operator's
 // machine via the npm package). Reading + base64-encoding here means
@@ -840,8 +844,6 @@ export const TOOLS = [
       const wsName = snapshot?.workspace?.name ?? "Your workspace";
       const chatbot = snapshot?.chatbot ?? null;
       const tier = snapshot?.tier ?? null;
-      const bookingInfo = snapshot?.booking ?? null;
-      const intakeInfo = snapshot?.intake ?? null;
       if (!publicUrls.home || !publicUrls.book || !publicUrls.intake) {
         throw new Error(
           "Snapshot did not return public_urls (home/book/intake). Re-check the workspace.",
@@ -894,9 +896,8 @@ export const TOOLS = [
       }
 
       // Step 3: closing summary — formatted exactly the way Claude Code
-      // should paraphrase to the operator. Pulls the personality label
-      // + pipeline stages from the snapshot so the "What's configured"
-      // section reflects the actual workspace shape.
+      // should paraphrase to the operator. Personality + pipeline are
+      // surfaced in the response payload (not the summary text).
       const personality =
         snapshot?.workspace?.settings?.crmPersonality ?? null;
       const personalityLabel =
@@ -905,125 +906,15 @@ export const TOOLS = [
           : null;
       const pipelineStages = personality?.pipeline?.stages ?? [];
 
-      // 2026-05-15 — Agency-voice product moment summary. See spec
-      // docs/superpowers/specs/2026-05-15-agency-output-product-moment-design.md
-      const intakeSpecialNote =
-        personality?.vertical === "hvac" || personality?.vertical === "plumbing"
-          ? "emergency-line fallback"
-          : "structured lead-qualification";
-
-      const tierLabel = tier?.current_tier_label ?? "Free";
-      const isPaid =
-        tier?.current_tier === "growth" || tier?.current_tier === "scale";
-      const isScale = tier?.current_tier === "scale";
-
-      const intakeFieldCount = intakeInfo?.field_count ?? 0;
-      const intakeTitle = intakeInfo?.title ?? "lead qualification";
-
-      const lines = [];
-
-      // Header
-      lines.push(`✅ ${wsName} — client OS shipped.`);
-      lines.push("");
-      lines.push("Your client's stack is wired and live:");
-      lines.push("");
-
-      // Public site
-      lines.push("🌐 Public site (paste a screenshot in your Slack)");
-      lines.push(`   ${publicUrls.home}`);
-      lines.push("");
-
-      // Chatbot
-      if (chatbot && chatbot.embed_snippet) {
-        lines.push("🤖 AI chatbot — paste on the client's existing site (before </body>):");
-        lines.push(`   ${chatbot.embed_snippet}`);
-        lines.push(
-          `   In ${String(chatbot.status).toUpperCase()} mode. Powered by your Claude Code key (swap in settings).`,
-        );
-        lines.push(
-          `   Publish live: publish_agent({ agent_id: "${chatbot.agent_id}", status: "live" })`,
-        );
-      } else {
-        lines.push("🤖 AI chatbot — scaffold pending. Retry:");
-        lines.push(`   create_agent({ archetype: "website-chatbot", channel: "web_chat" })`);
-      }
-      lines.push("");
-
-      // Booking
-      lines.push("📋 Booking page (client's customers self-serve appointments)");
-      lines.push(`   ${publicUrls.book}`);
-      lines.push("");
-
-      // Intake
-      lines.push(`📝 Intake form (${intakeFieldCount}-question ${intakeTitle})`);
-      lines.push(`   ${publicUrls.intake}`);
-      lines.push("");
-
-      // Admin
-      lines.push("🔐 Your admin (CRM, pipeline, leads, deals)");
-      lines.push(`   ${adminUrl}`);
-      lines.push("");
-
-      // Client portal
-      if (tier?.client_portal_url) {
-        lines.push("👥 Client portal (your client logs in here to see their leads + bookings)");
-        lines.push(`   ${tier.client_portal_url}`);
-        if (isPaid) {
-          lines.push(`   ✅ Active. Forward this URL to your client; they log in via magic email.`);
-        } else {
-          lines.push(`   🔒 Growth tier ($29/mo) unlocks this for your client. Preview it`);
-          lines.push(`       yourself at the URL above right now.`);
-        }
-        lines.push("");
-      }
-
-      // What's wired
-      lines.push("What's wired:");
-      if (personalityLabel) {
-        const stageCount = pipelineStages.length;
-        lines.push(`   • ${personalityLabel} personality • ${stageCount}-stage CRM pipeline`);
-      }
-      if (bookingInfo) {
-        lines.push(
-          `   • ${bookingInfo.hours_summary} bookings, ${bookingInfo.duration_minutes}-min slots`,
-        );
-      }
-      if (intakeInfo) {
-        lines.push(`   • ${intakeFieldCount}-question intake with ${intakeSpecialNote}`);
-      }
-      if (chatbot) {
-        lines.push(`   • AI chatbot trained on the homepage (FAQ scaffold ready to refine)`);
-      }
-      lines.push(
-        emailSent
-          ? `   • Welcome email + admin link sent to ${a.email}`
-          : `   • Welcome email NOT yet sent (rerun finalize_workspace to retry)`,
-      );
-      lines.push("");
-
-      // What you can prompt next (5 agency-meaningful examples)
-      lines.push("What you can prompt next:");
-      lines.push(`   • "Refine the chatbot FAQ from the site" → update_website_chatbot`);
-      lines.push(`   • "Add SMS missed-call-text-back automation" → install_archetype`);
-      lines.push(`   • "Customize the hero with the client's brand voice" → customize_block`);
-      lines.push(`   • "Wire Google Calendar so bookings sync" → connect_integration`);
-      lines.push(`   • "Add a Spanish version of the landing page" → clone_workspace + translate`);
-      lines.push("");
-
-      // Tier ladder (omit on Scale tier)
-      if (!isScale) {
-        lines.push(`Tier ladder (you're on ${tierLabel}):`);
-        lines.push(`   Free  → 1 client workspace, everything above wired`);
-        lines.push(`   Growth $29/mo → 3 workspaces, client portal goes live, custom domain`);
-        lines.push(`                   (e.g. crm.youragency.com), SMS/email automations`);
-        lines.push(`   Scale $99/mo → unlimited workspaces, full white-label, reseller pricing`);
-        lines.push("");
-      }
-
-      // Closer
-      lines.push("Forward your client this admin link when ready. Or stay here and iterate.");
-
-      const summary = lines.join("\n");
+      // v1.55.0 — Ops-stack-only workspace creation. The summary is
+      // built by buildFinalizeSummary in ./finalize-summary.js; we
+      // pass the snapshot + duration + archetype here.
+      const aestheticArchetype = snapshot?.theme?.aestheticArchetype ?? null;
+      const summary = buildFinalizeSummary({
+        snapshot,
+        durationSec: 0, // smoke test reports actual duration via Vercel logs, not the summary text
+        aestheticArchetype,
+      });
 
       return {
         ok: emailSent || leadRecorded,
@@ -1050,37 +941,52 @@ export const TOOLS = [
         lead_error: leadError,
         personality: personalityLabel,
         pipeline_stages: pipelineStages.map((s) => s?.name).filter(Boolean),
-        // 2026-05-15 — agency-meaningful next-step examples
+        // v1.55.0 — Ops-stack-first next-step ladder. Surfaces the
+        // chatbot-paste workflow + the 7 ready automations + the
+        // landing-page nudge so Claude Code can pick from a tight
+        // curated list rather than improvise tool calls.
         next_steps_available: [
           {
-            action: "publish_agent",
-            when: "operator has reviewed the chatbot and is ready to take it live for the client's website",
-            example: `publish_agent({ agent_id: "${chatbot?.agent_id ?? "ag_..."}", status: "live" })`,
+            id: "deploy_chatbot_embed",
+            label: "Paste chatbot embed on client's existing site",
+            action: "user_action",
+            payload: {
+              snippet: chatbot?.embed_snippet ?? null,
+              target: snapshot?.workspace?.settings?.source_url ?? null,
+            },
           },
           {
-            action: "update_website_chatbot",
-            when: "operator wants to refine the chatbot's FAQ before publishing",
-            example: `update_website_chatbot({ workspace_id, faq: [{ q: '...', a: '...' }] })`,
+            id: "promote_chatbot_to_live",
+            label: "Promote chatbot from TEST to LIVE (when ready for production)",
+            action: "publish_agent",
+            payload: { agent_id: chatbot?.agent_id ?? null },
           },
           {
-            action: "install_archetype",
-            when: "operator wants to wire pre-built automations (missed-call-text-back, speed-to-lead, review-requester)",
-            example: `install_archetype({ archetype: "missed-call-text-back" })`,
+            id: "activate_automation",
+            label: "Activate one of the 7 ready automations",
+            action: "open_dashboard",
+            payload: { url: snapshot?.ops_stack?.automations_url ?? null },
           },
           {
-            action: "customize_block",
-            when: "operator wants to refine landing-page hero / services / FAQ with brand voice",
-            example: `customize_block({ workspace_id, block_name: "hero", prompt: "make this feel more premium" })`,
+            id: "configure_integration",
+            label: "Configure Twilio / Resend / Stripe for SMS / email / payments",
+            action: "claude_assisted",
+            payload: { available_providers: ["twilio", "resend", "stripe"] },
           },
           {
-            action: "connect_integration",
-            when: "operator wants Google Calendar sync, Stripe payments, Twilio SMS",
-            example: `connect_integration({ workspace_id, provider: "google_calendar" })`,
+            id: "build_landing_page",
+            label: "Build a landing page (uses landing-page-creation skill)",
+            action: "claude_assisted",
+            payload: {
+              skill: "landing-page-creation",
+              archetype: snapshot?.theme?.aestheticArchetype ?? null,
+            },
           },
           {
-            action: "configure_llm_provider",
-            when: "operator wants to swap from the default Claude Code key to a different Anthropic key",
-            example: `configure_llm_provider({ workspace_id, provider: "anthropic", api_key: "sk-ant-..." })`,
+            id: "customize_chatbot_faq",
+            label: "Refine the chatbot's FAQ from source site content",
+            action: "claude_assisted",
+            payload: { agent_id: chatbot?.agent_id ?? null },
           },
         ],
       };