@viralspin/mcp 0.1.0

package/dist/client.js

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.get = get;
+exports.post = post;
+exports.del = del;
+exports.uploadFiles = uploadFiles;
+exports.deleteFiles = deleteFiles;
+const form_data_1 = __importDefault(require("form-data"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const API_URL = (process.env.VIRALSPIN_API_URL || "https://viralspinbackend.onrender.com").replace(/\/$/, "");
+const API_KEY = process.env.VIRALSPIN_API_KEY || "";
+if (!API_KEY) {
+    process.stderr.write("[viralspin-mcp] Warning: VIRALSPIN_API_KEY not set\n");
+}
+function headers(extra = {}) {
+    return { "X-API-Key": API_KEY, ...extra };
+}
+async function apiFetch(endpoint, init = {}) {
+    const url = `${API_URL}${endpoint}`;
+    const resp = await fetch(url, {
+        ...init,
+        headers: { ...(init.headers ?? {}), ...headers() },
+    });
+    if (!resp.ok) {
+        const text = await resp.text().catch(() => "");
+        let detail = text;
+        try {
+            detail = JSON.parse(text).detail ?? text;
+        }
+        catch { }
+        throw new Error(`API error ${resp.status}: ${detail}`);
+    }
+    return resp.json();
+}
+function get(endpoint) {
+    return apiFetch(endpoint, { method: "GET" });
+}
+function post(endpoint, body) {
+    return apiFetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+}
+function del(endpoint, body) {
+    return apiFetch(endpoint, {
+        method: "DELETE",
+        headers: body ? { "Content-Type": "application/json" } : {},
+        body: body ? JSON.stringify(body) : undefined,
+    });
+}
+/** Upload one or more local files. Returns { url, storage_path } or { urls, storage_paths } */
+async function uploadFiles(filePaths) {
+    const form = new form_data_1.default();
+    const fieldName = filePaths.length === 1 ? "file" : "files";
+    for (const fp of filePaths) {
+        form.append(fieldName, fs_1.default.createReadStream(fp), path_1.default.basename(fp));
+    }
+    const resp = await fetch(`${API_URL}/v1/media/upload`, {
+        method: "POST",
+        headers: { "X-API-Key": API_KEY, ...form.getHeaders() },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        body: form,
+    });
+    if (!resp.ok) {
+        const text = await resp.text().catch(() => "");
+        let detail = text;
+        try {
+            detail = JSON.parse(text).detail ?? text;
+        }
+        catch { }
+        throw new Error(`Upload failed ${resp.status}: ${detail}`);
+    }
+    const data = await resp.json();
+    if (data.urls)
+        return { urls: data.urls, storage_paths: data.storage_paths };
+    return { urls: [data.url], storage_paths: [data.storage_path] };
+}
+/** Delete uploaded files from storage (cleanup after publish) */
+async function deleteFiles(storagePaths) {
+    if (!storagePaths.length)
+        return;
+    await del(`/v1/media/${storagePaths[0]}`, storagePaths.length > 1 ? { storage_paths: storagePaths } : undefined);
+}

package/dist/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const connections_js_1 = require("./tools/connections.js");
+const publish_js_1 = require("./tools/publish.js");
+const posts_js_1 = require("./tools/posts.js");
+const captions_js_1 = require("./tools/captions.js");
+const tools = [
+    connections_js_1.listConnectionsTool,
+    publish_js_1.publishNowTool,
+    publish_js_1.schedulePostTool,
+    posts_js_1.listPostsTool,
+    posts_js_1.cancelPostTool,
+    captions_js_1.generateCaptionTool,
+];
+const server = new index_js_1.Server({ name: "viralspin", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    })),
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
+    const tool = tools.find((t) => t.name === req.params.name);
+    if (!tool) {
+        return { content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }], isError: true };
+    }
+    try {
+        const result = await tool.execute(req.params.arguments);
+        return { content: [{ type: "text", text: String(result) }] };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+    }
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("[viralspin-mcp] Server started\n");
+}
+main().catch((err) => {
+    process.stderr.write(`[viralspin-mcp] Fatal: ${err}\n`);
+    process.exit(1);
+});

