@nooticr/mcp 1.26.21 → 1.26.23

package/README.md

@@ -14,8 +14,8 @@ model of ours for an opinion first. You pay for the fetch and nothing else.
 
 It also **monitors a name**: `search_mentions` sweeps nine of those networks for
 every comment that says your brand, inside a date window you choose, and
-`search_spoken_mentions` reads the words actually said out loud in TikTok and
-YouTube videos for the mentions that were never typed anywhere.
+`search_spoken_mentions` reads the words actually said out loud in TikTok,
+YouTube and Douyin videos for the mentions that were never typed anywhere.
 
 Runs over stdio locally or as a hosted connector at `https://mcp.nooticr.com/mcp`.
 Billed against your nooticr credits; new accounts get 20 free.
@@ -52,7 +52,7 @@ npx @nooticr/mcp login   # one-time sign-in (Google)
 
 ## Tools
 
-49 tools, grouped by what you are trying to do. Prices are in nooticr credits and
+64 tools, grouped by what you are trying to do. Prices are in nooticr credits and
 match what the server actually charges.
 
 Seven of them — the ones under **Answer a question you actually have** — are not
@@ -67,7 +67,7 @@ them caps that fan-out with an argument.
 | Tool | Credits | What it is for |
 |------|---------|----------------|
 | `get_social_media` | 1 | The post's facts and media — contentType, title, caption, author, stats, direct media URLs, plus an inline thumbnail. Use when you want the post itself and nothing interpreted. |
-| `get_post_transcript` | 1 | The words actually spoken, read from the post's caption track (TikTok and YouTube). Exact rather than inferred, and far cheaper than watching the video. Use before any analysis when the wording matters. |
+| `get_post_transcript` | 1 | The words actually spoken. Where the platform publishes a caption track (TikTok, Douyin, YouTube) it is read as-is — exact rather than inferred, and far cheaper than watching the video; everywhere else the post's own audio is transcribed, which needs speech-to-text configured on the server. Use before any analysis when the wording matters. |
 | `get_post_frames` | 2 | Frames sampled evenly across a post's video, returned as **images you can actually look at** — not a description of them. ffmpeg opens the stream directly rather than downloading it, so HLS works and an expired link is re-resolved on the spot. Verified live at 3/3 on TikTok, YouTube, Instagram, Douyin and X; Reddit works on video posts. A carousel or slideshow returns its own images unchanged. Each frame costs roughly 1,200 tokens of your context. |
 | `get_post_comments` | 2 | Top comments plus the themes the platform clusters them into, with which ones the creator pinned or liked. Use when you want to read what people wrote. |
 
@@ -95,7 +95,7 @@ them caps that fan-out with an argument.
 | `discover_sounds` | 2 | Trending audio with playable previews. Sound is a major ranking signal on TikTok. |
 | `discover_hashtags` | 2 | Trending hashtags with volumes and whether each is rising, cooling or steady. |
 | `find_hook_pattern` | 2 | A creator's recent posts, so their opening lines can be read as a set and turned into fill-in-the-blank templates. One `get_user_posts` call. |
-| `search_mentions` | 2 per network (5 for Xiaohongshu) | **Brand monitoring.** Every *comment* that names a term, across nine networks at once, grouped under the post it was left on. A brand is named far more often in the replies than in a caption, so the comment is the unit — not the post. Takes a `since` date to read a past window, and pages with `offset`/`pageSize` so a nine-network sweep does not arrive all at once. Does not read speech inside a video — `search_spoken_mentions` does, on TikTok and YouTube. |
+| `search_mentions` | 2 per network (5 for Xiaohongshu) | **Brand monitoring.** Every *comment* that names a term, across nine networks at once, grouped under the post it was left on. A brand is named far more often in the replies than in a caption, so the comment is the unit — not the post. Takes a `since` date to read a past window, and pages with `offset`/`pageSize` so a nine-network sweep does not arrive all at once. Does not read speech inside a video — `search_spoken_mentions` does, on TikTok, YouTube and Douyin. |
 | `watch_creator` | free | Add a creator to your watchlist. Stores the handle only — nothing is fetched. |
 | `unwatch_creator` | free | Drop a creator from the watchlist. |
 | `catch_up_watchlist` | 2 per creator | What everyone you watch has posted since your last catch-up. Compares against the snapshot taken last time and moves it forward, so it answers "what is new" rather than "what exists". |
