@nooticr/mcp 1.26.46 → 1.26.48

package/README.md

@@ -52,7 +52,7 @@ npx @nooticr/mcp login   # one-time sign-in (Google)
 
 ## Tools
 
-86 tools, grouped by what you are trying to do. Prices are in nooticr credits and
+88 tools, grouped by what you are trying to do. Prices are in nooticr credits and
 match what the server actually charges.
 
 The job tools under **Answer a question you actually have** are not
@@ -101,9 +101,10 @@ them caps that fan-out with an argument.
 | `unwatch_creator` | free | Drop a creator from the watchlist. |
 | `list_watchlist` | free | Who you are watching: handle, platform, note, and when you last caught up on each. |
 | `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". |
-| `create_brand_watch` | free to call | Schedule a recurring sweep and get emailed only what is new. `kind: "mentions"` (default) is a recurring `search_mentions` sweep for `term`/`platforms`; `kind: "competitor"` is a recurring `get_user_posts` check on one creator (`handle`/`platform`), mailing only what beats their own recent median. Two calls by design: the first returns the quote (cost per run, cadence, cost per day) and a `confirmationToken`; nothing is created or charged until you call it again with `confirm: true` and that token. Each run then bills the same as calling the matching tool yourself — 2 credits per network (5 for Xiaohongshu) for mentions, a flat 2 credits for competitor. |
+| `create_brand_watch` | free to call | Schedule a recurring sweep and get emailed only what is new. `kind: "mentions"` (default) is a recurring `search_mentions` sweep for `term`/`platforms`; `kind: "competitor"` is a recurring `get_user_posts` check on one creator (`handle`/`platform`), mailing only what beats their own recent median; `kind: "report"` runs `job: {tool, args}` — `niche_report` (mailed as written every run) or `discover_social_posts` (only unseen posts) — on the schedule; `kind: "portfolio"` sweeps up to 25 `terms` (your brand, products, competitors) across the same networks under one budget and mails one digest with each term's share of voice. Two calls by design: the first returns the quote (cost per run, cadence, cost per day) and a `confirmationToken`; nothing is created or charged until you call it again with `confirm: true` and that token. Each run then bills the same as calling the matching tool yourself — 2 credits per network (5 for Xiaohongshu) for mentions, a flat 2 credits for competitor, the job tool's own price for a report (3 for `niche_report`), and a mentions sweep per term for a portfolio — whose budget is split evenly and trims networks, never terms, and which refunds any term whose sweep fails. |
 | `list_brand_watches` | free | Every watch you have scheduled: term, networks, cadence, cost per run, credits spent so far, runs made, and when the next one is due. |
 | `mention_trend` | free | **What a watch has seen over time**, which nothing else here answers — every other read is about now. One point per run: when it ran, how many mentions it found, how many were new, and both counts per network, so "which network is growing" and "did it go quiet or did we stop looking" come apart. On a competitor watch each point carries the median that run measured, which turns "they beat their own median" into "and that median has doubled". Plus the mentions more than one run has seen. Free because the sweeps were billed when they ran; charging again to read what was already paid for is the thing it fixes. |
+| `update_watch_portfolio` | free | Add or remove a portfolio watch's terms by `watchId`. No new confirmation, because the per-run budget you agreed to does not move — more terms split it more ways, and the reply names any network a run no longer reaches. |
 | `stop_brand_watch` | free | Stop a watch by `watchId` or `term`. Immediate — the next run does not happen and nothing more is charged. |
 | `niche_report` | 2 | Recent posts in a niche with their stats, so the dominant formats, hook patterns and the gaps nobody fills can be read off them. One `discover_social_posts` call. Use when deciding what to make. |
 | `analyze_creator_profile` | 2 | A creator's recent posts with their stats — the material of a teardown: niche, themes, hook formula, what over- and underperforms, who the audience is. One `get_user_posts` call. |
@@ -174,6 +175,7 @@ a `scanId` for the rest.
 | `check_nooticr_credits` | free | Balance and billing URL. |
 | `list_tool_runs` | free | Your tool-call history: what ran, whether it worked, and the credits each call actually took (0 for a free, refunded, cached or replayed call). `scope: "workspace"` shows every member's runs to owners and admins. |
 | `get_tool_run` | free | One run from that history by id, with its full error. |
+| `get_usage_report` | free | The run ledger added up over a window: total calls, failures and credits actually taken, per tool, per day and the most recent failures. `scope: "workspace"` adds one row per seat, for the workspace's owners and admins. |
 | `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**. "Manage comments" reports the platform's grant; no nooticr tool posts or replies to a comment. 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. |

package/dist/shared/brand-watch.js

@@ -34,7 +34,15 @@ const CADENCE_RATE = {
     weekly: { runs: 1, per: "week" },
 };
 /** Mirrors `crate::brand_watch::WatchKind` (nooticr-server, brand_watch.rs). */
