@sprid/scout 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 Väder AB. All rights reserved.
+
+Use is subject to Sprid's Terms of Service at https://sprid.studio/terms,
+which set out what you may do with these files.
+
+Bundled third-party components keep their own licences, which are included
+beside the files they cover.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @sprid/scout
+
+A local MCP server that researches the accounts already winning in your niche by
+driving your own Chrome. It finds accounts posting photo slideshows about your
+keywords, measures each one, and files what it learns into a library on your
+machine.
+
+Nothing leaves this computer unless you ask for it. There is no account and no
+server behind it; the Sprid plugin's `scout` skill teaches your agent how to use
+it well.
+
+## What it does
+
+- **Discovery**: searches for accounts posting slideshows about your keywords,
+  then visits each candidate profile and measures it. Accounts that clear your
+  filters are the answer; the ones that miss are kept too, with the margin by
+  which they missed.
+- **Analysis**: reads one named account in depth and reports what it is doing.
+- **Evidence**: pulls slideshows to disk with a `metadata.json` beside each one,
+  so a format can be taken apart.
+- **A local library**: everything discovery passes is filed and answers
+  instantly from then on, with no second browser run.
+
+## The ads lane
+
+The same niche, read from the other side: `start_ad_harvest` collects the ads
+currently running in a country from Meta's public Ad Library, which covers
+Facebook and Instagram. One source shows what people choose to watch, the other
+shows what somebody is paying to put in front of them.
+
+It needs no login and uses a throwaway browser rather than your signed-in
+research profile. From a terminal instead of an agent:
+
+```sh
+npm run ads -- harvest --country US --q "budget app" --brand "Acme"
+npm run ads -- push --account yourapp --file out/us-2026-01-31.json
+```
+
+**Days live is the only performance signal the Ad Library exposes** outside EU
+political ads. There is no spend, no impressions, no click-through rate. An ad
+running 200 days means somebody keeps paying for it, which is survival rather
+than efficiency - so nothing found here is "best-performing", however tempting
+the phrase.
+
+## What comes down is evidence, not material
+
+The numbers are facts about the world and yours to reason from. The posts belong
+to the people who made them, and they come down so you can study the structure -
+the order of the cards, where the hook sits, what the last one does - and rebuild
+it in your own words and images. Not to repost, and not to place in a draft.
+
+## How it works
+
+Plain Playwright launches your real Google Chrome, not a bundled Chromium,
+headless off, with a dedicated profile. You log in once in that window.
+
+Pages are loaded and scrolled the way a person would. The data comes from the
+JSON the pages fetch for themselves, read off the wire, plus the server-rendered
+blob stashed by an init script before hydration removes it. No private API is
+called directly, and there is **no bot-detection evasion in this package** - it
+reads pages you could open yourself, signed in as you.
+
+Runs are asynchronous: a tool returns a `job_id` immediately and `await_job`
+blocks server-side for up to an hour, sending progress notifications on a
+heartbeat so a long run survives inside one agent turn. When a verification
+appears, the job parks, Chrome is brought to the front, and your agent asks you
+to solve it and resume.
+
+## Install
+
+```sh
+npm install -g @sprid/scout
+sprid-scout                  # or: npm run start, from a checkout
+npm run register             # registers the stdio MCP server with Claude Code
+npm run login                # opens Chrome; log in once
+```
+
+`register` runs `claude mcp add --transport stdio --scope user scout -- <node> <path>/src/server.js`.
+If the `claude` CLI is not on PATH it prints the command to run by hand. The
+skill lives in the Sprid plugin, so nothing is copied into a skills directory
+from here.
+
+Start a new session afterwards and ask for something research-shaped.
+
+## Layout
+
+```
+src/config.js      paths, Chrome discovery, the name constant
+src/chrome.js      launch, profile, page leases, challenge detection, login
+src/tiktok.js      endpoint parsers, metrics, verdicts, marks
+src/discover.js    phase 1 search, phase 2 measure, the round loop
+src/analyze.js     one account, in depth
+src/download.js    slideshows to disk
+src/jobs.js        the async job registry and the wait protocol
+src/store.js       the local library
+src/server.js      the MCP surface
+src/register.js    registers the server with your agent
+src/push-to-sprid.js  optional: send a pull into Sprid as inspirations
+```
+
+Data lives in `~/.scout/`: `chrome-profile/`, `runs/`, `downloads/`, and
+`library.json`. A library written under the tool's previous name is read where it
+already is rather than moved.
+
+## Sending findings to Sprid
+
+Optional, and it needs a Sprid personal access token:
+
+```sh
+SPRID_PAT=sprd_... npm run push -- <account-slug> ~/.scout/downloads/<job-id>
+```
+
+They land in the inspiration library as reference for analysis - what the format
+was and how it performed - which is what lets Sprid cluster them into formats
+with evidence behind them.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@sprid/scout",
+  "version": "0.1.0",
+  "description": "Local MCP server that researches a niche over your own Chrome: the accounts winning it, and the ads running in it.",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://sprid.studio/agents",
+  "bugs": {
+    "email": "hello@sprid.studio"
+  },
+  "bin": {
+    "sprid-scout": "src/server.js",
+    "sprid-scout-ads": "src/ads/cli.mjs",
+    "sprid-scout-quick": "src/quick.js"
+  },
+  "main": "src/server.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "playwright-core": "^1.58.0",
+    "zod": "^3.25.76"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/ads/cli.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// The ads lane: harvest Meta's public Ad Library, push findings into Sprid.
+//
+// Runs on this machine, against a public page, with no login.
+
+import { writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { harvest, suggestArchetype } from "./harvest.mjs";
+import { pushToSprid } from "./push.mjs";
+
+function parseArgs(argv) {
+  const out = { _: [], q: [], brand: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--q" || a === "--brand") out[a.slice(2)].push(argv[++i]);
+    else if (a.startsWith("--")) out[a.slice(2)] = argv[++i];
+    else out._.push(a);
+  }
+  return out;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const cmd = args._[0];
+
+if (cmd === "harvest") {
+  const country = (args.country || "SE").toUpperCase();
+  const queries = [...args.q, ...args.brand];
+  if (!queries.length) {
+    console.error("Give at least one --q <keyword> or --brand <name>.\n" +
+      "Keywords discover who advertises in a niche and are noisy; brand names are the clean seam.");
+    process.exit(1);
+  }
+
+  const ads = await harvest({
+    country,
+    queries,
+    headless: args.headless === "true",
+    onProgress: ({ query, found, total }) =>
+      console.log(`  ${query}: ${found} cards (${total} unique so far)`),
+  });
+
+  const stamp = new Date().toISOString().slice(0, 10);
+  const file = args.out || join("out", `${country.toLowerCase()}-${stamp}.json`);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(ads, null, 1));
+
+  const statics = ads.filter((a) => !a.hasVideo).length;
+  console.log(`\n${ads.length} unique ads → ${file}`);
+  console.log(`  ${statics} static / ${ads.length - statics} video`);
+  const long = ads.filter((a) => (a.daysLive ?? 0) >= 150).length;
+  console.log(`  ${long} running 150+ days (the only survival signal the library gives)`);
+}
+
+else if (cmd === "push") {
+  const file = args.file;
+  const account = args.account;
+  if (!file || !account) {
+    console.error("Usage: scout ads push --account <slug> --file <harvest.json>");
+    process.exit(1);
+  }
+  const ads = JSON.parse(readFileSync(file, "utf8"));
+  const archetypes = Object.fromEntries(
+    ads.map((a) => [a.libraryId, suggestArchetype(a)]).filter(([, v]) => v),
+  );
+  const res = await pushToSprid({
+    account, ads, pat: process.env.SPRID_PAT, url: process.env.SPRID_URL, archetypes,
+  });
+  console.log(`created ${res.created}, failed ${res.failed.length}`);
+  if (res.failed.length) console.log(JSON.stringify(res.failed.slice(0, 5), null, 1));
+  console.log("\nArchetypes were guessed from the copy where possible and left null otherwise.\n" +
+    "Classification is a judgement call — read the creatives and correct them before pushing.");
+}
+
+else {
+  console.log(`scout ads — Meta Ad Library research
+
+  harvest --country US --q "budget app" --brand "Acme"   collect ads
+  push --account yourapp --file out/us-2026-01-31.json   send to Sprid
+
+Days live is the only performance signal the Ad Library exposes outside EU
+political ads. It means somebody keeps paying, not that it is efficient.`);
+}

package/src/ads/extract.mjs

@@ -0,0 +1,108 @@
+// The DOM walk, kept as a string because it is evaluated inside the page.
+//
+// Two card shapes exist and both must be handled: one says "See ad details"
+// before the advertiser name, the other "See summary details". Handling only
+// the first silently loses about a quarter of every result set, which looks
+// exactly like a thin niche.
+//
+// The UI language follows your IP, not the country parameter — searching US
+// from Sweden returns Swedish chrome around English ads — so every label is
+// matched in both languages.
+
+export const EXTRACT_FN = `(() => {
+  const walk = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  const ids = [];
+  let n;
+  while ((n = walk.nextNode())) {
+    if (/^(Biblioteks-id|Library ID)/.test(n.textContent.trim())) ids.push(n);
+  }
+  const seen = new Set();
+  const out = [];
+  for (const t of ids) {
+    let p = t.parentElement;
+    for (let i = 0; i < 10 && p; i++) {
+      if (p.textContent.length > 250 || p.querySelector('img')) break;
+      p = p.parentElement;
+    }
+    let guard = 0;
+    while (p && p.querySelectorAll('img,video').length === 0 && guard++ < 3) p = p.parentElement;
+    if (!p) continue;
+    const txt = p.innerText || '';
+    const idm = txt.match(/(?:Biblioteks-id|Library ID):\\s*(\\d+)/);
+    if (!idm || seen.has(idm[1])) continue;
+    seen.add(idm[1]);
+    const imgs = [...p.querySelectorAll('img')]
+      .map((i) => i.src)
+      .filter((s) => s && s.startsWith('http') && !/s60x60|p60x60|s32x32/.test(s));
+    out.push({ id: idm[1], text: txt, imgs, hasVideo: p.querySelectorAll('video').length > 0 });
+  }
+  return JSON.stringify(out);
+})()`;
+
+const MONTHS = {
+  jan: 1, feb: 2, mar: 3, apr: 4, maj: 5, may: 5, jun: 6, jul: 7,
+  aug: 8, sep: 9, okt: 10, oct: 10, nov: 11, dec: 12,
+};
+
+// Both date orders, because the library writes the one its own locale uses:
+// "Started running on 12 Aug 2026" in en-GB and Swedish chrome, "Started
+// running on Aug 12, 2026" in en-US. Matching only the first returns null for
+// every US ad, which reads as "nothing here has been running long" - the most
+// misleading answer this tool can give, since days live is its only signal.
+export function parseStartDate(text) {
+  const label = text.match(/(?:B[öo]rjade k[öo]ras den|Started running on)\s+([^\n]{0,28})/);
+  if (!label) return null;
+  const rest = label[1].trim();
+  const dayFirst = rest.match(/^(\d{1,2})\s+(\w{3})\w*\.?,?\s*(\d{4})/);
+  const monthFirst = rest.match(/^(\w{3})\w*\.?\s+(\d{1,2}),?\s*(\d{4})/);
+  const parts = dayFirst
+    ? { day: dayFirst[1], month: dayFirst[2], year: dayFirst[3] }
+    : monthFirst
+      ? { day: monthFirst[2], month: monthFirst[1], year: monthFirst[3] }
+      : null;
+  if (!parts) return null;
+  const mon = MONTHS[parts.month.slice(0, 3).toLowerCase()];
+  if (!mon) return null;
+  return `${parts.year}-${String(mon).padStart(2, "0")}-${String(Number(parts.day)).padStart(2, "0")}`;
+}
+
+export function parseCard(card, source, today = new Date()) {
+  const text = card.text.replace(/​/g, "");
+  const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+
+  let advertiser = null;
+  let body = [];
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (/^(Se annonsinformation|See ad details|Se detaljerad sammanfattning|See summary details)/.test(l)) {
+      advertiser = lines[i + 1] ?? null;
+      for (let j = i + 1; j < lines.length; j++) {
+        if (lines[j] === "Sponsras" || lines[j] === "Sponsored") {
+          body = lines.slice(j + 1);
+          break;
+        }
+      }
+      break;
+    }
+  }
+
+  const start = parseStartDate(text);
+  const daysLive = start
+    ? Math.round((today.getTime() - new Date(start + "T00:00:00Z").getTime()) / 86_400_000)
+    : null;
+
+  const vm = text.match(/(\d+)\s+annonser anv[äa]nder|(\d+)\s+ads use/);
+  const variants = vm ? Number(vm[1] || vm[2]) : (/flera versioner|multiple versions/.test(text) ? 2 : 1);
+
+  return {
+    libraryId: card.id,
+    advertiser,
+    start,
+    daysLive,
+    variants,
+    hasVideo: card.hasVideo || /0:00 \//.test(text),
+    primaryText: body.join("\n").trim(),
+    creatives: card.imgs,
+    source,
+  };
+}

