@nooticr/mcp 1.26.39 → 1.26.41

package/README.md

@@ -145,9 +145,9 @@ a `scanId` for the rest.
 | `scan_amazon_category` | 3 per listing collected (30 by default) | The category, collected: listings with prices, star histograms, Amazon's own review-aspect counts and the review text itself, plus the arithmetic over them — price spread, rating spread, which aspects recur across how many brands, and the share of each listing's ratings sitting at 1-2 stars, read from the histogram rather than from the handful of reviews a scrape returns. Pass `query` to search the category, `asins` to pin the competitors a customer named, or both; named competitors keep their place at the front. Because the price is set by an argument, it confirms the total before spending it. |
 | `amazon_scan_status` | free | Picks a running collection back up by `scanId` — the listings collected since, with the same rollup. Free: it is the poll `scan_amazon_category` asked for, and billing the second half of one answer would charge for a wait the server chose. |
 | `get_amazon_product` | 3 | One listing by ASIN or URL: price, rating, the full star histogram, features, specs, Amazon's review digest and aspect breakdown, and the reviews. |
-| `scan_marketplace_category` | 3 per product collected (30 by default) | The same category read on ten more sites — AliExpress, Cdiscount, Flipkart, Mercado Libre, Lazada, Otto, Rakuten, Trendyol, Jumia and Temu. `marketplace` picks the site; `market` picks the storefront for the sites that have several, and the argument names the real set per site so a model cannot send Otto a Lazada region. Same rollup, same confirmation before spending. |
+| `scan_marketplace_category` | 3 per product collected (30 by default) | The same category read on eleven more sites — AliExpress, Cdiscount, Flipkart, Mercado Libre, Lazada, Otto, Rakuten, Trendyol, Jumia, Vinted and Temu. Vinted is resale rather than retail, so its `rating` describes the seller and the scan says so in `ratingScope` — do not read it as a product's reviews. `marketplace` picks the site; `market` picks the storefront for the sites that have several, and the argument names the real set per site so a model cannot send Otto a Lazada region. Same rollup, same confirmation before spending. |
 | `marketplace_scan_status` | free | Picks a running marketplace collection back up by `scanId` and the same `marketplace`. Free, for the same reason `amazon_scan_status` is. |
-| `get_marketplace_product` | 3 | One product from any of the eleven sites, by id or URL: price, rating, the full star histogram, specs and the reviews. |
+| `get_marketplace_product` | 3 | One product from any of the twelve sites, by id or URL: price, rating, the full star histogram, specs and the reviews. |
 | `show_amazon_category_insights` | free | Draws the read **your model** wrote — purchase drivers, barriers, what each brand does well, the gaps, the positioning angles — beside the listings and their reviews, so a person can click a product and check any claim against the text it came from. The conclusions are attributed to your model, never presented as a nooticr rating of anyone's product. Makes no requests. |
 
 ### Make something
@@ -337,6 +337,76 @@ npx @nooticr/mcp --http     # remote HTTP with OAuth (for OpenAI Agents SDK)
 (mode `0600`). If your browser cannot be opened automatically, copy the URL it
 prints into a browser manually.
 
