@sprid/scout 0.1.0

package/src/server.js

@@ -0,0 +1,881 @@
+#!/usr/bin/env node
+"use strict";
+
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { z } = require("zod");
+
+const { NAME, ensureDirs, chromeUnavailable, PROFILE_DIR, DOWNLOADS_DIR } = require("./config");
+const chrome = require("./chrome");
+const store = require("./store");
+const jobsLib = require("./jobs");
+const { reevaluate, flagOutliers, breakdownOf } = require("./tiktok");
+const { runDiscovery } = require("./discover");
+const { runAnalysis } = require("./analyze");
+const { runDownload, DOWNLOAD_DEFAULTS, MAX_DOWNLOAD_COUNT, SORT_VALUES } = require("./download");
+const { runAdHarvest } = require("./ads/run");
+
+const INSTRUCTIONS = [
+  `${NAME} is a niche research tool running on this user's own machine. It reads two`,
+  "sources: the accounts posting photo slideshows on TikTok, profile by profile, and the",
+  "ads currently running in the same niche in Meta's public ad library. What people",
+  "choose to watch, and what somebody is paying to put in front of them. Everything it",
+  "finds is collected into a local library. It drives a real browser, so a run takes",
+  "minutes rather than seconds, and the TikTok half depends on the user being signed in.",
+  "Call status first: it says whether that is true and what is already running.",
+].join(" ");
+
+function text(value) {
+  return {
+    content: [
+      { type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) },
+    ],
+  };
+}
+
+function fail(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+function unknownJob(jobId) {
+  return fail(`No run with id ${jobId}. list_runs has the finished ones; status has what is in flight.`);
+}
+
+/** Every browser tool goes through here first. */
+function notReady() {
+  const missingChrome = chromeUnavailable();
+  if (missingChrome) return fail(missingChrome);
+  if (!chrome.isLoggedIn()) {
+    return fail(
+      "No TikTok session is saved on this machine, and every one of these tools reads TikTok as a logged-in user. Call login_tiktok: it opens a Chrome window for the user to log in once. Then stop and wait for them."
+    );
+  }
+  return null;
+}
+
+function busy(tool, label) {
+  const running = jobsLib.busyWith(tool);
+  if (!running) return null;
+  return fail(
+    `A ${label} run is already in flight (${running.id}). Only one at a time shares the browser. Follow it with await_job, or stop it with job_control.`
+  );
+}
+
+function started(job, note) {
+  return text({
+    job_id: job.id,
+    tool: job.tool,
+    started_at: new Date(job.startedAt).toISOString(),
+    note,
+  });
+}
+
+/** The compact row a discovered account rides as, everywhere it is listed. */
+function foundAccount(account) {
+  return {
+    username: account.username,
+    url: `https://www.tiktok.com/@${account.username}`,
+    display_name: account.display_name,
+    followers: account.followers,
+    verified: account.verified,
+    metrics: account.metrics,
+    passed: account.verdict?.passed ?? false,
+    failed: account.verdict?.failed ?? [],
+    no_posts_in_window: account.verdict?.noPostsInWindow ?? false,
+    unmeasured: account.verdict?.unmeasured ?? false,
+    high_views_per_follower: account.verdict?.highViewsPerFollower ?? false,
+    near_miss: account.verdict?.nearMiss ?? false,
+  };
+}
+
+/** Strip the retained per-post samples before anything is filed or returned. */
+function withoutSamples(account) {
+  const { samples, measuredAt, ...rest } = account;
+  return rest;
+}
+
+function discoveryResults(job) {
+  const measured = job.state.measured;
+  const passed = measured.filter((a) => a.verdict?.passed);
+  return {
+    run_id: job.id,
+    name: job.meta.name,
+    keywords: job.meta.keywords,
+    filters: job.meta.filters,
+    status: job.status,
+    vitals: jobsLib.vitalsFields(jobsLib.vitals(job)),
+    passed_accounts: passed.map(foundAccount),
+    measured_accounts: measured.map(foundAccount),
+    rejection_breakdown: breakdownOf(measured),
+    outliers: {
+      high_views_per_follower: measured
+        .filter((a) => a.verdict?.highViewsPerFollower)
+        .map((a) => a.username),
+      near_miss: measured.filter((a) => a.verdict?.nearMiss).map((a) => a.username),
+    },
+    tuning_history: job.meta.tuning ?? [],
+  };
+}
+
+/** Runs are launched, never awaited. The caller follows them with await_job. */
+function launch(job, work, onDone) {
+  work(job)
+    .then((result) => {
+      if (job.stopRequested) {
+        jobsLib.settle(job, "stopped", result);
+      } else {
+        jobsLib.settle(job, "done", result);
+      }
+      onDone?.(job);
+    })
+    .catch((error) => {
+      jobsLib.settle(job, "error", error instanceof Error ? error.message : String(error));
+      onDone?.(job);
+    });
+  return job;
+}
+
+function persistDiscovery(job) {
+  const results = discoveryResults(job);
+  store.saveRun({
+    id: job.id,
+    kind: "discover",
+    name: job.meta.name,
+    keywords: job.meta.keywords,
+    filters: job.meta.filters,
+    started_at: new Date(job.startedAt).toISOString(),
+    finished_at: new Date().toISOString(),
+    status: job.status,
+    accounts_passed: results.passed_accounts.length,
+    accounts_measured: results.measured_accounts.length,
+    results,
+  });
+  const passed = job.state.measured.filter((a) => a.verdict?.passed).map(withoutSamples);
+  if (passed.length) store.fileAccounts(job.id, job.meta.name, passed);
+}
+
+// ---------------------------------------------------------------------------
+
+const mcp = new McpServer({ name: NAME, version: "0.1.0" }, { instructions: INSTRUCTIONS });
+
+mcp.registerTool(
+  "status",
+  {
+    title: "Is anything ready or running",
+    description: [
+      "Says whether this machine can run anything and what is already in flight:",
+      "whether Chrome is installed, whether a TikTok session is saved here, which",
+      "runs are working right now, and how big the research library has grown.",
+      "",
+      "Call this first, every session. Both of the first two gate every browser tool,",
+      "and neither can be arranged from inside a run.",
+    ].join("\n"),
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  async () => {
+    const library = store.searchAccounts({ limit: 0 });
+    return text({
+      chrome_installed: chromeUnavailable() === null,
+      chrome_problem: chromeUnavailable(),
+      tiktok_session: chrome.isLoggedIn(),
+      profile_dir: PROFILE_DIR,
+      downloads_dir: DOWNLOADS_DIR,
+      running: jobsLib.inFlight().map((job) => ({
+        job_id: job.id,
+        tool: job.tool,
+        status: job.status,
+        elapsed: jobsLib.humanElapsed(job),
+        alert: job.alert?.kind ?? null,
+      })),
+      library_accounts: library.total,
+      runs_recorded: store.listRuns().length,
+    });
+  }
+);
+
+mcp.registerTool(
+  "login_tiktok",
+  {
+    title: "Log in to TikTok",
+    description: [
+      "Opens a real Chrome window on TikTok's login page and waits for the user to",
+      "sign in. The session is saved to a browser profile on this machine and every",
+      "other tool reads TikTok as that user from then on.",
+      "",
+      "This blocks while the window is open, so tell the user to go and log in before",
+      "you call it, and expect to wait. It answers as soon as the session cookie lands.",
+    ].join("\n"),
+    inputSchema: {
+      timeout_seconds: z
+        .number()
+        .int()
+        .min(30)
+        .max(600)
+        .optional()
+        .describe("How long to hold the window open. Defaults to 180."),
+    },
+    annotations: { readOnlyHint: false, openWorldHint: true },
+  },
+  async ({ timeout_seconds }) => {
+    const missingChrome = chromeUnavailable();
+    if (missingChrome) return fail(missingChrome);
+    if (chrome.isLoggedIn()) return text("A TikTok session is already saved on this machine.");
+    const { loggedIn } = await chrome.login((timeout_seconds ?? 180) * 1000);
+    return text(
+      loggedIn
+        ? "Logged in. The session is saved and every tool can read TikTok now."
+        : "The window closed without a session appearing. Call login_tiktok again when the user is ready."
+    );
+  }
+);
+
+mcp.registerTool(
+  "start_discovery",
+  {
+    title: "Find new accounts",
+    description: [
+      "Searches TikTok for accounts posting photo slideshows about the keywords given,",
+      "then visits each candidate profile and measures it: how much of what they post",
+      "is slideshows, how many views those get, how often they post, how steady it is.",
+      "Accounts that clear the filters are the result.",
+      "",
+      "This drives a real Chrome window on the user's machine and takes minutes, not",
+      "seconds. It returns a job_id straight away; await_job follows it and job_results",
+      "reads what it found, mid-run as well as at the end.",
+      "",
+      "Everything that passes is filed into the user's local library automatically, so",
+      "once the run is done the same accounts turn up in search_accounts and",
+      "get_account, with the run listed by list_runs.",
+      "",
+      "Keywords are the whole of the search: pick several phrasings of the thing being",
+      "looked for rather than one, since each is searched in turn until enough accounts",
+      "have passed. The filters are cheap to loosen and expensive to get wrong, so start",
+      "near the defaults unless the user asked otherwise.",
+    ].join("\n"),
+    inputSchema: {
+      keywords: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe("What to search TikTok for. Several phrasings work better than one."),
+      name: z.string().optional().describe("What to call this run in the library. Defaults to a dated name."),
+      max_accounts: z.number().int().min(1).optional().describe("How many accounts to aim for. Defaults to 20."),
+      min_followers: z.number().int().min(0).optional().describe("Drop accounts under this many followers. Defaults to 0, which keeps all."),
+      min_slideshow_pct: z
+        .number()
+        .min(0)
+        .max(100)
+        .optional()
+        .describe("Drop accounts whose posts are less than this percent photo slideshows. Defaults to 50."),
+      avg_views_days: z.number().int().min(1).optional().describe("The window the view averages are measured over, in days. Defaults to 30."),
+      min_avg_views: z.number().int().min(0).optional().describe("Drop accounts averaging fewer views than this over that window. Defaults to 0."),
+      min_total_views: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe(
+          "Drop accounts with fewer total views than this over that window. Defaults to 100000, the working floor for a healthy niche; pass 0 to turn the floor off."
+        ),
+      hashtag_pivot: z
+        .boolean()
+        .optional()
+        .describe("Search again on the hashtags the first pass turned up. Reaches accounts the original wording never would. Defaults to false."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  },
+  async (input) => {
+    const blocked = notReady() ?? busy("discover", "discovery");
+    if (blocked) return blocked;
+    const keywords = input.keywords.map((word) => word.trim()).filter(Boolean);
+    if (keywords.length === 0) return fail("Every keyword was blank. Give at least one thing to search TikTok for.");
+
+    const job = jobsLib.createJob("discover", {
+      name: input.name?.trim() || `run-${new Date().toISOString().slice(0, 10)}`,
+      keywords,
+      maxAccounts: input.max_accounts ?? 20,
+      hashtagPivot: input.hashtag_pivot ?? false,
+      filters: {
+        minFollowers: input.min_followers ?? 0,
+        minRatio: (input.min_slideshow_pct ?? 50) / 100,
+        avgViewsDays: input.avg_views_days ?? 30,
+        minAvgViews: input.min_avg_views ?? 0,
+        // 100k, not 0: a caller that leaves this unset still gets the working
+        // floor. Turning it off is a decision, made by passing 0 explicitly.
+        minTotalViews: input.min_total_views ?? 100_000,
+      },
+      tuning: [],
+    });
+    launch(job, runDiscovery, persistDiscovery);
+    return started(
+      job,
+      [
+        `Searching TikTok for ${keywords.length} keyword(s), then visiting each candidate`,
+        "profile one at a time to measure it. Both halves are a browser loading pages,",
+        "so this is the slowest tool here.",
+        "",
+        "Whatever passes the filters is filed into the user's library at the end.",
+      ].join("\n")
+    );
+  }
+);
+
+mcp.registerTool(
+  "analyze_account",
+  {
+    title: "Measure one account",
+    description: [
+      "Reads one TikTok account's posts and works out what they are doing: the share of",
+      "posts that are photo slideshows, average views, likes, comments, shares and saves,",
+      "how often they post, how steady it is, their top hashtags, and their best posts",
+      "over the window.",
+      "",
+      "top_posts is ordered by views, highest first. Slideshows and videos are ranked",
+      "together in one list, each entry saying which it is. Only the slideshow entries",
+      "can be downloaded, and their url is exactly what start_download takes as a link.",
+      "",
+      "This drives a real Chrome window and takes a few minutes. It returns a job_id",
+      "straight away; await_job follows it and job_results has the report.",
+      "",
+      "This is a fresh read of TikTok, not a library lookup. If the account is already",
+      "in the library, get_account answers at once and costs nobody anything; use this",
+      "when the account is new, or when the numbers need to be current.",
+      "",
+      "Nothing is written to the library by this tool.",
+    ].join("\n"),
+    inputSchema: {
+      username: z.string().min(1).describe("The TikTok handle, with or without the leading @."),
+      days: z.number().int().min(1).optional().describe("How far back to read, in days. Defaults to 30. Ignored when all_videos is true."),
+      all_videos: z
+        .boolean()
+        .optional()
+        .describe("Read the whole account rather than a window. Takes far longer on a big account. Defaults to false."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  },
+  async ({ username, days, all_videos }) => {
+    const blocked = notReady() ?? busy("profile", "single-account");
+    if (blocked) return blocked;
+    const handle = username.trim().replace(/^@+/, "");
+    if (!handle) return fail("That username was empty once the @ was taken off.");
+    const job = jobsLib.createJob("profile", {
+      username: handle,
+      days: days ?? 30,
+      allVideos: all_videos ?? false,
+    });
+    launch(job, runAnalysis);
+    return started(
+      job,
+      `Opening @${handle} and scrolling back through ${
+        all_videos ? "their whole account" : `the last ${days ?? 30} days`
+      } to read every post it can, then measuring what it read.`
+    );
+  }
+);
+
+mcp.registerTool(
+  "start_download",
+  {
+    title: "Download slideshows",
+    description: [
+      "Downloads photo slideshows to a folder on the user's disk. Give it either",
+      "accounts or links; both download the same thing and differ only in how the",
+      "targets are named. Give one or the other, never both.",
+      "",
+      "What comes down is evidence for a teardown, not material to publish. Study the",
+      "structure, then rebuild it in the user's own words and images. Never hand a",
+      "pulled image back as something to post.",
+      "",
+      "accounts takes handles and lets this tool choose which of their slideshows to",
+      "pull. links takes the URLs of particular posts and pulls exactly those.",
+      "",
+      "An account download is three choices. Leave all three alone and it takes the",
+      `${DOWNLOAD_DEFAULTS.count} most viewed slideshows of the account, of any age. count, sort and`,
+      "max_days at the top level move those defaults for every account in the call, and",
+      "any account may carry its own instead.",
+      "",
+      "The order of the work is: read the account's posts, drop anything older than",
+      "max_days, sort what is left by sort, take the first count of them, download those.",
+      "So max_days is the window the ranking happens inside rather than a filter applied",
+      "afterwards, and 0 means no window at all.",
+      "",
+      "views, likes, comments, shares and favorites each rank on that number as TikTok",
+      "reports it. engagement ranks on (likes + comments + shares + favorites) divided",
+      "by views, which favours posts that got a reaction over posts that merely got seen.",
+      "Those six are the whole list. Every slideshow arrives with a metadata.json beside",
+      "its images carrying views, likes, comments, shares, favorites, engagement_rate,",
+      "slide_count, hashtags and published_at, so a ranking this tool does not offer can",
+      "be worked out from what came down.",
+      "",
+      "include_videos pulls videos as well, and each one arrives with sheet.png beside",
+      "it: single frames taken at 0, 1, 2, 5 and 10 seconds, left to right, tiled into",
+      "one image. That is there because nothing can watch a video, and the first",
+      "seconds are what decide whether anyone else does either. Read the sheet to",
+      "describe the structure - the cover frame, what the opening card says, when the",
+      "first cut lands. sheet_offsets moves those times. It needs ffmpeg on the machine;",
+      "without it the video still lands and the sheet does not.",
+      "",
+      "It returns a job_id straight away. The files stay on disk under the downloads",
+      "directory that status reports; nothing is cleaned up behind the user.",
+    ].join("\n"),
+    inputSchema: {
+      accounts: z
+        .array(
+          z.object({
+            username: z.string().min(1),
+            count: z.number().int().min(1).max(MAX_DOWNLOAD_COUNT).optional(),
+            sort: z.enum(SORT_VALUES).optional(),
+            max_days: z.number().int().min(0).optional(),
+          })
+        )
+        .optional()
+        .describe("Handles to pull from, each optionally carrying its own count, sort and max_days."),
+      links: z
+        .array(z.string().url())
+        .optional()
+        .describe("URLs of particular posts, as https://www.tiktok.com/@handle/photo/..."),
+      count: z.number().int().min(1).max(MAX_DOWNLOAD_COUNT).optional().describe(`Slideshows per account. Defaults to ${DOWNLOAD_DEFAULTS.count}.`),
+      include_videos: z.boolean().optional().describe("Pull videos too, each with a sheet of frames for reading its structure. Off by default."),
+      sheet_offsets: z.array(z.number().min(0)).min(1).max(12).optional().describe("Seconds to take frames at. Defaults to 0, 1, 2, 5 and 10 - the cover frame and the window where a viewer decides."),
+      sort: z.enum(SORT_VALUES).optional().describe(`What counts as best. Defaults to ${DOWNLOAD_DEFAULTS.sort}.`),
+      max_days: z.number().int().min(0).optional().describe("Ignore slideshows older than this before ranking. 0, the default, means no window."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  },
+  async (input) => {
+    const blocked = notReady() ?? busy("download", "download");
+    if (blocked) return blocked;
+    const hasAccounts = Boolean(input.accounts?.length);
+    const hasLinks = Boolean(input.links?.length);
+    if (hasAccounts === hasLinks) {
+      return fail("Give either accounts or links, never both and never neither.");
+    }
+    const job = jobsLib.createJob("download", {
+      accounts: input.accounts ?? [],
+      links: input.links ?? [],
+      count: input.count ?? DOWNLOAD_DEFAULTS.count,
+      sort: input.sort ?? DOWNLOAD_DEFAULTS.sort,
+      maxDays: input.max_days ?? DOWNLOAD_DEFAULTS.maxDays,
+      includeVideos: input.include_videos ?? false,
+      sheetOffsets: input.sheet_offsets,
+    });
+    launch(job, runDownload);
+    return started(
+      job,
+      hasLinks
+        ? `Pulling ${input.links.length} post(s) one at a time.`
+        : `Reading ${input.accounts.length} account(s), then pulling their slideshows.`
+    );
+  }
+);
+
+mcp.registerTool(
+  "start_ad_harvest",
+  {
+    title: "Harvest the public ad library",
+    description: [
+      "Collects the ads currently running in a niche from Meta's public Ad Library,",
+      "which covers Facebook and Instagram. This is the other half of the research:",
+      "the organic side shows what people choose to watch, this shows what somebody is",
+      "paying to put in front of them.",
+      "",
+      "Give a country and at least one query. A keyword discovers who advertises in a",
+      "niche and is noisy; a brand name is the clean seam and is what to use once you",
+      "know who the competitors are.",
+      "",
+      "Days live is the only performance signal the library exposes outside EU political",
+      "ads: there is no spend, no impressions and no click-through rate. A long-running",
+      "ad means somebody keeps paying for it, which is evidence of survival and not of",
+      "efficiency. Never describe a find here as best-performing.",
+      "",
+      "It needs no login and does not touch the signed-in research profile. It returns a",
+      "job_id straight away; the full harvest is written to disk and the reply carries",
+      "the longest-running forty with an archetype guessed from the copy where one is",
+      "obvious. Those guesses are suggestions to check against the creative, never facts.",
+    ].join("\n"),
+    inputSchema: {
+      country: z.string().length(2).describe("ISO 3166 alpha-2, e.g. SE, US, GB. The library is searched per country."),
+      queries: z.array(z.string().min(2)).min(1).max(40)
+        .describe("Keywords or brand names. Brand names give the cleanest read."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  },
+  async ({ country, queries }) => {
+    const missingChrome = chromeUnavailable();
+    if (missingChrome) return fail(missingChrome);
+    const blocked = busy("ads", "ad harvest");
+    if (blocked) return blocked;
+    const job = jobsLib.createJob("ads", { country: country.toUpperCase(), queries });
+    launch(job, runAdHarvest);
+    return started(
+      job,
+      `Searching the ${country.toUpperCase()} ad library for ${queries.length} term(s), one at a time.`
+    );
+  }
+);
+
+mcp.registerTool(
+  "job_status",
+  {
+    title: "Check a run",
+    description: [
+      "Says where a run has got to: whether it is still going, how long it has been at",
+      "it, the last few lines it printed, anything it is waiting on, and what to do next.",
+      "Reads state already held, so it answers at once and costs nothing.",
+      "",
+      "This is a snapshot. To wait for the run rather than keep asking, use await_job.",
+      "next_step says what the status means and what to do about it; follow it rather",
+      "than deciding from the status word alone.",
+    ].join("\n"),
+    inputSchema: { job_id: z.string().describe("From start_discovery, analyze_account or start_download.") },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  async ({ job_id }) => {
+    const job = jobsLib.findJob(job_id);
+    if (!job) return unknownJob(job_id);
+    return text({ ...jobsLib.baseStatus(job), next_step: jobsLib.nextStep(job) });
+  }
+);
+
+mcp.registerTool(
+  "await_job",
+  {
+    title: "Wait for a run",
+    description: [
+      "Waits for a run and comes back the moment it does something worth hearing about,",
+      "so a finish or a challenge is known at once rather than whenever the next poll",
+      "happens to land. This is the way to follow a run; job_status is for a snapshot.",
+      "",
+      "It blocks until the first of these, then returns: the run settles (done, error or",
+      "stopped), a challenge appears that only a person can clear, the run is paused or",
+      "resumed, or the wait times out. event says which, and next_step says what to do.",
+      "If the run has already settled when this is called, it returns straight away.",
+      "",
+      "wake_on decides how light a sleeper this is. Left at done it wakes only for those",
+      "run-ending or person-needing moments. Set to events it also wakes on a discovery",
+      "run for the smaller things worth a look while it works: a new account passing, an",
+      "outlier or near-miss mark newly assigned, the keywords running out, the projected",
+      "finish climbing sharply. When it wakes on those, event is events, wake_events lists",
+      "what fired, and summary carries the same picture job_results gives, narrowed to",
+      "what changed since this wait began. That is the loop: start the run, await with",
+      "wake_on events, read the summary when woken, and either keep awaiting or tune_run",
+      "if the numbers say the question was wrong.",
+      "",
+      "A timeout is not an error: it means nothing happened in the window and the run is",
+      "still going. Call await_job again to keep waiting. The wait is long by default and",
+      "can be told to be longer, so a single call is usually enough.",
+    ].join("\n"),
+    inputSchema: {
+      job_id: z.string().describe("From start_discovery, analyze_account or start_download."),
+      timeout_seconds: z
+        .number()
+        .min(jobsLib.AWAIT_MIN_SECONDS)
+        .max(jobsLib.AWAIT_MAX_SECONDS)
+        .optional()
+        .describe(
+          `How long to wait before returning with event timeout. Defaults to ${jobsLib.AWAIT_DEFAULT_SECONDS}, from ${jobsLib.AWAIT_MIN_SECONDS} to ${jobsLib.AWAIT_MAX_SECONDS}. A timeout just means call again; it does not end the run.`
+        ),
+      wake_on: z
+        .enum(["done", "events"])
+        .optional()
+        .describe(
+          "done, the default, wakes only when the run ends or needs a person. events also wakes a discovery run on a new pass, a new mark, keywords running out, or the projection climbing sharply."
+        ),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  async ({ job_id, timeout_seconds, wake_on }, extra) => {
+    const job = jobsLib.findJob(job_id);
+    if (!job) return unknownJob(job_id);
+    if (!jobsLib.IN_FLIGHT.has(job.status)) return text(jobsLib.awaitResult(job, "settled"));
+    if (job.alert && jobsLib.surfacedAlert.get(job.id) !== job.alert) {
+      return text(jobsLib.awaitResult(job, "alert"));
+    }
+    const timeout = Math.min(
+      Math.max(timeout_seconds ?? jobsLib.AWAIT_DEFAULT_SECONDS, jobsLib.AWAIT_MIN_SECONDS),
+      jobsLib.AWAIT_MAX_SECONDS
+    );
+    const result = await jobsLib.waitForJob(job, timeout, extra, wake_on ?? "done", foundAccount);
+    return text(result);
+  }
+);
+
+mcp.registerTool(
+  "job_results",
+  {
+    title: "Read a run",
+    description: [
+      "Returns what a run has produced. The shape follows the tool: a discovery run",
+      "gives its live vitals, the accounts that passed, every profile it measured and",
+      "rejected with the reason, the rejections counted by reason, and the outliers it",
+      "flagged; an account analysis gives one report; a download gives what came down",
+      "and where it landed.",
+      "",
+      "Discovery answers while it is still running, so this is how to watch a run take",
+      "shape: nothing it has measured is hidden, a rejected account rides here as a",
+      "compact row saying by how much it fell short, and no_posts_in_window is kept",
+      "distinct from a real zero. An account analysis or download has nothing to read",
+      "until it reaches done.",
+      "",
+      "The passed accounts are also in the library once the run finishes, so",
+      "search_accounts and get_account answer follow-up questions about them, and",
+      "get_account has the bio and captions a compact row leaves out.",
+    ].join("\n"),
+    inputSchema: { job_id: z.string().describe("From any of the run tools.") },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  async ({ job_id }) => {
+    const job = jobsLib.findJob(job_id);
+    if (job) {
+      if (job.tool === "discover") return text(discoveryResults(job));
+      if (job.status === "error") return fail(`That run failed: ${job.error}`);
+      if (!job.result) return text(`Nothing to read yet: the run is ${job.status}.`);
+      return text(job.result);
+    }
+    const saved = store.loadRun(job_id);
+    if (saved) return text(saved.results ?? saved);
+    return unknownJob(job_id);
+  }
+);
+
+mcp.registerTool(
+  "job_control",
+  {
+    title: "Pause, resume or stop a run",
+    description: [
+      "The three buttons a person would have: pause holds the run where it is, resume",
+      "picks it back up, stop ends it for good.",
+      "",
+      "Resume is what clears a challenge: once the user has solved the verification in",
+      "the Chrome window, resume carries the run to the end with no second prompt.",
+      "",
+      "Stopping cannot be undone, so never stop a run the user did not ask you to stop.",
+      "Everything a run measured before it ended is kept either way, and job_results",
+      "still reads it back.",
+    ].join("\n"),
+    inputSchema: {
+      job_id: z.string(),
+      action: z.enum(["pause", "resume", "stop"]),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+  },
+  async ({ job_id, action }) => {
+    const job = jobsLib.findJob(job_id);
+    if (!job) return unknownJob(job_id);
+    const outcome = jobsLib.control(job, action);
+    if (!outcome.ok) return fail(outcome.reason);
+    return text({ job_id, action, status: job.status, next_step: jobsLib.nextStep(job) });
+  }
+);
+
+mcp.registerTool(
+  "tune_run",
+  {
+    title: "Retune a discovery in flight",
+    description: [
+      "Changes a discovery run's filters, window, target or keywords while it is still",
+      "going, and re-judges everything already measured on the spot. Nothing is browsed",
+      "again: the run holds every account it measured with the raw posts behind it, so a",
+      "filter change is answered in memory and at once.",
+      "",
+      "Every account marked as failing is re-decided against the new numbers instantly;",
+      "the ones that now clear the bar join the passing set, the ones that no longer",
+      "clear it fall back out, and the vitals, marks and breakdown are rebuilt. Changing",
+      "the window is exact too, recomputed from each account's own retained posts.",
+      "",
+      "From there the run carries the new numbers forward: every profile it measures next",
+      "is judged by them, the stop condition uses the new target, and appended keywords",
+      "extend what the search still has to draw on. Keywords are added to the end of the",
+      "list, never removed from it.",
+      "",
+      "The answer is the delta it caused, and the delta is the reading. Loosening a floor",
+      "and recovering a crowd of accounts says the floor was the problem. Recovering",
+      "nothing says the niche is genuinely thin here, which is the moment for fresh",
+      "keywords rather than a lower bar.",
+    ].join("\n"),
+    inputSchema: {
+      job_id: z.string().describe("A discovery run, in flight."),
+      min_followers: z.number().int().min(0).optional(),
+      min_slideshow_pct: z.number().min(0).max(100).optional(),
+      avg_views_days: z.number().int().min(1).optional(),
+      min_avg_views: z.number().int().min(0).optional(),
+      min_total_views: z.number().int().min(0).optional(),
+      max_accounts: z.number().int().min(1).optional().describe("Move the target the run is working towards."),
+      add_keywords: z.array(z.string().min(1)).optional().describe("Appended to the end of the keyword list."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+  },
+  async (input) => {
+    const job = jobsLib.findJob(input.job_id);
+    if (!job) return unknownJob(input.job_id);
+    if (job.tool !== "discover") return fail("tune_run only applies to a discovery run.");
+
+    const before = job.state.measured.filter((a) => a.verdict?.passed).map((a) => a.username);
+    const filters = { ...job.meta.filters };
+    if (input.min_followers !== undefined) filters.minFollowers = input.min_followers;
+    if (input.min_slideshow_pct !== undefined) filters.minRatio = input.min_slideshow_pct / 100;
+    if (input.avg_views_days !== undefined) filters.avgViewsDays = input.avg_views_days;
+    if (input.min_avg_views !== undefined) filters.minAvgViews = input.min_avg_views;
+    if (input.min_total_views !== undefined) filters.minTotalViews = input.min_total_views;
+    job.meta.filters = filters;
+
+    if (input.max_accounts !== undefined) {
+      job.meta.maxAccounts = input.max_accounts;
+      job.state.target = input.max_accounts;
+    }
+    if (input.add_keywords?.length) {
+      const added = input.add_keywords.map((k) => k.trim()).filter(Boolean);
+      job.meta.keywords.push(...added);
+      job.state.keywordsTotal = job.meta.keywords.length;
+    }
+
+    // Re-judge from each account's own retained posts, not from an aggregate.
+    for (const account of job.state.measured) {
+      if (account.verdict?.unmeasured) continue;
+      const redone = reevaluate(account, filters);
+      account.verdict = redone.verdict;
+      account.metrics = {
+        ...account.metrics,
+        slideshow_ratio: redone.ratioPct,
+        [`avg_views_last_${filters.avgViewsDays}d`]: redone.noPostsInWindow
+          ? null
+          : Math.trunc(redone.avgViews ?? 0),
+        [`total_views_last_${filters.avgViewsDays}d`]: redone.noPostsInWindow
+          ? null
+          : Math.trunc(redone.totalViewsWindow),
+        view_follower_ratio: redone.verdict.viewsPerFollower,
+      };
+    }
+    flagOutliers(job.state.measured);
+
+    const after = job.state.measured.filter((a) => a.verdict?.passed).map((a) => a.username);
+    const recovered = after.filter((name) => !before.includes(name));
+    const lost = before.filter((name) => !after.includes(name));
+    job.meta.tuning.push({
+      at: new Date().toISOString(),
+      changes: input,
+      recovered: recovered.length,
+      lost: lost.length,
+    });
+    jobsLib.log(job, `Retuned: ${recovered.length} recovered, ${lost.length} no longer passing.`);
+    jobsLib.emit("progress", job);
+
+    return text({
+      job_id: job.id,
+      filters,
+      passed_before: before.length,
+      passed_after: after.length,
+      recovered,
+      lost,
+      vitals: jobsLib.vitalsFields(jobsLib.vitals(job)),
+    });
+  }
+);
+
+mcp.registerTool(
+  "list_runs",
+  {
+    title: "Past runs",
+    description: [
+      "Lists every discovery run this machine has recorded: its name, keywords, when it",
+      "ran, and how many accounts it holds. This is where run ids come from, and it",
+      "answers instantly with no browser.",
+    ].join("\n"),
+    inputSchema: { limit: z.number().int().min(1).max(200).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  async ({ limit }) => {
+    const runs = store.listRuns().slice(0, limit ?? 50);
+    return text(
+      runs.map((run) => ({
+        run_id: run.id,
+        name: run.name,
+        keywords: run.keywords,
+        started_at: run.started_at,
+        status: run.status,
+        accounts_passed: run.accounts_passed,
+        accounts_measured: run.accounts_measured,
+      }))
+    );
+  }
+);
+
+mcp.registerTool(
+  "search_accounts",
+  {
+    title: "Search the library",
+    description: [
+      "Searches every account discovery has ever filed, by free text and by run, sorted",
+      "any of seven ways, one page at a time. Instant, no browser, no risk.",
+      "",
+      "query matches handles, display names, bios and hashtags. run_id narrows to one",
+      "run. Narrow and sort rather than paging through everything.",
+      "",
+      "The library is the user's own record of research already done, so it answers",
+      "questions about accounts they already hold and can never answer a request for new",
+      "accounts: handing its contents back is returning the user their own notebook.",
+    ].join("\n"),
+    inputSchema: {
+      query: z.string().optional(),
+      run_id: z.string().optional(),
+      sort: z.enum(store.SORT_ORDERS).optional().describe("Defaults to found, newest first."),
+      limit: z.number().int().min(1).max(100).optional().describe("Defaults to 25."),
+      offset: z.number().int().min(0).optional(),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  async ({ query, run_id, sort, limit, offset }) => {
+    const found = store.searchAccounts({
+      query,
+      runId: run_id,
+      sort: sort ?? "found",
+      limit: limit ?? 25,
+      offset: offset ?? 0,
+    });
+    return text({
+      total: found.total,
+      accounts: found.accounts.map(foundAccount),
+    });
+  }
+);
+
+mcp.registerTool(
+  "get_account",
+  {
+    title: "One account in full",
+    description: [
+      "Returns everything the library holds on one account: bio, sample captions, top",
+      "hashtags, and every measurement, plus which run found it and when.",
+      "",
+      "This is the instant answer to any follow-up about an account already found. It is",
+      "a stored reading, so it is as current as the run that took it; analyze_account is",
+      "the fresh read when the numbers need to be current.",
+    ].join("\n"),
+    inputSchema: { username: z.string().min(1).describe("With or without the leading @.") },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  async ({ username }) => {
+    const account = store.getAccount(username);
+    if (!account) {
+      return fail(
+        `@${username.replace(/^@+/, "")} is not in the library. analyze_account reads it fresh from TikTok, or start_discovery finds accounts like it.`
+      );
+    }
+    return text({
+      ...withoutSamples(account),
+      url: `https://www.tiktok.com/@${account.username}`,
+    });
+  }
+);
+
+async function main() {
+  ensureDirs();
+  const transport = new StdioServerTransport();
+  await mcp.connect(transport);
+  process.stderr.write(`${NAME}: ready\n`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${NAME}: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});