@mangomagic/cli 0.1.5 → 0.1.7

package/README.md

@@ -20,8 +20,10 @@ at `~/.mangomagic/credentials.json` (mode 0600) so the next runs skip auth.
 | `mangomagic home` | Show fast wins after sign-in. |
 | `mangomagic chat` | Start an interactive natural-language session. |
 | `mangomagic ask "..."` | Run one natural-language request. |
-| `mangomagic tools` | Show available MCP tools and near-next workflows. Add `--json` for machine-readable output. |
-| `mangomagic cards` | Open the Talking Cards workspace. Add `--no-open` to print the URL only. |
+| `mangomagic tools` | Show the CLI/MCP catalog. Add `--all` for the full list or `--json` for machine-readable output. |
+| `mangomagic tool <name> '{"json":"args"}'` | Run the same tool exposed to MCP clients. |
+| `mangomagic cards "idea"` | Create talking cards in the terminal and save them to your library. Add `--count 3`. |
+| `mangomagic open cards` | Open the Talking Cards workspace in a browser. |
 | `mangomagic splash` | Show the splash once. `--anim`, `--loop` supported. |
 | `mangomagic mcp` | Run as a stdio MCP server. Wire into Claude Desktop / Cursor. |
 | `mangomagic mcp-config` | Print MCP client JSON for copy-paste. |
@@ -44,11 +46,18 @@ Add to Claude Desktop's `claude_desktop_config.json` (or Cursor's MCP settings):
 The MCP server uses the same token cached by `mangomagic login`, so make sure
 you sign in first.
 
+MCP exposes:
+
+- Core user tools such as `list_episodes`, `get_episode`, and `search_episodes`.
+- First-class MangoMagic business tools such as `get_user_stats`, `get_user_clips`, `create_clip`, `qualify_leads`, and `generate_viral_caption`.
+- Admin/raw Edge Function tools prefixed with `edge_`, for example `edge_generate_carousels`. These go through a server-side runner with role checks and dry-run protection for webhook/auth/billing callbacks.
+
 ## Natural language
 
 ```bash
 npx -y @mangomagic/cli chat
 npx -y @mangomagic/cli create talking cards about AI adoption
+npx -y @mangomagic/cli cards "why founder-led sales stalls" --count 3
 ```
 
 Obvious requests are handled locally. Fuzzy routing uses MangoMagic's backend AI

package/bin/mangomagic.mjs

@@ -2,6 +2,12 @@
 // MangoMagic CLI entrypoint. Pure-Node, ESM, zero deps (MCP server uses
 // @modelcontextprotocol/sdk loaded lazily on demand).
 import { run } from "../src/index.mjs";