+## Running on a server (no browser)
+
+`login` and the OAuth flow both need a browser once, and both leave behind a
+15-minute access token kept alive by a refresh token. That is the wrong shape
+for an integration running server-side: nothing there can complete a consent
+screen, and a refresh chain that breaks has to be repaired by hand.
+
+An **API key** is the other way in. Mint one from a browser at
+[mcp.nooticr.com/dashboard](https://mcp.nooticr.com/dashboard) — sign in, name
+the key, copy it — or from a machine you *can* sign in on, once:
+
+```bash
+npx @nooticr/mcp login                                  # the one interactive step
+npx @nooticr/mcp api-key create --name "aybee-prod"     # prints the key, once
+```
+
+Then give it to the deployment. There is nothing else to configure and nothing
+to refresh — the key stays valid until you revoke it.
+
+```bash
+# stdio, as a subprocess of your own service
+NOOTICR_API_KEY=nk_... npx @nooticr/mcp
+```
+
+On a server, prefer the environment variable: it is what every container
+runtime and secret manager already injects, and it leaves nothing on a disk
+that a redeploy is going to throw away. Where setting one is the awkward part
+— a laptop, or a client like Claude Desktop that does not inherit your shell —
+store the key in the credentials file instead:
+
+```bash
+npx @nooticr/mcp login --api-key nk_...
+```
+
+That checks the key against the server before writing it, so a typo fails
+while you are still there to fix it, and then behaves exactly like the
+environment variable: no browser, no refresh, valid until revoked. The file
+holds one credential, so this replaces any session an earlier `login` left
+behind (and `NOOTICR_API_KEY` still overrides it).
+
+```http
+# or against the remote endpoint, as an ordinary bearer token —
+# no /authorize, no PKCE, no redirect URI
+POST https://mcp.nooticr.com/mcp
+Authorization: Bearer nk_...
+```
+
+Managing them, from the dashboard's **API keys** card or the CLI:
+
+```bash
+npx @nooticr/mcp api-key create --name "staging" --expires-in-days 90
+npx @nooticr/mcp api-key list
+npx @nooticr/mcp api-key revoke <id>
+```
+
+Every command takes `--json` for scripting. A few things worth knowing:
+
+- The key is shown **once**, by `api-key create`. nooticr stores only a hash of
+  it and cannot show it again; `list` shows the head (`nk_1a2b3c4d…`) so you
+  can tell keys apart.
+- A key carries the scope of whoever created it — their account, and the
+  workspace they were in (`--workspace-id` picks another one you belong to).
+- A key **cannot create or revoke keys**. That is deliberate: it means a leaked
+  key cannot mint a replacement that outlives revoking the original.
+- `--expires-in-days` is optional. Without it a key does not expire on its own.
+- Revoking takes effect immediately at the API. The hosted remote endpoint
+  caches the "this key is real" answer for up to five minutes, which only ever
+  lets a revoked key see the tool list — every call that touches your account
+  is checked against nooticr-server on the spot.
+
 ## Usage in Claude Desktop
 
 After `npx @nooticr/mcp login`, add to `claude_desktop_config.json`:
@@ -455,6 +525,11 @@ nooticr-mcp --stdio            Same as above
 nooticr-mcp --http [--port N]  Start the remote HTTP transport with OAuth (default port 3457)
 nooticr-mcp login              Sign in to nooticr via Google in your browser
 nooticr-mcp login --email ... --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 help
 ```
 
@@ -463,7 +538,8 @@ nooticr-mcp --help             Show help
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `NOOTICR_BASE_URL` | `https://api.nooticr.com` | nooticr server base URL (trailing slash stripped) |
-| `NOOTICR_ACCESS_TOKEN` | — | nooticr JWT access token; takes priority over the credentials file |
+| `NOOTICR_ACCESS_TOKEN` | — | nooticr JWT access token; takes priority over everything below |
+| `NOOTICR_API_KEY` | — | nooticr API key from `api-key create` — no browser, no refresh, valid until revoked; takes priority over the credentials file (including a key `login --api-key` put there) |
 | `NOOTICR_CREDENTIALS_FILE` | `~/.config/nooticr-mcp/credentials.json` | token store path |
 | `NOOTICR_PUBLIC_URL` | `http://localhost:3457` | public base URL advertised in OAuth metadata (HTTP mode) |
 | `NOOTICR_PORT` | `3457` | port for `--http` and `login` |
@@ -471,10 +547,20 @@ nooticr-mcp --help             Show help
 
 ## How authentication works
 
-**stdio mode** (Claude Desktop, Cursor): the server uses the token from
-`NOOTICR_ACCESS_TOKEN` or the credentials file written by `login`. If the token
-is expired it is automatically refreshed with the stored refresh token, and if
-the nooticr API returns `401` the request is retried once after a refresh.
+**stdio mode** (Claude Desktop, Cursor): the server uses the first credential
+it finds — `NOOTICR_ACCESS_TOKEN`, then `NOOTICR_API_KEY`, then the credentials
+file written by `login`. That file holds one credential, whichever `login` last
+wrote: an API key (`login --api-key`) or a session. A session token that has
+expired is refreshed with the stored refresh token, and a `401` from the
+nooticr API is retried once after a refresh. An API key is never refreshed
+wherever it came from: it does not expire, so a `401` on one means revoked or
+mistyped, and retrying would only hide that.
+
+**API key** (any transport, no browser): send it as the bearer token, or set
+`NOOTICR_API_KEY`. nooticr-server resolves the key to its owner and the
+workspace it was scoped to, and every authorization check downstream sees
+exactly what it would have seen for a signed-in session. See
+[Running on a server](#running-on-a-server-no-browser).
 
 **HTTP mode** (OpenAI Agents SDK, remote clients): the server runs its own
 OAuth 2.0 authorization server (Authorization Code + PKCE S256, public client,
@@ -488,7 +574,9 @@ per the MCP 2025-03-26 spec):
   one-time code
 - `POST /token` — verifies PKCE and issues an opaque Bearer token bound to the
   nooticr session (valid 1 hour)
-- every MCP RPC validates the Bearer token against the session map
+- every MCP RPC validates the Bearer token against the session map — or, when
+  the bearer is an API key, forwards it to nooticr-server as the caller's own
+  credential, which is what makes this endpoint usable with no browser at all
 
 ## Supported URLs
 
@@ -508,8 +596,14 @@ and text** posts.
 
 ## Troubleshooting
 
-- **`Not authenticated with nooticr` / 401**: run `npx @nooticr/mcp login` or set
-  `NOOTICR_ACCESS_TOKEN`.
+- **`Not authenticated with nooticr` / 401**: run `npx @nooticr/mcp login`, or
+  set `NOOTICR_API_KEY` (see [Running on a server](#running-on-a-server-no-browser)).
+- **`unknown, revoked or expired nooticr API key`**: the key is not one this
+  account has live. `npx @nooticr/mcp api-key list` shows every key and its
+  state, revoked ones included.
+- **`API keys cannot manage API keys`**: `api-key create`/`list`/`revoke` need a
+  signed-in session, which is why they ignore a key in `NOOTICR_API_KEY` *and*
+  one stored by `login --api-key`. Run `npx @nooticr/mcp login` first.
 - **402 paywall / `insufficient MCP credits`**: your nooticr account is out of
   credits. Prices are listed per tool in [Tools](#tools) — 1 credit for a post
   lookup or transcript, 2 for discovery and for a tool that makes one fetch, 3
@@ -541,7 +635,12 @@ package for **Claude Desktop**, **Cursor**, and **OpenAI Agents SDK**.
   (in-memory).
 - Access tokens are opaque, random, and bound to the in-memory session map;
   they expire after 1 hour. Restarting the server invalidates all sessions.
-- Never share your credentials file or `NOOTICR_ACCESS_TOKEN`.
+- API keys are stored as a sha256 hash, never in the clear, so a database dump
+  cannot be replayed against the API. They are scoped to one account and one
+  workspace, carry their owner's role as it is *now* rather than as it was when
+  the key was minted, and cannot be used to create or revoke keys.
+- Never share your credentials file, `NOOTICR_ACCESS_TOKEN` or
+  `NOOTICR_API_KEY`.
 
 ## Development
 

package/dist/auth.js

@@ -1,11 +1,23 @@
 /**
  * Token storage + resolution.
  *
- * Priority: env NOOTICR_ACCESS_TOKEN > credentials file (auto-refresh when
- * expired) > per-session tokens (HTTP OAuth mode only).
+ * Priority: env NOOTICR_ACCESS_TOKEN > env NOOTICR_API_KEY > credentials file
+ * (an API key stored by `login --api-key`, else a session token, refreshed
+ * when expired) > per-session tokens (HTTP OAuth mode only).
+ *
+ * `NOOTICR_ACCESS_TOKEN` stays first because it has always been the explicit
+ * "use exactly this token" override, and someone who exports one for a single
+ * debugging run should get it. An API key sits directly behind it: it is the
+ * credential a server holds permanently, so it outranks anything in a file.
+ *
+ * The file holds *one* credential, whichever `login` last wrote. A store
+ * carrying both a key and a session would make "which am I signed in as"
+ * unanswerable — and, worse, let a rejected key quietly fall back to a stale
+ * session belonging to someone else.
  */
 import fs from "node:fs";
 import path from "node:path";
+import { getApiKey } from "./config.js";
 import { NooticrClient, NooticrError } from "./nooticr.js";
 const REFRESH_BEFORE_EXPIRY_MS = 30_000;
 export class NooticrAuthError extends Error {
@@ -40,7 +52,7 @@ export class AuthManager {
         try {
             const raw = await fs.promises.readFile(this.credentialsFile, "utf8");
             const parsed = JSON.parse(raw);
-            if (parsed && typeof parsed.accessToken === "string") {
+            if (parsed && (typeof parsed.accessToken === "string" || typeof parsed.apiKey === "string")) {
                 return parsed;
             }
             return null;
@@ -63,15 +75,34 @@ export class AuthManager {
     /**
      * Resolves the current access token for a request. `session` provides the
      * per-session tokens issued via our own OAuth /token endpoint (HTTP mode).
+     *
+     * `allowApiKey` exists for the one caller that must not use one: the
+     * `api-key` CLI commands. The backend refuses key management to a
+     * key-authenticated caller, so resolving a key there would turn "create me
+     * a second key" into a 403 that reads like a permissions bug rather than
+     * the deliberate bound it is. It skips both places a key can live — the
+     * environment and the credentials file — since the bound is about the
+     * credential, not about where it was found.
      */
-    async getAccessToken(session) {
+    async getAccessToken(session, { allowApiKey = true } = {}) {
         const envToken = process.env.NOOTICR_ACCESS_TOKEN;
         if (envToken) {
             this.lastSource = "env";
             this.lastRefreshToken = undefined;
             return envToken;
         }
+        const apiKey = allowApiKey ? getApiKey() : undefined;
+        if (apiKey) {
+            this.lastSource = "apiKey";
+            this.lastRefreshToken = undefined;
+            return apiKey;
+        }
         const store = await this.loadStore();
+        if (allowApiKey && store?.apiKey) {
+            this.lastSource = "apiKey";
+            this.lastRefreshToken = undefined;
+            return store.apiKey;
+        }
         if (store?.accessToken && !isTokenExpired(store)) {
             this.lastSource = "file";
             this.lastRefreshToken = store.refreshToken;
@@ -101,6 +132,10 @@ export class AuthManager {
      * the current token. Returns true when a new token is available.
      */
     async onUnauthorized(session) {
+        // A key has nothing to redeem: a 401 on one means revoked, expired or
+        // mistyped, and retrying with the same string forever would hide that.
+        if (this.lastSource === "apiKey")
+            return false;
         let refreshToken = this.lastRefreshToken;
         if (this.lastSource === "session" && session?.refreshToken) {
             refreshToken = session.refreshToken;
@@ -131,7 +166,22 @@ export class AuthManager {
         await this.saveStore(store);
         this.lastSource = "file";
         this.lastRefreshToken = store.refreshToken;
-        return store.accessToken;
+        // `session.accessToken` rather than `store.accessToken`: the guard above
+        // has already narrowed it, and the store's field is optional now that a
+        // credentials file may hold an API key instead of a session.
+        return session.accessToken;
+    }
+    /**
+     * Persists an API key as this machine's credential, replacing whatever
+     * `login` last wrote. For clients that do not inherit a shell environment
+     * (Claude Desktop, Cursor) and for a laptop where editing JSON to set an
+     * env var is the annoying part; a server should still be given
+     * `NOOTICR_API_KEY` and left with nothing on disk.
+     */
+    async persistApiKey(apiKey, user) {
+        await this.saveStore({ apiKey, user });
+        this.lastSource = "apiKey";
+        this.lastRefreshToken = undefined;
     }
     /**
      * Persists a session obtained from login/OAuth completion.
@@ -150,7 +200,8 @@ export class AuthManager {
     }
     ensureUnauthenticatedError() {
         throw new NooticrAuthError("Not authenticated with nooticr. Run `npx nooticr-mcp login` to sign in " +
-            "with Google, or set the NOOTICR_ACCESS_TOKEN environment variable " +
+            "with Google, or — on a server with no browser — set NOOTICR_API_KEY " +
+            "to a key from `npx nooticr-mcp api-key create` " +
             "(see `npx nooticr-mcp --help`).");
     }
 }
@@ -161,7 +212,27 @@ export function createStdioTokenProvider(auth) {
         onUnauthorized: async () => auth.onUnauthorized(),
     };
 }
-/** Builds a TokenProvider for HTTP mode: env > file > per-session tokens. */
+/**
+ * Builds a TokenProvider for the `api-key` CLI commands: env access token or
+ * the credentials file, never `NOOTICR_API_KEY`. See `getAccessToken`.
+ */
+export function createManagementTokenProvider(auth) {
+    return {
+        getAccessToken: async () => auth.getAccessToken(undefined, { allowApiKey: false }),
+        onUnauthorized: async () => auth.onUnauthorized(),
+    };
+}
+/**
+ * Builds a TokenProvider for one caller's own API key — the headless path
+ * through HTTP mode, where the bearer the client presented *is* the nooticr
+ * credential. Deliberately not `createHttpTokenProvider`: that one falls back
+ * to the operator's environment and credentials file, which would answer one
+ * tenant's call with another's account.
+ */
+export function createApiKeyTokenProvider(apiKey) {
+    return { getAccessToken: async () => apiKey };
+}
+/** Builds a TokenProvider for HTTP mode: env > api key > file > per-session tokens. */
 export function createHttpTokenProvider(auth, session) {
     return {
         getAccessToken: async () => auth.getAccessToken(session),

package/dist/config.js

@@ -40,6 +40,17 @@ export function getPort() {
     }
     return port;
 }
+/**
+ * A nooticr API key from the environment, if one is set.
+ *
+ * This is the headless path: no browser, no credentials file, nothing to
+ * refresh. A server-side integration sets `NOOTICR_API_KEY` once and the key
+ * stays valid until someone revokes it.
+ */
+export function getApiKey() {
+    const raw = process.env.NOOTICR_API_KEY?.trim();
+    return raw ? raw : undefined;
+}
 export function getCredentialsFile() {
     if (process.env.NOOTICR_CREDENTIALS_FILE) {
         return process.env.NOOTICR_CREDENTIALS_FILE;

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

@@ -33,7 +33,25 @@ export function normaliseProducts(raw) {
         // raw `p.asin` there gave every review on every non-Amazon product the id
         // "review::0", "review::1" — colliding across products, so a model citing
         // one could not be pointed back at the right listing.
-        const id = String(p.asin ?? p.id ?? p.item_id ?? p.sku ?? p.product_id ?? "");
+        //
+        // This list must stay equal to `ID_KEYS` in nooticr-server's
+        // `crates/server/src/marketplace.rs`. The server computes `rollup.perProduct[].id`
+        // from its copy and the view joins those rows onto the tiles by the id
+        // resolved here, so a key in one list and not the other does not read as a
+        // missing id — it reads as a tile with no `negativeStarShare`, which looks
+        // like a site that publishes no histogram.
+        //
+        // `pid` and `goods_id` were the two missing, which is Flipkart and Temu:
+        // each collector publishes exactly one id field and those are theirs, so
+        // every product in a scan of either site resolved to "" and shared one
+        // blank key — the failure the comment below says was fixed for the others.
+        //
+        // Found by hand rather than by a test, and `??` is why it could be: it
+        // falls through null and undefined but not "", so a site that sends an
+        // empty id under an earlier key would stop the chain on the empty value
+        // rather than continue past it. Matching on a non-empty string closes
+        // both.
+        const id = String([p.asin, p.sku, p.pid, p.goods_id, p.item_id, p.product_id, p.id].find((v) => typeof v === "string" && v.trim() !== "") ?? "");
         const histogram = (p.rating_histogram ?? {});
         const reviews = Array.isArray(p.reviews) ? p.reviews : [];
         const aspects = Array.isArray(p.review_aspects) ? p.review_aspects : [];
@@ -137,6 +155,26 @@ export function categoryGuidance(opts) {
             : "."));
     if (opts.brands.length)
         lines.push(`Brands in the set: ${opts.brands.join(", ")}.`);
+    // Nothing came back, which is the one outcome where the next step is not
+    // "read the set" and the guidance above says nothing useful. Without this a
+    // model reports an empty category as a finding — the category is empty —
+    // when what actually happened is a search that found nothing, and the
+    // commonest reason is a query in a language that storefront does not sell
+    // in. Said here rather than only in the tool description because by the time
+    // this is read the description is long out of the model's attention.
+    if (opts.products === 0 && opts.complete) {
+        lines.push(`No listings came back. This is not a finding about the category — it is a search that ` +
+            `matched nothing. Before reporting it: check the query is in the language that ` +
+            `storefront sells in, try the common shopper's word for the thing rather than a ` +
+            `category or brand-family name, and drop any quotes or operators. If a second query ` +
+            `also returns nothing, say the search found nothing rather than that the category ` +
+            `is empty.`);
+    }
+    // Before the "still running" line and before the analysis prompt: a model
+    // that has already started composing a read is past the point where a
+    // caveat changes what it writes.
+    if (opts.freshness)
+        lines.push(opts.freshness);
     if (!opts.complete) {
         lines.push(`Collection is still running — ${opts.pending} listing${opts.pending === 1 ? "" : "s"} to go. ` +
             `Everything below is real and usable now; call ${statusTool} with scanId "${opts.scanId}" ` +

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/marketplace.js

@@ -5,7 +5,7 @@ import { withEvidence } from "./evidence-digest.js";
 import { confirmSpend, declinedResult } from "./spend.js";
 import { allReviews, categoryGuidance, listingCount, normaliseProducts, scanCost } from "./amazon.js";
 /**
- * The eleven sites, mirroring `MARKETPLACES` in nooticr-server.
+ * The twelve sites, mirroring `MARKETPLACES` in nooticr-server.
  *
  * Kept in the same order and the same words deliberately: a model reads this
  * text to decide what to send, and the server refuses on the same terms. Two
@@ -22,21 +22,25 @@ export const MARKETS = [
             hint: "a country code or host — com (US), co.uk, de, fr, it, es, ca, co.jp, in, com.br, " +
                 "com.mx, com.au, nl, se, pl, com.be, com.tr, ae, sa, eg, sg, cn. Default www.amazon.com",
         },
+        searchLang: "the storefront's own — English on com, co.uk, ca, in, com.au and sg, otherwise the country's",
     },
     {
         slug: "aliexpress",
         label: "AliExpress",
         idLabel: "the numeric id from /item/<id>.html, or a full AliExpress product URL",
+        searchLang: "English",
     },
     {
         slug: "cdiscount",
         label: "Cdiscount",
         idLabel: "the SKU from a product URL's /f-<category>-<sku>.html, or the full URL",
+        searchLang: "French",
     },
     {
         slug: "flipkart",
         label: "Flipkart",
         idLabel: "the 16-character PID from a product URL's pid= parameter, or the full URL",
+        searchLang: "English",
     },
     {
         slug: "mercadolibre",
@@ -48,6 +52,7 @@ export const MARKETS = [
                 "mercadolivre.com.br. Inferred from the ids when omitted, and a job runs against one " +
                 "market: an id from another is refused rather than mis-filed",
         },
+        searchLang: "Spanish, except Brazil (MLB), which is Portuguese",
     },
     {
         slug: "lazada",
@@ -59,6 +64,7 @@ export const MARKETS = [
             hint: "sg, my, th, vn, ph or id. An item id is scoped to one of them — the same id on another " +
                 "Lazada host is a different product or nothing at all",
         },
+        searchLang: "English on sg and ph; Thai, Vietnamese, Indonesian or Malay on th, vn, id and my",
     },
     {
         slug: "otto",
@@ -70,6 +76,7 @@ export const MARKETS = [
             hint: "de or at. The two are not interchangeable: an id from one does not address a product " +
                 "on the other",
         },
+        searchLang: "German, on both storefronts",
     },
     {
         slug: "rakuten",
@@ -81,6 +88,7 @@ export const MARKETS = [
             hint: "jp (Ichiba) or tw. Taiwan publishes no review text, so a category study there reads on " +
                 "price and rating alone",
         },
+        searchLang: "Japanese on jp, Traditional Chinese on tw",
     },
     {
         slug: "trendyol",
@@ -91,6 +99,7 @@ export const MARKETS = [
             hint: "one of 47 storefronts — tr, de, ae, sa, at, be, fr, it, nl, pl, ro and the rest. An id " +
                 "is scoped to one: the same number 404s on another country's",
         },
+        searchLang: "Turkish on tr; the storefront's own language elsewhere",
     },
     {
         slug: "jumia",
@@ -98,11 +107,30 @@ export const MARKETS = [
         idLabel: "a SKU such as OR537EA86PWGTNAFAMZ. A product URL does NOT contain it — the number at the " +
             "end of a product path is a different handle — so reach a product through `query` instead",
         region: { field: "market", hint: "ng, eg, ke, ma, ci, gh, sn, tn, ug or dz" },
+        searchLang: "English on ng, ke, gh and ug; French on ci, sn, ma, tn and dz; Arabic or French on eg",
+    },
+    // The one resale site here. Its `rating` describes the seller rather than the
+    // product, because a Vinted listing is a unique second-hand item with no
+    // reviews of its own — the server says so in `ratingScope`/`ratingNote` on
+    // every scan of it, and those are worth passing on rather than summarising
+    // away.
+    {
+        slug: "vinted",
+        label: "Vinted",
+        idLabel: "the numeric id from /items/<id>, or a full Vinted item URL",
+        region: {
+            field: "market",
+            hint: "one of 27 European storefronts — fr, de, es, it, pl, co.uk, com (US), com.au and the " +
+                "rest. A listing belongs to exactly one: the same item id does not exist on another " +
+                "country's Vinted",
+        },
+        searchLang: "the storefront's own — French on fr, German on de, Polish on pl, and so on",
     },
     {
         slug: "temu",
         label: "Temu",
         idLabel: "the goods id after -g- in a product URL, or the full URL",
+        searchLang: "English",
     },
 ];
 const BY_SLUG = new Map(MARKETS.map((m) => [m.slug, m]));
@@ -114,7 +142,7 @@ const SLUGS = MARKETS.map((m) => m.slug).join(", ");
 /**
  * The storefront argument, described site by site.
  *
- * One string rather than eleven schemas, because a tool takes one `marketplace`
+ * One string rather than twelve schemas, because a tool takes one `marketplace`
  * per call and the host shows the whole description whichever it picks. Sites
  * with a single storefront are named as taking none, so a model does not
  * invent one for Temu.
@@ -124,6 +152,8 @@ const MARKET_HINT = MARKETS.filter((m) => m.region)
     .join(" · ") +
     ` · ${MARKETS.filter((m) => !m.region).map((m) => m.label).join(", ")} have one storefront each ` +
     "and take no market argument.";
+/** Which language a query has to be in, site by site. */
+const LANG_HINT = MARKETS.map((m) => `${m.label}: ${m.searchLang}`).join(" · ");
 /** The product ids each site addresses by, for `items`. */
 const ID_HINT = MARKETS.map((m) => `${m.label}: ${m.idLabel}`).join(" · ");
 function structured(res) {
@@ -161,6 +191,9 @@ function marketplaceResult(payload, m, focus) {
         scanId: String(payload.scanId ?? ""),
         pending: Math.max(0, total - done),
         focus,
+        // Present only when the server answered from its own store. See the field's
+        // comment in `categoryGuidance` for why it is repeated in both channels.
+        freshness: typeof payload.freshness === "string" ? payload.freshness : undefined,
         site: m.label,
         statusTool: "marketplace_scan_status",
         // There is no free insights view for these sites yet, and pointing a model
@@ -177,6 +210,12 @@ function marketplaceResult(payload, m, focus) {
         complete: payload.complete !== false,
         query: payload.query ?? null,
         market: payload.market ?? payload.domain ?? null,
+        // Where this answer came from, and when the figures in it were measured.
+        // `collectedAt` is when the result was assembled, which on a stored answer
+        // is now and says nothing about the price's age; `observedAt` is the age.
+        servedFrom: payload.servedFrom ?? "live",
+        observedAt: payload.observedAt ?? null,
+        freshness: payload.freshness ?? null,
         progress,
         rollup,
         products,
@@ -197,7 +236,7 @@ export function registerMarketplaceTools(server, makeClient) {
     server.registerTool("scan_marketplace_category", {
         title: "Scan Marketplace Category",
         _meta: viewMeta("scan_marketplace_category"),
-        description: "Collect a category from any of eleven marketplaces and read it: products with prices, " +
+        description: "Collect a category from any of twelve marketplaces and read it: products with prices, " +
             "star histograms, the review text itself, and the arithmetic over them (price spread, " +
             "rating spread, which aspects recur across how many brands, and the share of each " +
             "product's ratings sitting at 1-2 stars). `marketplace` picks the site — one of " +
@@ -222,7 +261,17 @@ export function registerMarketplaceTools(server, makeClient) {
         inputSchema: z
             .object({
             marketplace: marketplaceArg,
-            query: z.string().optional().describe("Category or keyword to search, e.g. 'cast iron skillet'."),
+            query: z
+                .string()
+                .optional()
+                .describe("Category or keyword to search, e.g. 'cast iron skillet'. Two to four words, " +
+                "the common name a shopper would type rather than a catalogue description, " +
+                "and no quotes or AND/OR — none of these sites read them as operators, they " +
+                "search for them and narrow to nothing. It has to be in the storefront's " +
+                `language — ${LANG_HINT}. A query in the wrong language does not fail: it ` +
+                "returns a few imported listings, which reads as a thin category and is " +
+                "really a bad search. Brand names are not translated. A scan that came back " +
+                "with no products is a reason to change the query, not to raise the limit."),
             items: z
                 .array(z.string())
                 .optional()
@@ -329,7 +378,7 @@ export function registerMarketplaceTools(server, makeClient) {
     server.registerTool("get_marketplace_product", {
         title: "Get Marketplace Product",
         _meta: viewMeta("get_marketplace_product"),
-        description: "Fetch one product from any of eleven marketplaces by id or URL: price, rating, the full " +
+        description: "Fetch one product from any of twelve marketplaces by id or URL: price, rating, the full " +
             "star histogram, specs, and the review text. `marketplace` picks the site — one of " +
             `${SLUGS}. ` +
             "Costs 3 nooticr credits. " +

package/dist/shared/nooticr.js

@@ -98,11 +98,16 @@ export class NooticrClient {
             body = undefined;
         }
         const json = (body ?? {});
+        // Name the endpoint: a bare status code says nothing about which call
+        // failed, and these surface to the user as tool errors. Then add the
+        // body when it is plainly a sentence — dropping it leaves a headless
+        // caller with a number and no cause.
+        const detail = plainTextDetail(text);
         const errorMessage = typeof json.error === "string"
             ? json.error
-            : // Name the endpoint: a bare status code says nothing about which
-                // call failed, and these surface to the user as tool errors.
-                `nooticr API error (${res.status}) from ${path}`;
+            : detail
+                ? `nooticr API error (${res.status}) from ${path}: ${detail}`
+                : `nooticr API error (${res.status}) from ${path}`;
         if (res.status >= 200 && res.status < 300) {
             return body;
         }
@@ -172,6 +177,28 @@ export class NooticrClient {
             auth: true,
         });
     }
+    /**
+     * Mints a key for the signed-in user. Deliberately not callable *with* a
+     * key: the backend refuses key-management to key-authenticated callers so a
+     * leaked key cannot mint a sibling that survives its own revocation.
+     */
+    async createApiKey(input = {}) {
+        return this.request("POST", "/auth/api-keys", {
+            auth: true,
+            body: input,
+        });
+    }
+    async listApiKeys() {
+        const res = await this.request("GET", "/auth/api-keys", {
+            auth: true,
+        });
+        return res?.keys ?? [];
+    }
+    async revokeApiKey(id) {
+        await this.request("DELETE", `/auth/api-keys/${encodeURIComponent(id)}`, {
+            auth: true,
+        });
+    }
     async me() {
         return this.request("GET", "/auth/me", { auth: true });
     }
@@ -238,6 +265,21 @@ export class NooticrClient {
         throw new NooticrError(res.status, typeof json.error === "string" ? json.error : `Refresh failed (${res.status})`, { body });
     }
 }
+/**
+ * The backend answers a good many routes with a bare string rather than JSON
+ * (axum's `(StatusCode, String)`), and "nooticr API error (403)" tells whoever
+ * reads it nothing — least of all a headless integration, where the message is
+ * the only thing anyone will see. Use the body when it is plainly a sentence:
+ * short, one line, and not the start of a document.
+ */
+function plainTextDetail(text) {
+    const trimmed = text.trim();
+    if (!trimmed || trimmed.length > 300 || trimmed.includes("\n"))
+        return undefined;
+    if (/^[<{[]/.test(trimmed))
+        return undefined;
+    return trimmed;
+}
 async function parseJsonBody(res) {
     const text = await res.text();
     try {

package/dist/shared/tools-def.js

@@ -435,8 +435,8 @@ export const TOOL_DEFINITIONS = [
     {
         name: "scan_marketplace_category",
         title: "Scan Marketplace Category",
-        description: "Collect a category from any of eleven marketplaces and read it: products with prices, star histograms, the review text itself, and the arithmetic over them (price spread, rating spread, which aspects recur across how many brands, and the share of each product's ratings sitting at 1-2 stars). marketplace picks the site — one of amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, temu. Pass query to search the category, items to pin named competitors by id or URL, or both. You write the read: purchase drivers, barriers, what the incumbents do well, the gaps, and how a new entrant could position. Collection runs in the background, so this returns everything ready within waitSeconds plus a scanId to continue with marketplace_scan_status — that is free, and repeating it is how a scan gets more time. For Amazon specifically, scan_amazon_category returns the same shape plus Amazon's own review-aspect counts. Consumes 3 nooticr credits per product collected — a product with reviews is a real browser render behind the site's bot defences.",
-        inputSchema: z.object({ marketplace: z.string().describe("Which site to read. One of: amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, temu."), query: z.string().optional().describe("Category or keyword to search, e.g. 'cast iron skillet'."), items: z.array(z.string()).optional().describe("Named competitors, by product id or URL."), limit: z.number().int().optional().describe("Products to collect (default 10, max 50)."), reviews: z.boolean().optional().describe("Collect review text too (default true)."), market: z.string().optional().describe("The storefront to read, for the sites that have more than one. Amazon: a country code or host — com (US), co.uk, de, fr and the rest, default www.amazon.com · Mercado Libre: one of eighteen markets, named however it comes to hand — MLB, br, Brazil · Lazada: sg, my, th, vn, ph or id · Otto: de or at · Rakuten: jp (Ichiba) or tw · Trendyol: one of 47 storefronts — tr, de, ae, sa and the rest · Jumia: ng, eg, ke, ma, ci, gh, sn, tn, ug or dz · AliExpress, Cdiscount, Flipkart and Temu have one storefront each and take no market argument. An id is scoped to one storefront: the same id on another is a different product or nothing at all."), domain: z.string().optional().describe("Amazon only: the marketplace host. Other sites use market."), waitSeconds: z.number().int().optional().describe("How long to wait before returning partial results (default 45, max 55). Poll marketplace_scan_status for the rest instead; it is free and repeatable."), focus: z.string().optional().describe("An extra question to answer from the reviews.") }).strict(),
+        description: "Collect a category from any of twelve marketplaces and read it: products with prices, star histograms, the review text itself, and the arithmetic over them (price spread, rating spread, which aspects recur across how many brands, and the share of each product's ratings sitting at 1-2 stars). marketplace picks the site — one of amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, vinted, temu. Pass query to search the category, items to pin named competitors by id or URL, or both. You write the read: purchase drivers, barriers, what the incumbents do well, the gaps, and how a new entrant could position. Collection runs in the background, so this returns everything ready within waitSeconds plus a scanId to continue with marketplace_scan_status — that is free, and repeating it is how a scan gets more time. For Amazon specifically, scan_amazon_category returns the same shape plus Amazon's own review-aspect counts. Consumes 3 nooticr credits per product collected — a product with reviews is a real browser render behind the site's bot defences.",
+        inputSchema: z.object({ marketplace: z.string().describe("Which site to read. One of: amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, vinted, temu."), query: z.string().optional().describe("Category or keyword to search, e.g. 'cast iron skillet'."), items: z.array(z.string()).optional().describe("Named competitors, by product id or URL."), limit: z.number().int().optional().describe("Products to collect (default 10, max 50)."), reviews: z.boolean().optional().describe("Collect review text too (default true)."), market: z.string().optional().describe("The storefront to read, for the sites that have more than one. Amazon: a country code or host — com (US), co.uk, de, fr and the rest, default www.amazon.com · Mercado Libre: one of eighteen markets, named however it comes to hand — MLB, br, Brazil · Lazada: sg, my, th, vn, ph or id · Otto: de or at · Rakuten: jp (Ichiba) or tw · Trendyol: one of 47 storefronts — tr, de, ae, sa and the rest · Jumia: ng, eg, ke, ma, ci, gh, sn, tn, ug or dz · AliExpress, Cdiscount, Flipkart and Temu have one storefront each and take no market argument. An id is scoped to one storefront: the same id on another is a different product or nothing at all."), domain: z.string().optional().describe("Amazon only: the marketplace host. Other sites use market."), waitSeconds: z.number().int().optional().describe("How long to wait before returning partial results (default 45, max 55). Poll marketplace_scan_status for the rest instead; it is free and repeatable."), focus: z.string().optional().describe("An extra question to answer from the reviews.") }).strict(),
     },
     {
         name: "marketplace_scan_status",
@@ -447,8 +447,8 @@ export const TOOL_DEFINITIONS = [
     {
         name: "get_marketplace_product",
         title: "Get Marketplace Product",
-        description: "Fetch one product from any of eleven marketplaces by id or URL: price, rating, the full star histogram, specs, and the review text. marketplace picks the site — one of amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, temu. Use for a single product; for a category or a competitive set, scan_marketplace_category collects many in one job and rolls them up. Consumes 3 nooticr credits.",
-        inputSchema: z.object({ marketplace: z.string().describe("Which site the product is on. One of: amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, temu."), id: z.string().optional().describe("The product id, in whatever form the site addresses products by."), url: z.string().optional().describe("The full product URL, if you have that instead."), reviews: z.boolean().optional().describe("Collect review text too (default true)."), market: z.string().optional().describe("The storefront the product is on, for sites that have more than one. Amazon: a country code or host — com (US), co.uk, de, fr and the rest, default www.amazon.com · Mercado Libre: one of eighteen markets, named however it comes to hand — MLB, br, Brazil · Lazada: sg, my, th, vn, ph or id · Otto: de or at · Rakuten: jp (Ichiba) or tw · Trendyol: one of 47 storefronts — tr, de, ae, sa and the rest · Jumia: ng, eg, ke, ma, ci, gh, sn, tn, ug or dz · AliExpress, Cdiscount, Flipkart and Temu have one storefront each and take no market argument. An id is scoped to one storefront: the same id on another is a different product or nothing at all."), domain: z.string().optional().describe("Amazon only: the marketplace host. Other sites use market.") }).strict(),
+        description: "Fetch one product from any of twelve marketplaces by id or URL: price, rating, the full star histogram, specs, and the review text. marketplace picks the site — one of amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, vinted, temu. Use for a single product; for a category or a competitive set, scan_marketplace_category collects many in one job and rolls them up. Consumes 3 nooticr credits.",
+        inputSchema: z.object({ marketplace: z.string().describe("Which site the product is on. One of: amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, vinted, temu."), id: z.string().optional().describe("The product id, in whatever form the site addresses products by."), url: z.string().optional().describe("The full product URL, if you have that instead."), reviews: z.boolean().optional().describe("Collect review text too (default true)."), market: z.string().optional().describe("The storefront the product is on, for sites that have more than one. Amazon: a country code or host — com (US), co.uk, de, fr and the rest, default www.amazon.com · Mercado Libre: one of eighteen markets, named however it comes to hand — MLB, br, Brazil · Lazada: sg, my, th, vn, ph or id · Otto: de or at · Rakuten: jp (Ichiba) or tw · Trendyol: one of 47 storefronts — tr, de, ae, sa and the rest · Jumia: ng, eg, ke, ma, ci, gh, sn, tn, ug or dz · AliExpress, Cdiscount, Flipkart and Temu have one storefront each and take no market argument. An id is scoped to one storefront: the same id on another is a different product or nothing at all."), domain: z.string().optional().describe("Amazon only: the marketplace host. Other sites use market.") }).strict(),
     },
     {
         name: "show_amazon_category_insights",

package/dist/shared/tools.js

@@ -28,7 +28,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.39";
+export const MCP_SERVER_VERSION = "1.26.41";
 /** MCP Apps extension identifier */
 const UI_EXTENSION = "io.modelcontextprotocol/ui";
 /** MIME type for MCP Apps HTML resources */
@@ -346,6 +346,24 @@ function toolError(prefix, err) {
     // and what fixes it — including that they will not have to ask twice, which
     // is only true now that nooticr_login resumes the interrupted call.
     if (isAuthFailure(err)) {
+        // A deployment running on an API key has nobody to open a sign-in link:
+        // its 401 means the key was revoked, expired or mistyped, and "sign in
+        // again" sends whoever reads that log looking for a browser that does not
+        // exist. The backend names this case in its own message and the client
+        // carries plain-text errors through, so the two can be told apart here.
+        if (/api key/i.test(msg)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `${prefix}: this nooticr API key is not valid — revoked, expired, or mistyped. ` +
+                            `No sign-in link will help: nothing here can be re-authorised interactively. ` +
+                            `Replace the key (NOOTICR_API_KEY, or the bearer token sent to the remote ` +
+                            `endpoint) with a live one — \`npx @nooticr/mcp api-key list\` shows which are ` +
+                            `still active. (${msg})`,
+                    }],
+                isError: true,
+            };
+        }
         return {
             content: [{
                     type: "text",

package/dist/shared/ui-template.js

@@ -3677,6 +3677,7 @@ export const NOOTICR_UI_TEMPLATE = `<!DOCTYPE html>
     rakuten:{label:"Rakuten",color:"#BF0000",on:"#fff",path:"M23.277 21.3L3.939 24 .722 21.3h22.555zM7.6 19.276H3.939V0h6.052a6.653 6.653 0 0 1 6.65 6.646c0 2.234-1.108 4.204-2.799 5.418l5.418 7.211h-4.585l-4.486-5.979H7.6v5.98zm0-9.64h2.392a2.992 2.992 0 0 0 2.989-2.989 2.994 2.994 0 0 0-2.989-2.986H7.6v5.975z"},
     trendyol:{label:"Trendyol",color:"#F27A1A",on:"#fff"},
     jumia:{label:"Jumia",color:"#F68B1E",on:"#111"},
+    vinted:{label:"Vinted",color:"#007782",on:"#fff"},
     temu:{label:"Temu",color:"#FB7701",on:"#fff"}
   };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nooticr/mcp",
   "mcpName": "com.nooticr/mcp",
-  "version": "1.26.39",
+  "version": "1.26.41",
   "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": {