@@ -117,7 +117,7 @@ them caps that fan-out with an argument.
 | `show_collab_shortlist` | free | Draws the candidates you scored, ranked, and asks the user which to approach. The scores are attributed to your model, not presented as a nooticr rating, and a candidate scored without anything having been opened is marked unverified. Makes no requests. |
 | `why_did_this_underperform` | 3 | One post against the creator's own recent distribution, with the post taken back out of its own baseline. Returns median, quartiles, ratio and percentile, so the answer can be "this is an ordinary result, not a failure". Different question from `compare_posts`, which weighs two URLs you already picked. |
 | `what_should_i_make_next` | 2 + 2 per post read + 2 (12 by default) | Demand against supply: what your commenters explicitly ask for, set beside what a niche sweep shows is already being made. A gap nobody asked for is noise; a request nobody serves is the opportunity. Falls back to your most-used hashtag when you name no niche. |
-| `search_spoken_mentions` | 2 per platform narrowed by niche + 2 per creator handle + 1 per transcript, up to `maxTranscripts` | **The mirror of `search_mentions`, for what was said rather than typed.** Narrows to candidate posts (a niche sweep, named handles, and/or your watchlist), transcribes only the most-viewed survivors up to a hard ceiling, and searches the words for the term — TikTok and YouTube only, and only where the platform actually supplies a caption track. Reports how many candidates were found, transcribed and matched, so the spend is legible. |
+| `search_spoken_mentions` | 2 per platform narrowed by niche + 2 per creator handle + 1 per transcript, up to `maxTranscripts` | **The mirror of `search_mentions`, for what was said rather than typed.** Narrows to candidate posts (a niche sweep, named handles, and/or your watchlist), transcribes only the most-viewed survivors up to a hard ceiling, and searches the words for the term — TikTok, YouTube and Douyin, and only where the creator actually enabled captions. Reports how many candidates were found, transcribed and matched, so the spend is legible. |
 
 ### Make something
 
@@ -138,6 +138,10 @@ them caps that fan-out with an argument.
 | `check_nooticr_credits` | free | Balance and billing URL. |
 | `buy_nooticr_credits` | free | A Stripe Checkout URL for a credit pack. Credits land automatically after payment. |
 | `nooticr_login` | free | Re-link the account when a call fails with an authentication error. |
+| `list_social_connections` | free | What you have connected and what each connection is actually allowed to do — read the account, publish a post, manage comments — as yes, no or **unknown**. Unknown means the grant predates scope recording: treat it as "try it", not as a refusal. Also says which platforms can be linked at all, which is a smaller set than the networks nooticr reads. |
+| `connect_social_account` | free | A link the user opens to connect one account. They approve at the provider in their own browser; nothing is connected until they do, and no credential passes through the tool or the model's context. Each call mints a fresh link — an old one does not work twice. |
+| `create_product` | free | Create a product in your own workspace — the row every other own-account tool needs before it has anything to work with. Always creates in the calling session's workspace, never one you could name. `name` and `slug` are required; every other field is snake_case and read by exact key, so a camelCase `websiteUrl` lands nowhere. Writes no brand playbook. |
+| `update_product` | free | Patch a product's fields. An omitted argument leaves its column unchanged, so this cannot blank a field by not mentioning it, and the result lists what was actually written — a misspelled field shows up as one that did not change rather than as a silent no-op. |
 
 ### Your own product
 
@@ -250,17 +254,31 @@ selectable. Free, and it makes no requests.
 ## Before an expensive call, it asks
 
 Most tools print their price in their own description, so a call costs what you
-already read. Two do not, because their price is set by an argument:
+already read. Six do not, because their price is set by an argument — or by a
+list the request never mentions:
 
 - `search_mentions` bills **per network swept**, so a bare "monitor my brand"
   sweeps all nine for 21 credits.
