@seldonframe/mcp 1.0.3 → 1.0.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@seldonframe/mcp",
-  "version": "1.0.3",
-  "description": "MCP server for SeldonFrame — AI-native Business OS platform. One command creates a real hosted workspace with CRM, booking, intake, and Brain v2. v1.0.3: surfaces admin URL prominently in create_workspace response (no signup required to access dashboard).",
+  "version": "1.0.5",
+  "description": "MCP server for SeldonFrame — AI-native Business OS platform. One command creates a real hosted workspace with CRM, booking page, intake form, and AI agents. v1.0.5: collect_operator_email tool closes the onboarding loop (welcome email + lead capture); auto-injects x-org-id from workspace bearer for ALL tool calls (fixes list_contacts / list_deals / list_bookings / send_welcome_email); structured Soul-seed fields on create_workspace (phone, services, testimonials) so the landing page renders real data on the first GET; operator-facing labels replace internal slugs in responses.",
   "type": "module",
   "bin": {
     "seldonframe-mcp": "src/index.js"

package/src/client.js

@@ -139,6 +139,18 @@ export async function api(method, path, opts = {}) {
   };
   if (auth) headers.Authorization = auth;
 
+  // May 1, 2026 — inject x-org-id from the resolved workspace for
+  // EVERY tool call. Several CRM endpoints (contacts, deals,
+  // bookings, activities) use guardApiRequest which strictly
+  // requires x-org-id. Without this header, the bearer token alone
+  // returns 400 "Missing x-org-id" even though the bearer is
+  // workspace-scoped. Tools can opt out by passing
+  // `extra_headers: { "x-org-id": null }` if a route needs the
+  // header omitted, but the default is to send it.
+  if (workspace_id && !("x-org-id" in headers) && !("X-Org-ID" in headers)) {
+    headers["x-org-id"] = workspace_id;
+  }
+
   const res = await fetch(`${API_BASE}${path}`, {
     method,
     headers,

package/src/tools.js

@@ -1,5 +1,6 @@
 import {
   api,
+  API_INFO,
   fetchText,
   forgetWorkspace,
   htmlToText,
@@ -41,18 +42,61 @@ export const TOOLS = [
   {
     name: "create_workspace",
     description:
-      "Create a real, hosted workspace on <slug>.app.seldonframe.com with CRM, Cal.diy booking, Formbricks intake, and Brain v2 pre-installed. The first workspace requires no API key. Example: create_workspace({ name: 'Dental Clinic Laval', source: 'https://mysite.com' })",
+      "Create a real, hosted workspace on <slug>.app.seldonframe.com with a CRM, booking page, intake form, and AI agents pre-installed. The first workspace requires no API key. When the user mentions a phone, email, address, list of services, or testimonials, pass them as structured fields so the landing page renders with their real content immediately. Example: create_workspace({ name: 'Desert Cool HVAC', phone: '(602) 555-0188', services: [{ name: 'AC Repair' }, { name: 'Heating' }] })",
     inputSchema: obj(
       {
         name: str("Human-readable workspace name."),
-        source: str("Optional URL or description to seed the workspace's Soul from."),
+        source: str("Optional URL or description to seed the business profile from."),
+        phone: str("Operator's business phone (any format — we render as-is). Renders in nav, hero, and footer when set."),
+        email: str("Optional contact email surfaced in the landing footer."),
+        address: str("Optional business address. Comma-separated street, city, region, postal, country renders as-is."),
+        tagline: str("Short hero tagline (one line)."),
+        business_description: str("One paragraph about the business (used for hero subhead + about section)."),
+        services: {
+          type: "array",
+          description:
+            "List of services / products / offerings the business provides. Renders as the services grid on the landing page. Each item: { name, description? }.",
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string" },
+              description: { type: "string" },
+            },
+            required: ["name"],
+          },
+        },
+        testimonials: {
+          type: "array",
+          description:
+            "Optional customer testimonials to seed the landing page's testimonials section. Each item: { quote, name?, role?, company? }.",
+          items: {
+            type: "object",
+            properties: {
+              quote: { type: "string" },
+              name: { type: "string" },
+              role: { type: "string" },
+              company: { type: "string" },
+            },
+            required: ["quote"],
+          },
+        },
       },
       ["name"],
     ),
     handler: async (args) => {
       const firstEver = isFirstEverCall();
       const result = await api("POST", "/workspace/create", {
-        body: { name: args.name, source: args.source ?? null },
+        body: {
+          name: args.name,
+          source: args.source ?? null,
+          phone: args.phone ?? null,
+          email: args.email ?? null,
+          address: args.address ?? null,
+          tagline: args.tagline ?? null,
+          business_description: args.business_description ?? null,
+          services: args.services ?? null,
+          testimonials: args.testimonials ?? null,
+        },
         allow_anonymous: true,
       });
       const ws = result.workspace ?? result;
@@ -67,6 +111,16 @@ export const TOOLS = [
       // in the response. Operators paste it into their browser and land
       // directly on the dashboard — no signup, no login, no OAuth.
       const adminUrl = result.admin_url ?? null;
+      // v1.0.4: strip the misleading `admin_*` keys out of the legacy
+      // flat `urls` object so old clients don't surface the
+      // /switch-workspace login-required URLs as if they were the
+      // intended path. Public-facing keys (home/book/intake) stay.
+      const rawUrls = result.urls ?? ws.urls ?? null;
+      const publicUrls = rawUrls
+        ? Object.fromEntries(
+            Object.entries(rawUrls).filter(([key]) => !key.startsWith("admin_")),
+          )
+        : null;
       const payload = {
         ok: true,
         workspace: {
@@ -82,15 +136,43 @@ export const TOOLS = [
         admin_url_message: adminUrl
           ? `⚡ Admin Dashboard (bookmark this!): ${adminUrl}\nClick to open the dashboard — no signup needed. Token expires in 7 days; re-mint with list_workspaces({}) when it does.`
           : null,
-        urls: result.urls ?? ws.urls ?? null,
-        public_urls: result.public_urls ?? null,
-        installed: result.installed ?? ["crm", "caldiy-booking", "formbricks-intake", "brain-v2"],
+        urls: publicUrls,
+        public_urls: result.public_urls ?? publicUrls,
+        // May 1, 2026 — installed-block labels translated to operator
+        // copy. The MCP-internal slugs ("caldiy-booking",
+        // "formbricks-intake", "brain-v2") are deployment details no
+        // operator should need to learn — surfacing them on every
+        // create_workspace turn was friction without payoff.
+        installed: (result.installed ?? [
+          "crm",
+          "caldiy-booking",
+          "formbricks-intake",
+          "brain-v2",
+        ]).map((slug) => {
+          if (slug === "caldiy-booking") return "Booking page";
+          if (slug === "formbricks-intake") return "Intake form";
+          if (slug === "brain-v2") return "AI learning";
+          if (slug === "crm") return "CRM";
+          return slug;
+        }),
+        // May 1, 2026 — email collection promoted to the first
+        // suggested next step. Per the onboarding-loop spec, the
+        // operator gets a permanent inbox record (admin URLs,
+        // landing/booking/intake links) AND we earn a CRM lead in
+        // SeldonFrame's own workspace, so every workspace creation
+        // becomes a tracked relationship.
+        prompt_for_email: {
+          message:
+            "What's your email? I'll send you a summary with all the links above (so you don't lose them) and use it for your admin login when you upgrade. — calls collect_operator_email({ email, name? })",
+          tool: "collect_operator_email",
+        },
         next: [
           adminUrl
-            ? `Open the admin dashboard: ${adminUrl}  (paste into your browser; no signup needed)`
+            ? `⚡ Admin Dashboard (bookmark this!): ${adminUrl}  (paste into your browser; no signup needed; token expires in 7 days)`
             : null,
-          "install_vertical_pack({ pack: 'real-estate' })  // or 'dental', 'legal'",
-          "fetch_source_for_soul({ url: 'https://yoursite.com' }) → submit_soul({ soul })",
+          "Ask the user for their email, then call collect_operator_email({ email, name? }) — sends the welcome email + creates a permanent record. Do this BEFORE any further customization.",
+          "install_vertical_pack({ pack: '<industry>' }) — set up an industry template (real-estate, dental, legal, …)",
+          "fetch_source_for_soul({ url: 'https://yoursite.com' }) → submit_soul({ soul }) — pull the business profile from a website",
           "get_workspace_snapshot({}) — read workspace state to reason about next steps",
         ].filter(Boolean),
       };
@@ -197,6 +279,178 @@ export const TOOLS = [
       };
     },
   },
+  {
+    name: "send_welcome_email",
+    description:
+      "Email the active workspace's four key URLs (landing, booking, intake, admin dashboard) to a user. Use this AFTER create_workspace, only when the user has explicitly given their email — never auto-send. The admin URL is bearer-token-scoped and expires in 7 days. Example: send_welcome_email({ email: 'alice@example.com', name: 'Alice' }).",
+    inputSchema: obj(
+      {
+        email: str("Recipient email address."),
+        name: str("Optional recipient name (used in the greeting)."),
+        workspace_id: str("Optional workspace override. Defaults to active workspace."),
+      },
+      ["email"],
+    ),
+    handler: async (a) => {
+      const workspaceId = a.workspace_id ?? getDefaultWorkspace();
+      if (!workspaceId) {
+        throw new Error(
+          "No workspace selected. Run create_workspace({ name: '…' }) first, or pass workspace_id.",
+        );
+      }
+      const bearer = getWorkspaceBearer(workspaceId);
+      if (!bearer) {
+        throw new Error(
+          `No local bearer token for workspace ${workspaceId}. This device did not create it. Re-run create_workspace or switch to the device that did.`,
+        );
+      }
+
+      const snapshot = await api(
+        "GET",
+        `/workspace/${encodeURIComponent(workspaceId)}/snapshot`,
+        { workspace_id: workspaceId },
+      );
+      const publicUrls = snapshot?.public_urls ?? {};
+      if (!publicUrls.home || !publicUrls.book || !publicUrls.intake) {
+        throw new Error(
+          "Snapshot did not return public_urls (home/book/intake). Re-check the workspace.",
+        );
+      }
+
+      // Construct the bearer-scoped admin URL from the API base.
+      // API_INFO.base is `<host>/api/v1` — strip that suffix to get the app host.
+      const appHost = API_INFO.base.replace(/\/api\/v1\/?$/, "");
+      const adminUrl = `${appHost}/admin/${encodeURIComponent(workspaceId)}?token=${encodeURIComponent(bearer)}`;
+
+      await api("POST", "/email/send-welcome", {
+        body: {
+          email: a.email,
+          name: a.name ?? null,
+          workspace: {
+            landing_url: publicUrls.home,
+            booking_url: publicUrls.book,
+            intake_url: publicUrls.intake,
+            admin_url: adminUrl,
+          },
+        },
+        workspace_id: workspaceId,
+      });
+
+      return {
+        ok: true,
+        message: `Welcome email sent to ${a.email}`,
+      };
+    },
+  },
+  {
+    name: "collect_operator_email",
+    description:
+      "Onboarding-loop helper: ask the operator for their email post-create_workspace, then send the welcome email + record them as a lead in SeldonFrame's own CRM. Combines send_welcome_email + a lead-capture call so a single tool call closes the loop. Call this BEFORE further customization (configure_booking / customize_intake_form / install_vertical_pack) so the operator gets a permanent inbox record of their links. Example: collect_operator_email({ email: 'max@desertcool.com', name: 'Max' })",
+    inputSchema: obj(
+      {
+        email: str("Operator email — used as the welcome email recipient AND as the unique key for the SeldonFrame CRM lead."),
+        name: str("Optional operator name (used in the email greeting and on the CRM lead)."),
+        workspace_id: str("Optional workspace override. Defaults to the workspace just created."),
+      },
+      ["email"],
+    ),
+    handler: async (a) => {
+      const workspaceId = a.workspace_id ?? getDefaultWorkspace();
+      if (!workspaceId) {
+        throw new Error(
+          "No workspace selected. Run create_workspace({ name: '…' }) first, or pass workspace_id.",
+        );
+      }
+      const bearer = getWorkspaceBearer(workspaceId);
+      if (!bearer) {
+        throw new Error(
+          `No local bearer token for workspace ${workspaceId}. This device did not create it. Re-run create_workspace or switch to the device that did.`,
+        );
+      }
+
+      // Step 1: pull the workspace snapshot so we have the public URLs
+      // for the welcome email.
+      const snapshot = await api(
+        "GET",
+        `/workspace/${encodeURIComponent(workspaceId)}/snapshot`,
+        { workspace_id: workspaceId },
+      );
+      const publicUrls = snapshot?.public_urls ?? {};
+      const slug = snapshot?.workspace?.slug ?? null;
+      if (!publicUrls.home || !publicUrls.book || !publicUrls.intake) {
+        throw new Error(
+          "Snapshot did not return public_urls (home/book/intake). Re-check the workspace.",
+        );
+      }
+      const appHost = API_INFO.base.replace(/\/api\/v1\/?$/, "");
+      const adminUrl = `${appHost}/admin/${encodeURIComponent(workspaceId)}?token=${encodeURIComponent(bearer)}`;
+
+      // Step 2: send the welcome email. Failures here are surfaced
+      // (operator told us their email, we owe them the email) but
+      // don't block the lead-capture step below.
+      let emailSent = false;
+      let emailError = null;
+      try {
+        await api("POST", "/email/send-welcome", {
+          body: {
+            email: a.email,
+            name: a.name ?? null,
+            workspace: {
+              landing_url: publicUrls.home,
+              booking_url: publicUrls.book,
+              intake_url: publicUrls.intake,
+              admin_url: adminUrl,
+            },
+          },
+          workspace_id: workspaceId,
+        });
+        emailSent = true;
+      } catch (err) {
+        emailError = err?.message ?? String(err);
+      }
+
+      // Step 3: record the operator as a lead in SeldonFrame's own
+      // CRM workspace. Anonymous endpoint — no bearer required, ops
+      // workspace ID is server-side env only. Soft-failure: if the
+      // ops workspace isn't configured we still return ok.
+      let leadRecorded = false;
+      let leadId = null;
+      let leadError = null;
+      try {
+        const leadResp = await api("POST", "/leads/operator-signup", {
+          body: {
+            email: a.email,
+            name: a.name ?? null,
+            source_workspace_id: workspaceId,
+            source_workspace_slug: slug,
+            source: "mcp-onboarding",
+          },
+          allow_anonymous: true,
+        });
+        leadRecorded = Boolean(leadResp?.recorded);
+        leadId = leadResp?.lead_id ?? null;
+      } catch (err) {
+        leadError = err?.message ?? String(err);
+      }
+
+      return {
+        ok: emailSent || leadRecorded,
+        email_sent: emailSent,
+        email_error: emailError,
+        lead_recorded: leadRecorded,
+        lead_id: leadId,
+        lead_error: leadError,
+        message: emailSent
+          ? `Welcome email sent to ${a.email}. Check your inbox — the admin URL is in there too.`
+          : `Could not send welcome email${emailError ? `: ${emailError}` : ""}. Lead ${leadRecorded ? "recorded" : "not recorded"}.`,
+        next: [
+          "configure_booking({ title, duration_minutes, description }) — tune the booking page if you collected business hours",
+          "customize_intake_form({ ... }) — match your intake to the workspace's lead-qualification questions",
+          "install_vertical_pack({ pack: '<industry>' }) — add domain-specific objects, fields, and views",
+        ],
+      };
+    },
+  },
   {
     name: "revoke_bearer",
     description:
@@ -384,10 +638,10 @@ export const TOOLS = [
   {
     name: "install_vertical_pack",
     description:
-      "Install a vertical pack (e.g. 'real-estate', 'dental', 'legal'). Adds domain-specific objects, fields, views.",
+      "Set up an industry template (real-estate, dental, legal, …). Adds industry-specific objects, fields, and views to the CRM and pre-fills the booking page + intake form for that line of work.",
     inputSchema: obj(
       {
-        pack: str("Pack slug, e.g. 'real-estate', 'dental', 'legal'."),
+        pack: str("Industry template name, e.g. 'real-estate', 'dental', 'legal'."),
         workspace_id: str("Optional workspace override."),
       },
       ["pack"],
@@ -403,10 +657,10 @@ export const TOOLS = [
   {
     name: "install_caldiy_booking",
     description:
-      "Install the Cal.diy booking block (event types, availability, bookings). Example: install_caldiy_booking({})",
+      "Install the booking page (event types, availability, scheduled bookings). Example: install_caldiy_booking({})",
     inputSchema: obj({
       workspace_id: str("Optional workspace override."),
-      config: { type: "object", description: "Optional Cal.diy configuration overrides." },
+      config: { type: "object", description: "Optional booking-page configuration overrides." },
     }),
     handler: async (a) => {
       const ws = wsOrDefault(a.workspace_id);
@@ -419,10 +673,10 @@ export const TOOLS = [
   {
     name: "install_formbricks_intake",
     description:
-      "Install a Formbricks intake form (surveys, conditional logic, contact sync). Example: install_formbricks_intake({})",
+      "Install an intake form (questions, conditional logic, automatic CRM sync). Example: install_formbricks_intake({})",
     inputSchema: obj({
       workspace_id: str("Optional workspace override."),
-      form_id: str("Optional existing Formbricks form id to bind."),
+      form_id: str("Optional existing intake-form id to bind."),
     }),
     handler: async (a) => {
       const ws = wsOrDefault(a.workspace_id);
@@ -449,7 +703,7 @@ export const TOOLS = [
   {
     name: "fetch_source_for_soul",
     description:
-      "Fetch a URL and return normalized text (headings + body, up to 256KB). Use this to gather raw content; then you (the caller) extract a structured Soul and submit it with submit_soul. Zero LLM cost to Seldon — extraction runs in this session.",
+      "Fetch a URL and return normalized text (headings + body, up to 256KB). Use this to gather raw content from the operator's existing website; then extract a structured business profile and save it with submit_soul. Zero LLM cost to SeldonFrame — extraction runs in this session.",
     inputSchema: obj(
       {
         url: str("Absolute URL to fetch."),
@@ -468,7 +722,7 @@ export const TOOLS = [
         truncated,
         text,
         next: [
-          "Extract a Soul object: { mission, audience, tone, offerings[], differentiators[], faqs[] }",
+          "Extract a business profile: { mission, audience, tone, offerings[], differentiators[], faqs[] }",
           "submit_soul({ soul: <extracted> })",
         ],
       };
@@ -477,13 +731,13 @@ export const TOOLS = [
   {
     name: "submit_soul",
     description:
-      "Submit a compiled Soul object to the active workspace. The caller is expected to have produced the structured Soul from fetch_source_for_soul output or user conversation.",
+      "Save a business profile to the active workspace. The profile drives the landing page, intake form copy, and AI-agent context. Call this after fetch_source_for_soul or after gathering details from the user. Triggers a re-render of the public landing page so changes are visible immediately.",
     inputSchema: obj(
       {
         soul: {
           type: "object",
           description:
-            "Structured Soul. Expected keys: mission, audience, tone, offerings, differentiators, faqs. Additional keys allowed.",
+            "Business profile. Expected keys: business_name, tagline, soul_description, phone, email, address, offerings, faqs, testimonials. Additional keys allowed — they're preserved for future use.",
         },
         workspace_id: str("Optional workspace override."),
       },

package/src/welcome.js

@@ -104,9 +104,9 @@ Soul compilation runs HERE, not on the backend:
 
 ## When you'll need \`SELDONFRAME_API_KEY\`
 
-The first workspace is free forever. Paid tiers (Starter $49/mo, Operator
-$99/mo, Agency $149/mo) unlock additional workspaces, custom domains,
-white-label, and advanced Brain capabilities. A key is required for:
+The first workspace is free forever. Paid tiers (Growth $29/mo, Scale
+$99/mo, both with metered usage) unlock additional workspaces, custom
+domains, white-label, and advanced Brain capabilities. A key is required for:
 
 - Adding a **second workspace**
 - Connecting a **custom domain**