botverse-mcp 1.0.3 → 1.1.0

package/Dockerfile

@@ -0,0 +1,9 @@
+# Dockerfile for Glama (and any container-based MCP host).
+# Builds the thin stdio bridge. No dependencies, no build step.
+# Glama starts the container and sends an introspection request
+# (initialize / tools/list) — both answered locally from tools.json,
+# so the check passes with no API key and no network access.
+FROM node:20-alpine
+WORKDIR /app
+COPY package.json index.js tools.json ./
+ENTRYPOINT ["node", "index.js"]

package/README.md

@@ -1,6 +1,6 @@
 # botverse-mcp
 
-MCP server for [Botverse](https://botverse.cloud) — video transcoding and document conversion for AI agents.
+MCP server **and command-line tool** for [Botverse](https://botverse.cloud) — video transcoding and document conversion for AI agents and the humans who configure them.
 
 [![npm](https://img.shields.io/npm/v/botverse-mcp)](https://www.npmjs.com/package/botverse-mcp)
 
@@ -9,7 +9,7 @@ MCP server for [Botverse](https://botverse.cloud) — video transcoding and docu
 - **Video transcoding** — MP4 (H.264), WebM (VP9), ProRes 422, GIF, MP3 extraction · $0.25/job
 - **Document conversion** — Markdown ↔ DOCX ↔ PDF ↔ HTML ↔ XLSX · $0.05/file
 
-Three tool calls. No AWS. No FFmpeg. No infrastructure.
+Two ways to use it: an **MCP server** for your AI agents, and a **`botverse` CLI** for the shell — evaluation, CI/CD, cron, scripts, and local coding agents. No AWS. No FFmpeg. No infrastructure.
 
 ## Setup
 
@@ -51,16 +51,41 @@ Or with a connector URL (recommended for claude.ai):
 }
 ```
 
-## Tools
+## Command line (`botverse`)
+
+The same package ships a `botverse` CLI for the shell — it reads files from disk and
+streams them straight to the API (no content goes through an LLM), so it's the fast
+path for evaluation, automation, and local coding agents.
+
+```bash
+export BOTVERSE_API_KEY=bv_live_…        # or BOTVERSE_CONNECTOR_URL=…?token=bv_sess_…
+
+npx botverse convert report.md --to pdf
+npx botverse convert *.md --to docx,pdf -o ./out
+npx botverse transcode clip.mov --to mp4 -o ./out
+npx botverse transcribe call.mp4 --to docx --attendees "Sarah Chen,Mike Torres"
+npx botverse balance
+```
+
+Each job uploads → polls → downloads the finished file to `-o` (default: current dir).
+Globs and multiple `--to` formats run as a batch.
+
+> **Sandbox note:** the CLI needs outbound network to `botverse.cloud` and S3, so it does
+> **not** run inside sandboxed agent environments (claude.ai / Claude Desktop), whose
+> egress is allowlisted. There, use the MCP tools (`convert_content` / `get_output_content`).
+
+## Tools (MCP)
 
 | Tool | Description |
 |---|---|
 | `transcode_from_url` | Transcode video from a public URL |
 | `transcode_video` | Transcode an uploaded video file |
-| `convert_content` | Convert document content inline |
+| `convert_content` | Convert document content inline (up to 4 MB; sandbox-safe) |
 | `convert_from_url` | Convert a document from a public URL |
+| `convert_file` | Convert an uploaded document |
 | `get_job_status` | Poll a job until complete |
 | `get_download_url` | Get the signed download URL |
+| `get_output_content` | Get finished output bytes inline (sandbox-safe download) |
 | `get_wallet_balance` | Check wallet balance |
 
 ## Pricing

package/cli.js

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+/**
+ * botverse — command-line interface for Botverse.
+ *
+ * For humans and shell-capable automation (CI, cron, local coding agents) — it
+ * reads files from disk and streams them to the API directly, so it never serializes
+ * content through an LLM the way the in-chat MCP route must. Talks to the same
+ * hosted endpoint (botverse.cloud/mcp) with a bv_live_ key.
+ *
+ *   export BOTVERSE_API_KEY=bv_live_xxx
+ *   botverse convert report.md --to pdf
+ *   botverse convert *.md --to docx,pdf -o ./out
+ *   botverse transcode clip.mov --to mp4 -o ./out
+ *   botverse transcribe call.mp4 --to docx --attendees "Sarah Chen,Mike Torres"
+ *   botverse balance
+ *
+ * NOTE: this needs outbound network to botverse.cloud and S3. It does NOT work inside
+ * sandboxed agent environments (claude.ai / Claude Desktop) whose egress is allowlisted —
+ * there, use the MCP tools (convert_content / get_output_content) instead.
+ */
+
+"use strict";
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+const { URL } = require("url");
+
+const VERSION = "1.1.0";
+const BASE_URL = process.env.BOTVERSE_MCP_URL || "https://botverse.cloud/mcp";
+
+// ── tiny ANSI helpers ─────────────────────────────────────────────────────────
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const dim = (s) => c("2", s), bold = (s) => c("1", s), green = (s) => c("32", s), red = (s) => c("31", s), cyan = (s) => c("36", s);
+const log = (...a) => process.stderr.write(a.join(" ") + "\n");
+
+function die(msg) { log(red("error: ") + msg); process.exit(1); }
+
+// ── format maps ───────────────────────────────────────────────────────────────
+const CONTENT_TYPES = {
+  md: "text/markdown", markdown: "text/markdown", html: "text/html", htm: "text/html",
+  rst: "text/x-rst", txt: "text/plain", doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  mp4: "video/mp4", mov: "video/quicktime", webm: "video/webm", avi: "video/x-msvideo",
+  mkv: "video/x-matroska", m4v: "video/x-m4v", wav: "audio/wav", m4a: "audio/mp4",
+  mp3: "audio/mpeg", flac: "audio/flac", wma: "audio/x-ms-wma",
+};
+const TEXT_INPUTS = new Set(["md", "markdown", "html", "htm", "rst", "txt"]);
+const EXT_OF = (f) => (path.extname(f).slice(1) || "").toLowerCase();
+const MAX_INLINE = 4 * 1024 * 1024; // proxy inline ceiling
+
+// ── HTTP / JSON-RPC ───────────────────────────────────────────────────────────
+// Auth: either a bv_live_ API key (Authorization: Bearer) or a full connector URL
+// containing ?token=bv_sess_… (BOTVERSE_CONNECTOR_URL). Returns the endpoint + headers.
+function authTarget(contentLength) {
+  const connector = argv.flags["connector-url"] || process.env.BOTVERSE_CONNECTOR_URL;
+  const key = argv.flags["api-key"] || process.env.BOTVERSE_API_KEY;
+  if (!connector && !key) {
+    die("no credentials. Set BOTVERSE_API_KEY=bv_live_… (or BOTVERSE_CONNECTOR_URL=…?token=bv_sess_…). Get a key at https://botverse.cloud/dashboard/api-keys");
+  }
+  const headers = { "Content-Type": "application/json", "Content-Length": contentLength, "User-Agent": "botverse-cli/" + VERSION };
+  if (!connector && key) headers["Authorization"] = `Bearer ${key}`;
+  return { url: connector || BASE_URL, headers };
+}
+
+function request(urlStr, { method = "POST", headers = {}, body }) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(urlStr);
+    const req = https.request(
+      { hostname: u.hostname, port: u.port || 443, path: u.pathname + u.search, method, headers },
+      (res) => {
+        const chunks = [];
+        res.on("data", (d) => chunks.push(d));
+        res.on("end", () => resolve({ status: res.statusCode, buffer: Buffer.concat(chunks) }));
+      }
+    );
+    req.on("error", reject);
+    req.setTimeout(180000, () => req.destroy(new Error("request timed out")));
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+let RPC_ID = 0;
+async function mcp(tool, args) {
+  const body = JSON.stringify({ jsonrpc: "2.0", id: ++RPC_ID, method: "tools/call", params: { name: tool, arguments: args } });
+  const { url, headers } = authTarget(Buffer.byteLength(body));
+  const { status, buffer } = await request(url, { headers, body });
+  let json;
+  try { json = JSON.parse(buffer.toString()); }
+  catch { throw new Error(`HTTP ${status}: ${buffer.toString().slice(0, 200)}`); }
+  if (json.error) throw new Error(json.error.message || JSON.stringify(json.error));
+  const text = json.result?.structuredContent ?? json.result?.content?.[0]?.text;
+  if (text == null) throw new Error("unexpected response shape");
+  return typeof text === "string" ? JSON.parse(text) : text;
+}
+
+// ── S3 multipart upload (presigned POST) ──────────────────────────────────────
+async function uploadFile(filePath) {
+  const filename = path.basename(filePath);
+  const ext = EXT_OF(filename);
+  const ct = CONTENT_TYPES[ext] || "application/octet-stream";
+  const up = await mcp("get_upload_url", { filename, content_type: ct });
+  const fields = up.upload_fields || {};
+  const fileBuf = fs.readFileSync(filePath);
+
+  const boundary = "----botverse" + Math.random().toString(16).slice(2);
+  const pre = [];
+  for (const [k, v] of Object.entries(fields)) {
+    pre.push(`--${boundary}\r\nContent-Disposition: form-data; name="${k}"\r\n\r\n${v}\r\n`);
+  }
+  pre.push(`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${filename}"\r\nContent-Type: ${fields["Content-Type"] || ct}\r\n\r\n`);
+  const body = Buffer.concat([Buffer.from(pre.join("")), fileBuf, Buffer.from(`\r\n--${boundary}--\r\n`)]);
+
+  const { status, buffer } = await request(up.upload_url, {
+    headers: { "Content-Type": `multipart/form-data; boundary=${boundary}`, "Content-Length": body.length },
+    body,
+  });
+  if (status !== 204 && status !== 201 && status !== 200) {
+    throw new Error(`S3 upload failed (HTTP ${status}): ${buffer.toString().slice(0, 200)}`);
+  }
+  return up.object_key;
+}
+
+// ── job polling + download ────────────────────────────────────────────────────
+async function poll(jobId) {
+  const start = Date.now();
+  for (;;) {
+    const s = await mcp("get_job_status", { job_id: jobId });
+    if (s.status === "complete") return s;
+    if (s.status === "failed") throw new Error(s.error || "job failed");
+    if (Date.now() - start > 30 * 60 * 1000) throw new Error("timed out waiting for job");
+    if (s.stage_message) process.stderr.write("\r" + dim("  " + s.stage_message.padEnd(48)));
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+}
+
+async function downloadOutput(jobId, outPath) {
+  const dl = await mcp("get_download_url", { job_id: jobId });
+  const { status, buffer } = await request(dl.download_url, { method: "GET" });
+  if (status !== 200) throw new Error(`download failed (HTTP ${status})`);
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, buffer);
+  return buffer.length;
+}
+
+// ── submit helpers ────────────────────────────────────────────────────────────
+async function submitConvert(filePath, outFmt) {
+  const ext = EXT_OF(filePath);
+  const size = fs.statSync(filePath).size;
+  // Small text files go inline (no upload round-trip); large or binary go via S3.
+  if (TEXT_INPUTS.has(ext) && size <= MAX_INLINE) {
+    const r = await mcp("convert_content", {
+      content: fs.readFileSync(filePath, "utf8"),
+      input_format: ext === "markdown" ? "md" : ext === "htm" ? "html" : ext,
+      output_format: outFmt,
+    });
+    return r.job_id;
+  }
+  const key = await uploadFile(filePath);
+  const r = await mcp("convert_file", { object_key: key, output_format: outFmt });
+  return r.job_id;
+}
+
+async function submitTranscode(filePath, outFmt, opts) {
+  const key = await uploadFile(filePath);
+  const r = await mcp("transcode_video", { object_key: key, output_format: outFmt, ...(opts ? { options: opts } : {}) });
+  return r.job_id;
+}
+
+async function submitTranscribe(filePath, outFmt, opts) {
+  const key = await uploadFile(filePath);
+  const r = await mcp("transcribe_media", { object_key: key, output_format: outFmt, ...(opts ? { options: opts } : {}) });
+  return r.job_id;
+}
+
+// ── commands ──────────────────────────────────────────────────────────────────
+async function runBatch(files, formats, submit, outDir) {
+  if (!files.length) die("no input files");
+  let failures = 0;
+  for (const file of files) {
+    if (!fs.existsSync(file)) { log(red("✗ ") + file + dim(" — not found")); failures++; continue; }
+    for (const fmt of formats) {
+      const t0 = Date.now();
+      const base = path.basename(file, path.extname(file));
+      const outPath = path.join(outDir, `${base}.${fmt}`);
+      process.stderr.write(dim(`· ${path.basename(file)} → ${fmt} …`));
+      try {
+        const jobId = await submit(file, fmt);
+        await poll(jobId);
+        const bytes = await downloadOutput(jobId, outPath);
+        process.stderr.write("\r" + green("✓ ") + outPath + dim(`  (${(bytes / 1024).toFixed(0)} KB, ${((Date.now() - t0) / 1000).toFixed(1)}s)`).padEnd(20) + "\n");
+      } catch (e) {
+        process.stderr.write("\r" + red("✗ ") + `${path.basename(file)} → ${fmt}` + dim("  " + (e.message || e)) + "\n");
+        failures++;
+      }
+    }
+  }
+  if (failures) process.exitCode = 1;
+}
+
+function parseFormats(flag, allowed, label) {
+  if (!flag) die(`--to is required (${label}). e.g. --to ${allowed[0]}`);
+  const fmts = String(flag).split(",").map((s) => s.trim()).filter(Boolean);
+  for (const f of fmts) if (!allowed.includes(f)) die(`unsupported --to "${f}". Allowed: ${allowed.join(", ")}`);
+  return fmts;
+}
+
+const COMMANDS = {
+  async convert() {
+    const fmts = parseFormats(argv.flags.to, ["docx", "pdf", "html", "txt", "md", "rst", "xlsx"], "convert");
+    await runBatch(argv.files, fmts, (f, fmt) => submitConvert(f, fmt), argv.flags.o || argv.flags.out || ".");
+  },
+  async transcode() {
+    const fmts = parseFormats(argv.flags.to, ["mp4", "webm", "mov_prores", "mp3", "gif"], "transcode");
+    const opts = {};
+    if (argv.flags.resolution) opts.height = ({ "4k": 2160, "1080p": 1080, "720p": 720, "480p": 480, "360p": 360 }[argv.flags.resolution]) || undefined;
+    await runBatch(argv.files, fmts, (f, fmt) => submitTranscode(f, fmt, Object.keys(opts).length ? opts : null), argv.flags.o || argv.flags.out || ".");
+  },
+  async transcribe() {
+    const fmts = parseFormats(argv.flags.to, ["txt", "json", "srt", "vtt", "docx", "pdf"], "transcribe");
+    const opts = {};
+    if (argv.flags.attendees) opts.attendees = String(argv.flags.attendees).split(",").map((n) => ({ name: n.trim() })).filter((a) => a.name);
+    if (argv.flags.language) opts.language = argv.flags.language;
+    await runBatch(argv.files, fmts, (f, fmt) => submitTranscribe(f, fmt, Object.keys(opts).length ? opts : null), argv.flags.o || argv.flags.out || ".");
+  },
+  async balance() {
+    const r = await mcp("get_wallet_balance", {});
+    log(bold("Wallet: ") + green(`$${Number(r.balance_usd).toFixed(2)}`) + (r.auto_refill_enabled ? dim("  (auto-refill on)") : ""));
+  },
+};
+
+function usage() {
+  log(`${bold("botverse")} ${dim("v" + VERSION)} — Botverse from the command line
+
+${bold("Usage:")}
+  botverse convert    <files…> --to <fmt[,fmt]> [-o dir]
+  botverse transcode  <files…> --to <fmt> [--resolution 1080p] [-o dir]
+  botverse transcribe <files…> --to <fmt> [--attendees "A,B"] [--language en-US] [-o dir]
+  botverse balance
+
+${bold("Auth:")}  export BOTVERSE_API_KEY=bv_live_…   (or --api-key)
+
+${bold("Examples:")}
+  ${cyan("botverse convert report.md --to pdf")}
+  ${cyan("botverse convert *.md --to docx,pdf -o ./out")}
+  ${cyan("botverse transcode clip.mov --to mp4 -o ./out")}
+  ${cyan("botverse transcribe call.mp4 --to docx --attendees \"Sarah Chen,Mike Torres\"")}
+
+Docs: https://botverse.cloud/docs/cli`);
+}
+
+// ── arg parsing ───────────────────────────────────────────────────────────────
+function parseArgs(args) {
+  const flags = {}; const files = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("-")) { flags[key] = next; i++; } else flags[key] = true;
+    } else if (a.startsWith("-")) {
+      const key = a.slice(1);
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("-")) { flags[key] = next; i++; } else flags[key] = true;
+    } else files.push(a);
+  }
+  return { flags, files };
+}
+
+const rawArgs = process.argv.slice(2);
+const command = rawArgs[0];
+const argv = parseArgs(rawArgs.slice(1));
+
+(async () => {
+  if (!command || command === "help" || argv.flags.help || argv.flags.h) return usage();
+  if (command === "version" || argv.flags.version || argv.flags.v) return log("botverse " + VERSION);
+  const fn = COMMANDS[command];
+  if (!fn) { log(red(`unknown command: ${command}`)); usage(); process.exit(1); }
+  try { await fn(); }
+  catch (e) { die(e.message || String(e)); }
+})();

