@viralspin/mcp 0.5.2 → 0.5.4

package/dist/organize-watch.js

@@ -22,6 +22,7 @@ const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const http_1 = __importDefault(require("http"));
+const phoneReceive_1 = require("./phoneReceive");
 const path_1 = __importDefault(require("path"));
 const organize_js_1 = require("./tools/organize.js");
 const plan_js_1 = require("./organizer/plan.js");
@@ -233,6 +234,39 @@ function startThumbServer(log) {
             res.setHeader("Cache-Control", "private, max-age=3600");
             return void fs_1.default.createReadStream(f).pipe(res);
         }
+        // receiving from an iPhone over the home network (phoneReceive.ts): the page starts, watches and stops it; the phone talks to the LAN server
+        if (route === "/receive/status") {
+            if (!ORIGIN_OK.test(origin)) {
+                res.statusCode = 403;
+                return res.end();
+            }
+            res.setHeader("Content-Type", "application/json");
+            return res.end(JSON.stringify({ ...(0, phoneReceive_1.receiveStatus)(), defaultDest: (0, phoneReceive_1.defaultDest)() }));
+        }
+        if (route === "/receive/start" || route === "/receive/stop") {
+            if (req.method !== "POST" || !ORIGIN_OK.test(origin)) {
+                res.statusCode = 403;
+                return res.end();
+            }
+            if (route === "/receive/stop") {
+                (0, phoneReceive_1.stopReceive)(log);
+                res.setHeader("Content-Type", "application/json");
+                return res.end(JSON.stringify((0, phoneReceive_1.receiveStatus)()));
+            }
+            let raw = "";
+            req.on("data", (c) => { raw += c; if (raw.length > 10000)
+                req.destroy(); });
+            req.on("end", () => {
+                let dest;
+                try {
+                    dest = JSON.parse(raw || "{}").dest;
+                }
+                catch { /* the default folder */ }
+                (0, phoneReceive_1.startReceive)(dest, log).then((st) => { res.setHeader("Content-Type", "application/json"); res.end(JSON.stringify(st)); })
+                    .catch((e) => { res.statusCode = 500; res.setHeader("Content-Type", "application/json"); res.end(JSON.stringify({ error: e.message })); });
+            });
+            return;
+        }
         if (route === "/ping") {
             res.setHeader("Content-Type", "application/json");
             return res.end(JSON.stringify({ ok: true, items: 1 }));

package/dist/organizer/edit.js

@@ -17,6 +17,8 @@ const plan_1 = require("./plan");
 const path_1 = __importDefault(require("path"));
 const images_1 = require("./images");
 const topics_1 = require("./topics");
+const images_2 = require("./images");
+const phoneTopics_1 = require("./phoneTopics");
 const same = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
 /** The creator's labels after the ops: the ones the sort started with, plus added ones, minus removed ones. */
 function labelsAfter(start, ops) {
@@ -33,6 +35,15 @@ function labelsAfter(start, ops) {
 function regroup(plan, ops) {
     for (const o of ops) {
         const out = o.op === "exclude" ? new Set(o.items) : null;
+        // the phone's topics, as the pictures they matched: those pictures take that topic (a later merge / rename / hide still applies to it)
+        if (o.op === "assign") {
+            for (const [i, t] of o.items) {
+                const it = plan.items[i];
+                if (it && it.dupOf === undefined)
+                    it.topic = t;
+            }
+            continue;
+        }
         plan.items.forEach((it, i) => {
             if (!it.topic)
                 return;
@@ -83,10 +94,35 @@ async function backfillEmbeddings(plan, embPath, onProgress) {
     }
     fs_1.default.writeFileSync(embPath, Buffer.from((buf ?? new Float32Array(0)).buffer));
 }
+/**
+ * Every picture's fingerprint for matching the phone's: the one the scan kept, else (a HEIC sharp can't read, mostly) one made from the small
+ * preview the sort already saved on this computer. Videos and duplicates get none. Previews made here are kept on the item for next time.
+ */
+async function pictureHashes(plan) {
+    const out = plan.items.map((it) => (it.kind === "image" && it.dupOf === undefined ? it.dhash : undefined));
+    const missing = plan.items.map((it, i) => i).filter((i) => plan.items[i].kind === "image" && plan.items[i].dupOf === undefined && !out[i] && plan.items[i].thumb && fs_1.default.existsSync(plan.items[i].thumb));
+    for (const i of missing) {
+        const h = await (0, images_2.dhash)(plan.items[i].thumb).catch(() => null);
+        if (h) {
+            out[i] = h;
+            plan.items[i].dhash = h;
+        }
+    }
+    return out;
+}
 async function applyOps(planPath, embPath, add, onProgress) {
     const plan = JSON.parse(fs_1.default.readFileSync(planPath, "utf8"));
     if (plan.by !== "topic")
         throw new Error("Changing folders needs a sort By topic.");
+    // the phone's topics arrive as fingerprints: match them against this sort's pictures once, and keep only what matched
+    const filed = new Map();
+    add = await Promise.all(add.map(async (o) => {
+        if (o.op !== "phone_topics")
+            return o;
+        const m = (0, phoneTopics_1.matchPhoneTopics)(await pictureHashes(plan), o.rows ?? []);
+        filed.set(o.source ?? "iPhone", m);
+        return { op: "assign", items: [...m.entries()], source: o.source ?? "iPhone" };
+    }));
     const ops = [...(plan.ops ?? []), ...add];
     const before = new Map();
     for (const it of plan.items)
@@ -141,6 +177,10 @@ async function applyOps(planPath, embPath, add, onProgress) {
             lines.push(`Renamed ${o.from} to ${o.to}`);
         if (o.op === "exclude")
             lines.push(`Took ${o.items.length} out of ${o.bucket}`);
+        if (o.op === "assign") {
+            const m = filed.get(o.source ?? "iPhone");
+            lines.push(o.items.length ? `Filed ${o.items.length.toLocaleString()} pictures under your ${o.source ?? "iPhone"}'s topics${m ? `: ${(0, phoneTopics_1.sayTopics)(m)}` : ""}` : `None of these pictures are in your ${o.source ?? "iPhone"}'s sort`);
+        }
         if (o.op === "hide")
             lines.push(`Hid ${o.bucket} (${(before.get(o.bucket) ?? 0).toLocaleString()} pictures stay on your computer)`);
     }

package/dist/organizer/phoneTopics.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEAR = void 0;
+exports.matchPhoneTopics = matchPhoneTopics;
+exports.sayTopics = sayTopics;
+/**
+ * FILE THIS COMPUTER'S COPIES UNDER THE PHONE'S TOPICS. The iPhone app sorts the phone's library into topics and (opt-in) sends a small
+ * preview + topic per picture to My Story; the server fingerprints each preview (organized_assets.fp, the same 64-bit difference hash this
+ * organizer keeps per picture as `dhash`). Most people's phone photos are ALSO on their computer (an iCloud folder, an old backup, a camera
+ * roll dump), so a sort of that folder can take the phone's topics for the pictures it shares with the phone: no upload, nothing copied.
+ *
+ * A computer picture takes a phone topic when its hash is within NEAR bits of a phone picture's, the closest one winning. Videos are left
+ * alone (the phone sorts photos), and so are flat pictures (nearly every bit the same: a blank, dark or one-colour frame looks like any other).
+ * Candidates are found through the hash's four 16-bit quarters (two hashes within 3 bits always share one; 4 usually do), so 15k pictures
+ * against 5k phone rows is a few thousand comparisons, not 75 million.
+ */
+const plan_1 = require("./plan");
+exports.NEAR = 4;
+const usable = (h) => !!h && /^[0-9a-f]{16}$/i.test(h);
+const flat = (h) => { const n = (0, plan_1.hamming)(h.toLowerCase(), "0000000000000000"); return n < 6 || n > 58; };
+/**
+ * For each computer picture (by index) with a hash, the phone topic it takes, or nothing. `hashes[i]` is picture i's hash (undefined for a
+ * video, a duplicate, or a picture that could not be read). Pure.
+ */
+function matchPhoneTopics(hashes, rows) {
+    const bands = new Map();
+    const phone = rows.filter((r) => usable(r.fp) && !flat(r.fp) && r.topic && r.topic.trim()).map((r) => ({ fp: r.fp.toLowerCase(), topic: r.topic.trim() }));
+    phone.forEach((r, k) => {
+        for (let b = 0; b < 4; b++) {
+            const key = `${b}${r.fp.slice(b * 4, b * 4 + 4)}`;
+            const l = bands.get(key);
+            if (l)
+                l.push(k);
+            else
+                bands.set(key, [k]);
+        }
+    });
+    const out = new Map();
+    hashes.forEach((h, i) => {
+        if (!usable(h) || flat(h))
+            return;
+        const hh = h.toLowerCase();
+        let best = exports.NEAR + 1, topic = null;
+        const seen = new Set();
+        for (let b = 0; b < 4; b++) {
+            for (const k of bands.get(`${b}${hh.slice(b * 4, b * 4 + 4)}`) ?? []) {
+                if (seen.has(k))
+                    continue;
+                seen.add(k);
+                const d = (0, plan_1.hamming)(hh, phone[k].fp);
+                if (d < best) {
+                    best = d;
+                    topic = phone[k].topic;
+                }
+            }
+        }
+        if (topic)
+            out.set(i, topic);
+    });
+    return out;
+}
+/** "Beach 220 · Family 140 · Tennis 38 · 4 more" for the note the app shows after the change. */
+function sayTopics(m) {
+    const n = new Map();
+    for (const t of m.values())
+        n.set(t, (n.get(t) ?? 0) + 1);
+    const top = [...n.entries()].sort((a, b) => b[1] - a[1]);
+    const shown = top.slice(0, 4).map(([t, c]) => `${t} ${c.toLocaleString()}`).join(" · ");
+    return top.length > 4 ? `${shown} · ${top.length - 4} more` : shown;
+}

package/dist/phoneReceive.js

@@ -0,0 +1,199 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECEIVE_PORT = void 0;
+exports.lanAddresses = lanAddresses;
+exports.isPrivate = isPrivate;
+exports.safePart = safePart;
+exports.targetPath = targetPath;
+exports.defaultDest = defaultDest;
+exports.receiveStatus = receiveStatus;
+exports.stopReceive = stopReceive;
+exports.startReceive = startReceive;
+/**
+ * RECEIVE FROM AN IPHONE, over the home network. The iPhone app sends the ORIGINAL photos and videos of the topics the creator ticked, straight
+ * to this computer, into <folder>/<topic>/<file name>: nothing goes through ViralSpin's servers.
+ *
+ * The web page starts a session over loopback (POST /receive/start, ViralSpin origins only, like every other loopback route). Only then does
+ * this open a second, small server on the LAN (RECEIVE_PORT), which answers only:
+ *   - requests carrying the session's one-time token (shown to the phone in a QR code), and
+ *   - from private-network addresses (10/8, 172.16/12, 192.168/16, link-local, loopback),
+ * and it closes itself after IDLE_MS without a request, or when the page stops it. A name or topic is reduced to a plain file name, so nothing
+ * is ever written outside the chosen folder.
+ */
+const http_1 = __importDefault(require("http"));
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+exports.RECEIVE_PORT = 47840;
+const IDLE_MS = 30 * 60000;
+let session = null;
+/** This computer's addresses a phone on the same Wi-Fi can reach: private IPv4s, wired/wireless first, no virtual adapters' link-local. */
+function lanAddresses() {
+    const out = [];
+    for (const [name, addrs] of Object.entries(os_1.default.networkInterfaces())) {
+        if (/vEthernet|VirtualBox|VMware|WSL|Hyper-V|docker|utun|tailscale|ZeroTier/i.test(name))
+            continue;
+        for (const a of addrs ?? [])
+            if (a.family === "IPv4" && !a.internal && isPrivate(a.address))
+                out.push(a.address);
+    }
+    return [...new Set(out)];
+}
+/** Is this a private / local address (the only ones the LAN server answers)? */
+function isPrivate(ip) {
+    const v = ip.replace(/^::ffff:/, "");
+    if (v === "127.0.0.1" || v === "::1")
+        return true;
+    const m = /^(\d+)\.(\d+)\.\d+\.\d+$/.exec(v);
+    if (m) {
+        const a = +m[1], b = +m[2];
+        return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+    }
+    return /^fe80:/i.test(v) || /^f[cd][0-9a-f]{2}:/i.test(v);
+}
+/** A topic or file name as one safe path part: no separators, no "..", no characters Windows refuses, never empty. */
+function safePart(s, fallback) {
+    const t = String(s ?? "").normalize("NFC").replace(/[\\/:*?"<>|\x00-\x1f]/g, " ").replace(/\s+/g, " ").replace(/^[.\s]+|[.\s]+$/g, "").slice(0, 120); // no leading dots, no trailing dot or space (Windows)
+    return t && t !== "." && t !== ".." ? t : fallback;
+}
+/** Where a file of a topic lands: <dest>/<topic>/<name>, inside dest whatever the request said. */
+function targetPath(dest, topic, name) {
+    const p = path_1.default.join(dest, safePart(topic, "Other"), safePart(name, "photo"));
+    if (!path_1.default.resolve(p).startsWith(path_1.default.resolve(dest) + path_1.default.sep))
+        throw new Error("outside the folder");
+    return p;
+}
+function defaultDest() { return path_1.default.join(os_1.default.homedir(), "Pictures", "From iPhone"); }
+function receiveStatus() {
+    if (!session)
+        return { active: false, received: 0, skipped: 0, bytes: 0 };
+    const { dest, port, hosts, token, received, skipped, bytes, last, phone, startedAt } = session;
+    return { active: true, dest, port, hosts, token, received, skipped, bytes, last, phone, startedAt };
+}
+function stopReceive(log) {
+    if (!session)
+        return;
+    clearTimeout(session.idle);
+    session.server.close();
+    log?.(`[receive] stopped: ${session.received} file(s) received, ${session.skipped} already there`);
+    session = null;
+}
+function touch(log) {
+    if (!session)
+        return;
+    session.lastAt = Date.now();
+    clearTimeout(session.idle);
+    session.idle = setTimeout(() => stopReceive(log), IDLE_MS);
+}
+/** Start (or restart into another folder) a receive session. Resolves once the LAN server listens. */
+function startReceive(destIn, log) {
+    const dest = path_1.default.resolve(destIn && destIn.trim() ? destIn.trim() : defaultDest());
+    fs_1.default.mkdirSync(dest, { recursive: true });
+    if (session && session.dest === dest) {
+        touch(log);
+        return Promise.resolve(receiveStatus());
+    }
+    stopReceive(log);
+    const token = crypto_1.default.randomBytes(12).toString("base64url");
+    const server = http_1.default.createServer((req, res) => handle(req, res, log));
+    return new Promise((resolve, reject) => {
+        let port = exports.RECEIVE_PORT;
+        const tryListen = () => server.listen(port, "0.0.0.0");
+        server.on("error", (e) => { if (e.code === "EADDRINUSE" && port < exports.RECEIVE_PORT + 5) {
+            port++;
+            tryListen();
+        }
+        else
+            reject(e); });
+        server.on("listening", () => {
+            session = { token, dest, server, port, hosts: lanAddresses(), received: 0, skipped: 0, bytes: 0, lastAt: Date.now(), startedAt: Date.now(), idle: setTimeout(() => stopReceive(log), IDLE_MS) };
+            log(`[receive] waiting for an iPhone on ${session.hosts.join(", ") || "this network"}:${port}, saving into ${dest}`);
+            resolve(receiveStatus());
+        });
+        tryListen();
+    });
+}
+function json(res, code, body) { res.statusCode = code; res.setHeader("Content-Type", "application/json"); res.end(JSON.stringify(body)); }
+function handle(req, res, log) {
+    const s = session;
+    const ip = String(req.socket.remoteAddress ?? "");
+    const url = new URL(req.url || "/", "http://x");
+    if (!s || !isPrivate(ip))
+        return json(res, 403, { error: "not receiving" });
+    const tok = url.searchParams.get("t") ?? String(req.headers["x-viralspin-token"] ?? "");
+    if (!tok || tok.length !== s.token.length || !crypto_1.default.timingSafeEqual(Buffer.from(tok), Buffer.from(s.token)))
+        return json(res, 403, { error: "wrong code" });
+    touch(log);
+    s.phone = ip.replace(/^::ffff:/, "");
+    // the phone checks it found the right computer
+    if (url.pathname === "/hello" && req.method === "GET")
+        return json(res, 200, { ok: true, computer: os_1.default.hostname(), folder: path_1.default.basename(s.dest) });
+    // which of these are here already: [{ topic, name, size? }] -> [true/false]. A file of that name in that topic (and size, when given) is skipped
+    if (url.pathname === "/have" && req.method === "POST") {
+        let raw = "";
+        req.on("data", (c) => { raw += c; if (raw.length > 4000000)
+            req.destroy(); });
+        req.on("end", () => {
+            try {
+                const files = (JSON.parse(raw).files ?? []);
+                const have = files.slice(0, 5000).map((f) => {
+                    try {
+                        const st = fs_1.default.statSync(targetPath(s.dest, f.topic, f.name));
+                        return !f.size || st.size === f.size;
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                s.skipped += have.filter(Boolean).length;
+                json(res, 200, { have });
+            }
+            catch {
+                json(res, 400, { error: "bad list" });
+            }
+        });
+        return;
+    }
+    // one file: PUT /file?topic=&name=&taken=<unix seconds>, the bytes as the body. Written to a .part file and renamed when complete
+    if (url.pathname === "/file" && req.method === "PUT") {
+        let to;
+        try {
+            to = targetPath(s.dest, url.searchParams.get("topic") ?? "", url.searchParams.get("name") ?? "");
+        }
+        catch {
+            return json(res, 400, { error: "bad name" });
+        }
+        fs_1.default.mkdirSync(path_1.default.dirname(to), { recursive: true });
+        const part = `${to}.part`;
+        const out = fs_1.default.createWriteStream(part);
+        let n = 0;
+        req.on("data", (c) => { n += c.length; });
+        req.pipe(out);
+        out.on("finish", () => {
+            try {
+                fs_1.default.renameSync(part, to);
+                const taken = Number(url.searchParams.get("taken"));
+                if (taken > 0) {
+                    const d = new Date(taken * 1000);
+                    fs_1.default.utimesSync(to, d, d);
+                } // the photo's own date, so the folder sorts by when it was taken
+                s.received++;
+                s.bytes += n;
+                s.last = path_1.default.relative(s.dest, to);
+                json(res, 200, { ok: true });
+            }
+            catch (e) {
+                json(res, 500, { error: e.message });
+            }
+        });
+        const fail = () => { out.destroy(); fs_1.default.rm(part, { force: true }, () => undefined); };
+        req.on("aborted", fail);
+        out.on("error", () => { fail(); json(res, 500, { error: "could not write" }); });
+        return;
+    }
+    json(res, 404, { error: "unknown" });
+}

package/dist/tools/organize.js

@@ -127,6 +127,7 @@ exports.organizeAddToStoryTool = {
         return addPlanToStory(file, { post: client_js_1.post });
     },
 };
+const UPLOADS_AT_ONCE = 16;
 /** 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}`;
@@ -154,17 +155,26 @@ async function addPlanToStory(file, io, progress, only) {
         });
         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++;
-        }
+        // UPLOADS_AT_ONCE thumbnails in flight: one at a time left the line idle (12,700 pictures were "about 38 minutes")
+        let next = 0;
+        const worker = async () => {
+            while (next < r.uploads.length) {
+                const u = r.uploads[next++];
+                const t = byRel.get(u.rel)?.thumb;
+                if (!t)
+                    continue;
+                try {
+                    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++;
+                }
+                catch { /* one thumbnail missing never stops the rest */ }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(UPLOADS_AT_ONCE, r.uploads.length) }, worker));
         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,6 +1,6 @@
 {
   "name": "@viralspin/mcp",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "ViralSpin MCP server — publish local videos and carousels to TikTok, Instagram, and YouTube from Claude Code",
   "main": "dist/index.js",
   "bin": {