@seldonframe/mcp 1.57.0 → 1.59.0

package/README.md

@@ -1,3 +1,4 @@
+<!-- mcp-name: io.github.seldonframe/mcp -->
 # @seldonframe/mcp
 
 Official SeldonFrame MCP server for Claude Code and Claude Desktop.

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "@seldonframe/mcp",
-  "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",
-  "type": "module",
-  "bin": {
-    "seldonframe-mcp": "src/index.js"
-  },
-  "files": [
-    "src",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "start": "node src/index.js",
-    "check:syntax": "node --check --input-type=module < src/index.js && node --check --input-type=module < src/client.js && node --check --input-type=module < src/tools.js && node --check --input-type=module < src/welcome.js",
-    "prepublishOnly": "npm run check:syntax"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "seldonframe",
-    "ai",
-    "agents",
-    "business-os",
-    "claude-code",
-    "crm",
-    "gohighlevel-alternative",
-    "gohighlevel",
-    "agency",
-    "whitelabel",
-    "partner-agency",
-    "booking",
-    "intake-form",
-    "landing-page",
-    "local-service-business",
-    "sms",
-    "twilio",
-    "ai-receptionist",
-    "ai-chatbot",
-    "missed-call"
-  ],
-  "homepage": "https://seldonframe.com",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/seldonframe/seldonframe",
-    "directory": "skills/mcp-server"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@seldonframe/mcp",
+  "version": "1.59.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",
+  "type": "module",
+  "bin": {
+    "seldonframe-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "check:syntax": "node --check --input-type=module < src/index.js && node --check --input-type=module < src/client.js && node --check --input-type=module < src/tools.js && node --check --input-type=module < src/welcome.js",
+    "prepublishOnly": "npm run check:syntax"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "seldonframe",
+    "ai",
+    "agents",
+    "business-os",
+    "claude-code",
+    "crm",
+    "gohighlevel-alternative",
+    "gohighlevel",
+    "agency",
+    "whitelabel",
+    "partner-agency",
+    "booking",
+    "intake-form",
+    "landing-page",
+    "local-service-business",
+    "sms",
+    "twilio",
+    "ai-receptionist",
+    "ai-chatbot",
+    "missed-call"
+  ],
+  "homepage": "https://seldonframe.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seldonframe/seldonframe.git",
+    "directory": "skills/mcp-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/finalize-summary.js

@@ -15,9 +15,16 @@
  * @param {string|null} args.aestheticArchetype — workspace's classified
  *   archetype (from snapshot.theme.aestheticArchetype). Used in the
  *   closing landing-page nudge.
+ * @param {string|null} [args.adminUrl] — bearer-token-scoped admin URL
+ *   (built in tools.js as `${appHost}/admin/${workspaceId}?token=${bearer}`,
+ *   same variable the welcome-email path already uses). Takes priority
+ *   over snapshot.ops_stack.admin_url, which is tokenless (the snapshot
+ *   endpoint has no bearer to mint one) and 404s at /admin/invalid if
+ *   printed as-is. Falls back to the tokenless value only if omitted, so
+ *   existing callers that don't pass it keep working.
  * @returns {string} the formatted operator summary
  */