package/dist/tools/captions.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateCaptionTool = void 0;
+const client_js_1 = require("../client.js");
+exports.generateCaptionTool = {
+    name: "generate_caption",
+    description: "Generate an AI caption and hashtags for a post on a specific platform.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            title: { type: "string", description: "Video or content title/description." },
+            platform: {
+                type: "string",
+                enum: ["tiktok", "instagram", "youtube"],
+                description: "Target platform.",
+            },
+        },
+        required: ["title", "platform"],
+    },
+    async execute(args) {
+        const data = await (0, client_js_1.post)("/v1/publish/generate-caption", {
+            video_title: args.title,
+            platform: args.platform,
+        });
+        const tags = data.hashtags.map((h) => `#${h.replace(/^#/, "")}`).join(" ");
+        return `Caption:\n${data.caption}\n\nHashtags:\n${tags}`;
+    },
+};

package/dist/tools/connections.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listConnectionsTool = void 0;
+const client_js_1 = require("../client.js");
+exports.listConnectionsTool = {
+    name: "list_connections",
+    description: "List your connected social media accounts (TikTok, Instagram, YouTube).",
+    inputSchema: { type: "object", properties: {}, required: [] },
+    async execute(_args) {
+        const connections = await (0, client_js_1.get)("/v1/publish/connections");
+        if (!connections.length) {
+            return "No platforms connected yet. Visit https://www.viralspin.ai/spin/settings to connect your accounts.";
+        }
+        return connections
+            .map((c) => `${c.platform}: ${c.display_name} (${c.username}) — ${c.follower_count.toLocaleString()} followers`)
+            .join("\n");
+    },
+};

package/dist/tools/posts.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cancelPostTool = exports.listPostsTool = void 0;
+const client_js_1 = require("../client.js");
+exports.listPostsTool = {
+    name: "list_posts",
+    description: "List your scheduled, published, or failed posts.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            status: {
+                type: "string",
+                enum: ["pending", "published", "cancelled", "failed"],
+                description: "Filter by status. Omit to list all posts.",
+            },
+        },
+        required: [],
+    },
+    async execute(args) {
+        const qs = args.status ? `?status=${args.status}` : "";
+        const posts = await (0, client_js_1.get)(`/v1/publish/posts${qs}`);
+        if (!posts.length)
+            return "No posts found.";
+        return posts
+            .map((p) => {
+            const time = p.published_at ?? p.scheduled_time;
+            const label = p.published_at ? "published" : "scheduled";
+            return `[${p.id.slice(0, 8)}] ${p.status.toUpperCase()} — ${p.platforms.join("+")} ${p.media_type} | ${label}: ${time}\n  "${p.caption?.slice(0, 60)}${(p.caption?.length ?? 0) > 60 ? "…" : ""}"${p.failed_reason ? `\n  Error: ${p.failed_reason}` : ""}`;
+        })
+            .join("\n\n");
+    },
+};
+exports.cancelPostTool = {
+    name: "cancel_post",
+    description: "Cancel a pending scheduled post by ID.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            post_id: { type: "string", description: "The post ID to cancel." },
+        },
+        required: ["post_id"],
+    },
+    async execute(args) {
+        await (0, client_js_1.del)(`/v1/publish/posts/${args.post_id}`);
+        return `Post ${args.post_id} cancelled.`;
+    },
+};

package/dist/tools/publish.js

