@nooticr/mcp 1.26.40 → 1.26.42

package/dist/index.js

@@ -5,7 +5,8 @@
  *
  * Modes:
  *   nooticr-mcp            stdio transport (default; Claude Desktop, Cursor)
- *   nooticr-mcp login      browser-based Google sign-in to nooticr
+ *   nooticr-mcp login      browser-based Google sign-in (or --api-key, no browser)
+ *   nooticr-mcp api-key    mint/list/revoke a key for a server with no browser
  *   nooticr-mcp --http     remote HTTP transport with OAuth (OpenAI Agents SDK)
  */
 import http from "node:http";
@@ -13,7 +14,8 @@ import { randomUUID } from "node:crypto";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { getBaseUrl, getPublicUrl, getPort, getCredentialsFile, getTransportMode, DEFAULT_PORT, } from "./config.js";
-import { AuthManager, NooticrAuthError, createHttpTokenProvider, createStdioTokenProvider } from "./auth.js";
+import { AuthManager, NooticrAuthError, createApiKeyTokenProvider, createHttpTokenProvider, createManagementTokenProvider, createStdioTokenProvider, } from "./auth.js";
+import { looksLikeApiKey } from "./shared/api-key.js";
 import { NooticrClient, NooticrError } from "./nooticr.js";
 import { OAuthManager, SCOPES } from "./oauth.js";
 import { createMcpServer } from "./shared/tools.js";
@@ -78,12 +80,21 @@ function bearerToken(req) {
 }
 /**
  * A request bearer token is valid when it was issued by our OAuth `/token`
- * endpoint, or when it matches `NOOTICR_ACCESS_TOKEN` (pre-provisioned
- * deployments and local testing — no browser OAuth round-trip needed).
+ * endpoint, when it is a nooticr API key, or when it matches
+ * `NOOTICR_ACCESS_TOKEN` (pre-provisioned deployments and local testing — no
+ * browser OAuth round-trip needed).
+ *
+ * A key is accepted on its shape alone because this process does not hold the
+ * secret to check it against — only nooticr-server does, and it checks every
+ * call. What that admits without a round trip is `initialize` and
+ * `tools/list`, both of which answer the same for everyone; the first call
+ * that touches an account gets the backend's own 401.
  */
 function validMcpToken(token, oauth) {
     if (oauth.verifyToken(token))
         return true;
+    if (looksLikeApiKey(token))
+        return true;
     const envToken = process.env.NOOTICR_ACCESS_TOKEN;
     return typeof envToken === "string" && envToken.length > 0 && token === envToken;
 }