package/index.js

@@ -2,48 +2,71 @@
 /**
  * botverse-mcp — stdio bridge for the Botverse MCP server.
  *
- * Reads MCP JSON-RPC from stdin, forwards to botverse.cloud/mcp,
- * writes responses to stdout. Compatible with Claude Desktop, Cursor,
- * VS Code, Windsurf, Zed, and any MCP-compatible agent runtime.
+ * Answers `initialize` and `tools/list` locally from tools.json (no key,
+ * no network — so the server is introspectable in any sandbox). Proxies
+ * actual tool calls to botverse.cloud/mcp, which requires auth.
  *
- * Auth (set one):
- *   BOTVERSE_API_KEY=bv_live_...      — API key, sent as Authorization: Bearer
+ * Auth (set one — only needed to *call* tools, not to introspect):
+ *   BOTVERSE_API_KEY=bv_live_...        — API key, sent as Authorization: Bearer
  *   BOTVERSE_CONNECTOR_URL=https://...  — Full connector URL with ?token=bv_sess_...
+ *
+ * Compatible with Claude Desktop, Cursor, VS Code, Windsurf, Zed, and any
+ * MCP-compatible agent runtime.
  */
 
 const { createInterface } = require("readline");
+const { readFileSync } = require("fs");
+const path = require("path");
 const https = require("https");
 const { URL } = require("url");
 
 const CONNECTOR_URL = process.env.BOTVERSE_CONNECTOR_URL;
 const API_KEY = process.env.BOTVERSE_API_KEY;
 const BASE_URL = "https://botverse.cloud/mcp";