@@ -0,0 +1,144 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schedulePostTool = exports.publishNowTool = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const client_js_1 = require("../client.js");
+const IMAGE_EXTS = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp"]);
+const VIDEO_EXTS = new Set([".mp4", ".mov", ".webm", ".avi"]);
+function detectMediaType(filePaths) {
+    if (filePaths.length > 1)
+        return "carousel";
+    const ext = path_1.default.extname(filePaths[0]).toLowerCase();
+    return IMAGE_EXTS.has(ext) ? "carousel" : "video";
+}
+/** Expand a folder path into individual file paths (images/videos only, sorted) */
+function expandPaths(inputs) {
+    const result = [];
+    for (const p of inputs) {
+        const stat = fs_1.default.statSync(p, { throwIfNoEntry: false });
+        if (!stat)
+            throw new Error(`Path not found: ${p}`);
+        if (stat.isDirectory()) {
+            const files = fs_1.default.readdirSync(p)
+                .filter((f) => {
+                const ext = path_1.default.extname(f).toLowerCase();
+                return IMAGE_EXTS.has(ext) || VIDEO_EXTS.has(ext);
+            })
+                .sort()
+                .map((f) => path_1.default.join(p, f));
+            result.push(...files);
+        }
+        else {
+            result.push(p);
+        }
+    }
+    return result;
+}
+const publishSchema = {
+    type: "object",
+    properties: {
+        paths: {
+            type: "array",
+            items: { type: "string" },
+            description: "Local file path(s) or a folder path. Single video → video post. Multiple images or image folder → carousel.",
+        },
+        platforms: {
+            type: "array",
+            items: { type: "string", enum: ["tiktok", "instagram", "youtube"] },
+            description: "Platforms to publish to. Must be connected.",
+        },
+        caption: { type: "string", description: "Post caption." },
+        hashtags: {
+            type: "array",
+            items: { type: "string" },
+            description: "Hashtags without # prefix.",
+        },
+    },
+    required: ["paths", "platforms", "caption"],
+};
+exports.publishNowTool = {
+    name: "publish_now",
+    description: "Upload local file(s) and publish immediately to TikTok, Instagram, and/or YouTube. Pass a folder path to publish all images in it as a carousel.",
+    inputSchema: publishSchema,
+    async execute(args) {
+        const filePaths = expandPaths(args.paths);
+        if (!filePaths.length)
+            throw new Error("No media files found in the provided paths.");
+        const mediaType = detectMediaType(filePaths);
+        if (mediaType === "carousel" && filePaths.length > 10) {
+            throw new Error(`Instagram supports max 10 images per carousel. Found ${filePaths.length} files.`);
+        }
+        // Upload files
+        const { urls, storage_paths } = await (0, client_js_1.uploadFiles)(filePaths);
+        let result;
+        try {
+            result = await (0, client_js_1.post)("/v1/publish/schedule", {
+                media_urls: urls,
+                media_type: mediaType,
+                platforms: args.platforms,
+                caption: args.caption,
+                hashtags: args.hashtags ?? [],
+                publish_now: true,
+            });
+        }
+        finally {
+            // Always clean up uploaded files
+            await (0, client_js_1.deleteFiles)(storage_paths).catch(() => { });
+        }
+        const { status, platform_post_ids, failed_reason } = result.post;
+        const published = Object.keys(platform_post_ids);
+        let summary = `Status: ${status}\n`;
+        if (published.length)
+            summary += `Published to: ${published.join(", ")}\n`;
+        if (failed_reason)
+            summary += `Errors: ${failed_reason}`;
+        return summary.trim();
+    },
+};
+exports.schedulePostTool = {
+    name: "schedule_post",
+    description: "Upload local file(s) and schedule a post for a future time. Pass a folder path to schedule all images as a carousel.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ...publishSchema.properties,
+            scheduled_time: {
+                type: "string",
+                description: "ISO 8601 datetime string for when to publish (e.g. '2026-05-10T09:00:00'). Uses your local timezone if no timezone offset provided.",
+            },
+            timezone: {
+                type: "string",
+                description: "IANA timezone name (e.g. 'America/New_York'). Defaults to UTC.",
+            },
+        },
+        required: ["paths", "platforms", "caption", "scheduled_time"],
+    },
+    async execute(args) {
+        const filePaths = expandPaths(args.paths);
+        if (!filePaths.length)
+            throw new Error("No media files found in the provided paths.");
+        const mediaType = detectMediaType(filePaths);
+        // Upload files (storage URLs remain valid for 1 hour; cron will publish before then if scheduled soon,
+        // otherwise the cron route will fail — advise scheduling within the hour for now)
+        const { urls, storage_paths } = await (0, client_js_1.uploadFiles)(filePaths);
+        const result = await (0, client_js_1.post)("/v1/publish/schedule", {
+            media_urls: urls,
+            media_type: mediaType,
+            platforms: args.platforms,
+            caption: args.caption,
+            hashtags: args.hashtags ?? [],
+            scheduled_time: args.scheduled_time,
+            timezone: args.timezone,
+            publish_now: false,
+        });
+        // Note: storage_paths are NOT deleted here — the cron job needs the URLs to stay valid.
+        // They expire after 1 hour. For posts scheduled further out, re-upload closer to publish time.
+        void storage_paths;
+        const { post: p } = result;
+        return `Scheduled post ${p.id}\nPlatforms: ${args.platforms.join(", ")}\nTime: ${args.scheduled_time}\nStatus: ${p.status}`;
+    },
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@viralspin/mcp",
+  "version": "0.1.0",
+  "description": "ViralSpin MCP server — publish local videos and carousels to TikTok, Instagram, and YouTube from Claude Code",
+  "main": "dist/index.js",
+  "bin": {
+    "viralspin-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["mcp", "viralspin", "tiktok", "instagram", "youtube", "social-media"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "form-data": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/form-data": "^2.5.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/client.ts

@@ -0,0 +1,80 @@
+import FormData from "form-data";
+import fs from "fs";
+import path from "path";
+
+const API_URL = (process.env.VIRALSPIN_API_URL || "https://viralspinbackend.onrender.com").replace(/\/$/, "");
+const API_KEY = process.env.VIRALSPIN_API_KEY || "";
+
+if (!API_KEY) {
+  process.stderr.write("[viralspin-mcp] Warning: VIRALSPIN_API_KEY not set\n");
+}
+
+function headers(extra: Record<string, string> = {}): Record<string, string> {
+  return { "X-API-Key": API_KEY, ...extra };
+}
+
+async function apiFetch<T>(endpoint: string, init: RequestInit = {}): Promise<T> {
+  const url = `${API_URL}${endpoint}`;
+  const resp = await fetch(url, {
+    ...init,
+    headers: { ...(init.headers as Record<string, string> ?? {}), ...headers() },
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    let detail = text;
+    try { detail = JSON.parse(text).detail ?? text; } catch {}
+    throw new Error(`API error ${resp.status}: ${detail}`);
+  }
+  return resp.json() as Promise<T>;
+}
+
+export function get<T>(endpoint: string): Promise<T> {
+  return apiFetch<T>(endpoint, { method: "GET" });
+}
+
+export function post<T>(endpoint: string, body: unknown): Promise<T> {
+  return apiFetch<T>(endpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+export function del<T>(endpoint: string, body?: unknown): Promise<T> {
+  return apiFetch<T>(endpoint, {
+    method: "DELETE",
+    headers: body ? { "Content-Type": "application/json" } : {},
+    body: body ? JSON.stringify(body) : undefined,
+  });
+}
+
+/** Upload one or more local files. Returns { url, storage_path } or { urls, storage_paths } */
+export async function uploadFiles(filePaths: string[]): Promise<{ urls: string[]; storage_paths: string[] }> {
+  const form = new FormData();
+  const fieldName = filePaths.length === 1 ? "file" : "files";
+  for (const fp of filePaths) {
+    form.append(fieldName, fs.createReadStream(fp), path.basename(fp));
+  }
+
+  const resp = await fetch(`${API_URL}/v1/media/upload`, {
+    method: "POST",
+    headers: { "X-API-Key": API_KEY, ...form.getHeaders() },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    body: form as any,
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    let detail = text;
+    try { detail = JSON.parse(text).detail ?? text; } catch {}
+    throw new Error(`Upload failed ${resp.status}: ${detail}`);
+  }
+  const data = await resp.json() as { url?: string; storage_path?: string; urls?: string[]; storage_paths?: string[] };
+  if (data.urls) return { urls: data.urls, storage_paths: data.storage_paths! };
+  return { urls: [data.url!], storage_paths: [data.storage_path!] };
+}
+
+/** Delete uploaded files from storage (cleanup after publish) */
+export async function deleteFiles(storagePaths: string[]): Promise<void> {
+  if (!storagePaths.length) return;
+  await del(`/v1/media/${storagePaths[0]}`, storagePaths.length > 1 ? { storage_paths: storagePaths } : undefined);
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+#!/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 { listConnectionsTool } from "./tools/connections.js";
+import { publishNowTool, schedulePostTool } from "./tools/publish.js";
+import { listPostsTool, cancelPostTool } from "./tools/posts.js";
+import { generateCaptionTool } from "./tools/captions.js";
+
+const tools = [
+  listConnectionsTool,
+  publishNowTool,
+  schedulePostTool,
+  listPostsTool,
+  cancelPostTool,
+  generateCaptionTool,
+];
+
+const server = new Server(
+  { name: "viralspin", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = tools.find((t) => t.name === req.params.name);
+  if (!tool) {
+    return { content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }], isError: true };
+  }
+
+  try {
+    const result = await tool.execute(req.params.arguments as never);
+    return { content: [{ type: "text", text: String(result) }] };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write("[viralspin-mcp] Server started\n");
+}
+
+main().catch((err) => {
+  process.stderr.write(`[viralspin-mcp] Fatal: ${err}\n`);
+  process.exit(1);
+});

package/src/tools/captions.ts

@@ -0,0 +1,32 @@
+import { post } from "../client.js";
+
+interface CaptionResponse {
+  caption: string;
+  hashtags: string[];
+}
+
+export const generateCaptionTool = {
+  name: "generate_caption",
+  description: "Generate an AI caption and hashtags for a post on a specific platform.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      title: { type: "string", description: "Video or content title/description." },
+      platform: {
+        type: "string",
+        enum: ["tiktok", "instagram", "youtube"],
+        description: "Target platform.",
+      },
+    },
+    required: ["title", "platform"],
+  },
+
+  async execute(args: { title: string; platform: string }) {
+    const data = await post<CaptionResponse>("/v1/publish/generate-caption", {
+      video_title: args.title,
+      platform: args.platform,
+    });
+    const tags = data.hashtags.map((h) => `#${h.replace(/^#/, "")}`).join(" ");
+    return `Caption:\n${data.caption}\n\nHashtags:\n${tags}`;
+  },
+};

package/src/tools/connections.ts

@@ -0,0 +1,27 @@
+import { get } from "../client.js";
+
+interface Connection {
+  id: string;
+  platform: string;
+  display_name: string;
+  username: string;
+  follower_count: number;
+  is_active: boolean;
+  connected_at: string;
+}
+
+export const listConnectionsTool = {
+  name: "list_connections",
+  description: "List your connected social media accounts (TikTok, Instagram, YouTube).",
+  inputSchema: { type: "object", properties: {}, required: [] },
+
+  async execute(_args: Record<string, unknown>) {
+    const connections = await get<Connection[]>("/v1/publish/connections");
+    if (!connections.length) {
+      return "No platforms connected yet. Visit https://www.viralspin.ai/spin/settings to connect your accounts.";
+    }
+    return connections
+      .map((c) => `${c.platform}: ${c.display_name} (${c.username}) — ${c.follower_count.toLocaleString()} followers`)
+      .join("\n");
+  },
+};

package/src/tools/posts.ts

@@ -0,0 +1,58 @@
+import { get, del } from "../client.js";
+
+interface ScheduledPost {
+  id: string;
+  platforms: string[];
+  caption: string;
+  status: string;
+  scheduled_time: string;
+  published_at: string | null;
+  failed_reason: string | null;
+  media_type: string;
+}
+
+export const listPostsTool = {
+  name: "list_posts",
+  description: "List your scheduled, published, or failed posts.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      status: {
+        type: "string",
+        enum: ["pending", "published", "cancelled", "failed"],
+        description: "Filter by status. Omit to list all posts.",
+      },
+    },
+    required: [],
+  },
+
+  async execute(args: { status?: string }) {
+    const qs = args.status ? `?status=${args.status}` : "";
+    const posts = await get<ScheduledPost[]>(`/v1/publish/posts${qs}`);
+    if (!posts.length) return "No posts found.";
+    return posts
+      .map((p) => {
+        const time = p.published_at ?? p.scheduled_time;
+        const label = p.published_at ? "published" : "scheduled";
+        return `[${p.id.slice(0, 8)}] ${p.status.toUpperCase()} — ${p.platforms.join("+")} ${p.media_type} | ${label}: ${time}\n  "${p.caption?.slice(0, 60)}${(p.caption?.length ?? 0) > 60 ? "…" : ""}"${p.failed_reason ? `\n  Error: ${p.failed_reason}` : ""}`;
+      })
+      .join("\n\n");
+  },
+};
+
+export const cancelPostTool = {
+  name: "cancel_post",
+  description: "Cancel a pending scheduled post by ID.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      post_id: { type: "string", description: "The post ID to cancel." },
+    },
+    required: ["post_id"],
+  },
+
+  async execute(args: { post_id: string }) {
+    await del(`/v1/publish/posts/${args.post_id}`);
+    return `Post ${args.post_id} cancelled.`;
+  },
+};