-export function buildFinalizeSummary({ snapshot, durationSec, aestheticArchetype }) {
+export function buildFinalizeSummary({ snapshot, durationSec, aestheticArchetype, adminUrl = null }) {
   const ws = snapshot.workspace ?? {};
   const businessName = ws.name ?? "Your workspace";
   const chatbot = snapshot.chatbot ?? null;
@@ -57,7 +64,10 @@ export function buildFinalizeSummary({ snapshot, durationSec, aestheticArchetype
   // 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 ?? ""}`);
+  // The token-bearing adminUrl (computed in tools.js from the workspace's
+  // bearer) is required to open the dashboard — the snapshot's
+  // ops_stack.admin_url has no token and 404s at /admin/invalid if clicked.
+  lines.push(`🔧 Admin:   ${adminUrl ?? opsStack.admin_url ?? ""}`);
   lines.push("");
 
   // 7-automation callout

package/src/tools.js

@@ -471,19 +471,19 @@ export const TOOLS = [
       return firstEver ? withFirstCallBanner(payload) : payload;
     },
   },
-  // create_workspace_from_url — atomic crawl + workspace + chatbot.
-  // Thin wrapper around create_full_workspace with include_chatbot=true
-  // and auto_extract_faq=true. The orchestrator at /api/v1/workspace/create
-  // (POST) handles the multi-phase composition; this tool exists for
-  // discoverability — operators reading the MCP tool list see a name
-  // that matches the marketing pitch ("paste a URL → workspace").
+  // create_workspace_from_url — URL → extraction playbook → atomic build.
+  // Returns the server's extraction instructions; Claude WebFetches +
+  // extracts, then calls create_full_workspace (v1.58.1: the atomic path —
+  // it now builds the production multi-page R1 site server-side, the same
+  // engine as the SeldonFrame dashboard's /clients/new, so the old
+  // block-iterated v2 follow-up is no longer the best pipeline here).
   {
     name: "create_workspace_from_url",
     description:
-      "Entry point for URL-based workspace creation. Returns instructions Claude follows: WebFetch the URL, optionally WebFetch up to 2 priority sub-pages (e.g. /about, /services, /contact, /pricing), extract structured business facts, ask the operator for any required field that can't be determined, then call `create_workspace_v2` with the result. " +
-      "THIS TOOL DOES NOT CREATE A WORKSPACE — it returns the playbook. The workspace is created by the follow-up `create_workspace_v2` call (then per-block: get_block_skill + persist_block + complete_workspace_v2 + finalize_workspace). " +
+      "Entry point for URL-based workspace creation. Returns instructions Claude follows: WebFetch the URL, optionally WebFetch up to 2 priority sub-pages (e.g. /about, /services, /contact, /pricing), extract structured business facts, ask the operator for any required field that can't be determined, then call `create_full_workspace` with the result — ONE atomic call that builds the workspace + the production multi-page website (vertical-aware landing + per-service detail pages, the same engine as the SeldonFrame dashboard) + booking page + intake form + CRM + draft chatbot. " +
+      "THIS TOOL DOES NOT CREATE A WORKSPACE — it returns the playbook. The workspace is created by the follow-up `create_full_workspace` call. Do NOT use the block-iterated create_workspace_v2 flow for URL builds. " +
       "When operator provides ANY of: 'http://', 'https://', a domain (.com/.io/.net/.co/.app/.dev/.us etc), or 'create workspace for <URL>' — call this tool. Do NOT manually WebFetch first; the instructions returned by this tool tell you exactly what to fetch and in what order. " +
-      "MANDATORY FOLLOW-UP: After create_workspace_v2 returns 'ready' and all blocks land via persist_block + complete_workspace_v2, ask the operator 'What email should I use for your account?' and call finalize_workspace({ workspace_id, email }).",
+      "MANDATORY FOLLOW-UP: After create_full_workspace returns, ask the operator 'What email should I use for your account?' and call finalize_workspace({ workspace_id, email }).",
     inputSchema: obj(
       {
         url: str("Business website URL the operator provided, e.g. https://quigleyac.com"),
@@ -914,6 +914,9 @@ export const TOOLS = [
         snapshot,
         durationSec: 0, // smoke test reports actual duration via Vercel logs, not the summary text
         aestheticArchetype,
+        adminUrl, // token-bearing (same variable the welcome-email body uses below) —
+        // without this the summary's Admin line falls back to the snapshot's
+        // tokenless ops_stack.admin_url and 404s at /admin/invalid when clicked.
       });
 
       return {
@@ -4849,6 +4852,78 @@ export const TOOLS = [
     },
   },
 
+  // ───────────────────────────────────────────────────────────────────────
+  // v1.59.0 — IMPROVE. The 5th verb of the builder ladder: build → test →
+  // deploy → sell → improve. `improve_agent` replays an agent's own recent
+  // REAL conversations as graded evals against the current blueprint AND a
+  // proposed patch (a shadow candidate), clusters the failure modes, and
+  // hands back a paired before/after score diff — a marketplace-legible
+  // trust signal, not just a debugging tool. `apply_improvement` is the
+  // ONLY way a proposal's patch ever reaches the live blueprint: the pair
+  // together IS the propose-only contract — improve_agent can never apply
+  // anything on its own, by construction (see packages/crm/src/lib/agents/
+  // improve/improve-run.ts — nothing in that module imports
+  // updateAgentBlueprint).
+  // ───────────────────────────────────────────────────────────────────────
+
+  {
+    name: "improve_agent",
+    description:
+      "USE WHEN USER SAYS: 'improve the agent', 'make the chatbot better', 'why does the agent keep messing up', 'learn from real conversations', 'find what's going wrong and fix it', 'run the improve loop'. " +
+      "Replays the agent's recent REAL conversations as graded evals, clusters the failure modes, and PROPOSES a blueprint patch with before/after scores (paired per-scenario flips + an honest verdict — 'inconclusive' means the sample is too small to call). NEVER applies anything — review the proposal, then call apply_improvement. Takes 1-3 minutes (two replay passes). " +
+      "Needs the workspace's OWN Anthropic key (BYOK) — unbounded build/test-tier LLM cost, same gate as run_agent_evals; returns ok:false reason='no_llm_key' (402) if unset, point the operator at configure_llm_provider. " +
+      "Also returns ok:false (422) with a reason string when there's nothing to replay yet: 'no_conversations' (agent hasn't talked to anyone real), 'no_scenarios' (none of the sampled conversations converted cleanly), or 'agent_not_found'. " +
+      "On success (ok:true): `proposalId` is null when the baseline was already perfect ('nothing to improve') or no patch was proposed/it failed guardrails (note explains why) — in those cases there's nothing to apply. Otherwise pass `proposalId` straight to apply_improvement if the operator approves. " +
+      "`verdict` is 'better' ONLY when paired.improved - paired.regressed >= 3 AND no critical scenario regressed; 'worse' on a clear net regression; otherwise 'inconclusive' — AT THAT SAMPLE SIZE ONLY LARGE EFFECTS ARE REAL, so relay verdict='inconclusive' to the operator as: 'Small sample — apply on judgment, not on the score.' Never round an inconclusive verdict up to sounding like a pass.",
+    inputSchema: obj(
+      {
+        workspace_id: str("Workspace id (bearer workspace)."),
+        agent_id: str("Agent id from list_agents / create_agent / deploy_agent."),
+      },
+      ["workspace_id", "agent_id"],
+    ),
+    handler: async (args) => {
+      const ws = args.workspace_id;
+      const result = await api("POST", "/build/improve", {
+        body: { agent_id: args.agent_id },
+        workspace_id: ws,
+      });
+      if (result?.ok && result.verdict === "inconclusive") {
+        return {
+          ...result,
+          guidance:
+            "Small sample — apply on judgment, not on the score. The paired flip counts and cluster evidence are real; the verdict just isn't confident enough to call 'better' at this sample size. Read the clusters yourself before deciding whether to apply_improvement.",
+        };
+      }
+      return result;
+    },
+  },
+
+  {
+    name: "apply_improvement",
+    description:
+      "USE WHEN USER SAYS: 'apply that improvement', 'go with the proposed fix', 'apply the patch', 'yes, use the better version', 'accept the improve_agent proposal'. " +
+      "Applies a previously PROPOSED patch (from improve_agent's `proposalId`) after human review — this is the ONLY tool that can move an improve proposal's patch onto the live blueprint. Re-validates the patch against the agent's CURRENT blueprint before writing (it may have moved since the proposal was created) and creates a new agent_versions snapshot, exactly like update_agent_blueprint. " +
+      "Version drift doesn't block the apply — if the blueprint changed since the proposal was made, the result just carries a `note: 'applied over vN'` so you know it landed on a newer base than it was proposed against. " +
+      "Rejects (ok:false, 422) with a reason when the proposal can't be applied: 'not_found' (wrong id/org, or already resolved), 'not_proposed' (already applied or dismissed — improve proposals are one-shot), 'revalidation_failed' (the patch no longer passes the guardrail against the current blueprint). None of these ever touch the blueprint. " +
+      "After applying, the agent is on a new version — suggest re-running run_agent_evals or publish_agent({status:'live'}) (which auto-evals) to confirm the new version still passes the safety gate before the operator relies on it.",
+    inputSchema: obj(
+      {
+        workspace_id: str("Workspace id (bearer workspace)."),
+        proposal_id: str("Proposal id from improve_agent's `proposalId` field."),
+      },
+      ["workspace_id", "proposal_id"],
+    ),
+    handler: async (args) => {
+      const ws = args.workspace_id;
+      const result = await api("POST", "/build/improve/apply", {
+        body: { proposal_id: args.proposal_id },
+        workspace_id: ws,
+      });
+      return result;
+    },
+  },
+
   {
     name: "update_agent_blueprint",
     description:
@@ -5086,11 +5161,13 @@ export const TOOLS = [
           error: "publish_failed_but_agent_created",
           agent: createResult.agent,
           embed_url: createResult.embed_url,
-          turn_url: createResult.turn_url,
+          turn_api_url: createResult.turn_url,
+          turn_api_method: "POST",
           publish_detail: publishResult,
           steps,
           next_steps: [
             `Agent ${agentId} was created but couldn't be published to test. Call publish_agent({ agent_id: '${agentId}', status: 'test' }) manually, or check the dashboard at /agents/${agentId}`,
+            `Turn API (POST) — this is not a clickable link, it's a POST-only endpoint: curl -sX POST ${createResult.turn_url} -H "Content-Type: application/json" -d '{"message":"hi"}'`,
           ],
         };
       }
@@ -5114,7 +5191,8 @@ export const TOOLS = [
         ok: true,
         agent: createResult.agent,
         embed_url: createResult.embed_url,
-        turn_url: createResult.turn_url,
+        turn_api_url: createResult.turn_url,
+        turn_api_method: "POST",
         dashboard_url: dashboardUrl,
         sandbox_url: `${dashboardUrl}/test`,
         llm_mode: llmMode,
@@ -5125,6 +5203,7 @@ export const TOOLS = [
           `3. When ready, publish to live: call publish_agent({ agent_id: '${agentId}', status: 'live' }) — auto-runs eval gate, requires ≥87.5% pass.`,
           `4. Add to the operator's SF-hosted landing page (one MCP call): embed_chatbot_on_workspace_landing({ workspace_id, agent_id: '${agentId}' }) — the chatbot bubble appears bottom-right on every public page. (For an external website the operator owns, paste this snippet manually: <script src="${createResult.embed_url}" async></script>)`,
           `5. ${llmKeyNote}`,
+          `6. Turn API (POST) — not a clickable link, it's a POST-only endpoint: curl -sX POST ${createResult.turn_url} -H "Content-Type: application/json" -d '{"message":"hi"}'`,
         ],
       };
     },

package/src/welcome.js

@@ -109,7 +109,7 @@ of v1.28.0 this is **ONE tool call**:
      // /settings/integrations/llm. Pass explicitly only when you need
      // per-workspace billing isolation (white-label / agency).
    })
-   // → returns { agent, embed_url, turn_url, dashboard_url, llm_mode, next_steps }
+   // → returns { agent, embed_url, turn_api_url, turn_api_method: "POST", dashboard_url, llm_mode, next_steps }
    // Internally: creates agent, publishes to test. Skips set_llm_key when
    // no key supplied (platform fallback in lib/ai/client.ts handles inference).
 
@@ -191,6 +191,18 @@ Code at any time:
 - \`run_agent_evals\` — manual eval suite trigger
 - \`replay_conversation\` — re-run a past chat against current blueprint
 
+### v1.59.0 — the builder ladder gains a 5th verb: improve
+
+The full ladder is now **build → test → deploy → sell → improve**. Once
+an agent has real conversation history, \`improve_agent({ agent_id })\`
+replays it as graded evals, clusters the failure modes, and proposes a
+blueprint patch with paired before/after scores — never applying
+anything on its own. Review the proposal with the operator, then call
+\`apply_improvement({ proposal_id })\` if it looks good. Treat an
+\"inconclusive\" verdict as a real answer, not a soft failure — small
+samples can't support a confident "better," so apply on judgment, not
+on the score.
+
 The dashboard surfaces (\`/agents\`, \`/agents/[id]/test\`, \`/agents/[id]/settings\`,
 \`/agents/[id]/evals\`, \`/agents/[id]/conversations\`) provide the same view
 without leaving the browser — operators iterate FAQ/pricing/greeting inline
@@ -226,9 +238,13 @@ server-side personality system still runs underneath for everything
 else (CRM, booking, intake, theme, pipeline) — v2 only owns the copy
 surfaces where v1's layer-mismatch bugs hurt most.
 
-If you find yourself reaching for \`create_full_workspace\` instead of
-\`create_workspace_v2\`, stop — that's the legacy path. It still works
-but the output quality is worse on niches outside SF's curated set.
+Flow choice: when the structured business FACTS are already in hand —
+a URL extraction (create_workspace_from_url's playbook), a Google Maps
+paste, or a filled fact sheet — call \`create_full_workspace\` instead.
+Its atomic build now runs the same multi-page R1 site engine as the
+SeldonFrame dashboard (vertical-aware landing + per-service detail
+pages), which beats block-by-block copy generation. Use the v2 flow
+below when the operator wants to craft the copy interactively with you.
 
 1. **Ask for the business details** (same as before — gather conversationally):
    - Business name
@@ -322,17 +338,21 @@ but the output quality is worse on niches outside SF's curated set.
    output. PARAPHRASE that summary verbatim to the operator — that's
    how they see what was configured.
 
-## v1 fallback (legacy — NOT preferred)
+## Atomic vs block-iterated — when to use which
 
-\`create_full_workspace\` still works as the v1 atomic creation path.
-Use it ONLY when:
-- The operator's IDE agent has no LLM (script context, no Anthropic key)
-- A network failure prevents repeated tool calls and you need atomicity
-- You're writing automated tests that don't want to think about block
-  generation
+\`create_full_workspace\` is the atomic creation path and (since v1.58)
+builds the production multi-page website server-side — the same R1
+engine the SeldonFrame dashboard's /clients/new uses: vertical-aware
+landing, per-service detail pages, booking, intake, CRM, and a draft
+chatbot, all from one call. Prefer it whenever the business facts are
+already in hand:
+- create_workspace_from_url extractions (its playbook routes here)
+- Google Maps paste flows
+- scripted/automated creation
 
-In normal interactive operator-facing flows, prefer v2 every time. The
-v2 quality gradient over v1 is meaningful on long-tail niches.
+Prefer \`create_workspace_v2\` when the operator wants to shape the copy
+interactively — you generate hero/services/faq blocks yourself from
+block skills and iterate with them before completing.
 
 After step 4 the operator can customize their workspace through
 further natural-language requests ("change the headline to …",
@@ -456,6 +476,24 @@ further natural-language requests ("change the headline to …",
   title, description.
 - **\`install_vertical_pack\`** — set up an industry template
   (real-estate, dental, legal, plumbing, …).
+- **\`improve_agent\`** (v1.59.0) — replays an agent's recent REAL
+  conversations as graded evals, clusters the failure modes, and
+  proposes a blueprint patch with paired before/after scores; it never
+  applies anything by itself. Takes 1-3 minutes (two eval replay
+  passes) and needs the workspace's own Anthropic key (BYOK), same gate
+  as \`run_agent_evals\`. Treat verdict='inconclusive' as an honest
+  answer, not a failure — the sample is too small to call "better," so
+  relay it to the operator as "small sample — apply on judgment, not
+  on the score."
+- **\`apply_improvement\`** (v1.59.0) — applies a proposal from
+  \`improve_agent\`'s \`proposalId\` after the operator reviews it,
+  re-validating the patch against the current blueprint and creating a
+  new version, exactly like \`update_agent_blueprint\`. This is the
+  ONLY tool that can move an improve proposal onto the live blueprint —
+  \`improve_agent\` is propose-only by construction. Re-run
+  \`run_agent_evals\` (or \`publish_agent({status:'live'})\`, which
+  auto-evals) after applying to confirm the new version still clears
+  the safety gate.
 - **\`list_contacts\`** / **\`create_contact\`** / **\`update_contact\`** —
   manage the CRM.
 - **\`list_deals\`** / **\`create_deal\`** / **\`move_deal_stage\`** —