package/src/ads/harvest.mjs

@@ -0,0 +1,90 @@
+// Drive a real Chrome against the Ad Library and collect cards.
+//
+// Deliberately slow and sequential. The grid is React and hydrates late; a
+// short wait returns an empty array that is indistinguishable from "no
+// results", which is why every search retries once before being believed.
+
+import { chromium } from "playwright-core";
+import { EXTRACT_FN, parseCard } from "./extract.mjs";
+
+const BASE = "https://www.facebook.com/ads/library/";
+
+export function searchUrl({ country, query, activeOnly = true }) {
+  const u = new URL(BASE);
+  u.searchParams.set("active_status", activeOnly ? "active" : "all");
+  u.searchParams.set("ad_type", "all");
+  u.searchParams.set("media_type", "all");
+  u.searchParams.set("search_type", "keyword_unordered");
+  u.searchParams.set("country", country);
+  u.searchParams.set("q", query);
+  return u.toString();
+}
+
+async function extractOnce(page, url, { settleMs, scrolls }) {
+  await page.goto(url, { waitUntil: "domcontentloaded" });
+  await page.waitForTimeout(settleMs);
+  for (let i = 0; i < scrolls; i++) {
+    await page.mouse.wheel(0, 2400);
+    await page.waitForTimeout(2500);
+  }
+  const raw = await page.evaluate(EXTRACT_FN);
+  try {
+    return JSON.parse(typeof raw === "string" ? raw : JSON.stringify(raw));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.country  ISO-3166 alpha-2
+ * @param {string[]} opts.queries  keywords or brand names
+ * @param {boolean} [opts.headless]
+ */
+export async function harvest({ country, queries, headless = false, settleMs = 7000, scrolls = 2, onProgress }) {
+  const browser = await chromium.launch({ headless, channel: "chrome" });
+  const context = await browser.newContext({ viewport: { width: 1280, height: 1400 } });
+  const page = await context.newPage();
+
+  const byId = new Map();
+  try {
+    for (const query of queries) {
+      const url = searchUrl({ country, query });
+      let cards = await extractOnce(page, url, { settleMs, scrolls });
+      // One retry: an empty result is far more often a slow hydrate than an
+      // empty niche, and believing the first empty answer is how a market
+      // gets written off.
+      if (cards.length === 0) {
+        await page.waitForTimeout(3000);
+        cards = await extractOnce(page, url, { settleMs: settleMs + 3000, scrolls });
+      }
+      const source = `${country.toLowerCase()}:${query}`;
+      for (const card of cards) {
+        const parsed = parseCard(card, source);
+        const existing = byId.get(parsed.libraryId);
+        if (existing) existing.source += `,${source}`;
+        else byId.set(parsed.libraryId, parsed);
+      }
+      onProgress?.({ query, found: cards.length, total: byId.size });
+    }
+  } finally {
+    await browser.close();
+  }
+
+  return [...byId.values()];
+}
+
+/**
+ * A first-pass archetype guess, offered as a suggestion and never written as
+ * fact. Classification is a judgement call and belongs to whoever reads the
+ * creative; this only narrows the list.
+ */
+export function suggestArchetype(ad) {
+  const t = (ad.primaryText || "").toLowerCase();
+  if (/\b(\d+\s?%|rabatt|off|kr\b|\$\d|pay once|no subscription)/.test(t)) return "offer";
+  if (/\bquiz|test\b|which .* are you|vilken .* är du/.test(t)) return "quadrant-quiz";
+  if (/\bvs\.?\b|jämför|compare|instead of/.test(t)) return "comparison";
+  if (/\(\d{2}\)|\b\d{2}-year-old|berättar|trodde/.test(t)) return "named-person";
+  if (ad.primaryText && ad.primaryText.length > 400) return "text-wall";
+  return null;
+}

package/src/ads/push.mjs

@@ -0,0 +1,56 @@
+// Push a harvest into Sprid as inspirations.
+//
+// Same door a phone screenshot upload uses: POST /api/inspirations with a PAT.
+// No schema change was needed — an Ad Library find maps onto the existing
+// columns.
+
+const DEFAULT_URL = process.env.SPRID_URL || "https://api.sprid.studio";
+
+export function toInspiration(ad, { archetype } = {}) {
+  return {
+    source: "meta_ads",
+    sourceUrl: `https://www.facebook.com/ads/library/?id=${ad.libraryId}`,
+    title: ad.advertiser ? `${ad.advertiser} · ${ad.daysLive ?? "?"}d` : `Ad ${ad.libraryId}`,
+    authorHandle: ad.advertiser ?? null,
+    caption: ad.primaryText || null,
+    // Using the archetype taxonomy for shapeKey is what puts a competitor's days-live next to our cost
+    // per event for the same shape.
+    shapeKey: archetype ?? null,
+    tags: [
+      ad.hasVideo ? "video" : "static",
+      ...(ad.source ? ad.source.split(",").map((s) => s.split(":")[0]) : []),
+    ],
+    notes: [
+      ad.start ? `Started ${ad.start}` : null,
+      ad.daysLive != null ? `${ad.daysLive} days live` : null,
+      ad.variants > 1 ? `${ad.variants} variants share this creative` : null,
+      `Library ID ${ad.libraryId}`,
+    ].filter(Boolean).join(" · "),
+    // Days live is a survival signal, not an efficiency one. It is stored
+    // under its own name so nobody later reads it as engagement.
+    metrics: {
+      daysLive: ad.daysLive,
+      variants: ad.variants,
+      isVideo: ad.hasVideo,
+    },
+    status: "ready",
+  };
+}
+
+export async function pushToSprid({ account, ads, pat, url = DEFAULT_URL, archetypes = {} }) {
+  if (!pat) throw new Error("SPRID_PAT is required");
+  const results = { created: 0, failed: [] };
+
+  for (const ad of ads) {
+    const body = toInspiration(ad, { archetype: archetypes[ad.libraryId] });
+    const res = await fetch(`${url}/api/inspirations?account=${encodeURIComponent(account)}`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${pat}`, "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (res.ok) results.created++;
+    else results.failed.push({ libraryId: ad.libraryId, status: res.status, body: await res.text() });
+  }
+
+  return results;
+}

package/src/ads/run.js

@@ -0,0 +1,67 @@
+"use strict";
+
+// The ads lane, as a run the job registry can follow.
+//
+// It launches its own throwaway Chrome rather than the persistent research
+// profile: the Ad Library is public and needs no session, and putting that
+// browsing inside the signed-in profile would mix two unrelated identities for
+// no gain.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const jobsLib = require("../jobs");
+const { ROOT } = require("../config");
+
+const HARVESTS_DIR = path.join(ROOT, "harvests");
+
+/** A compact row per ad, ordered by how long it has been paid for. */
+function row(ad, archetype) {
+  return {
+    library_id: ad.libraryId,
+    advertiser: ad.advertiser,
+    days_live: ad.daysLive,
+    variants: ad.variants,
+    media: ad.hasVideo ? "video" : "static",
+    suggested_archetype: archetype ?? null,
+    primary_text: (ad.primaryText || "").slice(0, 400),
+    found_by: ad.source,
+  };
+}
+
+async function runAdHarvest(job) {
+  const { country, queries } = job.meta;
+  const { harvest, suggestArchetype } = await import("./harvest.mjs");
+  const gate = jobsLib.gate(job);
+
+  const ads = await harvest({
+    country,
+    queries,
+    onProgress: ({ query, found, total }) =>
+      jobsLib.log(job, `${query}: ${found} cards (${total} unique so far)`),
+  });
+  if (!(await gate())) return { country, queries, unique_ads: ads.length, stopped: true };
+
+  fs.mkdirSync(HARVESTS_DIR, { recursive: true });
+  const file = path.join(HARVESTS_DIR, `${job.id}.json`);
+  fs.writeFileSync(file, JSON.stringify(ads, null, 1));
+
+  const statics = ads.filter((ad) => !ad.hasVideo).length;
+  const ranked = [...ads].sort((a, b) => (b.daysLive ?? 0) - (a.daysLive ?? 0));
+
+  return {
+    country,
+    queries,
+    file,
+    unique_ads: ads.length,
+    static_ads: statics,
+    video_ads: ads.length - statics,
+    running_150_days: ads.filter((ad) => (ad.daysLive ?? 0) >= 150).length,
+    signal:
+      "Days live is the only performance signal the Ad Library exposes outside EU political " +
+      "ads. It means somebody keeps paying for this, not that it is efficient. Never call a " +
+      "find here best-performing.",
+    ads: ranked.slice(0, 40).map((ad) => row(ad, suggestArchetype(ad))),
+  };
+}
+
+module.exports = { runAdHarvest, HARVESTS_DIR };