sortviral-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# sortviral-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use [SortViral](https://sortviral.com) from Claude Desktop, Claude Code, Cursor, Windsurf or any app that runs local MCP servers. Ask "find the outliers on @mrbeast's TikTok from the last 90 days" and SortViral loads and scores the page in your own Chrome, signed in as you.
+
+This package only passes messages between your AI app and the SortViral Chrome extension over `ws://127.0.0.1` (ports 47821–47825). It has no dependencies and sends nothing to any server.
+
+## Setup
+
+1. Install SortViral in Chrome and turn on **Use with AI** (the AI button in the SortViral bar, or the toolbar menu).
+2. Add the server to your AI app:
+
+```json
+{ "mcpServers": { "sortviral": { "command": "npx", "args": ["-y", "sortviral-mcp"] } } }
+```
+
+Claude Code: `claude mcp add sortviral -- npx -y sortviral-mcp`
+
+3. The first time, SortViral shows a 4-digit code. Check it matches the code your AI app reports and click **Approve**.
+
+## Tools
+
+`sort_page`, `find_outliers`, `scan_watchlist`, `list_watchlist`, `add_to_watchlist`, `get_post`, `get_transcript`, `find_formats`, `search`. Read-only: nothing is posted, liked or followed. Requests run one at a time at the same pace as the extension.
+
+Only Chrome extensions can connect to the bridge (web pages are refused by origin). The pairing token is stored in `~/.config/sortviral-mcp/pair.json`.

package/bin/sortviral-mcp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "../index.js";
+main();

package/index.js