-- `catch_up_watchlist` bills **per creator**, so the price is the length of a
-  list the request never mentions.
-
-Above 6 credits those two ask first, over MCP `elicitation` — the client shows
-the number and you accept or decline. Declining spends nothing and is not an
-error. A client that does not support elicitation is not blocked; the call runs
-as it always did.
+- `catch_up_watchlist` bills **per creator**, so the price is the length of your
+  watchlist.
+- `answer_my_audience` and `what_should_i_make_next` bill **per post opened**
+  (14 and 12 credits at their defaults), so they ask once the real post count is
+  known rather than on a worst case.
+- `search_spoken_mentions` bills per network, per handle and per transcript, so
+  it asks on the worst case it could reach.
+- `create_brand_watch` asks **however small the number is**, because what is
+  being agreed to is a recurring charge rather than one run.
+
+Above 6 credits those first five ask first, over MCP `elicitation` — the client
+shows the number and you accept or decline. Declining spends nothing and is not
+an error. A client that does not support elicitation is not blocked; the call
+runs as it always did.
+
+Two rules go further than the threshold. A scheduled watch always asks, because
+the standing arrangement is the thing being approved. And a watch that emails a
+digest refuses to accept a `deliverTo` address unless a person actually saw the
+dialog and said yes — "nobody could be asked" is a fine answer for a spend and
+the wrong one for an address.
 
 ## Prerequisites
 

package/dist/shared/connections.js

@@ -16,6 +16,12 @@
  */
 import { z } from "zod";
 import { OUTPUT_SCHEMAS } from "./output-schemas.js";
