@seldonframe/mcp 1.25.4 → 1.26.1

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@seldonframe/mcp",
-  "version": "1.25.4",
+  "version": "1.26.1",
+  "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.26.1: AGENTS GO LIVE — BYOK + embed.js + 5 new MCP tools. WHAT SHIPS: (1) BYOK (BRING-YOUR-OWN-KEY). SF clients (the agencies + their HVAC/dental/coaching operators) use Claude Code or Cursor to build agents — they already have Anthropic API keys. SF doesn't markup LLM cost; SF charges per agent turn (separate revenue line). lib/agents/runtime.ts swaps from process.env.ANTHROPIC_API_KEY to getAIClient({ orgId }) — the same BYOK helper that lib/ai/client.ts already exposes for the rest of the platform (encrypted at rest in organizations.integrations.anthropic.apiKey with v1. prefix; decryptIfNeeded resolves at call time). When a workspace hasn't configured a key, executeTurn returns { ok: false, reason: 'llm_not_configured', fallbackMessage } — the public turn endpoint surfaces a graceful 'I'm not set up to chat yet — please reach out directly' instead of crashing. (2) EMBED.JS — single-line install on operator's website. New endpoint GET /api/v1/public/agent/<orgSlug>--<agentSlug>/embed.js returns a self-contained IIFE (~3KB) that injects a bottom-right chat bubble + chat panel. Click bubble → panel opens → user types → POST to /turn → response appears. Anonymous session id stored in localStorage (sf_agent_session_<agentSlug>) so multi-message sessions thread together server-side via agent_conversations.anonymous_session_id. Themed via agent's blueprint.greeting + workspace's theme.primaryColor. Returns no-op script (still 200) when agent not 'live' so operator's site console stays clean during draft → test → live progression. CSS namespaced .sf-agent-* (zero collision risk on operator's site). Operator's install snippet: <script src=\"https://app.seldonframe.com/api/v1/public/agent/cypress-pine-hvac--default/embed.js\" async></script>. (3) 5 NEW MCP TOOLS so SF clients build + ship agents from Claude Code without touching the dashboard: configure_llm_provider({ provider: 'anthropic'|'openai', api_key }) — first-run setup, encrypts + writes to organizations.integrations[provider].apiKey. create_agent({ name, archetype, channel, capabilities?, faq?, pricing_facts?, greeting? }) — wraps lib/agents/store.createAgent, returns { agent, embed_url, turn_url, next_steps[] } so the SF client immediately gets the embed snippet to drop on their operator's site. update_agent_blueprint({ agent_id, patch, publish_notes? }) — wraps updateAgentBlueprint, bumps current_version + writes new agent_versions row. publish_agent({ agent_id, status: draft|test|live|paused }) — flips status. list_agents() — workspace-scoped roster with id/name/slug/channel/archetype/status/version/tokens/budget/created. (4) /api/v1/agents route extended with op='set_llm_key' handler so the new MCP tool routes through one endpoint. Validates provider ∈ {anthropic, openai}, api_key length ≥ 10, encrypts via encryptValue (returns 503 encryption_unavailable when ENCRYPTION_KEY env not set), merges into organizations.integrations preserving other providers' entries (kit, mailchimp, etc.). NO new migrations (0044 from v1.26.0 covers all agent tables). NO new env vars beyond ENCRYPTION_KEY (already required for the existing BYOK path). Backend redeploy + npm publish required. DEFERRED TO v1.26.2: SSE streaming on /turn; eval suite runner (executes scenarios from blocks/agent-website-chatbot/SKILL.md against the live agent); eval-gated publish (require ≥7/8 scenarios pass before flipping to live); /admin/agents/[id]/{conversations,test} debug surfaces; MCP debug tools (tail_agent_conversations, get_agent_conversation, replay_conversation, get_agent_metrics).",
+  "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.26.0: AGENT FOUNDATION — primitives for building chat / voice / SMS / email agents on top of Soul + Brain. Web chat archetype ships first; voice + SMS queued for v1.27/v1.28. Migration 0044 adds agents / agent_versions / agent_conversations / agent_turns / agent_evals tables. Schema (src/db/schema/agents.ts) typed with AgentBlueprint, AgentToolCall, AgentToolResult, AgentValidatorResult. System prompt composer (lib/agents/prompt.ts) derives prompts from Soul + blueprint, NEVER operator-authored — operators contribute knowledge (FAQ, services, pricing); platform owns the prompt. Five output validators (lib/agents/validators.ts) run on every assistant response: quotes_only_from_soul_pricing (critical — blocks hallucinated $X), no_prompt_injection_echo (critical — blocks 'ignore previous instructions' echoes), no_pii_leak (critical — blocks emails/phones not in user's message), no_avoid_words (warning — Soul voice rule), response_length_under_cap (warning — 600 chars). Critical fail = response replaced with 'let me check + escalate'. Five typed tools (lib/agents/tools.ts) with Zod input schemas: look_up_availability, book_appointment (wraps submitPublicBookingAction — same atomic primitive as /book), find_my_existing_appointment, escalate_to_human (writes portal_messages + activities), provide_faq_answer. Runtime (lib/agents/runtime.ts) executeTurn — loads conv + agent + soul, checks daily token budget, persists user turn, calls Anthropic with tools, loops on tool_use (max 6 iterations), runs validators, persists assistant turn with cost/latency, updates aggregates, activity-bridges first turn to operator's CRM. Non-streaming for v1.26.0; v1.26.1 adds SSE. Public turn endpoint POST /api/v1/public/agent/<orgSlug>--<agentSlug>/turn (anonymous; live/test status required). Agent CRUD endpoint POST /api/v1/agents (op: create | update_blueprint | publish | list — workspace bearer auth). createAgent generates slug, creates v1 in agent_versions, soul-derives blueprint defaults. blocks/agent-website-chatbot/SKILL.md documents the archetype + 8 eval scenarios including prompt-injection + PII-leak adversarial probes. NO new MCP tools yet (HTTP endpoint exposed; MCP-tool wiring + SSE streaming + embed.js + operator debug surfaces land in v1.26.1). NO new env vars beyond ANTHROPIC_API_KEY (already required). Backend redeploy required.",
   "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.25.4: operator 'Today' snapshot widget + remaining polish. NEW: replaces the v1.25.3 gap (where SF agency operators saw 'Newly installed blocks') with an operator-actionable 'Today' overview at the top of /dashboard. Four cards: today's bookings (count + first 3 with time/name), unread customer-portal messages, deals stuck >5 days (closedAt IS NULL + updatedAt < 5d ago), bookings-this-week trend. Each card click-throughs to its source surface (/bookings, /contacts, /deals). Below the cards: 'Up next' list of today's first 3 bookings rendered as time/name/title rows. All queries scoped by session orgId; widget renders only for isOperatorSession. POLISH: SeldonChat (the SF AI assistant floating button) hidden for operator sessions — that's an SF-builder tool. Command palette items split by session type — operator sessions only see Dashboard/Contacts/Deals/Bookings + their contact + deal hits; non-operator sessions get the full SF palette including Soul Marketplace, Studio, Seldon It, Pages, Email, Settings, Recent Activity. NO migrations, NO new env vars. Backend redeploy required.",
   "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.25.3: operator dashboard polish — hide SF-meta / SF-developer surfaces for operator sessions. From first principles: an HVAC owner / dentist doesn't have a build-time, doesn't speak block / soul / BLOCK.md, doesn't manage multiple workspaces, doesn't get support from SF Discord (their agency Acme AI is their support). Hides from /dashboard for operator sessions: (1) 'For the best experience, use Seldon directly from Claude Code with our MCP + Skill' hint banner — SF developer-facing. (2) 'Create New Client OS' button in the welcome header — agency-only action. (3) 'Newly installed blocks' section entirely — build-time SF-meta surface with View Public Page / Open Admin buttons. (4) 'BLOCK.md view metadata' subtitle on Pipeline section — replaced with 'Drag deals between stages to update their status' for operator sessions. (5) 'Docs' link in topbar — points at SF developer docs. (6) HelpButton floating popover — Discord / SF docs / report-a-bug links. (7) 'Discord' / 'Help' link from sidebar (already trimmed in v1.25.1; v1.25.3 fully removes it from operator nav). The welcome heading copy switches from 'This is your calm workspace overview' to 'Here's what's happening at your workspace today' for operator sessions — grounding the page in their business rather than SF-meta workspace concept. Each gate threaded via isOperatorSession prop from /(dashboard)/layout.tsx → DashboardTopbar / Sidebar / dashboard/page.tsx. NO migrations, NO new env vars. Backend redeploy required. v1.25.4 candidate (deferred): replace the now-empty top section with an operator-actionable 'Today snapshot' widget — count of today's bookings, deals needing attention, unread messages.",
   "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.25.2: TWO HOTFIXES from the v1.25.1 production smoke. (1) Operator session now PRECEDES NextAuth in helpers.ts. Pre-1.25.2 getCurrentUser/getOrgId/requireAuth checked NextAuth first, then operator-portal as a fallback. Smoke surfaced 2026-05-07: a user with BOTH a stale NextAuth cookie (from a prior /signup attempt that hit the Verification error) AND a fresh operator-portal cookie was treated as a NextAuth user — full SF admin nav showed instead of the trimmed operator nav. v1.25.2 reorders: operator portal cookie wins when present + valid. Falls through to NextAuth → admin-token otherwise. Intent-based — clicking an operator magic link clearly means the user wants operator portal access. Same precedence applied across getCurrentUser, getOrgId, requireAuth. (2) Dashboard page org_members + organizations queries now gate on isOperatorPortalUserId. Pre-1.25.2 the dashboard page had its own org_members lookup `where userId = synthetic-id` that bypassed the v1.25.0 helpers' opCtx check, crashing with PostgreSQL 22P02 'invalid input syntax for type uuid' (the synthetic id `__sf_operator_portal__:<orgId>` isn't a valid uuid). v1.25.2 short-circuits: when isOperatorPortalUserId(user.id), membershipRows = [{ orgId }] (the operator's single workspace) instead of querying org_members, and directWorkspaceRows queries by organizations.id only (skipping the ownerId/parentUserId clauses that also crash). Defense-in-depth: lib/billing/orgs.ts's listManagedOrganizations + listManagedOrganizationsForUser now early-return [] when user.id doesn't match the UUID_SHAPE regex (8-4-4-4-12 hex). NO migrations, NO new env vars. Backend redeploy required.",