+const VERSION = "1.0.4";
+
+let TOOLS = [];
+try {
+  TOOLS = JSON.parse(readFileSync(path.join(__dirname, "tools.json"), "utf8"));
+} catch {
+  TOOLS = []; // introspection still responds, just with an empty tool list
+}
 
-if (!CONNECTOR_URL && !API_KEY) {
-  process.stderr.write(
-    "[botverse-mcp] Error: set BOTVERSE_API_KEY or BOTVERSE_CONNECTOR_URL.\n" +
-    "  Get credentials at https://botverse.cloud/dashboard/api-keys\n"
-  );
-  process.exit(1);
+const SERVER_INFO = {
+  name: "Botverse",
+  version: VERSION,
+  description:
+    "Offload compute-heavy tasks to Botverse — video transcoding and document " +
+    "conversion run server-side and return download links. Video (MP4, WebM, " +
+    "ProRes, MP3, GIF) and documents (Markdown/HTML/DOCX to DOCX, PDF, HTML, XLSX, TXT).",
+};
+
+function reply(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+function ok(id, result) {
+  reply({ jsonrpc: "2.0", id, result });
+}
+function err(id, message, code = -32603) {
+  reply({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
 }
 
 function getTargetUrl() {
   return CONNECTOR_URL || BASE_URL;
 }
-
 function getHeaders(bodyLength) {
   const headers = {
     "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
     "Content-Length": bodyLength,
-    "User-Agent": "botverse-mcp/1.0.3",
+    "User-Agent": "botverse-mcp/" + VERSION,
   };
-  if (!CONNECTOR_URL && API_KEY) {
-    headers["Authorization"] = `Bearer ${API_KEY}`;
-  }
+  if (!CONNECTOR_URL && API_KEY) headers["Authorization"] = `Bearer ${API_KEY}`;
   return headers;
 }
 
-function post(body) {
+// Proxy a request to the hosted Botverse MCP endpoint (used for tool calls).
+function proxy(body) {
   return new Promise((resolve, reject) => {
     const raw = JSON.stringify(body);
     const target = new URL(getTargetUrl());
@@ -54,10 +77,9 @@ function post(body) {
       method: "POST",
       headers: getHeaders(Buffer.byteLength(raw)),
     };
-
     const req = https.request(options, (res) => {
       let data = "";
-      res.on("data", (chunk) => { data += chunk; });
+      res.on("data", (c) => (data += c));
       res.on("end", () => {
         try {
           resolve(JSON.parse(data));
@@ -66,9 +88,8 @@ function post(body) {
         }
       });
     });
-
     req.on("error", reject);
-    req.setTimeout(60000, () => { req.destroy(new Error("Request timed out")); });
+    req.setTimeout(120000, () => req.destroy(new Error("Request timed out")));
     req.write(raw);
     req.end();
   });
@@ -80,27 +101,47 @@ rl.on("line", async (line) => {
   const trimmed = line.trim();
   if (!trimmed) return;
 
-  let message;
+  let msg;
   try {
-    message = JSON.parse(trimmed);
+    msg = JSON.parse(trimmed);
   } catch {
     return; // ignore malformed input
   }
 
+  const { id, method } = msg;
+
+  // Notifications (no id) — acknowledge silently per MCP.
+  if (id === undefined || id === null) return;
+
+  // Handle introspection locally — no key, no network.
+  if (method === "initialize") {
+    return ok(id, {
+      protocolVersion: msg.params?.protocolVersion || "2024-11-05",
+      capabilities: { tools: {} },
+      serverInfo: SERVER_INFO,
+    });
+  }
+  if (method === "tools/list") {
+    return ok(id, { tools: TOOLS });
+  }
+  if (method === "ping") {
+    return ok(id, {});
+  }
+
+  // Everything else (tools/call, etc.) needs auth and goes to the hosted server.
+  if (!CONNECTOR_URL && !API_KEY) {
+    return err(
+      id,
+      "Botverse needs credentials to run a job. Set BOTVERSE_API_KEY or " +
+        "BOTVERSE_CONNECTOR_URL. Get one at https://botverse.cloud/dashboard/api-keys"
+    );
+  }
   try {
-    const response = await post(message);
-    process.stdout.write(JSON.stringify(response) + "\n");
-  } catch (err) {
-    const errorResponse = {
-      jsonrpc: "2.0",
-      id: message.id ?? null,
-      error: {
-        code: -32603,
-        message: err instanceof Error ? err.message : "Internal error",
-      },
-    };
-    process.stdout.write(JSON.stringify(errorResponse) + "\n");
+    const response = await proxy(msg);
+    reply(response);
+  } catch (e) {
+    err(id, e instanceof Error ? e.message : "Internal error");
   }
 });
 
-rl.on("close", () => { process.exit(0); });
+rl.on("close", () => process.exit(0));

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "botverse-mcp",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "mcpName": "io.github.MkTurner74/botverse",
-  "description": "MCP server for Botverse — video transcoding and document conversion for AI agents. $0.25/transcode · $0.05/convert · No AWS required.",
+  "description": "Botverse for AI agents and the command line — video transcoding and document conversion. MCP server + `botverse` CLI. $0.25/transcode · $0.05/convert · No AWS required.",
   "main": "index.js",
   "bin": {
-    "botverse-mcp": "index.js"
+    "botverse-mcp": "index.js",
+    "botverse": "cli.js"
   },
   "scripts": {
     "start": "node index.js"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/MkTurner74/botverse-mcp",
     "source": "github"
   },
-  "version": "1.0.3",
+  "version": "1.0.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "botverse-mcp",
-      "version": "1.0.3",
+      "version": "1.0.4",
       "transport": {
         "type": "stdio"
       },

package/tools.json

@@ -0,0 +1,750 @@
+[
+  {
+    "name": "get_upload_url",
+    "description": "Get a presigned PUT URL to upload any file — video, audio, or document (markdown, HTML, DOCX, etc.). The URL expires in 15 minutes. PUT raw file bytes directly to the URL. After upload, pass the object_key to transcode_video (for video) or convert_file (for documents).",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "filename": {
+          "type": "string",
+          "description": "Original filename including extension, e.g. report.md or footage.mp4"
+        },
+        "content_type": {
+          "type": "string",
+          "description": "MIME type. Video: \"video/mp4\". Documents: \"text/markdown\", \"text/html\", \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\", \"text/plain\"."
+        }
+      },
+      "required": [
+        "filename",
+        "content_type"
+      ]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "upload_url": {
+          "type": "string",
+          "description": "Presigned HTTPS PUT URL. Send raw file bytes as the request body."
+        },
+        "object_key": {
+          "type": "string",
+          "description": "storage object key — pass this to transcode_video or convert_file."
+        },
+        "expires_in": {
+          "type": "number",
+          "description": "Seconds until the upload URL expires (900 = 15 minutes)."
+        }
+      },
+      "required": [
+        "upload_url",
+        "object_key",
+        "expires_in"
+      ]
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": true
+    }
+  },
+  {
+    "name": "transcode_from_url",
+    "description": "Offload a video or audio transcode to Botverse using a public URL — no upload step needed. Accepts Dropbox, Google Drive, OneDrive, SharePoint, and Box share links directly — pass the share URL as-is, no manual conversion needed. Also works with any direct HTTPS download URL (CDN, object storage, etc.). Limited to 2 GB. Returns a job_id immediately. IMPORTANT: tell the user the job_id right away so they can track it. Then poll get_job_status every 5 seconds. Large video files (>100 MB) can take 5–15 minutes — keep polling until status is 'complete' or 'failed', no matter how many polls it takes. Never give up early. Wallet debited on completion. Use options.start_time and options.duration to trim — e.g. start_time='00:01:00', duration=120 for a 2-minute clip.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "source_url": {
+          "type": "string",
+          "description": "Public HTTPS URL of the source video or audio file."
+        },
+        "output_format": {
+          "type": "string",
+          "enum": [
+            "mp4",
+            "webm",
+            "mov_prores",
+            "mp3",
+            "gif"
+          ],
+          "description": "Target output format. One of: mp4 (H.264), webm (VP9), mov_prores (ProRes 422), mp3 (audio extraction), gif."
+        },
+        "options": {
+          "type": "object",
+          "description": "Optional encoding parameters. All are optional.",
+          "properties": {
+            "start_time": {
+              "type": "string",
+              "description": "Seek to this position before encoding, e.g. '00:01:30' or '90'. Useful for trimming long files."
+            },
+            "duration": {
+              "type": "number",
+              "description": "Encode only this many seconds of content after start_time. Use with start_time to extract a clip."
+            },
+            "width": {
+              "type": "number",
+              "description": "Output width in pixels. Height scales proportionally if only width is set."
+            },
+            "height": {
+              "type": "number",
+              "description": "Output height in pixels. Width scales proportionally if only height is set."
+            },
+            "bitrate": {
+              "type": "string",
+              "description": "Video bitrate, e.g. '2M' for 2 Mbps."
+            },
+            "framerate": {
+              "type": "number",
+              "description": "Output frame rate, e.g. 24 or 30."
+            },
+            "audio_bitrate": {
+              "type": "string",
+              "description": "Audio bitrate for mp3 output, e.g. '128k' or '320k'."
+            },
+            "h264_profile": {
+              "type": "string",
+              "enum": [
+                "baseline",
+                "main",
+                "high"
+              ],
+              "description": "H.264 encoding profile for mp4 output. baseline = max device compatibility (mobile, streaming, older hardware). main = balanced (default). high = best quality for modern playback."
+            }
+          }
+        }
+      },
+      "required": [
+        "source_url",
+        "output_format"
+      ]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "job_id": {
+          "type": "string",
+          "description": "Unique identifier for this job. Pass to get_job_status and get_download_url."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "queued",
+            "processing"
+          ],
+          "description": "Initial job state — always queued or processing immediately after submission."
+        },
+        "estimated_seconds": {
+          "type": "number",
+          "description": "Rough estimated processing time in seconds. Actual time may vary."
+        }
+      },
+      "required": [
+        "job_id",
+        "status"
+      ]
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": true
+    }
+  },
+  {
+    "name": "transcode_video",
+    "description": "Offload a video transcode to Botverse — encoding runs server-side so you can continue with other tasks. Returns a job_id immediately. Source must be ≤ 10 minutes and ≤ 5 GB. Poll get_job_status every 5 seconds until 'complete', then get_download_url. Wallet debited on completion.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "object_key": {
+          "type": "string",
+          "description": "storage object key returned by get_upload_url."
+        },
+        "output_format": {
+          "type": "string",
+          "enum": [
+            "mp4",
+            "webm",
+            "mov_prores",
+            "mp3",
+            "gif"
+          ],
+          "description": "Target output format. One of: mp4 (H.264), webm (VP9), mov_prores (ProRes 422), mp3 (audio extraction), gif."
+        },
+        "options": {
+          "type": "object",
+          "description": "Optional encoding parameters. All are optional.",
+          "properties": {
+            "start_time": {
+              "type": "string",
+              "description": "Seek to this position before encoding, e.g. '00:01:30' or '90'."
+            },
+            "duration": {
+              "type": "number",
+              "description": "Encode only this many seconds of content after start_time."
+            },
+            "width": {
+              "type": "number",
+              "description": "Output width in pixels."
+            },
+            "height": {
+              "type": "number",
+              "description": "Output height in pixels."
+            },
+            "bitrate": {
+              "type": "string",
+              "description": "Video bitrate, e.g. '2M'."
+            },
+            "framerate": {
+              "type": "number",
+              "description": "Output frame rate, e.g. 24 or 30."
+            },
+            "audio_bitrate": {
+              "type": "string",
+              "description": "Audio bitrate for mp3 output, e.g. '128k'."
+            },
+            "h264_profile": {
+              "type": "string",
+              "enum": [
+                "baseline",
+                "main",
+                "high"
+              ],
+              "description": "H.264 encoding profile for mp4 output. baseline = max device compatibility. main = balanced (default). high = best quality for modern playback."
+            }
+          }
+        }
+      },
+      "required": [
+        "object_key",
+        "output_format"
+      ]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "job_id": {
+          "type": "string",
+          "description": "Unique identifier for this job. Pass to get_job_status and get_download_url."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "queued",
+            "processing"
+          ],
+          "description": "Initial job state — always queued or processing immediately after submission."
+        },
+        "estimated_seconds": {
+          "type": "number",
+          "description": "Rough estimated processing time in seconds. Actual time may vary."
+        }
+      },
+      "required": [
+        "job_id",
+        "status"
+      ]
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": true
+    }
+  },
+  {
+    "name": "get_job_status",
+    "description": "Poll the status of a transcode or convert job. Call every 5 seconds until status is 'complete' or 'failed'. Status 'queued' or 'processing' is normal — large files take 5–15 minutes. Keep polling indefinitely until a terminal status is reached. Do not stop polling after a fixed number of attempts.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "job_id": {
+          "type": "string",
+          "description": "Job ID returned by transcode_video, transcode_from_url, convert_file, convert_from_url, or convert_content."
+        }
+      },
+      "required": [
+        "job_id"
+      ]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "job_id": {
+          "type": "string",
+          "description": "The job identifier."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "queued",
+            "processing",
+            "complete",
+            "failed"
+          ],
+          "description": "Current job state."
+        },
+        "progress_pct": {
+          "type": "number",
+          "description": "Encoding progress 0–100. Only present while status is 'processing'."
+        },
+        "output_key": {
+          "type": "string",
+          "description": "storage object key of the completed output. Present when status is 'complete'. Pass to get_download_url."
+        },
+        "cost_usd": {
+          "type": "number",
+          "description": "Amount debited from the wallet on completion, in USD."
+        },
+        "error_message": {
+          "type": "string",
+          "description": "Human-readable error description. Present when status is 'failed'."
+        }
+      },
+      "required": [
+        "job_id",
+        "status"
+      ]
+    },
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": true
+    }
+  },
+  {
+    "name": "get_download_url",
+    "description": "Get a presigned HTTPS URL to download the completed output file. Call after get_job_status returns 'complete'. URL expires in 24 hours.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "job_id": {
+          "type": "string",
+          "description": "Job ID from transcode_video, transcode_from_url, or any convert tool."
+        }
+      },
+      "required": [
+        "job_id"
+      ]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "download_url": {
+          "type": "string",
+          "description": "Presigned HTTPS GET URL for the output file. Valid for 24 hours."
+        },
+        "filename": {
+          "type": "string",
+          "description": "Suggested filename for the downloaded file including extension."
+        },
+        "expires_at": {
+          "type": "string",
+          "description": "ISO 8601 timestamp when the download URL expires."
+        },
+        "size_bytes": {
+          "type": "number",
+          "description": "File size of the output in bytes."
+        }
+      },
+      "required": [
+        "download_url",
+        "filename",
+        "expires_at"
+      ]
+    },
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": true
+    }
+  },
+  {
+    "name": "get_wallet_balance",
+    "description": "Check the current prepaid wallet balance for this Botverse account. Use before large batch jobs to confirm sufficient funds.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {},
+      "required": []
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "balance_usd": {
+          "type": "number",
+          "description": "Current wallet balance in USD."
+        },
+        "auto_refill_enabled": {
+          "type": "boolean",
+          "description": "Whether automatic wallet top-up is enabled."
+        },
+        "refill_threshold_usd": {
+          "type": "number",
+          "description": "Balance threshold in USD that triggers an auto-refill, if enabled."
+        },
+        "refill_amount_usd": {
+          "type": "number",
+          "description": "Amount in USD added on each auto-refill, if enabled."
+        }
+      },
+      "required": [
+        "balance_usd",
+        "auto_refill_enabled"
+      ]
+    },
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    }
+  },
+  {
+    "name": "convert_from_url",
+    "description": "Offload a document conversion to Botverse — runs server-side in seconds, returns a download link, and frees you to continue with other tasks while it processes. Use this when the source document is at a public URL — including Dropbox, Google Drive, OneDrive, SharePoint, and Box share links (pass the share URL as-is). If you already have the content as a string, use convert_content instead — no upload step needed. Supported inputs: md, html, rst, txt, docx. Supported outputs: docx (Word), pdf, html, txt, md, rst, xlsx (tables extracted). Returns a job_id immediately. Poll get_job_status every 5s until 'complete', then get_download_url. Flat fee $0.05 per file.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "source_url": {
+          "type": "string",
+          "description": "Public HTTPS URL of the source document."
+        },
+        "output_format": {
+          "type": "string",
+          "enum": [
+            "docx",
+            "html",
+            "txt",
+            "md",
+            "rst",
+            "pdf",
+            "xlsx"
+          ],
+          "description": "Target format: docx | html | txt | md | rst | pdf | xlsx"
+        }
+      },
+      "required": [
+        "source_url",
+        "output_format"
+      ]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "job_id": {
+          "type": "string",
+          "description": "Unique identifier for this job. Pass to get_job_status and get_download_url."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "queued",
+            "processing"
+          ],
+          "description": "Initial job state — always queued or processing immediately after submission."
+        },
+        "estimated_seconds": {
+          "type": "number",
+          "description": "Rough estimated processing time in seconds. Actual time may vary."
+        }
+      },
+      "required": [
+        "job_id",
+        "status"
+      ]
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": true
+    }
+  },
+  {
+    "name": "convert_file",
+    "description": "Offload a document conversion to Botverse using an already-uploaded file. Workflow: (1) call get_upload_url to get a presigned upload URL, (2) PUT the raw file bytes to that URL, (3) call convert_file with the object_key — Botverse handles the rest server-side. Returns a job_id immediately so you can continue with other tasks while conversion runs. Supported inputs: md, html, rst, txt, docx. Supported outputs: docx, pdf, html, txt, md, rst, xlsx. Poll get_job_status until complete, then get_download_url. Flat fee $0.05 per file.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "object_key": {
+          "type": "string",
+          "description": "The object_key returned by get_upload_url."
+        },
+        "output_format": {
+          "type": "string",
+          "enum": [
+            "docx",
+            "html",
+            "txt",
+            "md",
+            "rst",
+            "pdf",
+            "xlsx"
+          ],
+          "description": "Target format: docx | html | txt | md | rst | pdf | xlsx"
+        }
+      },
+      "required": [
+        "object_key",
+        "output_format"
+      ]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "job_id": {
+          "type": "string",
+          "description": "Unique identifier for this job. Pass to get_job_status and get_download_url."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "queued",
+            "processing"
+          ],
+          "description": "Initial job state — always queued or processing immediately after submission."
+        },
+        "estimated_seconds": {
+          "type": "number",
+          "description": "Rough estimated processing time in seconds. Actual time may vary."
+        }
+      },
+      "required": [
+        "job_id",
+        "status"
+      ]
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": true
+    }
+  },
+  {
+    "name": "submit_workflow",
+    "description": "Submit a multi-step workflow to the Botverse workflow engine. Steps execute in dependency order; parallel branches (multiple steps with the same depends_on) run simultaneously. Returns a workflow_id immediately — poll get_workflow_status every 5–10 seconds until terminal. Requires auto-refill to be enabled at botverse.cloud/dashboard/billing to prevent mid-workflow balance failures. Workflow definition uses BWDL (Botverse Workflow Definition Language) — schema at botverse.cloud/schemas/workflow/v1.json.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "definition": {
+          "type": "object",
+          "description": "BWDL workflow definition. Must include workflow_id (string) and steps (array). Each step needs id, tool, and inputs."
+        }
+      },
+      "required": [
+        "definition"
+      ]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "workflow_id": {
+          "type": "string",
+          "description": "Unique workflow identifier. Pass to get_workflow_status."
+        },
+        "status": {
+          "type": "string",
+          "description": "Initial status: QUEUED or PROCESSING."
+        },
+        "step_count": {
+          "type": "number",
+          "description": "Number of steps in the workflow."
+        },
+        "already_exists": {
+          "type": "boolean",
+          "description": "True if this workflow_id was already submitted — idempotent resubmit."
+        }
+      },
+      "required": [
+        "workflow_id",
+        "status"
+      ]
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": true
+    }
+  },
+  {
+    "name": "get_workflow_status",
+    "description": "Get the current status of a workflow and all its steps. Each call may advance the workflow by dispatching steps whose dependencies have completed. Poll every 5–10 seconds until status is COMPLETED, FAILED, PARTIALLY_FAILED, or CANCELLED.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "workflow_id": {
+          "type": "string",
+          "description": "Workflow ID returned by submit_workflow."
+        }
+      },
+      "required": [
+        "workflow_id"
+      ]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "workflow_id": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "QUEUED",
+            "PROCESSING",
+            "COMPLETED",
+            "PARTIALLY_FAILED",
+            "FAILED",
+            "CANCELLED"
+          ]
+        },
+        "total_cost_usd": {
+          "type": "number"
+        },
+        "steps": {
+          "type": "array",
+          "description": "Array of step status objects."
+        },
+        "completed_at": {
+          "type": "string",
+          "description": "ISO timestamp when workflow reached terminal state."
+        }
+      },
+      "required": [
+        "workflow_id",
+        "status"
+      ]
+    },
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": true
+    }
+  },
+  {
+    "name": "cancel_workflow",
+    "description": "Cancel an in-progress workflow. All queued and dispatched steps are marked CANCELLED. Completed steps are not reversed. You are only billed for steps that completed before cancellation.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "workflow_id": {
+          "type": "string",
+          "description": "Workflow ID to cancel."
+        }
+      },
+      "required": [
+        "workflow_id"
+      ]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "workflow_id": {
+          "type": "string"
+        },
+        "cancelled": {
+          "type": "boolean"
+        },
+        "status": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "workflow_id",
+        "cancelled"
+      ]
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
+    }
+  },
+  {
+    "name": "convert_content",
+    "description": "Offload an inline document conversion to Botverse — pass the content directly as a string. ONLY use this tool for content you generated yourself (e.g. Markdown you just wrote). HARD LIMIT: content must be under 10,000 characters. If the content is longer than 10,000 characters, or came from an uploaded or external file, DO NOT use this tool — tell the user to make the file available at a public URL (Google Drive share link, Dropbox, object storage, etc.) and use convert_from_url instead. Supported inputs: md, html, rst, txt (plain text), docx (base64). Supported outputs: docx (Word), pdf, html, txt, md, rst, xlsx. Flat fee $0.05 per file.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "content": {
+          "type": "string",
+          "description": "The file content as a plain text string (for md, html, rst, txt) or base64-encoded bytes (for docx)."
+        },
+        "input_format": {
+          "type": "string",
+          "enum": [
+            "md",
+            "html",
+            "rst",
+            "txt",
+            "docx"
+          ],
+          "description": "Source format of the content."
+        },
+        "output_format": {
+          "type": "string",
+          "enum": [
+            "docx",
+            "html",
+            "txt",
+            "md",
+            "rst",
+            "pdf",
+            "xlsx"
+          ],
+          "description": "Target format: docx | html | txt | md | rst | pdf | xlsx"
+        },
+        "encoding": {
+          "type": "string",
+          "enum": [
+            "text",
+            "base64"
+          ],
+          "description": "Encoding of the content field. Defaults to \"text\". Use \"base64\" for binary inputs like .docx."
+        }
+      },
+      "required": [
+        "content",
+        "input_format",
+        "output_format"
+      ]
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "job_id": {
+          "type": "string",
+          "description": "Unique identifier for this job. Pass to get_job_status and get_download_url."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "queued",
+            "processing"
+          ],
+          "description": "Initial job state — always queued or processing immediately after submission."
+        },
+        "estimated_seconds": {
+          "type": "number",
+          "description": "Rough estimated processing time in seconds. Actual time may vary."
+        }
+      },
+      "required": [
+        "job_id",
+        "status"
+      ]
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": true
+    }
+  }
+]