+// Both of these shipped view-less. The grant a connection actually carries —
+// read, publish, manage comments, each yes/no/unknown — is a table, and a
+// table read out as prose is the thing a view is for; the third value
+// especially, since "unknown" means nobody recorded the scope and must never
+// be drawn as the refusal it is not.
+import { viewMeta } from "./view-meta.js";
 function toResult(proxy) {
     const textBlock = proxy.contentBlocks.find((c) => c.type === "text");
     return {
@@ -32,6 +38,7 @@ function failed(prefix, err) {
 }
 export function registerConnectionTools(server, makeClient) {
     server.registerTool("list_social_connections", {
+        _meta: viewMeta("list_social_connections"),
         title: "List Social Connections",
         description: "List the social accounts your workspace has connected and what each connection is " +
             "allowed to do — read the account, publish a post, manage comments. Each answer is yes, " +
@@ -52,6 +59,7 @@ export function registerConnectionTools(server, makeClient) {
         }
     });
     server.registerTool("connect_social_account", {
+        _meta: viewMeta("connect_social_account"),
         title: "Connect Social Account",
         description: "Get a link to open so you can connect one social account. Takes the platform, and " +
             "optionally influencerId or appId when your workspace has more than one creator profile " +

package/dist/shared/evidence.js

@@ -35,6 +35,23 @@
  * documentation; it is the steering, and it lands in the model's context.
  */
 import { BACKEND_CALL_CREDITS, costOf } from "./spend.js";
+import { numberOf } from "./performance.js";
+/**
+ * Every fan-out is capped; the cap is an argument, and the argument is clamped.
+ *
+ * Lives here rather than beside its first caller in jobs.ts because the
+ * evidence plans need it too, and for a while did not have it: three of them
+ * documented a `max` in their zod schema and then passed the argument straight
+ * through, so the ceiling a host read was never enforced and `limit: 500`
+ * fetched 500. One clamp for both files, and the import already runs this way
+ * round — jobs.ts imports evidence.ts, never the reverse.
+ */
+export function clamp(value, fallback, min, max) {
+    const n = Math.floor(numberOf(value ?? fallback));
+    if (!n)
+        return fallback;
+    return Math.min(max, Math.max(min, n));
+}
 const url = (a) => String(a.url ?? "");
 /**
  * Platforms whose accounts can be found by NAME. This is the backend's
@@ -217,24 +234,33 @@ export const EVIDENCE_PLANS = {
         args: (a) => ({
             username: String(a.username ?? ""),
             platform: a.platform,
-            limit: Number(a.limit ?? 12),
+            limit: clamp(a.limit, 12, 1, 30),
         }),
-        guidance: (a) => [
-            `Recent posts by ${a.username}, with their stats.`,
-            "",
-            "Work out this creator's niche, recurring themes, hook formula, what",
-            "over- and under-performs for them, and who their audience is. Use the",
-            "spread of the numbers, not just the best post. Name the posts you are",
-            "reasoning from.",
-            ownIt,
-        ].join("\n"),
+        guidance: (a) => {
+            const focus = String(a.focus ?? "").trim();
+            return [
+                `Recent posts by ${a.username}, with their stats.`,
+                "",
+                "Work out this creator's niche, recurring themes, hook formula, what",
+                "over- and under-performs for them, and who their audience is. Use the",
+                "spread of the numbers, not just the best post. Name the posts you are",
+                "reasoning from.",
+                ...(focus
+                    ? [
+                        "",
+                        `Focus for this pass, as asked: ${focus}. Still cover the profile as a whole, but weight what you cover toward this.`,
+                    ]
+                    : []),
+                ownIt,
+            ].join("\n");
+        },
     },
     find_hook_pattern: {
         via: "get_user_posts",
         args: (a) => ({
             username: String(a.username ?? ""),
             platform: a.platform,
-            limit: Number(a.limit ?? 12),
+            limit: clamp(a.limit, 12, 1, 40),
         }),
         guidance: (a) => [
             `Recent posts by ${a.username}. Their opening lines are the material.`,
@@ -251,7 +277,7 @@ export const EVIDENCE_PLANS = {
         args: (a) => ({
             niche: String(a.niche ?? ""),
             platform: a.platform,
-            limit: Number(a.count ?? 12),
+            limit: clamp(a.count, 12, 1, 40),
         }),
         guidance: (a) => [
             `Recent posts in the "${a.niche}" niche, with their stats.`,

package/dist/shared/jobs.js

@@ -56,19 +56,12 @@
 import { z } from "zod";
 import { OUTPUT_SCHEMAS } from "./output-schemas.js";
 import { platformFromUrl, postSlug } from "./comment-review.js";
-import { handleMissGuidance, ownIt, PLATFORM_ARG } from "./evidence.js";
-import { confirmSpend, costOf, declinedResult, MAX_SPOKEN_HANDLE_CALLS, MAX_SPOKEN_TRANSCRIPTS, } from "./spend.js";
+import { clamp, handleMissGuidance, ownIt, PLATFORM_ARG } from "./evidence.js";
+import { confirmSpend, costOf, declinedResult, MAX_SPOKEN_HANDLE_CALLS, MAX_SPOKEN_TRANSCRIPTS, SPOKEN_PLATFORMS, } from "./spend.js";
 import { distributionOf, excluding, numberOf, standing, } from "./performance.js";
 import { normaliseHandle, watchEntryId, watchlistOwner } from "./watchlist.js";
 import { viewMeta } from "./view-meta.js";
 import { extractLinks, COLLAB_RUBRIC, vettingGuidance } from "./collab.js";
-/** Every fan-out is capped; the cap is an argument, and the argument is clamped. */
-function clamp(value, fallback, min, max) {
-    const n = Math.floor(numberOf(value ?? fallback));
-    if (!n)
-        return fallback;
-    return Math.min(max, Math.max(min, n));
-}
 const rowsOf = (value) => Array.isArray(value) ? value.filter((r) => r && typeof r === "object") : [];
 const structuredOf = (res) => (res.structured ?? {});
 const reason = (err) => (err instanceof Error ? err.message : String(err));
@@ -482,6 +475,48 @@ function nextGuidance(a) {
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/** "4:12", or "1:04:12" once there is an hour to show. */
+export function formatTimecode(ms) {
+    const total = Math.max(0, Math.floor(ms / 1000));
+    const s = total % 60;
+    const m = Math.floor(total / 60) % 60;
+    const h = Math.floor(total / 3600);
+    const pad = (n) => String(n).padStart(2, "0");
+    return h > 0 ? `${h}:${pad(m)}:${pad(s)}` : `${m}:${pad(s)}`;
+}
+/**
+ * The cue a character offset falls in — the line the term was said in.
+ *
+ * The cues are sorted by offset, so this keeps the last one that starts at or
+ * before the match and stops at the first that starts after it. A match
+ * landing in the gap before the first cue has no answer, which is the honest
+ * one.
+ */
+function cueAt(cues, position) {
+    let found = null;
+    for (const cue of cues) {
+        if (cue.offset > position)
+            break;
+        found = cue;
+    }
+    return found;
+}
+/** Attach the moment each excerpt was said, where the track carried one. */
+export function timeExcerpts(excerpts, rawCues) {
+    const cues = (Array.isArray(rawCues) ? rawCues : [])
+        .filter((c) => !!c && typeof c === "object"
+        && typeof c.offset === "number"
+        && typeof c.startMs === "number")
+        .sort((a, b) => a.offset - b.offset);
+    if (!cues.length)
+        return excerpts;
+    return excerpts.map((ex) => {
+        const cue = cueAt(cues, ex.position);
+        if (!cue)
+            return ex;
+        return { ...ex, startMs: cue.startMs, timecode: formatTimecode(cue.startMs) };
+    });
+}
 /**
  * Where a term is actually said, case-insensitively and on whole words —
  * "nike" must not fire inside "nikeisha". `\b` only means anything next to a
@@ -1530,9 +1565,12 @@ export function registerJobTools(server, makeClient, store) {
             "speech recognition — see get_post_transcript), and searches them for a term. Narrows to " +
             "candidate posts first (a niche/keyword sweep, named creator handles, and/or your " +
             "watchlist), transcribes only the most-viewed survivors up to a hard ceiling you set, and " +
-            "returns the matched line with surrounding context so tone can be judged. TikTok and " +
-            "YouTube only — the only two networks whose posts carry a caption track this cheaply — " +
-            "and even there a video with no captions is invisible to this tool; coverage is real but " +
+            "returns the matched line with surrounding context so tone can be judged. TikTok, YouTube " +
+            "and Douyin — the networks whose post detail already carries a caption track, which is " +
+            "what makes a transcript one cheap read rather than a wait. Every other network's audio " +
+            "can be transcribed too, at the same price, but not yet from here: see " +
+            "get_post_transcript for that route. Even on these three a video whose creator disabled " +
+            "captions is invisible to this tool; coverage is real but " +
             "partial, and the result says how many candidates were found, transcribed and matched so " +
             "the gap is never silent. Costs 2 nooticr credits per platform a niche is searched on, 2 " +
             "per creator handle checked (including ones added by useWatchlist), and 1 per transcript " +
@@ -1549,7 +1587,7 @@ export function registerJobTools(server, makeClient, store) {
                 .describe("Brand, product or person to listen for, e.g. 'nooticr'. Matched case-insensitively " +
                 "on whole words, so 'nike' will not match inside 'nikeisha'."),
             platforms: z
-                .array(z.enum(["tiktok", "youtube"]))
+                .array(z.enum(SPOKEN_PLATFORMS))
                 .optional()
                 .describe("Which networks to check (default: both). These are the only two whose posts carry " +
                 "a caption track this tool can read."),
@@ -1594,8 +1632,8 @@ export function registerJobTools(server, makeClient, store) {
             };
         }
         const platforms = [
-            ...new Set((args.platforms && args.platforms.length ? args.platforms : ["tiktok", "youtube"]).map((p) => String(p).toLowerCase())),
-        ].filter((p) => p === "tiktok" || p === "youtube");
+            ...new Set((args.platforms && args.platforms.length ? args.platforms : SPOKEN_PLATFORMS).map((p) => String(p).toLowerCase())),
+        ].filter((p) => SPOKEN_PLATFORMS.includes(p));
         const explicitHandles = [...new Set((args.usernames ?? []).map(normaliseHandle).filter(Boolean))];
         // A watchlist handle already knows its own platform, so it is checked
         // once there rather than once per requested platform — the same
@@ -1780,7 +1818,12 @@ export function registerJobTools(server, makeClient, store) {
                         post: { ...post, postId: id, postedAt: postDate(post) },
                         postId: id,
                         matchCount,
-                        excerpts,
+                        // TikTok and YouTube both publish a timed caption track, and
+                        // those are the only two platforms this tool narrows to — so a
+                        // hit here almost always knows the moment it was said. The
+                        // speech-to-text fallback carries no clock, and an excerpt from
+                        // one simply arrives without a timecode.
+                        excerpts: timeExcerpts(excerpts, structured.cues),
                         wordCount: numberOf(structured.wordCount),
                         language: structured.language ?? null,
                         autoGenerated: !!structured.autoGenerated,