@seldonframe/mcp 1.0.0

package/README.md

@@ -0,0 +1,112 @@
+# @seldonframe/mcp
+
+Official SeldonFrame MCP server for Claude Code and Claude Desktop.
+
+**One command, one real workspace.** The first time you run it, no API key is needed. Say `create_workspace({ name: "Dental Clinic Laval" })` and the server mints a real hosted workspace on `dental-clinic-laval.app.seldonframe.com` — with CRM, Cal.diy booking, Formbricks intake, and Brain v2 pre-installed — and returns live URLs. No signup wall, no "guest mode", no claim step.
+
+## 60-second quickstart
+
+```bash
+# 1. From the repo root
+cd skills/mcp-server && npm install
+
+# 2. Register with Claude Code — no env vars needed
+claude mcp add seldonframe -s user -- node "$(pwd)/src/index.js"
+
+# 3. In Claude Code, just ask:
+#    create_workspace({ name: "My Business OS" })
+```
+
+That call returns something like:
+
+```json
+{
+  "workspace": { "id": "wsp_…", "slug": "my-business-os", "tier": "free" },
+  "urls": {
+    "dashboard": "https://my-business-os.app.seldonframe.com",
+    "book": "https://my-business-os.app.seldonframe.com/book",
+    "intake": "https://my-business-os.app.seldonframe.com/intake"
+  },
+  "installed": ["crm", "caldiy-booking", "formbricks-intake", "brain-v2"],
+  "next": [ "…" ]
+}
+```
+
+Every subsequent tool response includes a `next:` array — follow the rails.
+
+## How auth works
+
+| Situation | What happens |
+|---|---|
+| First ever call | `create_workspace` POSTs with no auth. Server mints a workspace + bearer token. MCP stores the token in `~/.seldonframe/device.json`. |
+| Subsequent calls | MCP sends `Authorization: Bearer <workspace token>` automatically. |
+| `SELDONFRAME_API_KEY` set | Takes precedence over device tokens. Unlocks Pro capabilities. |
+
+You never have to juggle modes. The first workspace is free forever.
+
+## When you need `SELDONFRAME_API_KEY`
+
+- Adding a **second workspace**
+- Connecting a **custom domain**
+- **Full Brain v2** intelligence (heuristic Brain is always free)
+- Publishing, exporting, org-scoped secret rotation
+
+Get one at <https://app.seldonframe.com/settings/api>, then:
+
+```bash
+export SELDONFRAME_API_KEY=sk-…
+```
+
+Restart the MCP server. Your existing workspaces continue to work untouched.
+
+## Install via plugin manifest (one-shot)
+
+The repo ships a `.claude-plugin/plugin.json` at the root. From inside Claude Code:
+
+```
+/plugin install <path-to-repo>
+```
+
+## Install via npm
+
+```bash
+claude mcp add seldonframe -- npx -y @seldonframe/mcp
+```
+
+This is the canonical install command surfaced on the marketing site,
+the `/docs/quickstart` page, and the repo README. It uses `npx -y`
+so users never have to globally install anything; the latest version
+is fetched and run on demand.
+
+## Environment
+
+- `SELDONFRAME_API_KEY` *(optional)* — Enables Pro capabilities (second workspace, custom domains, full Brain v2).
+- `SELDONFRAME_API_BASE` *(optional)* — Override the API base URL. Defaults to `https://app.seldonframe.com/api/v1`.
+
+## Tools
+
+**Workspace:** `create_workspace`, `list_workspaces`, `switch_workspace`, `clone_workspace`, `link_workspace_owner`, `get_workspace_snapshot`.
+**Blocks:** `install_caldiy_booking`, `install_formbricks_intake`, `install_vertical_pack`.
+**Customize (typed, no backend LLM):** `update_landing_content`, `customize_intake_form`, `configure_booking`, `update_theme`.
+**Soul:** `fetch_source_for_soul`, `submit_soul`.
+**Ops:** `list_automations`, `connect_custom_domain`, `export_agent`, `store_secret`, `list_secrets`, `rotate_secret`.
+
+### Architecture: zero backend LLM cost
+
+Natural-language reasoning happens in the MCP session (Claude Code on the user's side). The backend only accepts **structured** commands and applies them deterministically. There is no `seldon_it` endpoint that parses prompts server-side; the old `query_brain` is replaced by `get_workspace_snapshot`, which returns raw state for Claude to reason over. Seldon spends $0 on LLM for the free tier — the user's Claude Code subscription is the reasoning engine.
+
+### Soul compilation (zero cost to Seldon)
+
+Soul compilation runs in **your** Claude Code session, not on Seldon's servers:
+
+1. `fetch_source_for_soul({ url })` — returns up to 256KB of normalized text.
+2. You (the agent) extract a structured Soul object.
+3. `submit_soul({ soul })` — persists it to the workspace.
+
+## Troubleshooting
+
+**`Seldon API 401`** — Your `SELDONFRAME_API_KEY` is invalid or expired. Regenerate at <https://app.seldonframe.com/settings/api>, or unset the env var to fall back to your device token.
+
+**`Seldon API 402`** — You tried a Pro capability without a key. Set `SELDONFRAME_API_KEY` and restart.
+
+**Want to reset device state?** Delete `~/.seldonframe/device.json`. Your hosted workspaces stay live at `app.seldonframe.com`; only the local tokens are cleared.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@seldonframe/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for SeldonFrame — AI-native Business OS platform. One command creates a real hosted workspace with CRM, booking, intake, and Brain v2.",
+  "type": "module",
+  "bin": {
+    "seldonframe-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "seldonframe",
+    "ai",
+    "agents",
+    "business-os",
+    "claude-code",
+    "crm"
+  ],
+  "license": "MIT",
+  "homepage": "https://seldonframe.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/seldonframe/seldonframe",
+    "directory": "skills/mcp-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.js

@@ -0,0 +1,194 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { VERSION } from "./welcome.js";
+
+const API_BASE =
+  process.env.SELDONFRAME_API_BASE ?? "https://app.seldonframe.com/api/v1";
+const API_KEY = process.env.SELDONFRAME_API_KEY;
+
+const SELDON_DIR = join(homedir(), ".seldonframe");
+const DEVICE_FILE = join(SELDON_DIR, "device.json");
+
+function loadDevice() {
+  if (!existsSync(DEVICE_FILE)) {
+    return { tokens: {}, default_workspace: null, created_at: null };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(DEVICE_FILE, "utf8"));
+    return {
+      tokens: parsed.tokens ?? {},
+      default_workspace: parsed.default_workspace ?? null,
+      created_at: parsed.created_at ?? null,
+    };
+  } catch {
+    return { tokens: {}, default_workspace: null, created_at: null };
+  }
+}
+
+function saveDevice(device) {
+  mkdirSync(SELDON_DIR, { recursive: true });
+  writeFileSync(DEVICE_FILE, JSON.stringify(device, null, 2));
+}
+
+export function rememberWorkspace({ workspace_id, bearer_token, make_default = true }) {
+  const d = loadDevice();
+  if (bearer_token) d.tokens[workspace_id] = bearer_token;
+  if (make_default || !d.default_workspace) d.default_workspace = workspace_id;
+  if (!d.created_at) d.created_at = new Date().toISOString();
+  saveDevice(d);
+}
+
+export function setDefaultWorkspace(workspace_id) {
+  const d = loadDevice();
+  d.default_workspace = workspace_id;
+  saveDevice(d);
+}
+
+// Remove a workspace's bearer token from the local device store. If it was the
+// default, clear the default pointer too. Used by revoke_bearer when the call
+// revokes the caller's own token — the device can't keep pretending it has
+// access.
+export function forgetWorkspace(workspace_id) {
+  const d = loadDevice();
+  delete d.tokens[workspace_id];
+  if (d.default_workspace === workspace_id) {
+    const remaining = Object.keys(d.tokens);
+    d.default_workspace = remaining[0] ?? null;
+  }
+  saveDevice(d);
+}
+
+export function getDefaultWorkspace() {
+  return loadDevice().default_workspace;
+}
+
+export function knownWorkspaceIds() {
+  return Object.keys(loadDevice().tokens);
+}
+
+export function hasApiKey() {
+  return !!API_KEY;
+}
+
+export function isFirstEverCall() {
+  const d = loadDevice();
+  return Object.keys(d.tokens).length === 0 && !API_KEY;
+}
+
+function resolveAuth(workspace_id) {
+  if (API_KEY) return `Bearer ${API_KEY}`;
+  const d = loadDevice();
+  const target = workspace_id ?? d.default_workspace;
+  if (target && d.tokens[target]) return `Bearer ${d.tokens[target]}`;
+  return null;
+}
+
+export function getWorkspaceBearer(workspace_id) {
+  const d = loadDevice();
+  const target = workspace_id ?? d.default_workspace;
+  if (!target) return null;
+  return d.tokens[target] ?? null;
+}
+
+export function getApiKey() {
+  return API_KEY ?? null;
+}
+
+function hintFor(status, data) {
+  if (status === 401) {
+    return " — credentials rejected. If you meant to use a paid capability, check SELDONFRAME_API_KEY at https://app.seldonframe.com/settings/api.";
+  }
+  if (status === 402) {
+    const need = data?.error?.requires ?? "a SeldonFrame API key";
+    return ` — this capability requires ${need}. Get one at https://app.seldonframe.com/settings/api and \`export SELDONFRAME_API_KEY=sk-…\`.`;
+  }
+  if (status === 409) {
+    return " — the requested resource already exists or conflicts with existing state.";
+  }
+  if (status === 429) return " — rate limited. Try again in a moment.";
+  return "";
+}
+
+export async function api(method, path, opts = {}) {
+  const {
+    body,
+    workspace_id,
+    allow_anonymous = false,
+    force_workspace_bearer = false,
+    extra_headers = {},
+  } = opts;
+
+  let auth = null;
+  if (force_workspace_bearer) {
+    const token = getWorkspaceBearer(workspace_id);
+    if (token) auth = `Bearer ${token}`;
+  } else {
+    auth = resolveAuth(workspace_id);
+  }
+
+  if (!auth && !allow_anonymous) {
+    throw new Error(
+      "No workspace available. Run create_workspace({ name: '…' }) first, or set SELDONFRAME_API_KEY.",
+    );
+  }
+  const headers = {
+    "Content-Type": "application/json",
+    "User-Agent": `seldonframe-mcp/${VERSION}`,
+    ...extra_headers,
+  };
+  if (auth) headers.Authorization = auth;
+
+  const res = await fetch(`${API_BASE}${path}`, {
+    method,
+    headers,
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : {};
+  } catch {
+    data = { raw: text };
+  }
+  if (!res.ok) {
+    const msg = data?.error?.message ?? data?.message ?? text ?? res.statusText;
+    throw new Error(`Seldon API ${res.status}: ${msg}${hintFor(res.status, data)}`);
+  }
+  return data;
+}
+
+export async function fetchText(url, { maxBytes = 256 * 1024 } = {}) {
+  const res = await fetch(url, {
+    headers: { "User-Agent": `seldonframe-mcp/${VERSION} (+soul-compiler)` },
+    redirect: "follow",
+  });
+  if (!res.ok) {
+    throw new Error(`Fetch ${url} failed: ${res.status} ${res.statusText}`);
+  }
+  const raw = await res.text();
+  const truncated = raw.length > maxBytes;
+  const html = truncated ? raw.slice(0, maxBytes) : raw;
+  return { html, truncated, status: res.status, final_url: res.url };
+}
+
+export function htmlToText(html) {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<noscript[\s\S]*?<\/noscript>/gi, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<(h[1-6]|p|li|br|div|section|article|header|footer)[^>]*>/gi, "\n")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+export const API_INFO = { base: API_BASE };

package/src/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { WELCOME_MARKDOWN, VERSION } from "./welcome.js";
+import { TOOLS, TOOL_MAP } from "./tools.js";
+
+const server = new Server(
+  { name: "seldonframe", version: VERSION },
+  {
+    capabilities: { tools: {} },
+    instructions: WELCOME_MARKDOWN,
+  },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map(({ name, description, inputSchema }) => ({
+    name,
+    description,
+    inputSchema,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = TOOL_MAP[req.params.name];
+  if (!tool) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }],
+    };
+  }
+  try {
+    const result = await tool.handler(req.params.arguments ?? {});
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }],
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);