package/src/tools.js

@@ -4039,6 +4039,214 @@ export const TOOLS = [
       return result;
     },
   },
+
+  // ── v1.26 — agent foundation ────────────────────────────────────────────
+  // Build agents (web chat / voice / SMS / email) on top of Soul + Brain.
+  // BYOK: operators bring their own LLM key (Anthropic / OpenAI) — they
+  // pay LLM bills directly to the provider. SF makes money per agent
+  // turn (separate billing). configure_llm_provider sets the key;
+  // create_agent registers a new agent draft; list_agents shows the
+  // workspace's agents.
+
+  {
+    name: "configure_llm_provider",
+    description:
+      "Set the LLM API key for this workspace's agents (BYOK — Bring Your Own Key). " +
+      "The OPERATOR pays the LLM provider directly (Anthropic / OpenAI / etc.); SF charges separately for agent platform usage. " +
+      "Stored encrypted at rest using the deployment's ENCRYPTION_KEY. " +
+      "Operators get keys from console.anthropic.com (recommended for v1.26.x — best tool-use support) or platform.openai.com. " +
+      "Call this BEFORE create_agent — agents fail-graceful with 'I'm not set up yet' if no key configured.",
+    inputSchema: obj(
+      {
+        workspace_id: str("Workspace id (bearer workspace)."),
+        provider: {
+          type: "string",
+          enum: ["anthropic", "openai"],
+          description:
+            "LLM provider. v1.26 ships full Anthropic support (tool use, streaming-ready). OpenAI support for chat is partial — recommend Anthropic for production agents.",
+        },
+        api_key: str(
+          "API key. Anthropic keys start with 'sk-ant-...'. Stored encrypted; never echoed back in responses.",
+        ),
+      },
+      ["workspace_id", "provider", "api_key"],
+    ),
+    handler: async (args) => {
+      const ws = args.workspace_id;
+      const result = await api("POST", "/agents", {
+        body: {
+          op: "set_llm_key",
+          provider: args.provider,
+          api_key: args.api_key,
+        },
+        workspace_id: ws,
+      });
+      return result;
+    },
+  },
+
+  {
+    name: "create_agent",
+    description:
+      "Create a new agent for this workspace. Agents are conversational interfaces (web chat, voice, SMS) that answer FAQs, book appointments, and escalate to humans — composed from typed primitives + the workspace's Soul (industry, voice, services). " +
+      "WHAT GETS COMPOSED AUTOMATICALLY: persona derived from soul.industry + soul.voice; FAQ knowledge from your `faq` array; pricing facts from `pricing_facts` (validators block any $-amount the agent invents that's not in this list); typed tools (look_up_availability, book_appointment, find_my_existing_appointment, escalate_to_human, provide_faq_answer). " +
+      "WHAT YOU PROVIDE: name, archetype (website-chatbot for v1.26.x; voice-receptionist + sms-followup-bot queued), channel (web_chat / voice / sms / email), inline FAQ pairs, allowed pricing facts, optional greeting. " +
+      "STATUS LIFECYCLE: created in 'draft' (not callable). Flip to 'test' to chat with it in sandbox (tool calls return synthetic results — no real bookings). Flip to 'live' once you're confident. v1.26.2 will add eval-gating that blocks 'live' until a test scenario suite passes. " +
+      "SAFETY: response validators run on every turn — quotes_only_from_soul_pricing (critical, blocks hallucinated $X), no_prompt_injection_echo (critical), no_pii_leak (critical), no_avoid_words (warning), response_length_under_cap (warning). Critical fail = agent says 'let me check + escalate' instead of sending the bad response. " +
+      "OUTPUT: the agent's embed URL (one-line <script> for the operator's website) and turn URL (POST endpoint for direct API integration).",
+    inputSchema: obj(
+      {
+        workspace_id: str("Workspace id (bearer workspace)."),
+        name: str(
+          "Agent display name (e.g. 'Cypress HVAC Assistant'). Surfaces in the chat header.",
+        ),
+        archetype: {
+          type: "string",
+          enum: ["website-chatbot", "voice-receptionist", "sms-followup-bot"],
+          description:
+            "Agent shape. v1.26.x ships website-chatbot with full feature support; voice-receptionist + sms-followup-bot are queued for v1.27/v1.28.",
+        },
+        channel: {
+          type: "string",
+          enum: ["web_chat", "voice", "sms", "email"],
+          description:
+            "Delivery channel. v1.26.x ships web_chat only (embed.js bubble). Other channels queued.",
+        },
+        faq: {
+          type: "array",
+          description:
+            "Operator-curated FAQ pairs. Each item is { q: string, a: string }. The agent has these in its system prompt; visitors get answers without an LLM round-trip when the question is a clear match. v1.27 adds vector RAG over uploaded docs.",
+          items: obj(
+            {
+              q: str("Question as a visitor would phrase it."),
+              a: str("Operator's exact answer (1-3 sentences)."),
+            },
+            ["q", "a"],
+          ),
+        },
+        pricing_facts: {
+          type: "array",
+          description:
+            "ONLY prices the agent may quote. Validators block any $-amount in the agent's response that's not in this list (or doesn't match exactly). If you want the agent to refuse all price questions, omit this. Each item: { label: string, amount: number, currency: 'USD' | etc. }",
+          items: obj(
+            {
+              label: str("Service name (e.g. 'Furnace tune-up')."),
+              amount: { type: "number" },
+              currency: str("3-letter currency code, e.g. USD."),
+            },
+            ["label", "amount", "currency"],
+          ),
+        },
+        greeting: str(
+          "Optional first message shown when the chat opens (default: 'Hi! How can I help you today?').",
+        ),
+        capabilities: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Optional explicit subset of typed tools the agent may call. Default: all five (look_up_availability, book_appointment, find_my_existing_appointment, escalate_to_human, provide_faq_answer). Restrict if you want a read-only agent (omit book_appointment) or a no-escalation agent (omit escalate_to_human).",
+        },
+      },
+      ["workspace_id", "name", "archetype", "channel"],
+    ),
+    handler: async (args) => {
+      const ws = args.workspace_id;
+      const result = await api("POST", "/agents", {
+        body: {
+          op: "create",
+          name: args.name,
+          archetype: args.archetype,
+          channel: args.channel,
+          faq: args.faq ?? undefined,
+          pricing_facts: args.pricing_facts ?? undefined,
+          greeting: args.greeting ?? undefined,
+          capabilities: args.capabilities ?? undefined,
+        },
+        workspace_id: ws,
+      });
+      return result;
+    },
+  },
+
+  {
+    name: "list_agents",
+    description:
+      "List all agents in this workspace with status (draft/test/live/paused), version, daily token usage vs budget, and metadata. Use to find an agent_id before calling publish_agent or update_agent_blueprint, or to audit which agents are live across a workspace.",
+    inputSchema: obj(
+      { workspace_id: str("Workspace id (bearer workspace).") },
+      ["workspace_id"],
+    ),
+    handler: async (args) => {
+      const ws = args.workspace_id;
+      const result = await api("POST", "/agents", {
+        body: { op: "list" },
+        workspace_id: ws,
+      });
+      return result;
+    },
+  },
+
+  {
+    name: "publish_agent",
+    description:
+      "Change an agent's status: draft → test (sandboxed playground; tools return synthetic results), test → live (real bookings, real escalations, customer-facing), live → paused (chat bubble disabled). v1.26.2 will add eval-gating that blocks 'live' until the agent's eval suite passes; for v1.26.x, the operator-side responsibility is to test in 'test' mode before flipping to 'live'.",
+    inputSchema: obj(
+      {
+        workspace_id: str("Workspace id (bearer workspace)."),
+        agent_id: str("Agent id from create_agent."),
+        status: {
+          type: "string",
+          enum: ["draft", "test", "live", "paused"],
+          description: "Target status.",
+        },
+      },
+      ["workspace_id", "agent_id", "status"],
+    ),
+    handler: async (args) => {
+      const ws = args.workspace_id;
+      const result = await api("POST", "/agents", {
+        body: { op: "publish", agent_id: args.agent_id, status: args.status },
+        workspace_id: ws,
+      });
+      return result;
+    },
+  },
+
+  {
+    name: "update_agent_blueprint",
+    description:
+      "Update an agent's blueprint (FAQ, pricing facts, greeting, capabilities). Bumps current_version + writes a new agent_versions row for rollback. The agent's status is unchanged — flip to test/live separately when you're ready. " +
+      "PATCH SEMANTICS: arrays REPLACE (not merge). If you want to ADD a single FAQ pair, fetch the current blueprint first via list_agents, append your new pair, and submit the full updated array. " +
+      "Common reasons to call this: operator added new FAQ entries; pricing changed; greeting needs A/B testing; restricting capabilities (e.g. removing book_appointment to make agent answer-only).",
+    inputSchema: obj(
+      {
+        workspace_id: str("Workspace id (bearer workspace)."),
+        agent_id: str("Agent id from create_agent."),
+        patch: {
+          type: "object",
+          description:
+            "Partial blueprint patch. Fields: faq, pricing_facts, greeting, capabilities, archetype. Arrays REPLACE.",
+        },
+        publish_notes: str(
+          "Optional one-line note for the audit log (e.g. 'Added emergency-call FAQ').",
+        ),
+      },
+      ["workspace_id", "agent_id", "patch"],
+    ),
+    handler: async (args) => {
+      const ws = args.workspace_id;
+      const result = await api("POST", "/agents", {
+        body: {
+          op: "update_blueprint",
+          agent_id: args.agent_id,
+          patch: args.patch,
+          publish_notes: args.publish_notes ?? undefined,
+        },
+        workspace_id: ws,
+      });
+      return result;
+    },
+  },
 ];
 
 export const TOOL_MAP = Object.fromEntries(TOOLS.map((t) => [t.name, t]));