+
+process.stdout.on("error", (err) => {
+  if (err?.code === "EPIPE") process.exit(0);
+  throw err;
+});
+
 run(process.argv.slice(2)).catch((err) => {
   process.stderr.write(`\nmangomagic: ${err?.message ?? err}\n`);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mangomagic/cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "MangoMagic CLI — sign in, manage episodes, and expose MangoMagic to MCP clients (Claude Desktop, Cursor).",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -19,8 +19,13 @@ export async function apiCall(path, { method = "POST", body, query } = {}) {
   const text = await res.text();
   let json; try { json = JSON.parse(text); } catch { json = { raw: text }; }
   if (res.status === 401) {
-    clearToken();
-    throw new Error("Your CLI token was rejected. Run `mangomagic login` again.");
+    const message = json.error ?? json.raw ?? "";
+    const tokenWasChecked = path.startsWith("cli-") || /not_authenticated|token_revoked|token_expired/i.test(String(message));
+    if (tokenWasChecked) {
+      clearToken();
+      throw new Error("Your CLI token was rejected. Run `mangomagic login` again.");
+    }
+    throw new Error(`${path} rejected the CLI token. This backend function may need the CLI-auth bridge deployed.`);
   }
   if (!res.ok) throw new Error(json.error ?? `HTTP ${res.status}`);
   return json;

package/src/chat/natural-language.mjs

@@ -2,6 +2,8 @@ import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { apiCall } from "../api.mjs";
 import { planWithKimi } from "../ai/kimi.mjs";
+import { ALL_MCP_TOOL_CATALOG } from "../tools/catalog.mjs";
+import { runCatalogTool } from "../tools/run.mjs";
 
 const GOLD = "\x1b[38;2;241;171;28m";
 const DIM = "\x1b[2m";
@@ -22,7 +24,7 @@ function localPlan(text) {
     return { action: "open_brand_doc", args: {} };
   }
   if (t.includes("talking card") || t.includes("carousel") || /\bcards?\b/.test(t)) {
-    return { action: "open_cards", args: { focus: raw } };
+    return { action: "create_talking_cards", args: { focus: raw, count: inferCount(raw) } };
   }
   if (t.includes("mcp") && (t.includes("config") || t.includes("connect") || t.includes("claude") || t.includes("cursor") || t.includes("codex"))) {
     return { action: "mcp_config", args: {} };
@@ -40,6 +42,12 @@ function localPlan(text) {
   return null;
 }
 
+function inferCount(text) {
+  const match = text.match(/(?:^|\s)(?:make|create|generate)?\s*(\d{1,2})\s+(?:talking\s+)?cards?\b/i);
+  if (!match) return 3;
+  return Math.max(1, Math.min(Number(match[1]), 10));
+}
+
 function asArray(data) {
   if (Array.isArray(data)) return data;
   if (Array.isArray(data?.episodes)) return data.episodes;
@@ -76,12 +84,71 @@ function printEpisode(data) {
   if (ep.id) process.stdout.write(`\n${DIM}${ep.id}${RESET}\n`);
 }
 
+function cardUrl(card) {
+  return card?.id ? `https://mangomagic.live/carousels/${card.id}` : null;
+}
+
+export function printCards(result) {
+  const cards = Array.isArray(result?.carousels) ? result.carousels : [];
+  if (!cards.length) {
+    process.stdout.write("No cards were created.\n");
+    return;
+  }
+
+  process.stdout.write(`${BOLD}Created ${cards.length} talking card${cards.length === 1 ? "" : "s"}.${RESET}\n\n`);
+  for (const [idx, card] of cards.entries()) {
+    process.stdout.write(`${GOLD}${idx + 1}. ${card.title || "Untitled card"}${RESET}\n`);
+    if (card.seam) process.stdout.write(`   ${DIM}${card.seam}${RESET}\n`);
+    const slides = Array.isArray(card?.spec?.slides) ? card.spec.slides : [];
+    for (const slide of slides.slice(0, 8)) {
+      const line = (slide.lines || []).map((l) => l.text).filter(Boolean).join(" / ");
+      if (line) process.stdout.write(`   - ${line}\n`);
+    }
+    if (card.caption) process.stdout.write(`\n   Caption: ${card.caption.replace(/\n/g, "\n            ")}\n`);
+    const url = cardUrl(card);
+    if (url) process.stdout.write(`   Edit: ${url}\n`);
+    process.stdout.write("\n");
+  }
+}
+
+export async function createTalkingCards({ focus, count = 3 } = {}) {
+  const cleanFocus = compact(focus);
+  if (!cleanFocus) {
+    process.stdout.write(`Give me an idea, for example:\n  ${GOLD}mangomagic cards "why founder-led sales stalls" --count 3${RESET}\n`);
+    return;
+  }
+
+  process.stdout.write(`${DIM}Creating ${count} talking card${count === 1 ? "" : "s"}...${RESET}\n`);
+  try {
+    const result = await apiCall("cli-create-talking-cards", {
+      body: { focus: cleanFocus, count: Math.max(1, Math.min(Number(count || 3), 10)) },
+    });
+    printCards(result);
+  } catch (err) {
+    const message = err?.message ?? String(err);
+    if (message.includes("HTTP 404")) {
+      process.stdout.write(`${BOLD}The terminal card-creation backend is not deployed yet.${RESET}\n`);
+      process.stdout.write(`This CLI is ready, but MangoMagic Cloud still needs the \`cli-create-talking-cards\` function deployed.\n`);
+      return;
+    }
+    throw err;
+  }
+}
+
 export async function handleNaturalLanguage(text, actions, { allowModel = true } = {}) {
   let plan = localPlan(text);
   if (!plan && allowModel) {
     try {
       plan = await planWithKimi(text, {
-        availableTools: ["open_cards", "open_brand_doc", "show_tools", "mcp_config", "list_episodes", "search_episodes", "get_episode", "home"],
+        availableTools: [
+          "create_talking_cards",
+          "open_cards",
+          "open_brand_doc",
+          "show_tools",
+          "mcp_config",
+          "home",
+          ...ALL_MCP_TOOL_CATALOG.map((tool) => tool.name),
+        ],
       });
     } catch (err) {
       process.stdout.write(`
@@ -107,6 +174,8 @@ ${DIM}${err?.message ?? err}${RESET}
   switch (action) {
     case "exit":
       return "exit";
+    case "create_talking_cards":
+      return createTalkingCards({ focus: args.focus || text, count: args.count || 3 });
     case "open_cards":
       return actions.cards({ path: "/carousels/generate", focus: args.focus });
     case "open_brand_doc":
@@ -137,6 +206,15 @@ ${DIM}${err?.message ?? err}${RESET}
       const data = await apiCall("cli-get-episode", { body: { episode: args.episode } });
       return printEpisode(data);
     }
+    case "run_tool": {
+      if (!args.toolName) {
+        process.stdout.write("Which tool should I run?\n");
+        return;
+      }
+      const data = await runCatalogTool(args.toolName, args.args || {});
+      process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+      return;
+    }
     case "answer":
       process.stdout.write(`${args.text || "I can help with MangoMagic episodes, talking cards, and MCP setup."}\n`);
       return;

package/src/index.mjs

@@ -1,9 +1,10 @@
 import { deviceLogin } from "./auth/device-flow.mjs";
-import { chat, handleNaturalLanguage } from "./chat/natural-language.mjs";
+import { chat, createTalkingCards, handleNaturalLanguage } from "./chat/natural-language.mjs";
 import { loadToken, saveToken, clearToken, credentialsPath } from "./auth/token-store.mjs";
 import { APP_ORIGIN } from "./config.mjs";
 import { openUrl } from "./system/open-url.mjs";
-import { COMMAND_PREFIX, MCP_TOOL_CATALOG, NEXT_WORKFLOWS, QUICK_WINS } from "./tools/catalog.mjs";
+import { ALL_MCP_TOOL_CATALOG, COMMAND_PREFIX, MCP_TOOL_CATALOG, NEXT_WORKFLOWS, QUICK_WINS } from "./tools/catalog.mjs";
+import { runCatalogTool } from "./tools/run.mjs";
 import { playSplash } from "./ui/splash.mjs";
 
 const GOLD = "\x1b[38;2;241;171;28m";
@@ -21,7 +22,9 @@ ${BOLD}mangomagic${RESET}  ${DIM}— sign into MangoMagic and bring your account
   ${GOLD}mangomagic home${RESET}        Show fast wins for creating value right now.
   ${GOLD}mangomagic chat${RESET}        Talk to MangoMagic in natural language.
   ${GOLD}mangomagic tools${RESET}       Show available MCP tools and next workflows.
-  ${GOLD}mangomagic cards${RESET}       Open the Talking Cards workspace.
+  ${GOLD}mangomagic tool <name>${RESET} Run a CLI/MCP tool with optional JSON args.
+  ${GOLD}mangomagic cards "idea"${RESET} Create talking cards in the terminal.
+  ${GOLD}mangomagic open cards${RESET}  Open the Talking Cards workspace in a browser.
   ${GOLD}mangomagic splash${RESET}      Show the MangoMagic splash once. Add --anim or --loop for motion.
   ${GOLD}mangomagic mcp${RESET}         Run as a stdio MCP server (for Claude Desktop / Cursor).
   ${GOLD}mangomagic mcp-config${RESET}  Print MCP client config for copy-paste.
@@ -58,10 +61,10 @@ ${DIM}Token cache:${RESET} ${credentialsPath()}
 `);
 }
 
-function tools({ json = false } = {}) {
+function tools({ json = false, all = false } = {}) {
   if (json) {
     process.stdout.write(JSON.stringify({
-      mcpTools: MCP_TOOL_CATALOG,
+      mcpTools: ALL_MCP_TOOL_CATALOG,
       quickWins: QUICK_WINS,
       nextWorkflows: NEXT_WORKFLOWS,
     }, null, 2) + "\n");
@@ -71,13 +74,35 @@ function tools({ json = false } = {}) {
   process.stdout.write(`
 ${BOLD}MangoMagic MCP Tools${RESET}
 
-${DIM}Available now:${RESET}
+${DIM}Core tools available now:${RESET}
 `);
   for (const tool of MCP_TOOL_CATALOG) {
     process.stdout.write(`  ${GOLD}${tool.name.padEnd(18)}${RESET} ${tool.description}\n`);
     process.stdout.write(`  ${DIM}${"".padEnd(18)} Try: ${tool.example}${RESET}\n`);
   }
 
+  process.stdout.write(`
+${DIM}Catalog:${RESET} ${ALL_MCP_TOOL_CATALOG.length} tools total (${MCP_TOOL_CATALOG.length} core, ${ALL_MCP_TOOL_CATALOG.length - MCP_TOOL_CATALOG.length} business/admin/raw tools).
+${DIM}Run:${RESET} ${GOLD}mangomagic tool get_user_stats${RESET}
+${DIM}Run with JSON:${RESET} ${GOLD}mangomagic tool get_user_episodes '{"limit":3}'${RESET}
+${DIM}Full list:${RESET} ${GOLD}mangomagic tools --all${RESET}
+`);
+
+  if (all) {
+    const byCategory = new Map();
+    for (const tool of ALL_MCP_TOOL_CATALOG) {
+      const category = tool.category || "core";
+      byCategory.set(category, [...(byCategory.get(category) || []), tool]);
+    }
+    for (const [category, rows] of [...byCategory.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      process.stdout.write(`\n${BOLD}${category}${RESET}\n`);
+      for (const tool of rows) {
+        process.stdout.write(`  ${GOLD}${tool.name}${RESET} ${DIM}${tool.description}${RESET}\n`);
+      }
+    }
+    process.stdout.write("\n");
+  }
+
   process.stdout.write(`
 ${DIM}Next high-value workflows to wire in:${RESET}
 `);
@@ -90,6 +115,27 @@ ${DIM}Use \`mangomagic mcp-config\` to connect an MCP client.${RESET}
 `);
 }
 
+function parseJsonArgs(raw) {
+  const text = raw.join(" ").trim();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Tool arguments must be JSON. Example: mangomagic tool get_user_episodes '{"limit":3}'`);
+  }
+}
+
+async function runToolCommand(argv) {
+  const name = argv[0];
+  if (!name) {
+    process.stdout.write(`Name a tool to run. See ${GOLD}mangomagic tools --all${RESET}\n`);
+    return;
+  }
+  const args = parseJsonArgs(argv.slice(1));
+  const result = await runCatalogTool(name, args);
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+}
+
 async function login({ openInBrowser = true } = {}) {
   if (loadToken()) {
     process.stdout.write(`${DIM}You're already signed in. Run \`mangomagic logout\` first to switch accounts.${RESET}\n`);
@@ -148,6 +194,25 @@ function cards({ openInBrowser = process.env.MANGOMAGIC_CLI_NO_OPEN !== "1", pat
   if (focus) process.stdout.write(`${DIM}Idea: ${focus}${RESET}\n`);
 }
 
+function parseCount(argv, fallback = 3) {
+  const flagIndex = argv.findIndex((v) => v === "--count" || v === "-n");
+  if (flagIndex >= 0 && argv[flagIndex + 1]) return Math.max(1, Math.min(Number(argv[flagIndex + 1]), 10));
+  const inline = argv.find((v) => /^--count=/.test(v));
+  if (inline) return Math.max(1, Math.min(Number(inline.split("=")[1]), 10));
+  return fallback;
+}
+
+function stripFlags(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const v = argv[i];
+    if (v === "--count" || v === "-n") { i++; continue; }
+    if (v.startsWith("--count=")) continue;
+    out.push(v);
+  }
+  return out;
+}
+
 async function mcpServer() {
   // Lazy-load so users who only run `login` don't pay the import cost.
   const { startMcpServer } = await import("./mcp/server.mjs");
@@ -179,8 +244,12 @@ export async function run(argv) {
     case "home":       return home();
     case "chat":       return chat(actions());
     case "ask":        return handleNaturalLanguage(argv.slice(1).join(" "), actions());
-    case "tools":      return tools({ json: argv.includes("--json") });
-    case "cards":      return cards({ openInBrowser: !argv.includes("--no-open") && process.env.MANGOMAGIC_CLI_NO_OPEN !== "1" });
+    case "tools":      return tools({ json: argv.includes("--json"), all: argv.includes("--all") });
+    case "tool":       return runToolCommand(argv.slice(1));
+    case "cards":      return createTalkingCards({ focus: stripFlags(argv.slice(1)).join(" "), count: parseCount(argv.slice(1)) });
+    case "open":
+      if (argv[1] === "cards" || argv[1] === "carousels") return cards({ openInBrowser: !argv.includes("--no-open") && process.env.MANGOMAGIC_CLI_NO_OPEN !== "1" });
+      return openPath(`/${argv[1] || ""}`);
     case "splash":     return playSplash({ mode: argv.includes("--loop") ? "loop" : argv.includes("--anim") ? "anim" : "static" });
     case "mcp":        return mcpServer();
     case "mcp-config": return mcpConfig();

package/src/mcp/server.mjs

@@ -1,26 +1,15 @@
-// Stdio MCP server exposing a small set of MangoMagic tools to clients like
-// Claude Desktop and Cursor. All tools call existing edge functions using the
-// user's CLI PAT cached at ~/.mangomagic/credentials.json.
+// Stdio MCP server exposing MangoMagic tools to clients like Claude Desktop
+// and Cursor. All tools call backend functions using the user's CLI PAT cached
+// at ~/.mangomagic/credentials.json.
 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 { apiCall } from "../api.mjs";
 import { loadToken } from "../auth/token-store.mjs";
-import { MCP_TOOL_CATALOG } from "../tools/catalog.mjs";
-
-const TOOL_HANDLERS = {
-  list_episodes: async ({ limit = 10 }) => apiCall("cli-list-episodes", { body: { limit } }),
-  get_episode: async ({ episode }) => apiCall("cli-get-episode", { body: { episode } }),
-  search_episodes: async ({ query }) => apiCall("cli-search-episodes", { body: { query } }),
-};
-
-const TOOLS = MCP_TOOL_CATALOG.map((tool) => ({
-  ...tool,
-  handler: TOOL_HANDLERS[tool.name],
-}));
+import { ALL_MCP_TOOL_CATALOG } from "../tools/catalog.mjs";
+import { runCatalogTool } from "../tools/run.mjs";
 
 export async function startMcpServer() {
   if (!loadToken()) {
@@ -34,16 +23,16 @@ export async function startMcpServer() {
   );
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+    tools: ALL_MCP_TOOL_CATALOG.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
   }));
 
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
-    const tool = TOOLS.find(t => t.name === req.params.name);
+    const tool = ALL_MCP_TOOL_CATALOG.find(t => t.name === 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 ?? {});
+      const result = await runCatalogTool(req.params.name, req.params.arguments ?? {});
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (err) {
       return {

package/src/tools/catalog.mjs

@@ -1,4 +1,6 @@
 import { APP_ORIGIN } from "../config.mjs";
+import { EDGE_FUNCTION_TOOL_CATALOG } from "./edge-functions.mjs";
+import { MAGIC_TOOL_CATALOG } from "./magic-catalog.mjs";
 
 export const COMMAND_PREFIX = "npx -y @mangomagic/cli";
 
@@ -38,14 +40,32 @@ export const MCP_TOOL_CATALOG = [
     },
     example: "Use MangoMagic to search my episodes for customer discovery.",
   },
+  {
+    name: "create_talking_cards",
+    description: "Generate branded LinkedIn-ready talking cards from a short idea and save them as draft carousels.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        focus: { type: "string", description: "The idea, theme, or LinkedIn angle to turn into cards" },
+        count: { type: "integer", minimum: 1, maximum: 10, default: 3 },
+      },
+      required: ["focus"],
+    },
+    example: "Use MangoMagic to create three talking cards about why founder-led sales stalls.",
+  },
+];
+
+export const ALL_MCP_TOOL_CATALOG = [
+  ...MCP_TOOL_CATALOG,
+  ...MAGIC_TOOL_CATALOG,
+  ...EDGE_FUNCTION_TOOL_CATALOG,
 ];
 
 export const QUICK_WINS = [
   {
-    command: `${COMMAND_PREFIX} cards`,
+    command: `${COMMAND_PREFIX} cards "why founder-led sales stalls" --count 3`,
     title: "Create Talking Cards",
-    description: "Open the card workspace, build a Brand Doc, choose colours, and generate LinkedIn-ready cards.",
-    url: `${APP_ORIGIN}/carousels`,
+    description: "Generate LinkedIn-ready talking cards from the terminal and save them to your library.",
     status: "ready",
   },
   {
@@ -63,7 +83,7 @@ export const QUICK_WINS = [
   {
     command: `${COMMAND_PREFIX} tools`,
     title: "See Every Tool",
-    description: "Show the full MCP tool list plus the next high-value workflows to wire in.",
+    description: "Show the full CLI/MCP tool catalog, including business tools and admin Edge Functions.",
     status: "ready",
   },
 ];
@@ -71,7 +91,7 @@ export const QUICK_WINS = [
 export const NEXT_WORKFLOWS = [
   {
     name: "create_talking_cards",
-    description: "Generate a batch of branded cards from a short idea, saved to the user's carousel library.",
+    description: "Generate a batch of branded talking cards from a short idea, saved to the user's carousel library.",
   },
   {
     name: "sync_linkedin_brand_context",

package/src/tools/edge-functions.mjs

@@ -0,0 +1,214 @@
+export const EDGE_FUNCTION_NAMES = [
+  "add-calendar-event",
+  "add-credits",
+  "ai-fill-missing-data",
+  "analyze-guests",
+  "analyze-highlights",
+  "analyze-inbox-message",
+  "analyze-logs",
+  "analyze-reply",
+  "application-email-cron",
+  "approve-log-fixes",
+  "attribute-referral",
+  "auto-create-episode",
+  "auto-topup",
+  "batch-process-all-episodes",
+  "bulk-process-pending-episodes",
+  "cancel-booking",
+  "check-subscription",
+  "clay-receive-company",
+  "clay-receive-email",
+  "clay-receive-mobile",
+  "clay-receive-people",
+  "cli-ai-route",
+  "cli-create-talking-cards",
+  "client-error-log",
+  "create-booking",
+  "create-checkout",
+  "customer-portal",
+  "deduct-credits",
+  "detect-stale-processing",
+  "download-episode-video",
+  "draft-demographic-doc",
+  "draft-inbox-reply",
+  "draft-reply",
+  "elevenlabs-health-check",
+  "elevenlabs-scribe-token",
+  "email-sequence-cron",
+  "email-unsubscribe",
+  "enrich-episode-content",
+  "enrich-guest-profile",
+  "enrich-profile-company",
+  "enrich-visitor",
+  "enterprise-onboarding-ai",
+  "enterprise-send-invitation",
+  "enterprise-trigger-enrichment",
+  "enterprise-validate-invitation",
+  "episode-share",
+  "estimate-processing-cost",
+  "extract-clip",
+  "fix-episode-urls",
+  "fix-referral-codes",
+  "fix-stuck-episodes",
+  "generate-carousels",
+  "generate-content",
+  "generate-email-sequence",
+  "generate-episode",
+  "generate-episode-articles",
+  "generate-episode-clips",
+  "generate-episode-og-image",
+  "generate-episode-transcript",
+  "generate-og-image",
+  "generate-outreach-email",
+  "generate-personalized-onboarding-email",
+  "generate-referral-code",
+  "generate-spike-og-image",
+  "generate-transcript",
+  "generate-use-cases",
+  "generate-video-thumbnail",
+  "generate-viral-caption",
+  "generate-visitor-email",
+  "get-host-availability",
+  "get-mango-network-stats",
+  "get-signed-url",
+  "gold-coach",
+  "google-drive-upload",
+  "grant-daily-referral-bonus",
+  "host-assistant",
+  "import-from-gdrive",
+  "import-gcs-episodes",
+  "import-google-sheet",
+  "linkedin-ads-accounts",
+  "linkedin-ads-analytics",
+  "linkedin-ads-auth",
+  "linkedin-ads-campaigns",
+  "linkedin-archive-reminder",
+  "linkedin-auth",
+  "linkedin-end-event-beacon",
+  "linkedin-post-carousel",
+  "linkedin-publish",
+  "linkedin-refresh-stats",
+  "linkedin-stream",
+  "livekit-token",
+  "log-analysis-cron",
+  "magic-assistant",
+  "magic-import",
+  "mango-schedule",
+  "migrate-drive-video",
+  "migrate-guest-photos",
+  "notify-admin-email",
+  "notify-host-join",
+  "notify-linkedin-lead",
+  "parse-display-name",
+  "process-email-queue",
+  "process-episode-complete",
+  "process-episodes-batch",
+  "process-first-pod-referral",
+  "process-pending-episodes",
+  "process-podcast",
+  "process-revenue-share",
+  "process-subscription-referral",
+  "proxy-gdrive-video",
+  "proxy-recording",
+  "qc-email",
+  "qualify-leads",
+  "rb2b-webhook",
+  "recalculate-referral-tier",
+  "recover-all-stuck-videos",
+  "recover-orphan-recordings",
+  "regenerate-episode-section",
+  "request-magic-link",
+  "resend-inbound-webhook",
+  "reset-free-credits",
+  "retry-enrichment",
+  "sales-call-coach",
+  "save-highlight-clip",
+  "save-transcript",
+  "seed-discover-episodes",
+  "send-admin-reply",
+  "send-application-confirmation",
+  "send-application-sequence-email",
+  "send-auth-email",
+  "send-booking-request",
+  "send-leads-qualified",
+  "send-meeting-invite",
+  "send-meeting-summary",
+  "send-recording-complete",
+  "send-referral-notification",
+  "send-sequence-email",
+  "send-visitor-email",
+  "send-welcome-email",
+  "social-share",
+  "stripe-webhook",
+  "sync-discover-to-leads",
+  "sync-resend-inbox",
+  "track-email",
+  "trigger-enrichment",
+  "update-referral-code",
+  "upload-recording",
+  "upload-recording-chunk",
+  "validate-referral-code",
+  "verify-magic-link",
+  "visitor-email-cron",
+];
+
+const CATEGORY_PREFIXES = [
+  ["linkedin", "linkedin"],
+  ["generate", "generation"],
+  ["send", "messaging"],
+  ["process", "processing"],
+  ["import", "import"],
+  ["sync", "sync"],
+  ["fix", "maintenance"],
+  ["recover", "maintenance"],
+  ["cron", "scheduled"],
+  ["webhook", "webhook"],
+  ["stripe", "billing"],
+  ["episode", "episodes"],
+  ["booking", "bookings"],
+  ["enrich", "enrichment"],
+  ["analyze", "analysis"],
+  ["draft", "drafting"],
+  ["upload", "upload"],
+  ["download", "download"],
+  ["save", "save"],
+  ["cli", "cli"],
+];
+
+export function edgeToolName(functionName) {
+  return `edge_${functionName.replace(/-/g, "_")}`;
+}
+
+export function functionNameFromEdgeTool(toolName) {
+  if (!toolName.startsWith("edge_")) return null;
+  const functionName = toolName.slice("edge_".length).replace(/_/g, "-");
+  return EDGE_FUNCTION_NAMES.includes(functionName) ? functionName : null;
+}
+
+function categoryFor(functionName) {
+  const found = CATEGORY_PREFIXES.find(([prefix]) => functionName.startsWith(prefix) || functionName.includes(`-${prefix}`));
+  return found?.[1] || "edge";
+}
+
+export const EDGE_FUNCTION_TOOL_CATALOG = EDGE_FUNCTION_NAMES.map((functionName) => ({
+  name: edgeToolName(functionName),
+  backendName: functionName,
+  category: categoryFor(functionName),
+  rawEdgeFunction: true,
+  description: `Admin/raw Edge Function invocation for \`${functionName}\`. Use first-class MangoMagic tools when available; this is for operational access.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      input: {
+        type: "object",
+        description: "JSON body to send to the Edge Function.",
+        additionalProperties: true,
+      },
+      dryRun: {
+        type: "boolean",
+        description: "When true, validates and describes the invocation without running it.",
+        default: true,
+      },
+    },
+  },
+}));

package/src/tools/magic-catalog.mjs

@@ -0,0 +1,345 @@
+export const MAGIC_TOOL_CATALOG = [
+  {
+    name: "get_user_episodes",
+    backendName: "get_user_episodes",
+    category: "episodes",
+    description: "Fetch the signed-in user's episodes, recordings, or content.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Maximum number of episodes to return", default: 5 },
+        status: { type: "string", enum: ["all", "published", "draft"], description: "Filter by publication status" },
+      },
+    },
+  },
+  {
+    name: "get_user_clips",
+    backendName: "get_user_clips",
+    category: "clips",
+    description: "Fetch the signed-in user's video clips and highlights.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Maximum number of clips to return", default: 5 },
+      },
+    },
+  },
+  {
+    name: "get_user_leads",
+    backendName: "get_user_leads",
+    category: "leads",
+    description: "Fetch leads, LinkedIn connections, guests, or contacts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        stage: { type: "string", enum: ["all", "new", "contacted", "scheduled", "booked", "declined"], description: "Pipeline stage" },
+        limit: { type: "number", description: "Maximum number of leads to return", default: 10 },
+      },
+    },
+  },
+  {
+    name: "get_user_stats",
+    backendName: "get_user_stats",
+    category: "account",
+    description: "Get account stats including level, XP, streak, episodes count, plan, and credits.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "get_upcoming_meetings",
+    backendName: "get_upcoming_meetings",
+    category: "meetings",
+    description: "Get upcoming scheduled meetings and recording sessions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "Maximum number of meetings to return", default: 5 },
+      },
+    },
+  },
+  {
+    name: "search_user_episodes",
+    backendName: "search_episodes",
+    category: "episodes",
+    description: "Search the signed-in user's episodes by title, guest name, or topic.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "get_achievements",
+    backendName: "get_achievements",
+    category: "account",
+    description: "Get achievement progress and unlocked badges.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "create_clip",
+    backendName: "create_clip",
+    category: "clips",
+    description: "Create a highlight clip from an episode recording.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        episodeId: { type: "string", description: "Episode ID" },
+        startTime: { type: "number", description: "Start time in seconds" },
+        endTime: { type: "number", description: "End time in seconds" },
+        title: { type: "string", description: "Optional clip title" },
+      },
+      required: ["episodeId", "startTime", "endTime"],
+    },
+  },
+  {
+    name: "enrich_lead",
+    backendName: "enrich_lead",
+    category: "leads",
+    description: "Prepare enrichment for a lead to get contact/company data.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        leadId: { type: "string", description: "Lead ID" },
+        enrichmentType: { type: "string", enum: ["full", "email", "mobile", "company"], default: "full" },
+      },
+      required: ["leadId"],
+    },
+  },
+  {
+    name: "send_outreach_email",
+    backendName: "send_outreach_email",
+    category: "leads",
+    description: "Draft or prepare sending an outreach email to a lead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        leadId: { type: "string", description: "Lead ID" },
+        angle: { type: "string", description: "Outreach angle or topic" },
+        send: { type: "boolean", description: "Whether to send or only draft", default: false },
+      },
+      required: ["leadId"],
+    },
+  },
+  {
+    name: "schedule_meeting",
+    backendName: "schedule_meeting",
+    category: "meetings",
+    description: "Create a new meeting or recording session.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Meeting name" },
+        scheduledAt: { type: "string", description: "ISO date/time" },
+        guestEmail: { type: "string", description: "Optional guest email" },
+      },
+      required: ["name"],
+    },
+  },
+  {
+    name: "get_transcript",
+    backendName: "get_transcript",
+    category: "episodes",
+    description: "Get the transcript for an episode.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        episodeId: { type: "string", description: "Episode ID" },
+      },
+      required: ["episodeId"],
+    },
+  },
+  {
+    name: "update_episode",
+    backendName: "update_episode",
+    category: "episodes",
+    description: "Prepare metadata updates for an episode.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        episodeId: { type: "string", description: "Episode ID" },
+        title: { type: "string", description: "New title" },
+        description: { type: "string", description: "New description" },
+        isPublic: { type: "boolean", description: "Public/private visibility" },
+        seoTitle: { type: "string", description: "SEO title" },
+        seoDescription: { type: "string", description: "SEO description" },
+      },
+      required: ["episodeId"],
+    },
+  },
+  {
+    name: "upload_video_url",
+    backendName: "upload_video_url",
+    category: "episodes",
+    description: "Prepare importing a video URL into a full episode page.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        videoUrl: { type: "string", description: "YouTube, Vimeo, or direct video URL" },
+        title: { type: "string", description: "Optional title" },
+      },
+      required: ["videoUrl"],
+    },
+  },
+  {
+    name: "generate_viral_caption",
+    backendName: "generate_viral_caption",
+    category: "social",
+    description: "Generate a viral LinkedIn/social caption for a clip.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        clipId: { type: "string", description: "Clip ID" },
+      },
+      required: ["clipId"],
+    },
+  },
+  {
+    name: "generate_transcript",
+    backendName: "generate_transcript",
+    category: "episodes",
+    description: "Prepare transcript generation for an episode that has a recording.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        episodeId: { type: "string", description: "Episode ID" },
+      },
+      required: ["episodeId"],
+    },
+  },
+  {
+    name: "get_episode_highlights",
+    backendName: "get_episode_highlights",
+    category: "episodes",
+    description: "Get or prepare AI highlights, key takeaways, and quotes for an episode.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        episodeId: { type: "string", description: "Episode ID" },
+      },
+      required: ["episodeId"],
+    },
+  },
+  {
+    name: "bulk_enrich_leads",
+    backendName: "bulk_enrich_leads",
+    category: "leads",
+    description: "Prepare enrichment for multiple leads in a stage.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        stage: { type: "string", enum: ["new", "contacted", "scheduled", "all"], description: "Pipeline stage" },
+        limit: { type: "number", description: "Maximum leads to enrich, max 10", default: 5 },
+      },
+    },
+  },
+  {
+    name: "bulk_send_emails",
+    backendName: "bulk_send_emails",
+    category: "leads",
+    description: "Draft outreach emails for multiple leads in a stage.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        stage: { type: "string", enum: ["new", "contacted", "scheduled", "all"], description: "Pipeline stage" },
+        angle: { type: "string", description: "Outreach angle or topic" },
+        limit: { type: "number", description: "Maximum emails to draft, max 10", default: 5 },
+      },
+    },
+  },
+  {
+    name: "get_inbox",
+    backendName: "get_inbox",
+    category: "admin",
+    description: "Admin: get inbox threads and messages.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "string", enum: ["all", "open", "archived"], default: "open" },
+        limit: { type: "number", description: "Maximum threads to return", default: 10 },
+      },
+    },
+  },
+  {
+    name: "draft_reply",
+    backendName: "draft_reply",
+    category: "admin",
+    description: "Admin: draft an AI reply to an inbox thread.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        threadId: { type: "string", description: "Inbox thread ID" },
+        instructions: { type: "string", description: "Optional tone/key point instructions" },
+      },
+      required: ["threadId"],
+    },
+  },
+  {
+    name: "get_bookings",
+    backendName: "get_bookings",
+    category: "bookings",
+    description: "Get booking requests and upcoming bookings.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "string", enum: ["all", "confirmed", "pending", "cancelled"], description: "Booking status" },
+        limit: { type: "number", description: "Maximum bookings to return", default: 10 },
+      },
+    },
+  },
+  {
+    name: "qualify_leads",
+    backendName: "qualify_leads",
+    category: "leads",
+    description: "Run AI qualification scoring on leads to identify promising guests.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        stage: { type: "string", enum: ["new", "contacted", "all"], default: "new" },
+        limit: { type: "number", description: "Number of leads to qualify", default: 10 },
+      },
+    },
+  },
+  {
+    name: "update_credits",
+    backendName: "update_credits",
+    category: "admin",
+    description: "Admin: prepare adding credits to a user's balance.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        amount: { type: "number", description: "Credit amount" },
+        targetUserId: { type: "string", description: "Target user ID, defaults to current user" },
+      },
+      required: ["amount"],
+    },
+  },
+  {
+    name: "update_plan",
+    backendName: "update_plan",
+    category: "admin",
+    description: "Admin: prepare updating a user's plan type.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        planType: { type: "string", enum: ["free_trial", "pro", "enterprise"] },
+        targetUserId: { type: "string", description: "Target user ID, defaults to current user" },
+      },
+      required: ["planType"],
+    },
+  },
+  {
+    name: "assign_role",
+    backendName: "assign_role",
+    category: "admin",
+    description: "Super admin: prepare assigning a role to a user.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        role: { type: "string", enum: ["admin", "moderator", "reporting"] },
+        targetUserId: { type: "string", description: "Target user ID" },
+      },
+      required: ["role", "targetUserId"],
+    },
+  },
+];

package/src/tools/run.mjs

@@ -0,0 +1,44 @@
+import { apiCall } from "../api.mjs";
+import { ALL_MCP_TOOL_CATALOG } from "./catalog.mjs";
+import { functionNameFromEdgeTool } from "./edge-functions.mjs";
+
+const BUILTIN_TOOL_HANDLERS = {
+  list_episodes: async ({ limit = 10 }) => apiCall("cli-list-episodes", { body: { limit } }),
+  get_episode: async ({ episode }) => apiCall("cli-get-episode", { body: { episode } }),
+  search_episodes: async ({ query }) => apiCall("cli-search-episodes", { body: { query } }),
+  create_talking_cards: async ({ focus, count = 3 }) => apiCall("cli-create-talking-cards", {
+    body: {
+      focus,
+      count: Math.max(1, Math.min(Number(count || 3), 10)),
+    },
+  }),
+};
+
+export function findTool(name) {
+  return ALL_MCP_TOOL_CATALOG.find((tool) => tool.name === name);
+}
+
+export async function runCatalogTool(name, args = {}) {
+  const tool = findTool(name);
+  if (!tool) throw new Error(`Unknown tool: ${name}`);
+
+  if (BUILTIN_TOOL_HANDLERS[name]) return BUILTIN_TOOL_HANDLERS[name](args);
+
+  const edgeFunctionName = functionNameFromEdgeTool(name);
+  if (edgeFunctionName) {
+    return apiCall("cli-run-edge-function", {
+      body: {
+        functionName: edgeFunctionName,
+        input: args.input && typeof args.input === "object" ? args.input : {},
+        dryRun: args.dryRun !== false,
+      },
+    });
+  }
+
+  return apiCall("magic-assistant", {
+    body: {
+      toolName: tool.backendName || name,
+      args,
+    },
+  });
+}