@@ -0,0 +1,120 @@
+// sortviral-mcp: a local MCP server (stdio) that forwards tool calls to the SortViral Chrome extension over
+// ws://127.0.0.1. It only passes messages; the extension loads and scores posts in the user's own browser.
+// Pairing: the first time the extension connects, both sides show the same 4-digit code and the user
+// approves it in SortViral. The token is kept in ~/.config/sortviral-mcp/pair.json.
+import { randomBytes, randomInt } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { listen } from './ws.js';
+import { TOOLS, TOOL_NAMES } from './tools.js';
+
+const VERSION = '1.0.0';
+export const PORTS = [47821, 47822, 47823, 47824, 47825];
+const DIR = process.env.SORTVIRAL_MCP_DIR || join(homedir(), '.config', 'sortviral-mcp');
+const CALL_TIMEOUT = 10 * 60e3;
+const log = (...a) => process.stderr.write(`[sortviral-mcp] ${a.join(' ')}\n`);
+
+// ---- pairing and the extension link ----
+let token = null, ext = null, paired = false, code = null, seq = 0;
+const pending = new Map();
+async function loadToken() { try { token = JSON.parse(await readFile(join(DIR, 'pair.json'), 'utf8')).token || null; } catch { token = null; } }
+async function saveToken(t) { await mkdir(DIR, { recursive: true }); await writeFile(join(DIR, 'pair.json'), JSON.stringify({ token: t }), { mode: 0o600 }); token = t; }
+
+function onClient(conn) {
+  if (ext) ext.close();
+  ext = conn; paired = false;
+  conn.on('message', async msg => {
+    if (msg.type === 'hello') {
+      if (token && msg.token === token) { paired = true; code = null; conn.send({ type: 'ready', version: VERSION }); log('extension connected'); }
+      else { code = String(randomInt(1000, 10000)); conn.send({ type: 'pair', code }); log(`pairing code ${code}`); }
+    } else if (msg.type === 'approve') {
+      if (!code || msg.code !== code) return conn.send({ type: 'pair', code: code || String(randomInt(1000, 10000)), wrong: true });
+      const t = randomBytes(24).toString('hex');
+      await saveToken(t);
+      paired = true; code = null;
+      conn.send({ type: 'paired', token: t, version: VERSION });
+      log('paired');
+    } else if (msg.type === 'result' && pending.has(msg.id)) {
+      const p = pending.get(msg.id); pending.delete(msg.id); clearTimeout(p.timer);
+      msg.error ? p.reject(Object.assign(new Error(msg.error.message || 'Failed'), { code: msg.error.code })) : p.resolve(msg.result);
+    }
+  });
+  conn.on('close', () => {
+    if (ext !== conn) return;
+    ext = null; paired = false;
+    for (const [id, p] of pending) { clearTimeout(p.timer); p.reject(new Error('SortViral disconnected (Chrome closed or the AI connection was turned off).')); pending.delete(id); }
+  });
+}
+
+export function notReady() {
+  if (!ext) return 'SortViral is not connected. In Chrome, open SortViral (the toolbar icon or the AI button in the SortViral bar) and turn on "Use with AI". Chrome must stay open.';
+  if (!paired) return `Approve this connection in Chrome: SortViral shows a pairing code; check it is ${code} and click Approve. Then ask again.`;
+  return null;
+}
+
+function callExtension(tool, args) {
+  return new Promise((resolve, reject) => {
+    const id = ++seq;
+    const timer = setTimeout(() => { pending.delete(id); reject(new Error('SortViral took longer than 10 minutes. Try a smaller page or a limit.')); }, CALL_TIMEOUT);
+    pending.set(id, { resolve, reject, timer });
+    ext.send({ type: 'call', id, tool, args });
+  });
+}
+
+// ---- MCP over stdio (JSON-RPC 2.0, one message per line) ----
+const out = obj => process.stdout.write(JSON.stringify(obj) + '\n');
+const reply = (id, result) => out({ jsonrpc: '2.0', id, result });
+const fail = (id, code, message) => out({ jsonrpc: '2.0', id, error: { code, message } });
+
+export async function handle(msg) {
+  const { id, method, params } = msg;
+  if (method === 'initialize') {
+    return reply(id, {
+      protocolVersion: params?.protocolVersion || '2025-06-18',
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: 'sortviral', title: 'SortViral', version: VERSION },
+      instructions: 'SortViral sorts Instagram, TikTok, YouTube, Facebook and Pinterest pages by views, outlier score, rising speed and engagement, in the user\'s own Chrome. Read-only: it never posts, likes or follows.'
+    });
+  }
+  if (method === 'ping') return reply(id, {});
+  if (method === 'tools/list') return reply(id, { tools: TOOLS });
+  if (method === 'tools/call') {
+    const name = params?.name;
+    if (!TOOL_NAMES.has(name)) return fail(id, -32602, `Unknown tool: ${name}`);
+    const wait = notReady();
+    if (wait) return reply(id, { content: [{ type: 'text', text: wait }], isError: true });
+    try {
+      const result = await callExtension(name, params.arguments || {});
+      return reply(id, { content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result, null, 2) }], ...(result && typeof result === 'object' ? { structuredContent: Array.isArray(result) ? { items: result } : result } : {}) });
+    } catch (e) {
+      return reply(id, { content: [{ type: 'text', text: e.message }], isError: true });
+    }
+  }
+  if (id !== undefined && id !== null) return fail(id, -32601, `Method not found: ${method}`);
+}
+
+export async function main() {
+  await loadToken();
+  let server = null;
+  for (const port of PORTS) {
+    try { server = await listen(port, onClient); log(`listening on 127.0.0.1:${port}`); break; } catch (e) { if (e.code !== 'EADDRINUSE') throw e; }
+  }
+  if (!server) log(`ports ${PORTS[0]}-${PORTS.at(-1)} are busy; close other SortViral MCP servers`);
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    buf += chunk;
+    let i;
+    while ((i = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1);
+      if (!line) continue;
+      let msg; try { msg = JSON.parse(line); } catch { fail(null, -32700, 'Parse error'); continue; }
+      handle(msg).catch(e => msg.id != null && fail(msg.id, -32603, e.message));
+    }
+  });
+  process.stdin.on('end', () => process.exit(0));
+  // A ping keeps the extension's service worker awake while an AI app is open.
+  setInterval(() => ext?.send({ type: 'ping' }), 20e3).unref();
+}
+

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "sortviral-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Use SortViral with Claude, Cursor or any MCP app: sort Instagram, TikTok, YouTube, Facebook and Pinterest pages by views and outlier score in your own Chrome.",
+  "type": "module",
+  "bin": { "sortviral-mcp": "bin/sortviral-mcp.js" },
+  "files": ["bin", "index.js", "tools.js", "ws.js", "README.md"],
+  "engines": { "node": ">=18" },
+  "license": "MIT",
+  "homepage": "https://sortviral.com/ai/",
+  "keywords": ["mcp", "model-context-protocol", "instagram", "tiktok", "youtube", "outlier", "sortviral"],
+  "scripts": { "test": "node --test test/*.test.mjs" }
+}

package/tools.js

