@viralspin/mcp 0.4.0 → 0.5.0

package/dist/tools/organize.js

@@ -0,0 +1,171 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bucketKey = exports.organizeAddToStoryTool = exports.organizeUndoTool = exports.organizeApplyTool = exports.organizeScanTool = exports.planFile = exports.STATE_DIR = void 0;
+exports.addPlanToStory = addPlanToStory;
+/**
+ * organize_scan / organize_apply / organize_undo — sort a big folder of pictures + clips into buckets.
+ *
+ * SCAN is read-only and local: it walks the tree, finds exact and near-identical copies, optionally tags each picture with the local
+ * vision model, and PROPOSES buckets + moves. Nothing is moved and nothing is uploaded. APPLY is a separate step: without confirm it
+ * only previews; with confirm it renames files into <folder>/_Organized/<bucket>/ (never overwrites, never deletes; duplicates are
+ * moved to Duplicates, not removed) and writes an undo manifest. UNDO puts everything back.
+ */
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const client_js_1 = require("../client.js");
+const plan_js_1 = require("../organizer/plan.js");
+const scan_js_1 = require("../organizer/scan.js");
+const images_js_1 = require("../organizer/images.js");
+const STATE = path_1.default.join(os_1.default.homedir(), ".viralspin", "organize");
+exports.STATE_DIR = STATE;
+const planFile = (id) => path_1.default.join(STATE, `${id.replace(/[^\w-]/g, "")}.json`);
+exports.planFile = planFile;
+exports.organizeScanTool = {
+    name: "organize_scan",
+    description: "Scan a LOCAL folder (recursive) of pictures and clips and PROPOSE how to organize it into buckets — read-only, nothing is moved, nothing is uploaded. " +
+        "Finds exact + near-identical duplicates, then groups by `by`: folder (default), date (month), topic (needs vision = local vision tags, free on the GPU in local mode), or type. " +
+        "Returns a plan id + the buckets. Show the user the buckets, then call organize_apply (preview first, then confirm) if they want the files moved. " +
+        "Use preview_folder first for a quick count.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            folder: { type: "string", description: "Local folder to scan, e.g. E:\\Money and Design\\062521\\Money and Design" },
+            by: { type: "string", enum: ["folder", "date", "topic", "type"], description: "How to group. Default folder. topic implies vision." },
+            vision: { type: "boolean", description: "Tag each picture with the local vision model (slow on thousands). Implied by by:'topic'." },
+            labels: { type: "array", items: { type: "string" }, description: "Optional labels of the creator's own (e.g. [\"tennis\", \"kids at the beach\"]): each becomes its own bucket when pictures match. Built-in labels are added as the folder needs them." },
+            thumbs: { type: "boolean", description: "Also write 480px thumbnails (for the web animation / opt-in My Story upload). Local only." },
+        },
+        required: ["folder"],
+    },
+    async execute(args) {
+        if (!(await (0, images_js_1.canReadPictures)()))
+            return "organize_scan needs to read pictures: install ffmpeg, or reinstall the ViralSpin connector (it brings its own).";
+        const by = args.by || "folder";
+        fs_1.default.mkdirSync(STATE, { recursive: true });
+        const tmpId = Date.now().toString(36);
+        let plan;
+        try {
+            plan = await (0, scan_js_1.organizeScan)(args.folder, { by, labels: args.labels ?? [], vision: !!args.vision || by === "topic", thumbs: args.thumbs ? path_1.default.join(STATE, `${tmpId}-thumbs`) : "" });
+        }
+        catch (e) {
+            return `Couldn't scan ${args.folder}: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        fs_1.default.writeFileSync((0, exports.planFile)(plan.id), JSON.stringify(plan));
+        const t = plan.totals;
+        const lines = plan.buckets.slice(0, 25).map((b) => `- ${b.name} (${b.kind}): ${b.items.length}${b.items[0] !== undefined ? `, e.g. ${plan.items[b.items[0]].rel}` : ""}`);
+        return [
+            `Scanned ${plan.root} — read-only, nothing moved or uploaded. Plan ${plan.id}.`,
+            `${t.files} file(s): ${t.images} picture(s), ${t.videos} clip(s), ${(t.bytes / 1e9).toFixed(2)} GB; ${t.dupes} extra copy/copies; ${t.buckets} bucket(s) by ${plan.by}.`,
+            ...lines,
+            plan.buckets.length > 25 ? `…and ${plan.buckets.length - 25} more.` : "",
+            `To move the files: organize_apply {plan: "${plan.id}"} previews, then again with confirm:true. Everything is undoable with organize_undo.`,
+        ].filter(Boolean).join("\n");
+    },
+};
+exports.organizeApplyTool = {
+    name: "organize_apply",
+    description: "Move the files of an organize_scan plan into <folder>/_Organized/<bucket>/. Without confirm:true it only PREVIEWS (counts + first moves). " +
+        "With confirm:true it renames files (never overwrites, never deletes; duplicates go to a Duplicates bucket) and writes an undo manifest. " +
+        "Only call with confirm:true after the user has seen the preview and agreed.",
+    inputSchema: {
+        type: "object",
+        properties: { plan: { type: "string", description: "Plan id from organize_scan." }, confirm: { type: "boolean", description: "true = actually move the files." } },
+        required: ["plan"],
+    },
+    async execute(args) {
+        const file = (0, exports.planFile)(args.plan);
+        if (!fs_1.default.existsSync(file))
+            return `No plan ${args.plan}. Run organize_scan first.`;
+        const plan = JSON.parse(fs_1.default.readFileSync(file, "utf8"));
+        if (!args.confirm) {
+            const sample = plan.moves.slice(0, 12).map((m) => `- ${path_1.default.relative(plan.root, m.from)}  →  ${path_1.default.relative(plan.root, m.to)}`);
+            return [`PREVIEW — nothing has been moved. ${plan.moves.length} file(s) would move into ${path_1.default.join(plan.root, "_Organized")} (${plan.buckets.length} bucket(s)).`, ...sample, plan.moves.length > 12 ? `…and ${plan.moves.length - 12} more.` : "", "Nothing is deleted or overwritten, and organize_undo puts it all back. Call again with confirm:true to go ahead."].filter(Boolean).join("\n");
+        }
+        const r = (0, plan_js_1.applyMoves)(plan.root, plan.moves, plan.id);
+        return `Moved ${r.moved} file(s) into ${path_1.default.join(plan.root, "_Organized")}${r.skipped ? ` (${r.skipped} skipped: gone or unreadable)` : ""}. Undo manifest: ${r.manifest}. Use organize_undo {plan:"${plan.id}"} to put everything back.`;
+    },
+};
+exports.organizeUndoTool = {
+    name: "organize_undo",
+    description: "Put back every file moved by organize_apply for a plan (files changed or re-created since are left alone and counted).",
+    inputSchema: { type: "object", properties: { plan: { type: "string", description: "Plan id." } }, required: ["plan"] },
+    async execute(args) {
+        const file = (0, exports.planFile)(args.plan);
+        if (!fs_1.default.existsSync(file))
+            return `No plan ${args.plan}.`;
+        const plan = JSON.parse(fs_1.default.readFileSync(file, "utf8"));
+        const manifest = path_1.default.join(plan.root, "_Organized", `.viralspin-undo-${plan.id}.json`);
+        if (!fs_1.default.existsSync(manifest))
+            return `Nothing to undo for plan ${plan.id} (no manifest — it was not applied, or was already undone).`;
+        const r = (0, plan_js_1.undoMoves)(manifest);
+        return `Restored ${r.restored} file(s)${r.left ? `; ${r.left} left where they are (changed since)` : ""}.`;
+    },
+};
+/** The opt-in: send the tags + a small thumbnail of each organized file to My Story. The originals stay on this computer. */
+exports.organizeAddToStoryTool = {
+    name: "organize_add_to_story",
+    description: "OPT-IN. Add an organized folder (an organize_scan plan) to the user's My Story assets, so its buckets show in the ViralSpin web app and feed carousels and 7-second reels. " +
+        "Uploads ONLY a 480px thumbnail + tag + bucket per file (duplicates skipped); the original files stay on this computer and nothing is uploaded unless the user asked for this. " +
+        "Run it BEFORE organize_apply (thumbnails are read from the original locations). Needs a ViralSpin sign-in.",
+    inputSchema: {
+        type: "object",
+        properties: { plan: { type: "string", description: "Plan id from organize_scan." }, remove: { type: "boolean", description: "true = take this folder back out of My Story." } },
+        required: ["plan"],
+    },
+    async execute(args) {
+        const file = (0, exports.planFile)(args.plan);
+        if (!fs_1.default.existsSync(file))
+            return `No plan ${args.plan}. Run organize_scan first.`;
+        if (args.remove) {
+            const r = await (0, client_js_1.del)(`/v1/library/organized?plan_id=${encodeURIComponent(args.plan)}`);
+            return `Removed this folder from My Story (${r.removed} thumbnail(s) deleted). Your files were never touched.`;
+        }
+        return addPlanToStory(file, { post: client_js_1.post });
+    },
+};
+/** Upload a plan's tags + 480px thumbnails to My Story (the opt-in). Used by the tool and by the connector when the web app asks. */
+/** `only`: bucket keys ("image:Family", "video:Outfits") when the creator picked some folders; all of them when absent. */
+const bucketKey = (b) => `${b.media ?? "any"}:${b.name}`;
+exports.bucketKey = bucketKey;
+async function addPlanToStory(file, io, progress, only) {
+    let plan = JSON.parse(fs_1.default.readFileSync(file, "utf8"));
+    if (!plan.items.some((i) => i.thumb && fs_1.default.existsSync(i.thumb))) {
+        await (0, scan_js_1.makeThumbsFor)(file, path_1.default.join(STATE, `${plan.id}-thumbs`));
+        plan = JSON.parse(fs_1.default.readFileSync(file, "utf8"));
+    }
+    const label = path_1.default.basename(plan.root);
+    const entries = [];
+    const pick = only?.length ? new Set(only) : null;
+    for (const b of plan.buckets)
+        if (b.kind !== "duplicates" && (!pick || pick.has((0, exports.bucketKey)(b))))
+            for (const i of b.items)
+                entries.push({ item: plan.items[i], bucket: b });
+    let added = 0, thumbs = 0;
+    const totalN = entries.length;
+    for (let k = 0; k < entries.length; k += 200) {
+        const chunk = entries.slice(k, k + 200);
+        const r = await io.post("/v1/library/organized", {
+            plan_id: plan.id, root_label: label,
+            items: chunk.map(({ item, bucket }) => ({ rel: item.rel, kind: item.kind, bucket: bucket.name, bucket_kind: bucket.kind, subject: item.subject, tags: item.tags, month: item.month ?? null, live: !!item.live, has_thumb: !!(item.thumb && fs_1.default.existsSync(item.thumb)) })),
+        });
+        added += r.added;
+        const byRel = new Map(chunk.map((c) => [c.item.rel, c.item]));
+        for (const u of r.uploads) {
+            const t = byRel.get(u.rel)?.thumb;
+            if (!t)
+                continue;
+            const form = new FormData();
+            form.append("cacheControl", "31536000");
+            form.append("", new Blob([await fs_1.default.promises.readFile(t)], { type: "image/jpeg" }), "t.jpg");
+            const resp = await fetch(u.upload_url, { method: "PUT", body: form, headers: { "x-upsert": "true" } });
+            if (resp.ok)
+                thumbs++;
+        }
+        progress?.(Math.min(k + 200, totalN), totalN);
+    }
+    return `Added ${added} file(s) from "${label}" to My Story in ${plan.buckets.filter((b) => b.kind !== "duplicates").length} bucket(s) (${thumbs} thumbnail(s) uploaded; originals stay on this computer). They show in My Story ▸ Organized and feed carousels and 7s reels. organize_add_to_story {plan:"${plan.id}", remove:true} takes them back out.`;
+}

package/package.json

@@ -1,42 +1,46 @@
-{
-  "name": "@viralspin/mcp",
-  "version": "0.4.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"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "ts-node src/index.ts",
-    "start": "node dist/index.js",
-    "prepublishOnly": "npm run build",
-    "test": "tsc && node --test test/*.test.js"
-  },
-  "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"
-  }
-}
+{
+  "name": "@viralspin/mcp",
+  "version": "0.5.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"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build",
+    "test": "tsc && node --test test/"
+  },
+  "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"
+  },
+  "optionalDependencies": {
+    "@huggingface/transformers": "^4.3.2",
+    "sharp": "^0.35.5"
+  }
+}