@@ -93,8 +104,10 @@ async function handleMcpRequest(state, req, res) {
     if (!token || !validMcpToken(token, state.oauth)) {
         return sendJson(res, 401, {
             error: "Unauthorized",
-            error_description: "This MCP server requires OAuth authentication. Fetch an access token from " +
-                `${state.oauth.authorizationServerMetadata().authorization_endpoint} first.`,
+            error_description: "This MCP server requires authentication. Fetch an access token from " +
+                `${state.oauth.authorizationServerMetadata().authorization_endpoint}, or — on a ` +
+                "server with no browser — send a nooticr API key as the bearer token " +
+                "(npx @nooticr/mcp api-key create).",
         });
     }
     // Hand the validated token to the SDK transport, which forwards it to tool
@@ -221,8 +234,16 @@ export async function runHttp(port, publicUrl) {
         transports: new Map(),
         connections: new Map(),
         serverFactory: () => createMcpServer((extra) => {
-            const session = extra.authInfo?.token
-                ? oauth.verifyToken(extra.authInfo.token)
+            const bearer = extra.authInfo?.token;
+            // A caller who presented their own API key is answered as themselves.
+            // Falling through to `createHttpTokenProvider` here would resolve the
+            // *operator's* environment or credentials file instead — one tenant's
+            // request served from another's account.
+            if (looksLikeApiKey(bearer)) {
+                return new NooticrClient(baseUrl, createApiKeyTokenProvider(bearer));
+            }
+            const session = bearer
+                ? oauth.verifyToken(bearer)
                 : undefined;
             return new NooticrClient(baseUrl, createHttpTokenProvider(auth, session
                 ? {
@@ -253,6 +274,27 @@ export async function runLogin(opts) {
     const client = new NooticrClient(baseUrl, {
         getAccessToken: async () => undefined,
     });
+    if (opts.apiKey) {
+        // Check the key before writing it. This is the one moment a person is
+        // present to fix a typo — an unchecked key would instead surface as a
+        // failed tool call later, from a client that cannot explain itself.
+        const keyed = new NooticrClient(baseUrl, createApiKeyTokenProvider(opts.apiKey));
+        let user;
+        try {
+            user = await keyed.me();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new NooticrAuthError(`That API key was rejected by ${baseUrl}: ${msg}\n` +
+                "`npx nooticr-mcp api-key list` (signed in) shows which keys are still active.");
+        }
+        await auth.persistApiKey(opts.apiKey, user);
+        process.stdout.write(`Signed in as ${user?.email ?? "unknown user"} with an API key. ` +
+            `Saved to ${auth.getCredentialsFile()}\n` +
+            "The key does not expire, so there is nothing to refresh and no browser to open again.\n" +
+            "On a server, prefer NOOTICR_API_KEY over this file — see the README.\n");
+        return;
+    }
     if (opts.email && opts.password) {
         const session = await client.login(opts.email, opts.password);
         await auth.persistSession(session);
@@ -315,6 +357,98 @@ export async function runLogin(opts) {
         process.exit(1);
     }, 300_000).unref();
 }
+function formatDate(value) {
+    if (!value)
+        return "never";
+    const at = new Date(value);
+    return Number.isNaN(at.getTime()) ? value : at.toISOString().slice(0, 10);
+}
+function describeKey(key) {
+    const state = key.revokedAt
+        ? "revoked"
+        : key.expiresAt && new Date(key.expiresAt).getTime() <= Date.now()
+            ? "expired"
+            : "active";
+    return [
+        `${key.prefix}\u2026  ${key.name}`,
+        `  id         ${key.id}`,
+        `  state      ${state}`,
+        `  created    ${formatDate(key.createdAt)}`,
+        `  last used  ${formatDate(key.lastUsedAt)}`,
+        `  expires    ${formatDate(key.expiresAt)}`,
+    ].join("\n");
+}
+/**
+ * Mints, lists and revokes the keys a headless deployment authenticates with.
+ *
+ * Creating one needs an interactive session exactly once — that is the step it
+ * removes from every run afterwards — so these commands deliberately refuse to
+ * authenticate with `NOOTICR_API_KEY` even when one is set. The backend
+ * refuses key management to a key-authenticated caller anyway; resolving one
+ * here would only turn that bound into a 403 that reads like a bug.
+ */
+export async function runApiKey(opts) {
+    const baseUrl = getBaseUrl();
+    const auth = new AuthManager(baseUrl, getCredentialsFile());
+    const token = await auth.getAccessToken(undefined, { allowApiKey: false });
+    if (!token) {
+        // Telling these two apart matters: "sign in first" is wrong advice for
+        // someone who *is* signed in, with a key, and is being refused for a
+        // reason the message otherwise never mentions.
+        const hasKey = Boolean(await auth.getAccessToken());
+        throw new NooticrAuthError(hasKey
+            ? "You are signed in with an API key, and a key cannot manage keys — that bound is " +
+                "what stops a leaked key minting a replacement that outlives revoking the original. " +
+                "Sign in as yourself for this one: `npx nooticr-mcp login` " +
+                "(or `login --email ... --password ...`)."
+            : "Sign in first: `npx nooticr-mcp login` (or `login --email ... --password ...`). " +
+                "Minting a key is the one step that needs a browser, and it is the last one: " +
+                "the key it returns is what every run afterwards uses.");
+    }
+    const client = new NooticrClient(baseUrl, createManagementTokenProvider(auth));
+    if (opts.action === "create") {
+        const created = await client.createApiKey({
+            ...(opts.name !== undefined ? { name: opts.name } : {}),
+            ...(opts.workspaceId !== undefined ? { workspaceId: opts.workspaceId } : {}),
+            ...(opts.expiresInDays !== undefined ? { expiresInDays: opts.expiresInDays } : {}),
+        });
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(created, null, 2)}\n`);
+            return;
+        }
+        process.stdout.write(`Created API key "${created.name}" (${created.id}).\n\n` +
+            `  ${created.key}\n\n` +
+            "This is the only time the key is shown — nooticr stores a hash of it and\n" +
+            "cannot show it again. Store it wherever this deployment keeps its secrets,\n" +
+            "then give it to the server:\n\n" +
+            "  NOOTICR_API_KEY=<key> npx nooticr-mcp\n\n" +
+            "or, against the remote HTTP endpoint, as the bearer token:\n\n" +
+            "  Authorization: Bearer <key>\n");
+        return;
+    }
+    if (opts.action === "list") {
+        const keys = await client.listApiKeys();
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(keys, null, 2)}\n`);
+            return;
+        }
+        if (keys.length === 0) {
+            process.stdout.write("No API keys. Create one with `npx nooticr-mcp api-key create --name <name>`.\n");
+            return;
+        }
+        process.stdout.write(`${keys.map(describeKey).join("\n\n")}\n`);
+        return;
+    }
+    if (!opts.id) {
+        throw new NooticrError(400, "Usage: nooticr-mcp api-key revoke <id>");
+    }
+    await client.revokeApiKey(opts.id);
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({ id: opts.id, revoked: true }, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`Revoked ${opts.id}. Any server still presenting it now gets a 401.\n`);
+}
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
@@ -328,11 +462,18 @@ Usage:
                                 (default port ${DEFAULT_PORT}; also NOOTICR_PORT)
   nooticr-mcp login              Sign in to nooticr via Google in your browser
   nooticr-mcp login --email me@example.com --password '...'   Password login
+  nooticr-mcp login --api-key nk_...  Sign in with an API key (no browser)
+  nooticr-mcp api-key create [--name N] [--expires-in-days D] [--workspace-id W] [--json]
+                                Mint a key for a server with no browser
+  nooticr-mcp api-key list [--json]        List this account's keys
+  nooticr-mcp api-key revoke <id> [--json] Revoke one
   nooticr-mcp --help             Show this help
 
 Environment variables:
   NOOTICR_BASE_URL          nooticr server base URL (default http://localhost:8080)
   NOOTICR_ACCESS_TOKEN      nooticr JWT access token (bypasses login)
+  NOOTICR_API_KEY           nooticr API key from "api-key create" — no browser,
+                            no refresh, valid until revoked
   NOOTICR_CREDENTIALS_FILE  token store path (default ~/.config/nooticr-mcp/credentials.json)
   NOOTICR_PUBLIC_URL        public base URL for the HTTP mode (default http://localhost:3457)
   NOOTICR_PORT              port for --http and login (default ${DEFAULT_PORT})
@@ -343,6 +484,11 @@ Client setup:
     "command": "npx", "args": ["nooticr-mcp"]  (plus NOOTICR_ACCESS_TOKEN if needed)
   OpenAI Agents SDK (remote HTTP): use the RemoteMCPClient with URL
     <NOOTICR_PUBLIC_URL>/mcp — the OAuth flow will open your browser.
+  Server-side, no browser: mint a key once with "api-key create", then either
+    set NOOTICR_API_KEY for the stdio server, or send it to the remote endpoint
+    as "Authorization: Bearer <key>" and skip the OAuth flow entirely.
+  A client that does not inherit your shell environment: "login --api-key nk_..."
+    stores the same key in the credentials file instead.
 
 See README.md for full instructions.
 `);
@@ -361,6 +507,17 @@ async function main() {
         };
         const email = valueOf("--email");
         const password = valueOf("--password");
+        // Every other flag here is kebab-case; `--api_key` is the near-miss worth
+        // naming rather than ignoring, since ignoring it opens a browser instead.
+        if (rest.includes("--api_key")) {
+            process.stderr.write("Unknown flag --api_key. Did you mean --api-key?\n");
+            process.exit(1);
+        }
+        const apiKey = valueOf("--api-key");
+        if (rest.includes("--api-key") && !apiKey) {
+            process.stderr.write("--api-key needs a value (the nk_… key from `api-key create`).\n");
+            process.exit(1);
+        }
         let port = getPort();
         const portRaw = valueOf("--port");
         if (portRaw !== undefined)
@@ -373,8 +530,12 @@ async function main() {
             process.stderr.write("Both --email and --password must be provided together.\n");
             process.exit(1);
         }
+        if (apiKey && (email || password)) {
+            process.stderr.write("Use --api-key or --email/--password, not both.\n");
+            process.exit(1);
+        }
         try {
-            await runLogin({ email, password, port });
+            await runLogin({ email, password, apiKey, port });
         }
         catch (err) {
             process.stderr.write(`Login failed: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -382,6 +543,55 @@ async function main() {
         }
         return;
     }
+    if (args[0] === "api-key" || args[0] === "api-keys") {
+        const rest = args.slice(1);
+        const action = rest[0];
+        if (action !== "create" && action !== "list" && action !== "revoke") {
+            process.stderr.write("Usage: nooticr-mcp api-key <create|list|revoke> [options]\n" +
+                "       nooticr-mcp api-key create [--name N] [--expires-in-days D] [--workspace-id W]\n" +
+                "       nooticr-mcp api-key revoke <id>\n");
+            process.exit(1);
+        }
+        const flags = rest.slice(1);
+        const valueOf = (flag) => {
+            const idx = flags.indexOf(flag);
+            return idx >= 0 && flags[idx + 1] ? flags[idx + 1] : undefined;
+        };
+        const opts = { action, json: flags.includes("--json") };
+        const name = valueOf("--name");
+        if (name !== undefined)
+            opts.name = name;
+        const workspaceId = valueOf("--workspace-id");
+        if (workspaceId !== undefined)
+            opts.workspaceId = workspaceId;
+        const expiresRaw = valueOf("--expires-in-days");
+        if (expiresRaw !== undefined) {
+            const days = Number.parseInt(expiresRaw, 10);
+            if (!Number.isInteger(days) || days < 1) {
+                process.stderr.write("--expires-in-days must be a positive whole number of days.\n");
+                process.exit(1);
+            }
+            opts.expiresInDays = days;
+        }
+        if (action === "revoke") {
+            // The id is positional, so anything that starts with "-" is a flag the
+            // user meant for something else, not the key they want gone.
+            const id = flags.find((arg) => !arg.startsWith("-"));
+            if (!id) {
+                process.stderr.write("Usage: nooticr-mcp api-key revoke <id>\n");
+                process.exit(1);
+            }
+            opts.id = id;
+        }
+        try {
+            await runApiKey(opts);
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        return;
+    }
     const isHttp = args.includes("--http") || getTransportMode() === "http";
     let port = getPort();
     if (args.includes("--port")) {

package/dist/shared/amazon.js

@@ -192,7 +192,7 @@ export function categoryGuidance(opts) {
     lines.push("Judge only from what the reviews say. Where the evidence is thin, say so rather than", "producing a confident line the text does not support — a category read that overstates its", "basis is worse than a short one. Prices, ratings and mention counts are in the payload;", "do not re-derive them by hand.");
     if (insightsTool) {
         lines.push("");
-        lines.push("To show the result in the conversation — products, their reviews, and your read side by", `side — call ${insightsTool} with what you concluded. It costs nothing and`, "makes no further requests.");
+        lines.push("To show the result in the conversation — products, their reviews, and your read side by", `side — call ${insightsTool} with what you concluded${opts.scanId ? ` and scanId "${opts.scanId}"` : " and the scanId"}.`, "It costs nothing, and it re-reads the listings from the scan itself, so do not re-send them.");
     }
     return lines.join("\n");
 }
@@ -390,14 +390,19 @@ export function registerAmazonTools(server, makeClient) {
         description: "Display the category read you produced from scan_amazon_category: purchase drivers, " +
             "barriers, what each brand does well, the gaps, and the positioning angles — drawn beside " +
             "the listings and their reviews, so a person can click a product and check any claim " +
-            "against the text it came from. Free, and makes no requests: it only draws what you pass " +
-            "it, attributed to you rather than presented as a nooticr rating of anyone's product. " +
+            "against the text it came from. Pass the scanId: the listings are then re-read from the " +
+            "scan itself (free) rather than taken from you, so do not re-send them, and any ASIN you " +
+            "cite that the scan does not contain is flagged on the card. Without a scanId, listings " +
+            "you pass are drawn marked as not checked against a scan. Free. Your read is attributed " +
+            "to you rather than presented as a nooticr rating of anyone's product. " +
             "Call this after you have read the reviews, not instead of reading them.",
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
-            // Draws what it is given; reaches nothing.
+            // Draws what it is given. Its one request re-reads a scan the caller
+            // already ran, from nooticr's own job store with no wait, so it
+            // fetches nothing new from the marketplace (#107).
             openWorldHint: false,
         },
         outputSchema: OUTPUT_SCHEMAS.show_amazon_category_insights,
@@ -457,15 +462,17 @@ export function registerAmazonTools(server, makeClient) {
             products: z
                 .array(anyObject())
                 .optional()
-                .describe("The listings from the scan, passed straight through so the view can draw them."),
-            rollup: anyObject().optional().describe("The rollup from the scan, passed straight through."),
-            scanId: z.string().optional().describe("The scan this reads, for the record."),
+                .describe("Only when there is no scanId. With one, the listings are re-read from the scan and anything here is ignored."),
+            rollup: anyObject().optional().describe("Only when there is no scanId; re-read from the scan otherwise."),
+            scanId: z
+                .string()
+                .optional()
+                .describe("The scan this reads. Pass it: it is what lets the card draw the collector's own listings."),
         })
             .passthrough(),
-    }, async (args) => {
-        const products = Array.isArray(args.products)
-            ? args.products
-            : [];
+    }, async (args, extra) => {
+        const checked = await rehydrate(args, () => makeClient({ ...extra, arguments: args }));
+        const products = checked.products;
         const counts = {
             drivers: Array.isArray(args.drivers) ? args.drivers.length : 0,
             barriers: Array.isArray(args.barriers) ? args.barriers.length : 0,
@@ -475,7 +482,8 @@ export function registerAmazonTools(server, makeClient) {
         const text = `Category read for ${String(args.category ?? "this category")}: ${counts.drivers} driver(s), ` +
             `${counts.barriers} barrier(s), ${counts.gaps} gap(s), ${counts.positioning} positioning angle(s)` +
             `${products.length ? `, drawn beside ${products.length} listing(s)` : ""}.` +
-            (args.summary ? ` ${String(args.summary)}` : "");
+            (args.summary ? ` ${String(args.summary)}` : "") +
+            ` ${checked.verification.note}`;
         return {
             content: [{ type: "text", text }],
             structuredContent: {
@@ -489,14 +497,77 @@ export function registerAmazonTools(server, makeClient) {
                 gaps: args.gaps ?? [],
                 positioning: args.positioning ?? [],
                 products,
-                rollup: args.rollup ?? {},
+                rollup: checked.rollup,
                 scanId: args.scanId ?? null,
-                // Nothing was fetched, so nothing was charged.
+                verification: checked.verification,
+                // The one read is amazon_scan_status, which is free by design.
                 mcpCredits: { cost: 0 },
             },
         };
     });
 }
+/**
+ * The listings a category read is drawn beside, from the scan rather than
+ * from the model (#107).
+ *
+ * The card exists so a person can check a claim against the text it came
+ * from, which only works if the text is the collector's. A model that dropped
+ * three listings, mis-copied a price or invented a competitor used to produce
+ * a card identical to a truthful one. With a scanId the listings are re-read
+ * from the scan, free and with no wait, and whatever the model sent is only
+ * compared against them. Without one, or when the re-read fails, what the
+ * model sent is drawn and marked unverified rather than refused: a card with a
+ * visible caveat is more use to a person than no card.
+ */
+export async function rehydrate(args, client) {
+    const sent = Array.isArray(args.products) ? args.products : [];
+    const sentRollup = (args.rollup ?? {});
+    const scanId = typeof args.scanId === "string" ? args.scanId.trim() : "";
+    const unverified = (note) => ({
+        products: sent,
+        rollup: sentRollup,
+        verification: { status: "unverified", note },
+    });
+    if (!scanId) {
+        return unverified(sent.length
+            ? "No scanId was passed, so these listings are as re-sent and were not checked against a scan."
+            : "No scanId was passed, so there are no listings to draw beside this read.");
+    }
+    let payload;
+    try {
+        const res = await (await client()).callTool("amazon_scan_status", { scanId, waitSeconds: 0 });
+        payload = structured(res);
+    }
+    catch (err) {
+        const why = err instanceof Error ? err.message : String(err);
+        return unverified(`Scan ${scanId} could not be re-read (${why}), so these listings are as re-sent and were not checked.`);
+    }
+    const products = normaliseProducts(payload.products);
+    const ids = new Set(products.map((p) => String(p.asin ?? "")).filter(Boolean));
+    const idOf = (p) => String([p.asin, p.sku, p.pid, p.goods_id, p.item_id, p.product_id, p.id].find((v) => typeof v === "string" && v) ?? "");
+    const notInScan = [...new Set(sent.map(idOf).filter((id) => id && !ids.has(id)))];
+    const cited = Array.isArray(args.strengths)
+        ? args.strengths.map((s) => String(s.asin ?? "")).filter(Boolean)
+        : [];
+    const unknownAsins = [...new Set(cited.filter((a) => !ids.has(a)))];
+    const scanComplete = payload.complete !== false;
+    const flags = [
+        notInScan.length ? `${notInScan.length} listing(s) you sent are not in the scan (${notInScan.join(", ")}) and are not drawn.` : "",
+        unknownAsins.length ? `ASIN(s) cited in strengths but not in the scan: ${unknownAsins.join(", ")}.` : "",
+        scanComplete ? "" : "The scan is still running, so the set drawn is what it had collected so far.",
+    ].filter(Boolean);
+    return {
+        products,
+        rollup: (payload.rollup ?? {}),
+        verification: {
+            status: "verified",
+            note: [`The ${products.length} listing(s) drawn are the scan's own, re-read from ${scanId}.`, ...flags].join(" "),
+            scanComplete,
+            notInScan,
+            unknownAsins,
+        },
+    };
+}
 /**
  * One scan result, shaped for both channels.
  *

package/dist/shared/api-key.js

@@ -0,0 +1,20 @@
+/**
+ * nooticr API keys — the credential for a caller with no browser.
+ *
+ * Everything else this package can authenticate with ends at a 15-minute JWT:
+ * `login` writes one (plus a refresh token) to a credentials file, and the
+ * OAuth flows mint one behind a consent screen. Both assume a machine someone
+ * can sit at once. A partner's backend cannot run either, so it gets a key
+ * instead: one string, set once, valid until it is revoked.
+ *
+ * The prefix is load-bearing in two places that must agree — this file and
+ * nooticr-server's `routes::api_keys::API_KEY_PREFIX`. The server uses it to
+ * decide whether a bearer token is a key at all (and therefore whether to look
+ * in its database); this package uses it to decide whether a token can be
+ * refreshed. A JWT is three base64url segments, so it can never collide.
+ */
+export const API_KEY_PREFIX = "nk_";
+/** Whether a bearer token is a nooticr API key rather than a JWT. */
+export function looksLikeApiKey(token) {
+    return typeof token === "string" && token.startsWith(API_KEY_PREFIX);
+}

package/dist/shared/backend-only.js

@@ -0,0 +1,27 @@
+/**
+ * nooticr-server tools this public surface deliberately does not register.
+ *
+ * `POST /mcp` also serves the dashboard's internal copilot, so it carries
+ * tools that have no business in a Claude or ChatGPT host. Absence alone
+ * reads the same as "nobody got round to it", so each exclusion is written
+ * down with its reason (#106). A tool leaving this list for `TOOL_NAMES` is a
+ * product decision, not a cleanup; tests/backend-only.test.ts keeps the two
+ * lists disjoint.
+ */
+export const BACKEND_ONLY_TOOLS = {
+    get_watchlist_baseline: "Plumbing for BackendWatchStore, which reads a creator's baseline itself; a host has nothing to do with the raw row.",
+    advance_watchlist_baseline: "Plumbing for BackendWatchStore; catch_up_watchlist advances the baseline after the user confirms, so a host never needs to.",
+    buy_nooticr_credits: "No purchase path is exposed to a model (#100). Credits are topped up on the nooticr website.",
+    overlay_bake: "Rendering and publishing stay in the dashboard (#92).",
+    bake_job_status: "Rendering and publishing stay in the dashboard (#92).",
+    compose_sequence: "Rendering and publishing stay in the dashboard (#92).",
+    spawn_variants: "Rendering and publishing stay in the dashboard (#92).",
+    enqueue_publish_job: "Rendering and publishing stay in the dashboard (#92).",
+    schedule_post: "Rendering and publishing stay in the dashboard (#92).",
+    get_batch_history: "History of the dashboard's compose batches, which only exist once rendering does; stays with #92.",
+    get_latest_analysis: "Returns the dashboard's stored AI fleet-analysis verdict; the public surface sells the evidence, not a judgement of ours.",
+    brand_watch_history: "Not a deliberate exclusion: a candidate for the public surface once it has a trend view to draw. Listed so it reads as pending, not forgotten.",
+    get_google_analytics: "Site analytics are dashboard-only until #104 decides their shape.",
+    get_posthog_analytics: "Site analytics are dashboard-only until #104 decides their shape.",
+    get_search_console_data: "Site analytics are dashboard-only until #104 decides their shape.",
+};

package/dist/shared/connections.js

@@ -44,8 +44,10 @@ export function registerConnectionTools(server, makeClient) {
             "allowed to do — read the account, publish a post, manage comments. Each answer is yes, " +
             "no, or unknown; unknown means the grant predates scope recording, so treat it as \"try " +
             "it\", not as a refusal. Also returns which platforms can be connected at all, which is a " +
-            "smaller set than the networks nooticr can read. Call this before promising that " +
-            "something can be posted or replied to. No cost to call.",
+            "smaller set than the networks nooticr can read. \"Manage comments\" reports what the " +
+            "platform granted, not something nooticr does: no nooticr tool posts, replies to or " +
+            "moderates a comment, so a yes there never means a drafted reply will be sent. Call this " +
+            "before promising that something can be posted or replied to. No cost to call.",
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: z.object({}).strict(),
         outputSchema: OUTPUT_SCHEMAS.list_social_connections,