@@ -0,0 +1,52 @@
+// The tools SortViral offers an AI app. The extension does the work in the user's own browser; this list
+// only describes them. Same numbers as the in-page bar, capped at 50 posts unless `limit` says otherwise.
+const METRICS = ['views', 'outlier', 'rising', 'engagement', 'likes', 'comments', 'shares', 'saves', 'newest'];
+const limit = { type: 'integer', minimum: 1, maximum: 500, default: 50, description: 'How many posts to return (the whole page is still loaded and scored).' };
+const metric = { type: 'string', enum: METRICS, default: 'outlier', description: 'Sort order. Outlier = views ÷ the creator\'s usual (median of their 30 most recent posts); on search, hashtag and sound pages it is views ÷ the creator\'s followers. Rising = views per day for posts under 30 days old. Metrics a platform does not publish are skipped.' };
+const days = { type: 'integer', minimum: 1, maximum: 3650, description: 'Only posts from the last N days.' };
+
+export const TOOLS = [
+  {
+    name: 'sort_page',
+    description: 'Load every post on a creator page (Instagram Reels or Posts tab, TikTok profile, YouTube Videos or Shorts tab, Facebook Reels tab, Pinterest profile or board) or a search, hashtag or sound page, then sort it. Runs in a background tab of the user\'s Chrome, signed in as them.',
+    inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'The page link, e.g. https://www.tiktok.com/@mrbeast or https://www.instagram.com/mkbhd/reels/' }, metric, limit, days }, required: ['url'] }
+  },
+  {
+    name: 'find_outliers',
+    description: 'Scan several creators and return their best posts combined, each scored against its own creator\'s usual. Creators are profile links on any supported platform.',
+    inputSchema: { type: 'object', properties: { creators: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 25, description: 'Profile links' }, days: { ...days, default: 90 }, metric, limit: { ...limit, default: 20 } }, required: ['creators'] }
+  },
+  {
+    name: 'scan_watchlist',
+    description: 'Scan every creator on the user\'s SortViral Watchlist and return the combined top posts, each scored against its own creator.',
+    inputSchema: { type: 'object', properties: { days: { ...days, default: 90 }, metric, limit: { ...limit, default: 20 } } }
+  },
+  { name: 'list_watchlist', description: 'List the creators on the user\'s SortViral Watchlist, and their bookmarked posts.', inputSchema: { type: 'object', properties: {} } },
+  {
+    name: 'add_to_watchlist',
+    description: 'Add a creator to the SortViral Watchlist by profile link.',
+    inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'Profile link, e.g. https://www.tiktok.com/@khaby.lame' } }, required: ['url'] }
+  },
+  {
+    name: 'get_post',
+    description: 'Every number SortViral has for one post (views, likes, comments, shares, saves where published, outlier score against the creator, date, caption), loading the creator\'s page if needed.',
+    inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'Post link' } }, required: ['url'] }
+  },
+  {
+    name: 'get_transcript',
+    description: 'The published captions of a TikTok or YouTube video as plain text. Instagram, Facebook and Pinterest do not publish captions on the web.',
+    inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'Video link' } }, required: ['url'] }
+  },
+  {
+    name: 'find_formats',
+    description: 'Return a creator\'s loaded posts (or every scanned Watchlist creator\'s) with captions, transcripts where published and outlier scores, grouped for you to name the recurring formats: hook pattern plus how it is filmed. Rank formats by the median outlier score of their posts.',
+    inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'Creator page link, or "watchlist"' }, limit: { ...limit, default: 100 } }, required: ['url'] }
+  },
+  {
+    name: 'search',
+    description: 'Search a platform and sort the results. Outlier on search pages = views (or likes/saves) ÷ the creator\'s followers.',
+    inputSchema: { type: 'object', properties: { platform: { type: 'string', enum: ['instagram', 'tiktok', 'pinterest'] }, query: { type: 'string' }, metric, limit }, required: ['platform', 'query'] }
+  }
+];
+
+export const TOOL_NAMES = new Set(TOOLS.map(t => t.name));

package/ws.js