package/src/tools/publish.ts

@@ -0,0 +1,158 @@
+import fs from "fs";
+import path from "path";
+import { post, uploadFiles, deleteFiles } from "../client.js";
+
+const IMAGE_EXTS = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp"]);
+const VIDEO_EXTS = new Set([".mp4", ".mov", ".webm", ".avi"]);
+
+function detectMediaType(filePaths: string[]): "video" | "carousel" {
+  if (filePaths.length > 1) return "carousel";
+  const ext = path.extname(filePaths[0]).toLowerCase();
+  return IMAGE_EXTS.has(ext) ? "carousel" : "video";
+}
+
+/** Expand a folder path into individual file paths (images/videos only, sorted) */
+function expandPaths(inputs: string[]): string[] {
+  const result: string[] = [];
+  for (const p of inputs) {
+    const stat = fs.statSync(p, { throwIfNoEntry: false });
+    if (!stat) throw new Error(`Path not found: ${p}`);
+    if (stat.isDirectory()) {
+      const files = fs.readdirSync(p)
+        .filter((f) => {
+          const ext = path.extname(f).toLowerCase();
+          return IMAGE_EXTS.has(ext) || VIDEO_EXTS.has(ext);
+        })
+        .sort()
+        .map((f) => path.join(p, f));
+      result.push(...files);
+    } else {
+      result.push(p);
+    }
+  }
+  return result;
+}
+
+interface PublishResult {
+  post: { id: string; status: string; platform_post_ids: Record<string, string>; failed_reason?: string };
+}
+
+const publishSchema = {
+  type: "object",
+  properties: {
+    paths: {
+      type: "array",
+      items: { type: "string" },
+      description: "Local file path(s) or a folder path. Single video → video post. Multiple images or image folder → carousel.",
+    },
+    platforms: {
+      type: "array",
+      items: { type: "string", enum: ["tiktok", "instagram", "youtube"] },
+      description: "Platforms to publish to. Must be connected.",
+    },
+    caption: { type: "string", description: "Post caption." },
+    hashtags: {
+      type: "array",
+      items: { type: "string" },
+      description: "Hashtags without # prefix.",
+    },
+  },
+  required: ["paths", "platforms", "caption"],
+};
+
+export const publishNowTool = {
+  name: "publish_now",
+  description: "Upload local file(s) and publish immediately to TikTok, Instagram, and/or YouTube. Pass a folder path to publish all images in it as a carousel.",
+  inputSchema: publishSchema,
+
+  async execute(args: { paths: string[]; platforms: string[]; caption: string; hashtags?: string[] }) {
+    const filePaths = expandPaths(args.paths);
+    if (!filePaths.length) throw new Error("No media files found in the provided paths.");
+
+    const mediaType = detectMediaType(filePaths);
+    if (mediaType === "carousel" && filePaths.length > 10) {
+      throw new Error(`Instagram supports max 10 images per carousel. Found ${filePaths.length} files.`);
+    }
+
+    // Upload files
+    const { urls, storage_paths } = await uploadFiles(filePaths);
+
+    let result: PublishResult;
+    try {
+      result = await post<PublishResult>("/v1/publish/schedule", {
+        media_urls: urls,
+        media_type: mediaType,
+        platforms: args.platforms,
+        caption: args.caption,
+        hashtags: args.hashtags ?? [],
+        publish_now: true,
+      });
+    } finally {
+      // Always clean up uploaded files
+      await deleteFiles(storage_paths).catch(() => {});
+    }
+
+    const { status, platform_post_ids, failed_reason } = result.post;
+    const published = Object.keys(platform_post_ids);
+    let summary = `Status: ${status}\n`;
+    if (published.length) summary += `Published to: ${published.join(", ")}\n`;
+    if (failed_reason) summary += `Errors: ${failed_reason}`;
+    return summary.trim();
+  },
+};
+
+export const schedulePostTool = {
+  name: "schedule_post",
+  description: "Upload local file(s) and schedule a post for a future time. Pass a folder path to schedule all images as a carousel.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      ...publishSchema.properties,
+      scheduled_time: {
+        type: "string",
+        description: "ISO 8601 datetime string for when to publish (e.g. '2026-05-10T09:00:00'). Uses your local timezone if no timezone offset provided.",
+      },
+      timezone: {
+        type: "string",
+        description: "IANA timezone name (e.g. 'America/New_York'). Defaults to UTC.",
+      },
+    },
+    required: ["paths", "platforms", "caption", "scheduled_time"],
+  },
+
+  async execute(args: {
+    paths: string[];
+    platforms: string[];
+    caption: string;
+    hashtags?: string[];
+    scheduled_time: string;
+    timezone?: string;
+  }) {
+    const filePaths = expandPaths(args.paths);
+    if (!filePaths.length) throw new Error("No media files found in the provided paths.");
+
+    const mediaType = detectMediaType(filePaths);
+
+    // Upload files (storage URLs remain valid for 1 hour; cron will publish before then if scheduled soon,
+    // otherwise the cron route will fail — advise scheduling within the hour for now)
+    const { urls, storage_paths } = await uploadFiles(filePaths);
+
+    const result = await post<PublishResult>("/v1/publish/schedule", {
+      media_urls: urls,
+      media_type: mediaType,
+      platforms: args.platforms,
+      caption: args.caption,
+      hashtags: args.hashtags ?? [],
+      scheduled_time: args.scheduled_time,
+      timezone: args.timezone,
+      publish_now: false,
+    });
+
+    // Note: storage_paths are NOT deleted here — the cron job needs the URLs to stay valid.
+    // They expire after 1 hour. For posts scheduled further out, re-upload closer to publish time.
+    void storage_paths;
+
+    const { post: p } = result;
+    return `Scheduled post ${p.id}\nPlatforms: ${args.platforms.join(", ")}\nTime: ${args.scheduled_time}\nStatus: ${p.status}`;
+  },
+};

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}