-const KINDS = ["mentions", "competitor"];
+const KINDS = ["mentions", "competitor", "report", "portfolio"];
+/**
+ * Mirrors `SCHEDULABLE_JOBS` in nooticr-server's brand_watch.rs: the tools a
+ * report watch may run. Anything else is refused there too; listing them here
+ * is so the enum a host sees is the list that will actually be accepted.
+ */
+export const SCHEDULABLE_JOBS = ["niche_report", "discover_social_posts"];
+/** Mirrors `MAX_PORTFOLIO_TERMS` (and the migration's check). */
+const MAX_PORTFOLIO_TERMS = 25;
 /**
  * What one run of a competitor watch bills: one flat `get_user_posts` call,
  * whatever the platform. Mirrors `COMPETITOR_SWEEP_TOOL`'s cost
@@ -46,6 +54,47 @@ const KINDS = ["mentions", "competitor"];
 function competitorWatchCost() {
     return BACKEND_CALL_CREDITS.get_user_posts;
 }
+/**
+ * What one run of a report watch bills: its job's own price, the same number
+ * `mcp_tool_cost_for` charges for that call by hand. A discovery job that
+ * opens posts for their comments pays one call per post opened.
+ */
+function reportWatchCost(job) {
+    if (!job)
+        return 0;
+    if (job.tool === "niche_report")
+        return NICHE_REPORT_CREDITS;
+    const base = BACKEND_CALL_CREDITS.discover_social_posts;
+    if (!job.args?.includeComments)
+        return base;
+    const opened = Math.min(10, Math.max(1, Math.trunc(job.args.openPosts ?? 5)));
+    return base + opened;
+}
+/** `niche_report`'s price in `mcp_tool_cost` — text-only AI, no video. */
+const NICHE_REPORT_CREDITS = 3;
+/** The terms a portfolio watch sweeps, as the server will read them. */
+function portfolioTerms(terms) {
+    const out = [];
+    for (const raw of terms ?? []) {
+        const t = raw.trim();
+        if (t && !out.some((o) => o.toLowerCase() === t.toLowerCase()))
+            out.push(t);
+    }
+    return out;
+}
+/** An upper bound on one run of any kind, before the budget ceiling. */
+function sweepCost(args) {
+    switch (args.kind ?? "mentions") {
+        case "competitor":
+            return competitorWatchCost();
+        case "report":
+            return reportWatchCost(args.job);
+        case "portfolio":
+            return searchMentionsCost(args.platforms) * Math.max(1, portfolioTerms(args.terms).length);
+        default:
+            return searchMentionsCost(args.platforms);
+    }
+}
 /**
  * The human-facing half of the quote-then-confirm protocol.
  *
@@ -70,7 +119,7 @@ async function gateRecurringCharge(server, args) {
     // means a competitor watch's single 2-credit call always fits, so there is
     // nothing to trim in practice — unlike a mentions sweep, which frequently
     // does.
-    const sweep = kind === "competitor" ? competitorWatchCost() : searchMentionsCost(args.platforms);
+    const sweep = sweepCost(args);
     // An upper bound on the run, deliberately, rather than the exact figure.
     // The server does not bill the budget: `plan_run` drops whole platforms
     // until the rest fit under it, so a ceiling of 9 against 2-credit networks
@@ -81,10 +130,22 @@ async function gateRecurringCharge(server, args) {
     const rate = CADENCE_RATE[args.cadence ?? "daily"];
     const perPeriod = perRun * rate.runs;
     const where = args.deliverTo ? ` Its digest goes to ${args.deliverTo}.` : "";
-    const label = kind === "competitor" ? `@${args.handle} on ${args.platform ?? "?"}` : `"${args.term}"`;
+    const every = (args.cadence ?? "daily").replace(/_/g, " ");
+    const terms = portfolioTerms(args.terms);
+    const label = kind === "competitor"
+        ? `@${args.handle} on ${args.platform ?? "?"}`
+        : kind === "report"
+            ? `"${args.job?.args?.niche ?? "?"}" with ${args.job?.tool ?? "?"}`
+            : kind === "portfolio"
+                ? `${terms.length} term${terms.length === 1 ? "" : "s"} (${terms.join(", ")})`
+                : `"${args.term}"`;
     const what = kind === "competitor"
-        ? `email what beats their own median, ${(args.cadence ?? "daily").replace(/_/g, " ")}`
-        : `email what is new, ${(args.cadence ?? "daily").replace(/_/g, " ")}`;
+        ? `email what beats their own median, ${every}`
+        : kind === "report"
+            ? `email the result, ${every}`
+            : kind === "portfolio"
+                ? `email one digest with each term's share of voice, ${every}`
+                : `email what is new, ${every}`;
     const decision = await confirmSpend(server.server, {
         credits: perPeriod,
         // Not a number worth weighing against a dialog — a standing charge. See
@@ -102,9 +163,12 @@ async function gateRecurringCharge(server, args) {
         // Said plainly, because the first model to meet this read "cancelled" as
         // a server fault and reported the feature broken — one retry away from
         // treating a person's "no" as an obstacle to route around.
-        const oneOff = kind === "competitor"
-            ? `A one-off get_user_posts call costs ${perRun} credits and repeats never.`
-            : `A one-off search_mentions sweep costs ${perRun} credits and repeats never.`;
+        const oneOffTool = kind === "competitor"
+            ? "get_user_posts call"
+            : kind === "report"
+                ? `${args.job?.tool ?? "report"} call`
+                : "search_mentions sweep";
+        const oneOff = `A one-off ${oneOffTool} costs ${kind === "portfolio" ? searchMentionsCost(args.platforms) : perRun} credits${kind === "portfolio" ? " per term" : ""} and repeats never.`;
         return declinedResult(perPeriod, `That watch`, `Nothing was created, and nothing is wrong: the person paying declined the recurring ` +
             `charge, or could not be shown it. Calling again with the same token will reach the ` +
             `same answer — ask them directly instead. ${oneOff}`);
@@ -199,6 +263,36 @@ function perPlatformDirection(runs) {
         "purpose — `runs` is newest-first, so subtracting the ends by hand is where a real reading " +
         "of this went backwards. Use these rather than re-deriving them.");
 }
+/**
+ * A portfolio's share of voice, newest run against oldest — computed here for
+ * the same reason `perPlatformDirection` is: `runs` is newest-first.
+ */
+function portfolioShare(runs) {
+    const at = (r) => String(r.ranAt ?? "");
+    const chronological = [...runs].sort((a, b) => (at(a) < at(b) ? -1 : 1));
+    const shareOf = (r) => (r?.perTerm ?? {});
+    const latest = shareOf(chronological[chronological.length - 1]);
+    const earliest = shareOf(chronological[0]);
+    const terms = Object.keys(latest);
+    if (!terms.length) {
+        return ("This is a portfolio watch, but no run in this window recorded per-term counts, so there " +
+            "is no share of voice to report yet.");
+    }
+    const said = terms
+        .map((t) => {
+        const now = latest[t];
+        if (now?.error)
+            return `${t}: not searched in the latest run (its sweep failed and was refunded)`;
+        const then = earliest[t];
+        const was = chronological.length > 1 && typeof then?.share === "number" ? `, from ${then.share}%` : "";
+        return `${t}: ${now?.share ?? 0}% of mentions found (${now?.found ?? 0})${was}`;
+    })
+        .join("; ");
+    return (`This is a portfolio watch, so each point also carries \`perTerm\` — every term's found and new ` +
+        `counts and its share of all mentions found that run. Latest run: ${said}. A share is only ` +
+        "comparable between terms because every term was searched on the same networks; a term " +
+        "added to the portfolio part-way through has no share before it was added, which is not zero.");
+}
 function trendGuidance(sc, runs) {
     const n = runs.length;
     const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
@@ -252,6 +346,9 @@ function trendGuidance(sc, runs) {
         (created ? ` This watch was created ${created.slice(0, 10)}.` : "") +
         " A series that starts flat starts where the record does, which is not the same as a " +
         "period when nobody was talking.");
+    if (sc.kind === "portfolio") {
+        lines.push("", portfolioShare(runs));
+    }
     const recurring = Array.isArray(sc.recurring) ? sc.recurring : [];
     if (recurring.length) {
         lines.push("", `\`recurring\` lists the ${recurring.length} mention${recurring.length === 1 ? "" : "s"} more ` +
@@ -293,13 +390,21 @@ export function registerBrandWatch(server, makeClient) {
     server.registerTool("create_brand_watch", {
         title: "Create Brand Watch",
         description: "Run a sweep on a schedule and email the user what is new, instead of them remembering to " +
-            "ask. Two kinds, chosen with kind: kind: \"mentions\" (the default — omit kind entirely for " +
+            "ask. Four kinds, chosen with kind: kind: \"mentions\" (the default — omit kind entirely for " +
             "this one) runs a brand-mentions sweep for term across platforms; kind: \"competitor\" runs " +
             "a get_user_posts sweep for one creator (handle + platform) and reports only the posts that " +
             "beat that creator's own recent median — a raw view count would just measure follower size, " +
-            "so a run only mails what is unusually good for them. term/platforms belong to a mentions " +
-            "watch; handle/platform belong to a competitor watch — pass the pair that matches kind and " +
-            "leave the other pair out. Two calls by design, because this starts a charge that recurs " +
+            "so a run only mails what is unusually good for them; kind: \"report\" runs one tool on the " +
+            "schedule, given as job: {tool, args} — niche_report (the report is mailed as written every " +
+            "run) or discover_social_posts (only posts no earlier run mailed) — billed at that tool's " +
+            "own price; kind: \"portfolio\" sweeps several terms at once (a brand, its products and its " +
+            "competitors, up to 25) across the same platforms under one budget and mails one digest with " +
+            "each term's share of voice — the budget is split evenly across the terms and trims " +
+            "networks, never terms, and a term whose sweep fails is refunded. Add or remove a " +
+            "portfolio's terms later with update_watch_portfolio. term/platforms belong to a mentions " +
+            "watch; handle/platform belong to a competitor watch; job to a report; terms/platforms (and " +
+            "optionally term, as the portfolio's name) to a portfolio — pass what matches kind and " +
+            "leave the rest out. Two calls by design, because this starts a charge that recurs " +
             "while nobody is watching: call it once with no confirmation to get back the cost per run, " +
             "the cadence and what those multiply out to per day, put those numbers to the user in your " +
             "reply, and only then call it again with confirm: true and the confirmationToken you were " +
@@ -311,7 +416,9 @@ export function registerBrandWatch(server, makeClient) {
             "between them and a standing charge. Each run bills exactly what the same call costs when a " +
             "person asks for it themselves: for a mentions watch, 2 credits per network swept, 5 for " +
             "Xiaohongshu; for a competitor watch, a flat 2 credits (one get_user_posts call), whatever " +
-            "the platform. budgetCredits is a hard per-run ceiling enforced on the server, not a " +
+            "the platform; for a report, the job tool's own price (niche_report 3, discover_social_posts " +
+            "2, plus 1 per post opened for comments); for a portfolio, a mentions sweep per term. " +
+            "budgetCredits is a hard per-run ceiling enforced on the server, not a " +
             "suggestion — a mentions sweep that would cost more is trimmed to the networks that fit, " +
             "never widened. A run that turns up nothing new — or, for a competitor watch, nothing above " +
             "median — sends no mail. cadence is hourly, every_6_hours, every_12_hours, daily or weekly, " +
@@ -322,8 +429,8 @@ export function registerBrandWatch(server, makeClient) {
             kind: z
                 .enum(KINDS)
                 .optional()
-                .describe("\"mentions\" (default) or \"competitor\". Selects which of the two argument pairs " +
-                "below applies."),
+                .describe("\"mentions\" (default), \"competitor\", \"report\" or \"portfolio\". Selects which " +
+                "of the arguments below apply."),
             term: z
                 .string()
                 .optional()
@@ -346,6 +453,39 @@ export function registerBrandWatch(server, makeClient) {
                 .optional()
                 .describe("Required for kind: \"competitor\" — the single network that creator posts on, e.g. " +
                 "\"tiktok\". Not used for a mentions watch."),
+            job: z
+                .object({
+                tool: z
+                    .enum(SCHEDULABLE_JOBS)
+                    .describe("The tool to run on the schedule. Only these two can be scheduled."),
+                args: z
+                    .object({
+                    niche: z.string().describe("Niche or topic, e.g. \"home fitness\"."),
+                    platform: z.string().optional().describe("Platform to read (the tool's own default when omitted)."),
+                    count: z.number().int().optional().describe("niche_report only: posts to survey (default 20, max 40)."),
+                    keywords: z.string().optional().describe("discover_social_posts only: extra keywords."),
+                    limit: z.number().int().optional().describe("discover_social_posts only: max posts (default 6)."),
+                    includeComments: z
+                        .boolean()
+                        .optional()
+                        .describe("discover_social_posts only: also read comments — 1 extra credit per post opened, every run."),
+                    openPosts: z.number().int().optional().describe("discover_social_posts only: posts to open for comments (default 5, max 10)."),
+                    commentsPerPost: z.number().int().optional().describe("discover_social_posts only: comments per opened post."),
+                })
+                    .strict()
+                    .describe("The arguments the tool would take by hand. Pagination is not schedulable."),
+            })
+                .strict()
+                .optional()
+                .describe("Required for kind: \"report\" — the job each run performs. Not used for other kinds."),
+            terms: z
+                .array(z.string())
+                .min(1)
+                .max(MAX_PORTFOLIO_TERMS)
+                .optional()
+                .describe("Required for kind: \"portfolio\" — the terms to compare, e.g. your brand, your " +
+                "products and your competitors (1-25, duplicates ignored). Each is swept across " +
+                "platforms. Not used for other kinds; for a portfolio, term is its optional name."),
             cadence: z.enum(CADENCES).optional().describe("How often to run. Defaults to daily."),
             budgetCredits: z
                 .number()
@@ -494,6 +634,59 @@ export function registerBrandWatch(server, makeClient) {
             return failed("mention_trend failed", err);
         }
     });
+    server.registerTool("update_watch_portfolio", {
+        title: "Update Watch Portfolio",
+        description: "Add terms to a portfolio brand watch, or remove them, by watchId, with add and/or remove " +
+            "lists. No new confirmation: the per-run budget and cadence the user agreed to do not " +
+            "change, so a run still never costs more than that ceiling — but more terms split the same " +
+            "budget more ways, so the response says which networks a run will still search. If it " +
+            "names any in platformsSkipped, tell the user those networks are no longer searched and " +
+            "offer to remove a term or recreate the watch with a larger budget. A change the budget " +
+            "cannot cover at all is refused and nothing changes. No cost to call: no credits are spent.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z
+            .object({
+            watchId: z.string().describe("The portfolio watch's id, from list_brand_watches."),
+            add: z.array(z.string()).optional().describe("Terms to add (duplicates ignored)."),
+            remove: z
+                .array(z.string())
+                .optional()
+                .describe("Terms to take out, matched without regard to case."),
+        })
+            .strict(),
+        outputSchema: OUTPUT_SCHEMAS.update_watch_portfolio,
+    }, async (args, extra) => {
+        const client = await makeClient({ ...extra, arguments: args });
+        try {
+            const result = toResult(await client.callTool("update_watch_portfolio", args));
+            const sc = (result.structuredContent ?? {});
+            if (!sc.updated)
+                return result;
+            // Both channels (#44, #51): a host that renders structuredContent drops
+            // the text block, and one that shows only text never sees the payload —
+            // and a network the split budget stopped reaching is the one thing
+            // here the user has to be told.
+            const skipped = Array.isArray(sc.platformsSkipped) ? sc.platformsSkipped : [];
+            const terms = Array.isArray(sc.terms) ? sc.terms : [];
+            const guidance = `The portfolio now watches ${terms.length} term${terms.length === 1 ? "" : "s"}: ` +
+                `${terms.join(", ")}. A run costs ${sc.costPerRun ?? "?"} credits, within the ` +
+                `${sc.budgetPerRun ?? "?"}-credit ceiling already agreed, and searches ` +
+                `${(Array.isArray(sc.platformsSearched) ? sc.platformsSearched : []).join(", ") || "no network"}.` +
+                (skipped.length
+                    ? ` Split this many ways, the budget no longer reaches ${skipped.join(", ")} — tell the ` +
+                        "user those networks are not searched for any term now, and offer to remove a term " +
+                        "or recreate the watch with a larger budget if they matter."
+                    : "");
+            const payload = { guidance, ...sc };
+            return {
+                content: [{ type: "text", text: guidance }],
+                structuredContent: payload,
+            };
+        }
+        catch (err) {
+            return failed("update_watch_portfolio failed", err);
+        }
+    });
     server.registerTool("stop_brand_watch", {
         title: "Stop Brand Watch",
         description: "Stop a scheduled brand-monitoring watch, by watchId or by term. Takes effect immediately: " +

package/dist/shared/loading-plans.js

@@ -474,6 +474,7 @@ export const LOADING_PLANS = {
     create_brand_watch: { label: "Setting up the watch", kind: "text", n: 1, steps: [], free: true },
     list_brand_watches: { label: "Reading your watches", kind: "list", n: 3, steps: [], free: true },
     stop_brand_watch: { label: "Stopping the watch", kind: "text", n: 1, steps: [], free: true },
+    update_watch_portfolio: { label: "Updating the portfolio", kind: "text", n: 1, steps: [], free: true },
     // ─── Own-account reads: nooticr's own stored rows, never an upstream call ───
     list_own_apps: { label: "Reading your products", kind: "list", n: 3, steps: [], free: true },
     get_content_plan: { label: "Reading the saved plan", kind: "text", n: 1, steps: [], free: true },
@@ -495,6 +496,7 @@ export const LOADING_PLANS = {
     check_nooticr_credits: { label: "Checking your balance", kind: "text", n: 1, steps: [], free: true },
     list_tool_runs: { label: "Reading your run history", kind: "text", n: 1, steps: [], free: true },
     get_tool_run: { label: "Reading the run", kind: "text", n: 1, steps: [], free: true },
+    get_usage_report: { label: "Adding up the run ledger", kind: "text", n: 1, steps: [], free: true },
     nooticr_getting_started: { label: "Reading where your account stands", kind: "text", n: 1, steps: [], free: true },
     nooticr_login: { label: "Getting a sign-in link", kind: "text", n: 1, steps: [], free: true },
     watch_creator: { label: "Adding to your watchlist", kind: "text", n: 1, steps: [], free: true },

package/dist/shared/output-schemas.js

@@ -1135,6 +1135,23 @@ export const OUTPUT_SCHEMAS = {
             userId: scalar().describe("Whose run it was; only in the workspace scope."),
         }).nullish(),
     }),
+    get_usage_report: open({
+        report: scalar(),
+        scope: scalar().describe("mine or workspace."),
+        from: scalar(),
+        to: scalar(),
+        totals: open({
+            calls: scalar(),
+            failures: scalar(),
+            credits: scalar().describe("Credits actually taken: free first uses, refunds and replays are zero."),
+            tools: scalar(),
+            seats: scalar(),
+        }).nullish(),
+        byTool: listOf(open({ tool: scalar(), calls: scalar(), failures: scalar(), credits: scalar(), lastUsedAt: scalar() })),
+        bySeat: listOf(open({ userId: scalar(), email: scalar(), name: scalar(), calls: scalar(), failures: scalar(), credits: scalar() })).describe("Workspace reports only; empty on a personal one."),
+        byDay: listOf(open({ day: scalar(), calls: scalar(), failures: scalar(), credits: scalar() })),
+        recentFailures: listOf(open({ id: scalar(), tool: scalar(), error: scalar(), startedAt: scalar(), userId: scalar(), credits: scalar() })),
+    }),
     nooticr_login: open({
         signedIn: scalar().describe("true when the session is already good and no link is needed."),
         loginUrl: scalar().describe("Only present when a sign-in is actually required."),
@@ -1148,9 +1165,11 @@ export const OUTPUT_SCHEMAS = {
         confirmationToken: scalar().describe("Pass this back with confirm: true to actually create the watch."),
         expiresInSeconds: scalar(),
         quote: open({
-            kind: scalar().describe("\"mentions\" or \"competitor\"."),
-            term: scalar().describe("The search term (mentions) or the creator handle (competitor)."),
-            platforms: listOf(z.string()).describe("Networks swept (mentions), or the creator's single platform (competitor)."),
+            kind: scalar().describe("\"mentions\", \"competitor\", \"report\" or \"portfolio\"."),
+            term: scalar().describe("The search term (mentions), the creator handle (competitor), or the watch's name (report, portfolio)."),
+            platforms: listOf(z.string()).describe("Networks swept (mentions, portfolio), or the creator's single platform (competitor)."),
+            job: anyObject().nullish().describe("Report only: the {tool, args} each run performs, as it will run."),
+            terms: listOf(z.string()).describe("Portfolio only: the terms each run sweeps."),
             cadence: scalar(),
             cadenceMinutes: scalar(),
             costPerRun: scalar(),
@@ -1166,11 +1185,13 @@ export const OUTPUT_SCHEMAS = {
         rejected: scalar().describe("Set when confirm was true but the token didn't check out — nothing was created."),
         alreadyWatching: scalar().describe("Set when this term already has an enabled watch — creating another would double-charge."),
         watchId: scalar(),
-        kind: scalar().describe("\"mentions\" or \"competitor\"."),
+        kind: scalar().describe("\"mentions\", \"competitor\", \"report\" or \"portfolio\"."),
         term: scalar(),
         platforms: listOf(z.string()),
         competitorHandle: scalar().describe("Set only for a competitor watch."),
         competitorPlatform: scalar().describe("Set only for a competitor watch."),
+        job: anyObject().nullish().describe("Set only for a report watch."),
+        terms: listOf(z.string()).describe("Set only for a portfolio watch."),
         cadence: scalar(),
         costPerRun: scalar(),
         creditsPerDay: scalar(),
@@ -1202,6 +1223,7 @@ export const OUTPUT_SCHEMAS = {
             found: scalar().describe("Everything that sweep saw."),
             reported: scalar().describe("The subset that was new — a different question from found."),
             perPlatform: anyObject().nullish().describe('{"tiktok":{"found":12,"reported":3},...}'),
+            perTerm: anyObject().nullish().describe('Portfolio watches only: {"acme":{"found":9,"reported":2,"share":60},...}'),
             medianViews: scalar().describe("Competitor watches only: the baseline that run measured."),
             postsScored: scalar(),
             costCredits: scalar(),
@@ -1211,6 +1233,7 @@ export const OUTPUT_SCHEMAS = {
         term: scalar(),
         competitorHandle: scalar(),
         platforms: listOf(z.string()),
+        terms: listOf(z.string()).describe("Portfolio watches only."),
         windowDays: scalar(),
         // Two numbers a caller cannot derive and will otherwise assume: how long
         // anything is kept, and how long the watch has existed. A flat left edge
@@ -1233,11 +1256,13 @@ export const OUTPUT_SCHEMAS = {
     list_brand_watches: open({
         watches: listOf(open({
             watchId: scalar(),
-            kind: scalar().describe("\"mentions\" or \"competitor\"."),
+            kind: scalar().describe("\"mentions\", \"competitor\", \"report\" or \"portfolio\"."),
             term: scalar(),
             platforms: listOf(z.string()),
             competitorHandle: scalar().describe("Set only for a competitor watch."),
             competitorPlatform: scalar().describe("Set only for a competitor watch."),
+            job: anyObject().nullish().describe("Set only for a report watch: the {tool, args} each run performs."),
+            terms: listOf(z.string()).describe("Set only for a portfolio watch."),
             cadence: scalar(),
             costPerRun: scalar(),
             budgetPerRun: scalar(),
@@ -1253,6 +1278,20 @@ export const OUTPUT_SCHEMAS = {
         creditsPerDayAcrossAllWatches: scalar().describe("What every enabled watch together will cost per day if nothing changes."),
         cost: scalar(),
     }),
+    update_watch_portfolio: open({
+        guidance,
+        updated: scalar(),
+        watchId: scalar(),
+        term: scalar(),
+        terms: listOf(z.string()),
+        platformsSearched: listOf(z.string()).describe("What a run will search now, for every term."),
+        platformsSkipped: listOf(z.string()).describe("Networks the split budget no longer reaches — say so to the user."),
+        costPerRun: scalar(),
+        budgetPerRun: scalar(),
+        cadence: scalar(),
+        message: scalar(),
+        cost: scalar(),
+    }),
     stop_brand_watch: open({
         stopped: scalar(),
         alreadyStopped: scalar(),

package/dist/shared/tools-def.js

@@ -222,6 +222,12 @@ export const TOOL_DEFINITIONS = [
         description: "One run from list_tool_runs by its id, with its full error text, credentials scrubbed. A run outside your scope reads as not found. No cost to call. Use to look closely at one charge.",
         inputSchema: z.object({ id: z.number().int(), scope: z.enum(["mine", "workspace"]).optional() }).strict(),
     },
+    {
+        name: "get_usage_report",
+        title: "Get Usage Report",
+        description: "A usage report over a window: total calls, failures and credits actually taken, per tool, per day, and recent failures; scope workspace adds one row per seat, for owners and admins. No cost to call.",
+        inputSchema: z.object({ days: z.number().int().min(1).max(366).optional(), from: z.string().optional(), to: z.string().optional(), scope: z.enum(["mine", "workspace"]).optional() }).strict(),
+    },
     {
         name: "nooticr_login",
         title: "Nooticr Login",
@@ -255,8 +261,8 @@ export const TOOL_DEFINITIONS = [
     {
         name: "create_brand_watch",
         title: "Create Brand Watch",
-        description: "Run a sweep on a schedule and email what is new, instead of remembering to ask. kind: \"mentions\" (default) sweeps term across platforms; kind: \"competitor\" sweeps one creator's own posts (handle + platform) and reports only what beats their own recent median. Two calls by design: call it once with no confirmation to get back the cost per run and what it multiplies out to per day, then call it again with confirm: true and the confirmationToken to actually start it. The first call creates nothing and spends nothing. Bills 2 credits per network per run (5 for Xiaohongshu) for a mentions watch, or a flat 2 credits for a competitor watch, trimmed to fit budgetCredits. A run that finds nothing new (or, for a competitor watch, nothing above median) sends no mail. No cost to call.",
-        inputSchema: z.object({ kind: z.enum(["mentions", "competitor"]).optional().describe("\"mentions\" (default) or \"competitor\"."), term: z.string().optional().describe("kind: mentions only — what to watch for (max 120 chars)."), platforms: z.array(z.string()).optional().describe("kind: mentions only — networks to sweep (default: every searchable network)."), handle: z.string().optional().describe("kind: competitor only — the creator's handle."), platform: z.string().optional().describe("kind: competitor only — the platform that creator posts on."), cadence: z.enum(["hourly", "every_6_hours", "every_12_hours", "daily", "weekly"]).optional().describe("How often to run (default daily)."), budgetCredits: z.number().int().optional().describe("Hard per-run credit ceiling (default the full sweep's cost)."), deliverTo: z.string().optional().describe("Digest email (default the account's own)."), confirm: z.boolean().optional().describe("Set true only once the user has agreed to the quoted cost."), confirmationToken: z.string().optional().describe("The token the first call returned.") }).strict(),
+        description: "Run a sweep on a schedule and email what is new, instead of remembering to ask. kind: \"mentions\" (default) sweeps term across platforms; kind: \"competitor\" sweeps one creator's own posts (handle + platform) and reports only what beats their own recent median; kind: \"report\" runs job {tool, args} (niche_report or discover_social_posts) on the schedule at that tool's own price; kind: \"portfolio\" sweeps several terms across the same platforms under one budget and mails one digest with each term's share of voice. Two calls by design: call it once with no confirmation to get back the cost per run and what it multiplies out to per day, then call it again with confirm: true and the confirmationToken to actually start it. The first call creates nothing and spends nothing. Bills 2 credits per network per run (5 for Xiaohongshu) for a mentions watch, or a flat 2 credits for a competitor watch, trimmed to fit budgetCredits. A run that finds nothing new (or, for a competitor watch, nothing above median) sends no mail. No cost to call.",
+        inputSchema: z.object({ kind: z.enum(["mentions", "competitor", "report", "portfolio"]).optional().describe("\"mentions\" (default), \"competitor\", \"report\" or \"portfolio\"."), job: z.object({ tool: z.enum(["niche_report", "discover_social_posts"]), args: z.object({}).passthrough() }).optional().describe("kind: report only — the job each run performs."), terms: z.array(z.string()).optional().describe("kind: portfolio only — the terms to compare (1-25)."), term: z.string().optional().describe("kind: mentions only — what to watch for (max 120 chars)."), platforms: z.array(z.string()).optional().describe("kind: mentions only — networks to sweep (default: every searchable network)."), handle: z.string().optional().describe("kind: competitor only — the creator's handle."), platform: z.string().optional().describe("kind: competitor only — the platform that creator posts on."), cadence: z.enum(["hourly", "every_6_hours", "every_12_hours", "daily", "weekly"]).optional().describe("How often to run (default daily)."), budgetCredits: z.number().int().optional().describe("Hard per-run credit ceiling (default the full sweep's cost)."), deliverTo: z.string().optional().describe("Digest email (default the account's own)."), confirm: z.boolean().optional().describe("Set true only once the user has agreed to the quoted cost."), confirmationToken: z.string().optional().describe("The token the first call returned.") }).strict(),
     },
     {
         name: "list_brand_watches",
@@ -282,6 +288,12 @@ export const TOOL_DEFINITIONS = [
         description: "Stop a scheduled brand-monitoring watch, by watchId or by term. Takes effect immediately — the run that was due does not happen and nothing further is charged. Works even at a zero balance, since a user out of credits is exactly the user who needs to turn off what is spending them. No cost to call.",
         inputSchema: z.object({ watchId: z.string().optional().describe("The watch's id, from list_brand_watches."), term: z.string().optional().describe("Alternative to watchId — the term it was watching.") }).strict(),
     },
+    {
+        name: "update_watch_portfolio",
+        title: "Update Watch Portfolio",
+        description: "Add terms to a portfolio brand watch or remove them, by watchId. No new confirmation: the agreed per-run budget and cadence do not change, so a run never costs more credits than that ceiling — more terms split it more ways, and the response names any networks a run no longer reaches. A change the budget cannot cover is refused. No cost to call.",
+        inputSchema: z.object({ watchId: z.string().describe("The portfolio watch's id, from list_brand_watches."), add: z.array(z.string()).optional().describe("Terms to add."), remove: z.array(z.string()).optional().describe("Terms to take out.") }).strict(),
+    },
     {
         name: "list_own_apps",
         title: "List Own Apps",

package/dist/shared/tools.js

@@ -30,7 +30,7 @@ import { registerCollabTools } from "./collab.js";
 import { registerAmazonTools } from "./amazon.js";
 import { registerMarketplaceTools } from "./marketplace.js";
 /** Current MCP server version — bumped on every deploy for traceability. */
-export const MCP_SERVER_VERSION = "1.26.46";
+export const MCP_SERVER_VERSION = "1.26.48";
 /** MCP Apps extension identifier */
 const UI_EXTENSION = "io.modelcontextprotocol/ui";
 /** MIME type for MCP Apps HTML resources */
@@ -604,6 +604,7 @@ export function createMcpServer(rawMakeClient, opts) {
         "check_nooticr_credits",
         "list_tool_runs",
         "get_tool_run",
+        "get_usage_report",
         "list_watchlist",
         "nooticr_getting_started",
         "understand_social_post",
@@ -2610,6 +2611,43 @@ export function createMcpServer(rawMakeClient, opts) {
             return toolError("get_tool_run failed", err);
         }
     });
+    // The run ledger added up (#93): the question an owner or a security review
+    // asks ("what did the team run this month, what did it cost, what failed")
+    // answered from the same rows as the history, never from memory.
+    server.registerTool("get_usage_report", {
+        title: "Get Usage Report",
+        description: "A usage report over a window: total calls, failures and credits actually taken; one row " +
+            "per tool, most expensive first; one row per day, quiet days included; and the ten most " +
+            "recent failures with their errors, credentials scrubbed. scope: \"workspace\" covers " +
+            "every member of your workspace and adds one row per seat; it is for the workspace's " +
+            "owners and admins. Reads the stored run ledger, so it is free and says what happened, " +
+            "not what is running. No cost to call. Use for \"what did we spend this month and on " +
+            "what\" or an audit of what nooticr did on the workspace's behalf; list_tool_runs is the " +
+            "call-by-call view.",
+        _meta: {
+            ui: { resourceUri: uiResource("get_usage_report") },
+            "ui/resourceUri": uiResource("get_usage_report"),
+            "openai/outputTemplate": appsSdkResource("get_usage_report"),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        outputSchema: OUTPUT_SCHEMAS.get_usage_report,
+        inputSchema: z
+            .object({
+            days: z.number().int().min(1).max(366).optional().describe("The window, in days back from now (default 30)."),
+            from: z.string().optional().describe("Start of the window, ISO date or timestamp. Overrides days."),
+            to: z.string().optional().describe("End of the window, ISO date or timestamp (default now)."),
+            scope: runFilters.scope,
+        })
+            .strict(),
+    }, async (args, extra) => {
+        const client = await makeClient({ ...extra, arguments: args });
+        try {
+            return await toToolResult(await client.callTool("get_usage_report", { ...args }));
+        }
+        catch (err) {
+            return toolError("get_usage_report failed", err);
+        }
+    });
     server.registerTool("nooticr_login", {
         title: "Nooticr Login",
         description: "Get a fresh login URL to re-authenticate your MCP session. Call this tool when you need to reconnect or when the session has expired. No cost to call." +

package/dist/shared/ui-template.js

@@ -45,6 +45,7 @@ export const NOOTICR_UI_TEMPLATE = `<!DOCTYPE html>
     check_nooticr_credits:"Check Credits",
     list_tool_runs:"Tool Runs",
     get_tool_run:"Tool Run",
+    get_usage_report:"Usage Report",
     list_watchlist:"Watchlist",
     detect_spoken_mentions:"Spoken Mentions",
     nooticr_getting_started:"Getting Started",
@@ -84,6 +85,7 @@ export const NOOTICR_UI_TEMPLATE = `<!DOCTYPE html>
     check_nooticr_credits:"View your Nooticr credit balance and usage.",
     list_tool_runs:"Where your credits went: every call, what it cost, and whether it worked.",
     get_tool_run:"One call from your history, with its full error.",
+    get_usage_report:"What was spent, on what, by whom, and what failed.",
     list_watchlist:"The creators you are watching, and when you last caught up on each.",
     detect_spoken_mentions:"Brands named out loud in a video, beside what its caption says.",
     nooticr_getting_started:"Where your account stands and what to try first.",
@@ -3152,6 +3154,48 @@ export const NOOTICR_UI_TEMPLATE = `<!DOCTYPE html>
     return '<div class="fade-in">'+head+body+"</div>";
   }
 
+  // ─── Usage report (get_usage_report) ───
+  //
+  // A spend table: the totals first, then where it went. Credits are what was
+  // actually taken, so a free first use or a refund reads as 0, not as the
+  // tool's price.
+  function renderUsageReport(d){
+    var t=d.totals||{};
+    function tile(label,val){
+      return '<div style="flex:1;min-width:110px;padding:10px 12px;border:1px solid var(--border);border-radius:10px">'
+        +'<div style="font-size:11px;color:var(--muted);text-transform:uppercase;letter-spacing:.05em">'+esc(label)+"</div>"
+        +'<div style="font-size:18px;font-weight:700;margin-top:3px">'+esc(String(val==null?"—":val))+"</div></div>";
+    }
+    function table(title,cols,rows){
+      if(!rows.length)return "";
+      return '<div class="sec-label" style="margin-top:14px">'+esc(title)+"</div>"
+        +'<table style="width:100%;border-collapse:collapse;font-size:13px">'
+        +"<tr>"+cols.map(function(c,i){return '<th style="text-align:'+(i?"right":"left")+';font-weight:600;color:var(--muted);padding:4px 0">'+esc(c)+"</th>";}).join("")+"</tr>"
+        +rows.map(function(r){return '<tr data-usage-row style="border-top:1px solid var(--border)">'+r.map(function(v,i){return '<td style="padding:6px 0;text-align:'+(i?"right":"left")+'">'+esc(String(v))+"</td>";}).join("")+"</tr>";}).join("")
+        +"</table>";
+    }
+    var from=String(d.from||"").slice(0,10),to=String(d.to||"").slice(0,10);
+    var days=(d.byDay||[]),max=1;
+    days.forEach(function(x){max=Math.max(max,Number(x.credits)||0);});
+    var bars=days.length?'<div class="sec-label" style="margin-top:14px">Credits per day</div><div style="display:flex;align-items:flex-end;gap:2px;height:48px">'
+      +days.map(function(x){var c=Number(x.credits)||0;return '<span title="'+esc(String(x.day))+": "+c+' cr" style="flex:1;min-width:2px;background:var(--fg);opacity:'+(c?".6":".12")+';height:'+Math.max(2,Math.round(c/max*46))+'px"></span>';}).join("")+"</div>":"";
+    var fails=(d.recentFailures||[]).map(function(f){
+      return '<div style="padding:6px 0;border-top:1px solid var(--border);font-size:12.5px"><b>'+esc(f.tool||"")+"</b> "
+        +'<span style="color:var(--muted)">'+esc(String(f.startedAt||"").slice(0,16).split("T").join(" "))+"</span>"
+        +(f.error?'<div style="color:var(--muted);word-break:break-word">'+esc(f.error)+"</div>":"")+"</div>";
+    }).join("");
+    return '<div class="fade-in">'
+      +'<div style="font-size:15px;font-weight:700">'+(d.scope==="workspace"?"Workspace usage":"Your usage")+"</div>"
+      +'<div style="font-size:12px;color:var(--muted);margin:2px 0 12px">'+esc(from)+" → "+esc(to)+"</div>"
+      +'<div style="display:flex;gap:8px;flex-wrap:wrap">'+tile("Credits",t.credits)+tile("Calls",t.calls)+tile("Failures",t.failures)
+      +(d.scope==="workspace"?tile("Seats",t.seats):"")+"</div>"
+      +table("By tool",["Tool","Calls","Failed","Credits"],(d.byTool||[]).map(function(r){return [r.tool,r.calls,r.failures,r.credits];}))
+      +table("By seat",["Member","Calls","Failed","Credits"],(d.bySeat||[]).map(function(r){return [r.name||r.email||String(r.userId||"").slice(0,8),r.calls,r.failures,r.credits];}))
+      +bars
+      +(fails?'<div class="sec-label" style="margin-top:14px">Recent failures</div>'+fails:"")
+      +"</div>";
+  }
+
   // ─── Vetting strip ───
   //
   // Only show_collab_shortlist sends these fields, so every other creator card
@@ -4850,6 +4894,7 @@ export const NOOTICR_UI_TEMPLATE = `<!DOCTYPE html>
     // Credits
     if(d.gettingStarted===true){app.innerHTML=renderGettingStarted(d);setTimeout(reportSize,50);return;}
     if(d.connector==="google_analytics"||d.connector==="search_console"||d.connector==="posthog"){app.innerHTML=renderConnector(d);setTimeout(reportSize,50);return;}
+    if(d.report===true&&d.totals){app.innerHTML=renderUsageReport(d);setTimeout(reportSize,50);return;}
     if(d.balance!=null||d.tier){
       var bal=Number(d.balance)||0,tier=d.tier||"",ff=d.firstFreeTools||[];
       var freeHtml="";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nooticr/mcp",
   "mcpName": "com.nooticr/mcp",
-  "version": "1.26.46",
+  "version": "1.26.48",
   "description": "MCP server for nooticr - fetch, discover and understand TikTok/Instagram/YouTube/X/Reddit/LinkedIn/Weibo posts with AI (media metadata, niche discovery, brand monitoring, hook & viral analysis)",
   "homepage": "https://mcp.nooticr.com",
   "repository": {