@@ -0,0 +1,86 @@
+// A minimal WebSocket server (RFC 6455) for one local client: the SortViral extension's service worker.
+// Text frames only, no extensions. Kept dependency-free so `npx sortviral-mcp` installs nothing else.
+import { createServer } from 'node:http';
+import { createHash } from 'node:crypto';
+
+const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+// Only Chrome extensions may connect: a web page's Origin is http(s)://…, so a site can't reach the bridge.
+export const allowedOrigin = origin => /^chrome-extension:\/\/[a-p]{32}$/.test(String(origin || ''));
+
+export function encodeFrame(text, opcode = 0x1) {
+  const data = Buffer.from(text);
+  const len = data.length;
+  const head = len < 126 ? Buffer.from([0x80 | opcode, len])
+    : len < 65536 ? Buffer.from([0x80 | opcode, 126, len >> 8, len & 255])
+      : Buffer.concat([Buffer.from([0x80 | opcode, 127]), (() => { const b = Buffer.alloc(8); b.writeBigUInt64BE(BigInt(len)); return b; })()]);
+  return Buffer.concat([head, data]);
+}
+
+// Parses as many complete frames as `buf` holds. Returns { frames: [{ opcode, fin, payload }], rest }.
+export function decodeFrames(buf) {
+  const frames = [];
+  let off = 0;
+  while (buf.length - off >= 2) {
+    const b0 = buf[off], b1 = buf[off + 1];
+    let len = b1 & 127, pos = off + 2;
+    if (len === 126) { if (buf.length - pos < 2) break; len = buf.readUInt16BE(pos); pos += 2; }
+    else if (len === 127) { if (buf.length - pos < 8) break; len = Number(buf.readBigUInt64BE(pos)); pos += 8; }
+    const masked = !!(b1 & 128);
+    if (masked) { if (buf.length - pos < 4) break; }
+    const mask = masked ? buf.subarray(pos, pos + 4) : null;
+    if (masked) pos += 4;
+    if (buf.length - pos < len) break;
+    const payload = Buffer.from(buf.subarray(pos, pos + len));
+    if (mask) for (let i = 0; i < payload.length; i++) payload[i] ^= mask[i & 3];
+    frames.push({ fin: !!(b0 & 128), opcode: b0 & 15, payload });
+    off = pos + len;
+  }
+  return { frames, rest: buf.subarray(off) };
+}
+
+// Starts listening on 127.0.0.1:port. onClient(conn) gets { send(obj), close(), on('message'|'close', fn) }.
+export function listen(port, onClient) {
+  return new Promise((resolve, reject) => {
+    const server = createServer((req, res) => { res.writeHead(426, { 'content-type': 'text/plain' }); res.end('SortViral MCP bridge. Connect from the SortViral extension.\n'); });
+    server.on('upgrade', (req, socket) => {
+      const key = req.headers['sec-websocket-key'];
+      if (!key || !allowedOrigin(req.headers.origin) || req.headers.upgrade?.toLowerCase() !== 'websocket') {
+        socket.end('HTTP/1.1 403 Forbidden\r\n\r\n');
+        return;
+      }
+      const accept = createHash('sha1').update(key + GUID).digest('base64');
+      socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+      socket.setNoDelay(true);
+      const handlers = { message: [], close: [] };
+      let buf = Buffer.alloc(0), parts = [], closed = false;
+      const conn = {
+        origin: req.headers.origin,
+        send(obj) { if (!closed) socket.write(encodeFrame(JSON.stringify(obj))); },
+        close() { if (closed) return; closed = true; try { socket.write(encodeFrame('', 0x8)); } catch { /* gone */ } socket.end(); },
+        on(ev, fn) { handlers[ev].push(fn); }
+      };
+      const gone = () => { if (closed === 'done') return; closed = 'done'; handlers.close.forEach(fn => fn()); };
+      socket.on('data', chunk => {
+        buf = Buffer.concat([buf, chunk]);
+        const { frames, rest } = decodeFrames(buf);
+        buf = Buffer.from(rest);
+        for (const f of frames) {
+          if (f.opcode === 0x8) { conn.close(); return gone(); }
+          if (f.opcode === 0x9) { socket.write(encodeFrame(f.payload.toString(), 0xA)); continue; }
+          if (f.opcode === 0xA) continue;
+          parts.push(f.payload);
+          if (!f.fin) continue;
+          const text = Buffer.concat(parts).toString('utf8'); parts = [];
+          let msg; try { msg = JSON.parse(text); } catch { continue; }
+          handlers.message.forEach(fn => fn(msg));
+        }
+      });
+      socket.on('close', gone);
+      socket.on('error', gone);
+      onClient(conn);
+    });
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => { server.off('error', reject); resolve(server); });
+  });
+}