@plaud-ai/mcp 0.3.8 → 0.3.10

package/dist/{chunk-RUFCT6DQ.js → chunk-DIPROABB.js}

@@ -2,11 +2,12 @@
 import { Registry, Counter, Histogram, Gauge, collectDefaultMetrics } from "prom-client";
 var registry = new Registry();
 collectDefaultMetrics({ register: registry });
+var LATENCY_BUCKETS = [0.01, 0.05, 0.1, 0.25, 0.5, 0.75, 1, 1.5, 2, 3, 5, 10, 30];
 var httpRequestDuration = new Histogram({
   name: "http_request_duration_seconds",
   help: "HTTP request latency in seconds",
   labelNames: ["method", "handler", "status"],
-  buckets: [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+  buckets: LATENCY_BUCKETS,
   registers: [registry]
 });
 var httpRequestsInProgress = new Gauge({
@@ -25,7 +26,7 @@ var mcpToolDuration = new Histogram({
   name: "mcp_tool_duration_seconds",
   help: "MCP tool execution latency in seconds",
   labelNames: ["tool"],
-  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30],
+  buckets: LATENCY_BUCKETS,
   registers: [registry]
 });
 var oauthTokenRefresh = new Counter({
@@ -44,7 +45,7 @@ var httpClientDuration = new Histogram({
   name: "http_client_duration_seconds",
   help: "Outbound HTTP request latency in seconds",
   labelNames: ["host", "endpoint"],
-  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+  buckets: LATENCY_BUCKETS,
   registers: [registry]
 });
 

package/dist/{chunk-EY5K2UXG.js → chunk-PLFBTSKM.js}

@@ -5,7 +5,7 @@ import {
 import {
   httpClientDuration,
   httpClientRequests
-} from "./chunk-RUFCT6DQ.js";
+} from "./chunk-DIPROABB.js";
 
 // src/config.ts
 function buildExtraHeaders() {

package/dist/{chunk-DKOQXKKG.js → chunk-ZVOHKRNC.js}

@@ -12,7 +12,7 @@ import {
 import {
   mcpToolCalls,
   mcpToolDuration
-} from "./chunk-RUFCT6DQ.js";
+} from "./chunk-DIPROABB.js";
 
 // src/tools/index.ts
 import { z } from "zod";
@@ -21,7 +21,29 @@ var toolHooks = null;
 var MAX_FILTER_PAGES = 5;
 var FILTER_PAGE_SIZE = 100;
 var TRANSCRIPT_PAGE_SIZE = 50;
-var TRANSCRIPT_BLOCKS = ["transaction", "outline", "transaction_polish"];
+var TRANSCRIPT_BLOCKS = ["transaction", "outline", "transaction_polish", "mark_memo"];
+var BLOCK_ITEMS_KEY = { mark_memo: "marks" };
+function linkBackedTypes(list) {
+  return (list ?? []).filter(
+    (b) => !(typeof b.data_content === "string" && b.data_content.length > 0) && typeof b.data_link === "string" && b.data_link.length > 0
+  ).map((b) => typeof b.data_type === "string" ? b.data_type : "(untyped)");
+}
+async function resolveNotes(noteList) {
+  return Promise.all(
+    noteList.map(async (note) => {
+      if (typeof note.data_content === "string" && note.data_content.length > 0) return note;
+      if (typeof note.data_link !== "string" || note.data_link.length === 0) return note;
+      try {
+        return { ...note, data_content: await loadBlockContent(note) };
+      } catch (err) {
+        return {
+          ...note,
+          data_content_error: err instanceof Error ? err.message : "Failed to fetch content from data_link"
+        };
+      }
+    })
+  );
+}
 function encodeTranscriptCursor(offset) {
   return Buffer.from(JSON.stringify({ o: offset }), "utf8").toString("base64url");
 }
@@ -175,6 +197,18 @@ function registerTools(server, client, hooks) {
           const synced = !!(file.duration || file.source_list && file.source_list.length);
           text += synced ? "\n\nNote: `presigned_url` (audio download URL) is null for this otherwise-synced recording. This is usually a transient backend signing issue \u2014 retry get_file in a few minutes to obtain the URL." : "\n\nNote: `presigned_url` (audio download URL) is null \u2014 audio may not yet be available for this recording.";
         }
+        const linkedBlocks = linkBackedTypes(file.source_list);
+        const linkedNotes = linkBackedTypes(file.note_list);
+        if (linkedBlocks.length) {
+          text += `
+
+Note: source_list ${linkedBlocks.map((t) => `\`${t}\``).join(", ")} returned an empty \`data_content\` \u2014 the body lives behind \`data_link\`, not missing. Call get_transcript with the matching \`block\` to read it (it fetches the link).`;
+        }
+        if (linkedNotes.length) {
+          text += `
+
+Note: note_list ${linkedNotes.map((t) => `\`${t}\``).join(", ")} returned an empty \`data_content\` \u2014 the body lives behind \`data_link\`, not missing. Call get_note to read it (it fetches the link).`;
+        }
         recordToolMetric("get_file", "success", Date.now() - start, requestId, { file_id });
         logger.info({ event: "tool_call_end", tool: "get_file", duration_ms: Date.now() - start, presigned_url_present: !!file.presigned_url });
         return { content: [{ type: "text", text }] };
@@ -188,7 +222,7 @@ function registerTools(server, client, hooks) {
   server.registerTool(
     "get_note",
     {
-      description: "Fetch AI-generated notes for a Plaud recording \u2014 compact summary, action items, and key topics",
+      description: "Fetch the notes on a Plaud recording \u2014 one entry per tab in the app, so usually more than one: the AI summary (action items, key topics), any template tab, a saved Ask Plaud answer, and the highlights note when the user pressed the highlight button while recording.",
       annotations: {
         title: "Get recording notes",
         readOnlyHint: true,
@@ -203,9 +237,10 @@ function registerTools(server, client, hooks) {
       const requestId = emitToolClick("get_note", { file_id });
       try {
         const file = await client.getFile(file_id);
+        const notes = await resolveNotes(file.note_list ?? []);
         recordToolMetric("get_note", "success", Date.now() - start, requestId, { file_id });
-        logger.info({ event: "tool_call_end", tool: "get_note", duration_ms: Date.now() - start });
-        return { content: [{ type: "text", text: JSON.stringify(file.note_list ?? [], null, 2) }] };
+        logger.info({ event: "tool_call_end", tool: "get_note", duration_ms: Date.now() - start, notes: notes.length });
+        return { content: [{ type: "text", text: JSON.stringify(notes, null, 2) }] };
       } catch (err) {
         recordToolMetric("get_note", "error", Date.now() - start, requestId, { file_id }, err);
         logger.error({ event: "tool_call_error", tool: "get_note", duration_ms: Date.now() - start, error: String(err) });
@@ -216,7 +251,7 @@ function registerTools(server, client, hooks) {
   server.registerTool(
     "get_transcript",
     {
-      description: "Fetch the timestamped transcript with speaker attribution for a Plaud recording. Defaults to the `transaction` block (real speaker names + timestamps), returned one page of utterances at a time to stay within client size limits \u2014 call again with the returned `next_cursor` to fetch the next page. Set `block` to `outline` or `transaction_polish` to fetch those blocks instead.",
+      description: "Fetch the timestamped transcript with speaker attribution for a Plaud recording. Defaults to the `transaction` block (real speaker names + timestamps), returned one page of utterances at a time to stay within client size limits \u2014 call again with the returned `next_cursor` to fetch the next page. Set `block` to `outline`, `transaction_polish`, or `mark_memo` (the moments the user flagged with the device's highlight button) to fetch those blocks instead.",
       annotations: {
         title: "Get recording transcript",
         readOnlyHint: true,
@@ -226,10 +261,10 @@ function registerTools(server, client, hooks) {
       inputSchema: {
         file_id: z.string().describe("The file ID to retrieve transcript for"),
         block: z.enum(TRANSCRIPT_BLOCKS).optional().describe(
-          "Which source block to fetch: `transaction` (default; raw transcript, speaker + timestamps), `transaction_polish` (AI-cleaned transcript; same per-utterance shape, keeps speaker + timestamps), or `outline`."
+          "Which source block to fetch: `transaction` (default; raw transcript, speaker + timestamps), `transaction_polish` (AI-cleaned transcript; same per-utterance shape, keeps speaker + timestamps), `outline`, or `mark_memo` (highlights: the moments flagged by pressing the button on the device during recording; present only when the button was pressed, and returned under `marks`). Pair `mark_memo` with a `transaction` call to map each flagged moment onto what was said there."
         ),
         cursor: z.string().optional().describe("Opaque pagination cursor from a previous call's `next_cursor`. Omit to start from the first utterance."),
-        limit: z.number().int().min(1).max(500).optional().describe(`Max utterances to return in this page (default ${TRANSCRIPT_PAGE_SIZE}). Only applies to blocks returned as an utterance list.`)
+        limit: z.number().int().min(1).max(500).optional().describe(`Max items to return in this page (default ${TRANSCRIPT_PAGE_SIZE}). Only applies to list-shaped blocks.`)
       }
     },
     async ({ file_id, block, cursor, limit }) => {
@@ -267,7 +302,7 @@ function registerTools(server, client, hooks) {
         if (!segments) {
           recordToolMetric("get_transcript", "success", Date.now() - start, requestId, { file_id });
           logger.info({ event: "tool_call_end", tool: "get_transcript", duration_ms: Date.now() - start, block: blockType, paginated: false });
-          const text = content || `Block "${blockType}" has no content for this recording yet.`;
+          const text = content || (blockType === "mark_memo" ? "This recording has a highlights block, but it is empty \u2014 no highlight was recorded." : `Block "${blockType}" has no content for this recording yet.`);
           return { content: [{ type: "text", text }] };
         }
         let offset = 0;
@@ -295,7 +330,7 @@ function registerTools(server, client, hooks) {
           limit: pageSize,
           returned: page.length,
           next_cursor: hasMore ? encodeTranscriptCursor(nextOffset) : null,
-          segments: page
+          [BLOCK_ITEMS_KEY[blockType] ?? "segments"]: page
         };
         recordToolMetric("get_transcript", "success", Date.now() - start, requestId, { file_id });
         logger.info({ event: "tool_call_end", tool: "get_transcript", duration_ms: Date.now() - start, block: blockType, paginated: true, total: segments.length, offset, returned: page.length });

package/dist/index.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import {
   getClient
-} from "./chunk-EY5K2UXG.js";
+} from "./chunk-PLFBTSKM.js";
 import {
   loadSkills
 } from "./chunk-242FRP4P.js";
 import {
   normalizeMcpHost,
   registerTools
-} from "./chunk-DKOQXKKG.js";
+} from "./chunk-ZVOHKRNC.js";
 import {
   capture,
   classifyError,
@@ -23,7 +23,7 @@ import {
   shutdown
 } from "./chunk-5NWKLF3V.js";
 import "./chunk-NPCCDRWQ.js";
-import "./chunk-RUFCT6DQ.js";
+import "./chunk-DIPROABB.js";
 
 // src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -31,7 +31,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import open from "open";
 var server = new McpServer({
   name: "plaud",
-  version: "0.3.8"
+  version: "0.3.10"
 });
 var CALLBACK_PORT = 8199;
 var LOGIN_TIMEOUT_MS = 12e4;
@@ -158,7 +158,7 @@ async function main() {
   const sub = process.argv[2];
   const sub2 = process.argv[3];
   if (sub === "install") {
-    const { runInstall } = await import("./install-RTIXREYV.js");
+    const { runInstall } = await import("./install-SWKIKJ5C.js");
     const args = process.argv.slice(3);
     const yes = args.some((a) => a === "--yes" || a === "-y");
     const noLogin = args.some((a) => a === "--no-login");
@@ -191,8 +191,8 @@ async function main() {
     return;
   }
   if (sub === "http") {
-    const { startHttpServer } = await import("./server-VJAFEGJ6.js");
-    const { startMetricsServer } = await import("./server-NKCNUA6P.js");
+    const { startHttpServer } = await import("./server-SB6RRGY7.js");
+    const { startMetricsServer } = await import("./server-6RAC6S7E.js");
     startMetricsServer();
     startHttpServer();
     return;
@@ -217,7 +217,7 @@ Usage:
   try {
     await initTelemetry({
       surface: "mcp",
-      appVersion: "0.3.8",
+      appVersion: "0.3.10",
       transport: "stdio"
     });
   } catch {

package/dist/{install-RTIXREYV.js → install-SWKIKJ5C.js}

@@ -1,6 +1,6 @@
 import {
   getClient
-} from "./chunk-EY5K2UXG.js";
+} from "./chunk-PLFBTSKM.js";
 import {
   commandPathIsStale,
   copyToClipboard,
@@ -13,7 +13,7 @@ import {
 import {
   runOAuthCallback
 } from "./chunk-5NWKLF3V.js";
-import "./chunk-RUFCT6DQ.js";
+import "./chunk-DIPROABB.js";
 
 // src/install.ts
 import { createInterface } from "readline/promises";

package/dist/{server-NKCNUA6P.js → server-6RAC6S7E.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-NPCCDRWQ.js";
 import {
   registry
-} from "./chunk-RUFCT6DQ.js";
+} from "./chunk-DIPROABB.js";
 
 // src/metrics/server.ts
 import express from "express";

package/dist/{server-VJAFEGJ6.js → server-SB6RRGY7.js}

@@ -1,9 +1,10 @@
 import {
   normalizeMcpHost,
   registerTools
-} from "./chunk-DKOQXKKG.js";
+} from "./chunk-ZVOHKRNC.js";
 import {
-  PlaudClient
+  PlaudClient,
+  classifyError
 } from "./chunk-5NWKLF3V.js";
 import {
   logger
@@ -12,12 +13,12 @@ import {
   httpRequestDuration,
   httpRequestsInProgress,
   oauthTokenRefresh
-} from "./chunk-RUFCT6DQ.js";
+} from "./chunk-DIPROABB.js";
 
 // src/http/server.ts
 import express from "express";
 import { createServer } from "http";
-import { randomUUID as randomUUID3 } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { createOAuthMetadata, mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
@@ -25,12 +26,13 @@ import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middlew
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
 
 // src/http/oauth-provider.ts
-import { createCipheriv, createDecipheriv, createHmac, randomBytes, randomUUID, timingSafeEqual } from "crypto";
+import { createCipheriv, createDecipheriv, createHash as createHash2, createHmac, randomBytes, timingSafeEqual } from "crypto";
 import { ProxyOAuthServerProvider } from "@modelcontextprotocol/sdk/server/auth/providers/proxyProvider.js";
 import {
   InvalidGrantError,
   InvalidTokenError,
-  ServerError as McpServerError
+  ServerError as McpServerError,
+  TooManyRequestsError
 } from "@modelcontextprotocol/sdk/server/auth/errors.js";
 
 // src/http/cimd.ts
@@ -266,6 +268,245 @@ function validateMetadata(parsed, expectedClientIdUrl) {
   };
 }
 
+// src/http/token-verifier.ts
+import { createHash } from "crypto";
+function decodeJwtClaims(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const payload = parts[1];
+  if (!payload) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    if (!parsed || typeof parsed !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function sha256(value) {
+  return createHash("sha256").update(value).digest("base64url");
+}
+var Lru = class {
+  constructor(max) {
+    this.max = max;
+  }
+  max;
+  map = /* @__PURE__ */ new Map();
+  get(key) {
+    const value = this.map.get(key);
+    if (value === void 0) return void 0;
+    this.map.delete(key);
+    this.map.set(key, value);
+    return value;
+  }
+  set(key, value) {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    } else if (this.map.size >= this.max) {
+      const oldest = this.map.keys().next().value;
+      if (oldest !== void 0) this.map.delete(oldest);
+    }
+    this.map.set(key, value);
+  }
+  delete(key) {
+    this.map.delete(key);
+  }
+  get size() {
+    return this.map.size;
+  }
+};
+var TokenBucket = class {
+  constructor(capacity, refillPerSec, nowMs) {
+    this.capacity = capacity;
+    this.refillPerSec = refillPerSec;
+    this.tokens = capacity;
+    this.lastRefillMs = nowMs;
+  }
+  capacity;
+  refillPerSec;
+  tokens;
+  lastRefillMs;
+  take(nowMs) {
+    const elapsedSec = (nowMs - this.lastRefillMs) / 1e3;
+    if (elapsedSec > 0) {
+      this.tokens = Math.min(this.capacity, this.tokens + elapsedSec * this.refillPerSec);
+      this.lastRefillMs = nowMs;
+    }
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return true;
+    }
+    return false;
+  }
+};
+var DEFAULTS = {
+  cacheMaxEntries: 5e3,
+  positiveTtlMs: 6e4,
+  negativeTtlMs: 3e4,
+  strangerBurst: 40,
+  strangerRatePerSec: 20,
+  knownBurst: 10,
+  knownRatePerSec: 5,
+  knownSubMaxEntries: 2e4
+};
+var TokenVerifier = class {
+  cache;
+  subBuckets;
+  strangerBucket;
+  opts;
+  constructor(options) {
+    const now = options.now ?? (() => Date.now());
+    this.opts = {
+      verifyUpstream: options.verifyUpstream,
+      cacheEnabled: options.cacheEnabled ?? true,
+      cacheMaxEntries: options.cacheMaxEntries ?? DEFAULTS.cacheMaxEntries,
+      positiveTtlMs: options.positiveTtlMs ?? DEFAULTS.positiveTtlMs,
+      negativeTtlMs: options.negativeTtlMs ?? DEFAULTS.negativeTtlMs,
+      strangerBurst: options.strangerBurst ?? DEFAULTS.strangerBurst,
+      strangerRatePerSec: options.strangerRatePerSec ?? DEFAULTS.strangerRatePerSec,
+      knownBurst: options.knownBurst ?? DEFAULTS.knownBurst,
+      knownRatePerSec: options.knownRatePerSec ?? DEFAULTS.knownRatePerSec,
+      knownSubMaxEntries: options.knownSubMaxEntries ?? DEFAULTS.knownSubMaxEntries,
+      now
+    };
+    this.cache = new Lru(this.opts.cacheMaxEntries);
+    this.subBuckets = new Lru(this.opts.knownSubMaxEntries);
+    this.strangerBucket = new TokenBucket(
+      this.opts.strangerBurst,
+      this.opts.strangerRatePerSec,
+      now()
+    );
+  }
+  /**
+   * Seeds the cache with a token that was just minted upstream (OAuth code
+   * exchange or refresh).
+   *
+   * This is what keeps normal users out of the rate-limit tier entirely: their
+   * first request after logging in or rotating a token is already a cache hit,
+   * so it never draws from the budget that unrecognised tokens consume.
+   *
+   * clientId is taken from the JWT `sub` rather than the upstream user.id: we
+   * have not called upstream at this point and do not need to, since the token
+   * came straight from the token endpoint. Downstream only uses clientId for
+   * logging, and server.ts derives ctxUserId from `sub` first anyway.
+   */
+  prewarm(token) {
+    if (!this.opts.cacheEnabled) return;
+    const claims = decodeJwtClaims(token);
+    if (!claims) return;
+    const sub = typeof claims.sub === "string" ? claims.sub : void 0;
+    const exp = typeof claims.exp === "number" ? claims.exp : void 0;
+    if (!sub) return;
+    const nowMs = this.opts.now();
+    const expiresAt = exp ?? Math.floor(nowMs / 1e3) + 3600;
+    this.putPositive(sha256(token), sub, expiresAt, nowMs);
+    this.noteKnownSub(sub, nowMs);
+    logger.info({ event: "token_prewarmed", cache_size: this.cache.size });
+  }
+  async verify(token) {
+    const nowMs = this.opts.now();
+    const nowSec = Math.floor(nowMs / 1e3);
+    const claims = decodeJwtClaims(token);
+    if (!claims) {
+      logger.warn({ event: "token_rejected_local", reason: "malformed" });
+      return { ok: false, kind: "malformed" };
+    }
+    const sub = typeof claims.sub === "string" && claims.sub ? claims.sub : void 0;
+    const exp = typeof claims.exp === "number" ? claims.exp : void 0;
+    if (exp !== void 0 && exp <= nowSec) {
+      logger.warn({ event: "token_rejected_local", reason: "expired" });
+      return { ok: false, kind: "expired" };
+    }
+    const key = sha256(token);
+    if (this.opts.cacheEnabled) {
+      const hit = this.cache.get(key);
+      if (hit && hit.cacheExpiresAtMs > nowMs) {
+        return hit.valid ? { ok: true, clientId: hit.clientId, expiresAt: hit.expiresAt, source: "cache" } : { ok: false, kind: "invalid" };
+      }
+      if (hit) this.cache.delete(key);
+    }
+    const looksKnown = sub !== void 0 && sub.startsWith("client_user_");
+    const bucket = sub !== void 0 && looksKnown ? this.subBuckets.get(sub) : void 0;
+    const allowed = bucket ? bucket.take(nowMs) : this.strangerBucket.take(nowMs);
+    if (!allowed) {
+      logger.warn({
+        event: "token_verify_rate_limited",
+        scope: bucket ? "known_sub" : "stranger"
+      });
+      return { ok: false, kind: "rate_limited" };
+    }
+    const verdict = await this.opts.verifyUpstream(token);
+    if (verdict.kind === "valid") {
+      const expiresAt = exp ?? nowSec + 3600;
+      if (this.opts.cacheEnabled) this.putPositive(key, verdict.clientId, expiresAt, nowMs);
+      if (sub !== void 0) this.noteKnownSub(sub, nowMs);
+      logger.info({ event: "token_verified", client_id: verdict.clientId, expires_at: expiresAt });
+      return { ok: true, clientId: verdict.clientId, expiresAt, source: "upstream" };
+    }
+    if (verdict.kind === "invalid") {
+      if (this.opts.cacheEnabled) {
+        this.cache.set(key, {
+          valid: false,
+          clientId: "",
+          expiresAt: 0,
+          cacheExpiresAtMs: nowMs + this.opts.negativeTtlMs
+        });
+      }
+      logger.warn({ event: "token_verify_failed", reason: "invalid" });
+      return { ok: false, kind: "invalid" };
+    }
+    logger.error({ event: "token_verify_unavailable", reason: verdict.reason });
+    return { ok: false, kind: "unavailable" };
+  }
+  /** For /health and metrics — counts only, no tokens or user identifiers. */
+  stats() {
+    return {
+      cacheSize: this.cache.size,
+      knownSubs: this.subBuckets.size,
+      cacheEnabled: this.opts.cacheEnabled
+    };
+  }
+  putPositive(key, clientId, expiresAt, nowMs) {
+    const remainingMs = expiresAt * 1e3 - nowMs;
+    const ttlMs = Math.min(this.opts.positiveTtlMs, Math.max(0, remainingMs));
+    if (ttlMs <= 0) return;
+    this.cache.set(key, { valid: true, clientId, expiresAt, cacheExpiresAtMs: nowMs + ttlMs });
+  }
+  noteKnownSub(sub, nowMs) {
+    if (this.subBuckets.get(sub) === void 0) {
+      this.subBuckets.set(
+        sub,
+        new TokenBucket(this.opts.knownBurst, this.opts.knownRatePerSec, nowMs)
+      );
+    }
+  }
+};
+function tokenVerifierOptionsFromEnv() {
+  const num = (name, fallback) => {
+    const raw = process.env[name];
+    if (raw === void 0 || raw === "") return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+      logger.warn({ event: "token_verifier_bad_env", name, value: raw, using: fallback });
+      return fallback;
+    }
+    return parsed;
+  };
+  return {
+    cacheEnabled: !["0", "false", "no", "off"].includes(
+      (process.env["PLAUD_TOKEN_CACHE_ENABLED"] ?? "").toLowerCase()
+    ),
+    cacheMaxEntries: num("PLAUD_TOKEN_CACHE_MAX", DEFAULTS.cacheMaxEntries),
+    positiveTtlMs: num("PLAUD_TOKEN_CACHE_TTL_MS", DEFAULTS.positiveTtlMs),
+    negativeTtlMs: num("PLAUD_TOKEN_NEGATIVE_TTL_MS", DEFAULTS.negativeTtlMs),
+    strangerBurst: num("PLAUD_TOKEN_VERIFY_BURST", DEFAULTS.strangerBurst),
+    strangerRatePerSec: num("PLAUD_TOKEN_VERIFY_RATE", DEFAULTS.strangerRatePerSec),
+    knownBurst: num("PLAUD_TOKEN_KNOWN_BURST", DEFAULTS.knownBurst),
+    knownRatePerSec: num("PLAUD_TOKEN_KNOWN_RATE", DEFAULTS.knownRatePerSec),
+    knownSubMaxEntries: num("PLAUD_TOKEN_KNOWN_SUB_MAX", DEFAULTS.knownSubMaxEntries)
+  };
+}
+
 // src/http/oauth-provider.ts
 function subFromJwt(token) {
   if (!token) return void 0;
@@ -276,10 +517,33 @@ function subFromJwt(token) {
     return void 0;
   }
 }
+var AUTO_RECOVERED_CLIENT_NAME = "auto-recovered client";
+var REDIRECT_HOST_CLIENT_NAMES = {
+  "chatgpt.com": "chatgpt",
+  "openai.com": "chatgpt",
+  "claude.ai": "claude",
+  "claude.com": "claude"
+};
+function clientNameFromRedirectUri(redirectUri) {
+  if (!redirectUri) return void 0;
+  let host;
+  try {
+    host = new URL(redirectUri).hostname.toLowerCase().replace(/^www\./, "");
+  } catch {
+    return void 0;
+  }
+  if (!host) return void 0;
+  for (const [domain, name] of Object.entries(REDIRECT_HOST_CLIENT_NAMES)) {
+    if (host === domain || host.endsWith(`.${domain}`)) return name;
+  }
+  return host;
+}
 var DEFAULT_TOKEN_URL = "https://platform.plaud.ai/developer/api/oauth/third-party/access-token";
 var DEFAULT_REFRESH_URL = "https://platform.plaud.ai/developer/api/oauth/third-party/access-token/refresh";
 var STATELESS_CODE_PREFIX = "pc1_";
 var AUTHORIZATION_CODE_TTL_MS = 10 * 60 * 1e3;
+var STATELESS_STATE_PREFIX = "st1_";
+var AUTHORIZATION_STATE_TTL_MS = 30 * 60 * 1e3;
 function urlParts(value) {
   if (!value || !URL.canParse(value)) {
     return { host: null, path: null };
@@ -297,57 +561,73 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
   _debugOAuthLogs;
   _cimdLoader;
   _tracker;
+  /** Local pre-checks + cache + tiered rate limit + upstream call, all in one
+   *  place. See token-verifier.ts. */
+  _verifier;
   _registeredClients = /* @__PURE__ */ new Map();
   // HMAC secret used to sign DCR-issued client_ids so we can recover them
   // across container restarts without persistent storage. See verifyAndRecover.
   _clientIdSecret;
-  // internalState → client redirect, original client state, and resource indicator
-  // We generate our own state to track the pending flow regardless of whether the client sent one.
-  _pendingStates = /* @__PURE__ */ new Map();
+  // NOTE: there is deliberately no in-process store for pending authorizations.
+  // This class used to keep `_pendingStates: Map<state, {clientRedirectUri, …}>`,
+  // which meant /authorize and /auth/callback had to be served by the same
+  // process — the callback looked the state up and hard-failed with 400 if it
+  // wasn't there. That single map is what pinned the deployment to one replica
+  // (and it was never swept, so abandoned authorizations accumulated for the
+  // lifetime of the pod). The state parameter is now a sealed, self-contained
+  // envelope instead; see encodeAuthorizationState.
+  //
+  // Everything else here was already replica-safe: client_ids are HMAC-signed
+  // and recoverable (verifyAndRecover), and authorization codes are sealed the
+  // same way. This was the last piece holding it back.
   constructor(options) {
     const authUrl = options.authUrl ?? "https://web.plaud.ai/platform/oauth";
     const tokenUrl = options.tokenUrl ?? DEFAULT_TOKEN_URL;
     const refreshUrl = options.refreshUrl ?? DEFAULT_REFRESH_URL;
     const apiBase = options.apiBase ?? "https://platform.plaud.ai/developer/api";
+    const holder = {};
+    const verifyUpstream = async (token) => {
+      const client = new PlaudClient({
+        clientId: options.clientId,
+        clientSecret: "",
+        redirectUri: "",
+        apiBase,
+        staticToken: token
+      });
+      try {
+        const user = await client.getCurrentUser();
+        return { kind: "valid", clientId: String(user.id ?? "unknown") };
+      } catch (err) {
+        const type = classifyError(err);
+        if (type === "auth") return { kind: "invalid" };
+        return { kind: "unavailable", reason: type };
+      }
+    };
     super({
       endpoints: {
         authorizationUrl: authUrl,
         tokenUrl
       },
       verifyAccessToken: async (token) => {
-        const client = new PlaudClient({
-          clientId: options.clientId,
-          clientSecret: "",
-          redirectUri: "",
-          apiBase,
-          staticToken: token
-        });
-        try {
-          const user = await client.getCurrentUser();
-          let expiresAt;
-          try {
-            const payload = JSON.parse(
-              Buffer.from(token.split(".")[1], "base64url").toString()
-            );
-            expiresAt = typeof payload.exp === "number" ? payload.exp : Math.floor(Date.now() / 1e3) + 3600;
-          } catch {
-            expiresAt = Math.floor(Date.now() / 1e3) + 3600;
-          }
-          const authInfo = {
-            token,
-            clientId: String(user.id ?? "unknown"),
-            scopes: [],
-            expiresAt
-          };
-          logger.info({ event: "token_verified", client_id: authInfo.clientId, expires_at: expiresAt });
-          return authInfo;
-        } catch (err) {
-          logger.warn({ event: "token_verify_failed", error: String(err) });
-          throw new InvalidTokenError("Invalid or expired token");
+        const verifier = holder.verifier;
+        if (!verifier) throw new McpServerError("Token verifier not initialised");
+        const outcome = await verifier.verify(token);
+        if (outcome.ok) {
+          return { token, clientId: outcome.clientId, scopes: [], expiresAt: outcome.expiresAt };
+        }
+        switch (outcome.kind) {
+          case "unavailable":
+            throw new McpServerError("Upstream token verification temporarily unavailable");
+          case "rate_limited":
+            throw new TooManyRequestsError("Token verification rate limited");
+          default:
+            throw new InvalidTokenError("Invalid or expired token");
         }
       },
       getClient: async (id) => this._registeredClients.get(id)
     });
+    holder.verifier = new TokenVerifier({ ...tokenVerifierOptionsFromEnv(), verifyUpstream });
+    this._verifier = holder.verifier;
     this._plaudClientId = options.clientId;
     this._plaudClientSecret = options.clientSecret ?? "";
     this._plaudTokenUrl = tokenUrl;
@@ -369,6 +649,10 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
     }
     this.skipLocalPkceValidation = true;
   }
+  /** For /health and metrics — counts only, no tokens or user identifiers. */
+  get verifierStats() {
+    return this._verifier.stats();
+  }
   // Override clientsStore. registerClient signs the issued client_id with HMAC
   // so verifyAndRecover can later resurrect it across container restarts.
   get clientsStore() {
@@ -474,49 +758,116 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
     if (actual.length !== expected.length) return false;
     return timingSafeEqual(actual, expected);
   }
-  authorizationCodeKey() {
-    return createHmac("sha256", this._clientIdSecret).update("plaud-mcp-authorization-code").digest();
+  // Key is derived per purpose so a value sealed for one hop can never be
+  // unsealed as the other — an authorization code presented as a state (or vice
+  // versa) fails the GCM tag check rather than decoding into the wrong shape.
+  envelopeKey(purpose) {
+    return createHmac("sha256", this._clientIdSecret).update(purpose).digest();
   }
-  encodeAuthorizationCode(payload) {
+  // AES-256-GCM envelope: prefix + base64url(iv[12] | tag[16] | ciphertext).
+  // Self-contained, so any pod can open what any other pod sealed — that is what
+  // lets us run more than one replica without a shared store.
+  seal(purpose, prefix, payload, ttlMs) {
     const iv = randomBytes(12);
-    const cipher = createCipheriv("aes-256-gcm", this.authorizationCodeKey(), iv);
-    const plaintext = Buffer.from(JSON.stringify({
-      upstreamCode: payload.upstreamCode,
-      upstreamState: payload.upstreamState,
-      resource: payload.resource,
-      expiresAt: Date.now() + AUTHORIZATION_CODE_TTL_MS
-    }), "utf8");
+    const cipher = createCipheriv("aes-256-gcm", this.envelopeKey(purpose), iv);
+    const plaintext = Buffer.from(
+      JSON.stringify({ ...payload, expiresAt: Date.now() + ttlMs }),
+      "utf8"
+    );
     const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
     const tag = cipher.getAuthTag();
-    return `${STATELESS_CODE_PREFIX}${Buffer.concat([iv, tag, ciphertext]).toString("base64url")}`;
+    return `${prefix}${Buffer.concat([iv, tag, ciphertext]).toString("base64url")}`;
   }
-  decodeAuthorizationCode(code) {
-    if (!code.startsWith(STATELESS_CODE_PREFIX)) return null;
+  // Returns null for anything that isn't ours, has been tampered with, or has
+  // expired. Callers still validate the payload's own shape.
+  unseal(purpose, prefix, value) {
+    if (typeof value !== "string" || !value.startsWith(prefix)) return null;
     try {
-      const encoded = code.slice(STATELESS_CODE_PREFIX.length);
-      const data = Buffer.from(encoded, "base64url");
+      const data = Buffer.from(value.slice(prefix.length), "base64url");
       if (data.length <= 28) return null;
-      const iv = data.subarray(0, 12);
-      const tag = data.subarray(12, 28);
-      const ciphertext = data.subarray(28);
-      const decipher = createDecipheriv("aes-256-gcm", this.authorizationCodeKey(), iv);
-      decipher.setAuthTag(tag);
-      const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+      const decipher = createDecipheriv("aes-256-gcm", this.envelopeKey(purpose), data.subarray(0, 12));
+      decipher.setAuthTag(data.subarray(12, 28));
+      const plaintext = Buffer.concat([
+        decipher.update(data.subarray(28)),
+        decipher.final()
+      ]).toString("utf8");
       const payload = JSON.parse(plaintext);
-      if (typeof payload.upstreamCode !== "string" || typeof payload.upstreamState !== "string" || payload.resource !== void 0 && typeof payload.resource !== "string" || typeof payload.expiresAt !== "number") {
-        return null;
-      }
-      if (Date.now() > payload.expiresAt) {
+      if (typeof payload["expiresAt"] !== "number" || Date.now() > payload["expiresAt"]) {
         return null;
       }
-      return {
+      return payload;
+    } catch {
+      return null;
+    }
+  }
+  encodeAuthorizationCode(payload) {
+    return this.seal(
+      "plaud-mcp-authorization-code",
+      STATELESS_CODE_PREFIX,
+      {
         upstreamCode: payload.upstreamCode,
         upstreamState: payload.upstreamState,
         resource: payload.resource
-      };
-    } catch {
+      },
+      AUTHORIZATION_CODE_TTL_MS
+    );
+  }
+  decodeAuthorizationCode(code) {
+    const payload = this.unseal(
+      "plaud-mcp-authorization-code",
+      STATELESS_CODE_PREFIX,
+      code
+    );
+    if (!payload) return null;
+    if (typeof payload.upstreamCode !== "string" || typeof payload.upstreamState !== "string" || payload.resource !== void 0 && typeof payload.resource !== "string") {
       return null;
     }
+    return {
+      upstreamCode: payload.upstreamCode,
+      upstreamState: payload.upstreamState,
+      resource: payload.resource
+    };
+  }
+  // The authorize→callback hop. Everything the callback needs travels inside the
+  // state parameter itself, so the pod that handles the callback need not be the
+  // pod that started the flow. This is what replaced the in-process
+  // _pendingStates map — see the class docstring for why that map capped us at
+  // one replica.
+  encodeAuthorizationState(payload) {
+    return this.seal(
+      "plaud-mcp-authorization-state",
+      STATELESS_STATE_PREFIX,
+      {
+        clientRedirectUri: payload.clientRedirectUri,
+        originalState: payload.originalState,
+        resource: payload.resource
+      },
+      AUTHORIZATION_STATE_TTL_MS
+    );
+  }
+  // Stable short handle for correlating authorize and callback log lines.
+  // Not a secret and not reversible — purely a join key for reading logs.
+  stateHandle(state) {
+    if (typeof state !== "string") return "non-string";
+    return createHash2("sha256").update(state).digest("base64url").slice(0, 12);
+  }
+  decodeAuthorizationState(state) {
+    const payload = this.unseal(
+      "plaud-mcp-authorization-state",
+      STATELESS_STATE_PREFIX,
+      state
+    );
+    if (!payload) return null;
+    if (typeof payload.clientRedirectUri !== "string" || !URL.canParse(payload.clientRedirectUri)) {
+      return null;
+    }
+    if (payload.originalState !== void 0 && typeof payload.originalState !== "string") return null;
+    if (payload.resource !== void 0 && typeof payload.resource !== "string") return null;
+    return {
+      clientRedirectUri: payload.clientRedirectUri,
+      originalState: payload.originalState,
+      resource: payload.resource
+    };
   }
   // Recover a client_id that the registry doesn't know about. Directory clients
   // (OpenAI Apps, Claude directory) cache the client_id they got from /register;
@@ -532,12 +883,25 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
       if (redirectUri && !existing.redirect_uris.includes(redirectUri)) {
         existing.redirect_uris = [...existing.redirect_uris, redirectUri];
       }
+      if (existing.client_name === AUTO_RECOVERED_CLIENT_NAME) {
+        const upgradedName = clientNameFromRedirectUri(redirectUri);
+        if (upgradedName) {
+          existing.client_name = upgradedName;
+          logger.info({
+            event: "oauth_client_name_upgraded",
+            client_id: clientId,
+            name_source: "redirect_uri",
+            mcp_host: normalizeMcpHost(upgradedName) ?? null
+          });
+        }
+      }
       return true;
     }
     if (!this.verifyClientIdSignature(clientId)) {
       return false;
     }
     const recoveredName = this.decodeClientName(clientId);
+    const derivedName = recoveredName ?? clientNameFromRedirectUri(redirectUri);
     this._registeredClients.set(clientId, {
       client_id: clientId,
       client_id_issued_at: Math.floor(Date.now() / 1e3),
@@ -545,13 +909,20 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
       grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
       token_endpoint_auth_method: "none",
-      client_name: recoveredName ?? "auto-recovered client"
+      client_name: derivedName ?? AUTO_RECOVERED_CLIENT_NAME
     });
     logger.info({
       event: "oauth_client_recovered",
       client_id: clientId,
       redirect_uri: redirectUri ?? null,
-      name_recovered: recoveredName != null
+      // Unchanged semantics: true only when the name came out of the client_id
+      // itself — this is the field used to verify the #72 fix in prod.
+      name_recovered: recoveredName != null,
+      name_source: recoveredName != null ? "client_id" : derivedName != null ? "redirect_uri" : null,
+      // The bucket this recovery will put on every downstream auth event. Lets us
+      // verify attribution straight from prod logs (the warehouse events are
+      // batched, so they're not a live signal), and enumerate real hosts.
+      mcp_host: normalizeMcpHost(derivedName) ?? null
     });
     return true;
   }
@@ -560,8 +931,7 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
    * Store the client's original redirect_uri keyed by state so we can forward after Plaud calls back.
    */
   async authorize(_client, params, res) {
-    const internalState = randomUUID();
-    this._pendingStates.set(internalState, {
+    const internalState = this.encodeAuthorizationState({
       clientRedirectUri: params.redirectUri,
       originalState: params.state,
       resource: params.resource?.href
@@ -569,7 +939,10 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
     const redirectParts = urlParts(params.redirectUri);
     logger.info({
       event: "oauth_authorize_start",
-      internal_state: internalState,
+      // Short digest, not the sealed blob — it is 300+ chars and would bloat
+      // every line. Same value appears on the matching callback, so the two
+      // still correlate.
+      state_handle: this.stateHandle(internalState),
       redirect_uri: params.redirectUri,
       ...this._debugOAuthLogs ? {
         redirect_uri_host: redirectParts.host,
@@ -577,7 +950,7 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
         has_original_state: !!params.state,
         has_resource: !!params.resource,
         resource: params.resource?.href ?? null,
-        pending_states_count: this._pendingStates.size
+        state_len: internalState.length
       } : {}
     });
     const targetUrl = new URL(this._endpoints.authorizationUrl);
@@ -600,18 +973,28 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
     res.redirect(targetUrl.toString());
   }
   /**
-   * Called when Plaud redirects to our /oauth/callback.
-   * Looks up the original client redirect_uri and forwards the code+state to it.
+   * Called when Plaud redirects to our /auth/callback (CALLBACK_PATH in
+   * http/server.ts). NOT /oauth/callback — this comment said so until 2026-08-19
+   * and a downstream client registration was configured from it by mistake.
+   * Opens the sealed state to recover the client's redirect_uri and forwards the
+   * code+state to it. No lookup — the state is the storage, which is what allows
+   * this to be served by a pod that never saw the /authorize request.
    */
   handleCallback(code, state, res) {
-    const pending = this._pendingStates.get(state);
+    const pending = this.decodeAuthorizationState(state);
     if (!pending) {
-      logger.warn({ event: "oauth_callback_unknown_state", state });
+      logger.warn({
+        event: "oauth_callback_unknown_state",
+        state_handle: this.stateHandle(state),
+        // typeof-guarded: this is the one log line reached by a request whose
+        // parameter shape we do not control.
+        state_len: typeof state === "string" ? state.length : null,
+        sealed_shape: typeof state === "string" && state.startsWith(STATELESS_STATE_PREFIX)
+      });
       res.status(400).send("Unknown state \u2014 authorization request not found");
       return;
     }
-    this._pendingStates.delete(state);
-    logger.info({ event: "oauth_callback_received", internal_state: state });
+    logger.info({ event: "oauth_callback_received", state_handle: this.stateHandle(state) });
     const pendingCode = {
       upstreamCode: code,
       upstreamState: state,
@@ -624,10 +1007,12 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
       target.searchParams.set("state", pending.originalState);
     }
     const redirectParts = urlParts(pending.clientRedirectUri);
+    const isCustomScheme = !/^https?:$/.test(new URL(target.toString()).protocol);
     logger.info({
       event: "oauth_callback_redirect",
-      internal_state: state,
+      state_handle: this.stateHandle(state),
       redirect_uri: pending.clientRedirectUri,
+      custom_scheme: isCustomScheme,
       has_original_state: !!pending.originalState,
       original_state_len: pending.originalState?.length ?? 0,
       upstream_code_len: code.length,
@@ -642,7 +1027,37 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
         redirect_has_state: target.searchParams.has("state")
       } : {}
     });
-    res.redirect(target.toString());
+    if (!isCustomScheme) {
+      res.redirect(target.toString());
+      return;
+    }
+    res.status(200).type("html").send(this.appHandoffPage(target.toString()));
+  }
+  // Landing page for native-app callbacks. The URL goes into a data attribute
+  // rather than inline JS so nothing from `clientRedirectUri` can be parsed as
+  // script; it is only ever assigned to location.href.
+  appHandoffPage(redirectUrl) {
+    const esc = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+    const href = esc(redirectUrl);
+    return `<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>\u6388\u6743\u6210\u529F \xB7 Plaud</title></head>
+<body style="font-family:system-ui,-apple-system,sans-serif;margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:#fafafa;color:#111">
+<main id="p" data-href="${href}" style="text-align:center;padding:2rem;max-width:28rem">
+  <div style="font-size:2.5rem;line-height:1">\u2713</div>
+  <h1 style="font-size:1.25rem;margin:.75rem 0 .5rem">\u6388\u6743\u6210\u529F</h1>
+  <p style="color:#666;margin:0 0 1.5rem">\u6B63\u5728\u8FD4\u56DE\u5E94\u7528\uFF0C\u53EF\u4EE5\u5173\u95ED\u6B64\u9875\u9762\u3002</p>
+  <p style="font-size:.875rem;color:#888;margin:0">
+    \u6CA1\u6709\u81EA\u52A8\u8DF3\u8F6C\uFF1F<a id="m" href="#" style="color:#0066cc">\u70B9\u6B64\u624B\u52A8\u6253\u5F00</a>
+  </p>
+</main>
+<script>
+  var u = document.getElementById("p").dataset.href;
+  document.getElementById("m").href = u;
+  location.href = u;
+</script>
+</body></html>`;
   }
   // Override to use PKCE public-client flow — no Basic auth, client_id sent in body.
   async exchangeAuthorizationCode(client, authorizationCode, codeVerifier, _redirectUri, resource) {
@@ -719,6 +1134,7 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
       throw new McpServerError("Token endpoint returned non-JSON response");
     }
     logger.info({ event: "oauth_token_exchange_ok", has_refresh_token: !!data.refresh_token });
+    this._verifier.prewarm(data.access_token);
     const authorizedUserId = subFromJwt(data.access_token);
     this._tracker?.track({
       name: "auth.oauth_callback_success",
@@ -791,6 +1207,7 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
       throw new McpServerError("Refresh endpoint returned non-JSON response");
     }
     oauthTokenRefresh.inc({ result: "success" });
+    this._verifier.prewarm(data.access_token);
     this._tracker?.track({
       name: "auth.token_refresh_success",
       actorType: "user",
@@ -813,7 +1230,7 @@ var PlaudOAuthProvider = class extends ProxyOAuthServerProvider {
 };
 
 // src/telemetry-server/tracker.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID } from "crypto";
 
 // src/telemetry-server/transport.ts
 import { PostHog } from "posthog-node";
@@ -975,7 +1392,7 @@ var WarehouseTracker = class {
       service_version: this.common.serviceVersion,
       ...this.common.buildId ? { build_id: this.common.buildId } : {},
       // timing / tracing
-      event_id: randomUUID2(),
+      event_id: randomUUID(),
       ...input.requestId ? { request_id: input.requestId } : {},
       // (trace_id/span_id omitted — no OpenTelemetry; spec forbids fabricating)
       // non-user actors: don't create a PostHog person
@@ -1183,6 +1600,7 @@ var OPENAI_APPS_CHALLENGE_TOKEN = "bBlB7N7fF7YaQnONtEQNAGP7SLaqpJT3a3DS5Zv1F8s";
 var OAUTH_DEBUG_LOGS = !["0", "false", "no", "off"].includes(
   (process.env.PLAUD_OAUTH_DEBUG_LOGS ?? "").toLowerCase()
 );
+var ROOT_REDIRECT_URL = process.env.PLAUD_ROOT_REDIRECT_URL ?? "https://www.plaud.ai";
 var CIMD_ENABLED = ["1", "true", "yes", "on"].includes(
   (process.env.PLAUD_CIMD_ENABLED ?? "").toLowerCase()
 );
@@ -1239,8 +1657,8 @@ function startHttpServer() {
     common: {
       serviceName: process.env.PLAUD_WAREHOUSE_SERVICE_NAME ?? "plaudmcp",
       // matches §1.3 key label `plaudmcp:TRACKING_KEY_PLAUDMCP`; confirm exact string with David
-      serviceVersion: "0.3.8",
-      buildId: "be0dfaa",
+      serviceVersion: "0.3.10",
+      buildId: "e5eb255",
       // mcp tsup TODO: inject git short SHA (like CLI)
       region: process.env.PLAUD_REGION ?? "US",
       env: process.env.PLAUD_ENV ?? process.env.NODE_ENV ?? "development"
@@ -1330,13 +1748,19 @@ function startHttpServer() {
         server_url: process.env.PLAUD_SERVER_URL ?? "(default:localhost)",
         oauth_debug_logs: OAUTH_DEBUG_LOGS,
         cimd_enabled: CIMD_ENABLED
-      }
+      },
+      // Size of the token-verification cache, to confirm it is actually in
+      // effect. Counts only — no tokens or user identifiers.
+      token_verifier: provider.verifierStats
     });
   });
+  app.get("/", (_req, res) => {
+    res.redirect(302, ROOT_REDIRECT_URL);
+  });
   if (process.env.PLAUD_CALLBACK_URL) {
     app.get(CALLBACK_PATH, (req, res) => {
-      const code = req.query["code"];
-      const state = req.query["state"];
+      const code = queryValue(req.query["code"]);
+      const state = queryValue(req.query["state"]);
       if (!code || !state) {
         logger.warn({ event: "oauth_callback_invalid", code: !!code, state: !!state });
         res.status(400).send("Missing code or state");
@@ -1346,7 +1770,7 @@ function startHttpServer() {
     });
   }
   app.use((req, res, next) => {
-    const reqId = req.headers["x-request-id"] ?? randomUUID3();
+    const reqId = req.headers["x-request-id"] ?? randomUUID2();
     const startMs = Date.now();
     res.locals["reqId"] = reqId;
     res.on("finish", () => {
@@ -1498,7 +1922,7 @@ function startHttpServer() {
     requireBearerAuth({ verifier: provider, resourceMetadataUrl: protectedResourceMetadataUrl }),
     async (req, res) => {
       const token = req.auth.token;
-      const reqId = res.locals["reqId"] ?? randomUUID3();
+      const reqId = res.locals["reqId"] ?? randomUUID2();
       const reqLog = logger.child({ req_id: reqId });
       const startMs = Date.now();
       reqLog.info({ event: "mcp_request_start", client_id: req.auth.clientId });
@@ -1509,7 +1933,7 @@ function startHttpServer() {
         apiBase,
         staticToken: token
       });
-      const mcpServer = new McpServer({ name: "plaud", version: "0.3.8" });
+      const mcpServer = new McpServer({ name: "plaud", version: "0.3.10" });
       registerTools(mcpServer, client, warehouseToolHooks);
       const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: void 0,
@@ -1547,8 +1971,8 @@ function startHttpServer() {
   if (!process.env.PLAUD_CALLBACK_URL) {
     const callbackApp = express();
     callbackApp.get(CALLBACK_PATH, (req, res) => {
-      const code = req.query["code"];
-      const state = req.query["state"];
+      const code = queryValue(req.query["code"]);
+      const state = queryValue(req.query["state"]);
       if (!code || !state) {
         logger.warn({ event: "oauth_callback_invalid", code: !!code, state: !!state });
         res.status(400).send("Missing code or state");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaud-ai/mcp",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -8,7 +8,6 @@
   },
   "files": [
     "dist",
-    "plugin.json",
     ".mcp.json",
     "skills"
   ],
@@ -18,7 +17,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "clean": "rm -rf dist skills",
-    "prepublishOnly": "node -e \"const fs=require('fs'),v=require('./package.json').version,p=JSON.parse(fs.readFileSync('./plugin.json','utf8'));p.version=v;fs.writeFileSync('./plugin.json',JSON.stringify(p,null,2)+'\\n');\""
+    "prepublishOnly": "node -e \"const fs=require('fs'),v=require('./package.json').version,f='../../plugin.json',p=JSON.parse(fs.readFileSync(f,'utf8'));p.version=v;fs.writeFileSync(f,JSON.stringify(p,null,2)+'\\n');\""
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",

package/skills/plaud-read/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plaud-read
 version: 1.0.0
-description: "Read the transcript, AI summary, notes, or download audio for a specific Plaud recording. Use when the user says 'show the transcript', 'summarize this', 'what was said', 'get audio', 'the notes from', or names a specific recording to dig into. Also covers extracting structured fields from a recording."
+description: "Read the transcript, AI summary, notes, highlights, or download audio for a specific Plaud recording. Use when the user says 'show the transcript', 'summarize this', 'what was said', 'get audio', 'the notes from', 'my highlights', 'the moments I flagged', 'what I marked while recording', or names a specific recording to dig into. Also covers extracting structured fields from a recording."
 metadata:
   requires:
     bins: []
@@ -14,7 +14,7 @@ metadata:
 ## When to use
 
 - User names a specific recording (by name or ID) and wants to read its content.
-- User asks for "transcript", "summary", "action items", "audio", "who said what", or a structured extraction ("action items, decisions, attendees").
+- User asks for "transcript", "summary", "action items", "audio", "who said what", "my highlights" / "the moments I flagged", or a structured extraction ("action items, decisions, attendees").
 - If the user did **not** specify a recording, hand off to `plaud-find` (by topic) or `plaud-browse` (by recency) first.
 
 ## Tool selection matrix
@@ -23,8 +23,9 @@ metadata:
 |---|---|---|
 | AI summary, TL;DR, action items | `get_note` | Returns Markdown; usually enough — try this before `get_transcript` |
 | Verbatim quotes, full dialogue | `get_transcript` | Timestamped; paginated — follow `next_cursor` for long recordings |
+| Highlights — "the moments I flagged", "what I marked while recording" | `get_transcript` with `block: "mark_memo"` | Returned under `marks`. Exists only if the user pressed the device's highlight button; also surfaced as the `high_light` note by `get_note`. To turn marks into quotes, pair with a `transaction` call and match on the timestamps |
 | Audio download link | `get_file` then use `presigned_url` | Link expires in 24h |
-| Full metadata + availability flags | `get_file` | Check `source_list` / `note_list` populated before claiming content exists |
+| Full metadata + availability flags | `get_file` | Lists which blocks exist. **An entry with `data_content: ""` and a `data_link` is not empty** — its body is link-backed; read it with `get_transcript` / `get_note`, which resolve the link. Never report such a block as missing data |
 
 ## Structured extraction workflow
 

package/skills/plaud-shared/SKILL.md

@@ -19,15 +19,31 @@ metadata:
 
 ## Tool inventory
 
-| Tool | Purpose |
-|---|---|
-| `login` | Open browser for OAuth; blocks until callback or 2-min timeout |
-| `logout` | Revoke and clear tokens |
-| `get_current_user` | Verify who is signed in |
-| `list_files` | Browse, paginate, filter recordings (supports `query`, `date_from`, `date_to`) |
-| `get_file` | Full record incl. `presigned_url`, `source_list`, `note_list` |
-| `get_note` | AI-generated summary and action items |
-| `get_transcript` | Timestamped transcript with speaker labels |
+| Tool | Purpose | Local | Remote |
+|---|---|---|---|
+| `login` | Open browser for OAuth; blocks until callback or 2-min timeout | ✅ | — |
+| `logout` | Revoke and clear tokens | ✅ | — |
+| `get_current_user` | Verify who is signed in | ✅ | ✅ |
+| `list_files` | Browse, paginate, filter recordings (supports `query`, `date_from`, `date_to`) | ✅ | ✅ |
+| `get_file` | Full record incl. `presigned_url`, `source_list`, `note_list` | ✅ | ✅ |
+| `get_note` | AI-generated summary and action items | ✅ | ✅ |
+| `get_transcript` | Timestamped transcript with speaker labels | ✅ | ✅ |
+
+**Local** = the stdio server (`npx @plaud-ai/mcp`). **Remote** = a hosted connector
+the host dials by URL. Remote has no `login` / `logout`: authorization runs as a
+browser OAuth redirect driven by the host, not as a tool call. On a remote
+connector, treat "sign in" as something the user does in the host's UI.
+
+### Tool names may carry a host-applied prefix
+
+The names above are the canonical ones the server registers. Some hosts namespace
+them with the connector name the user chose. WorkBuddy, for example, turns a
+connector named `plaudcn` into `plaudcn_list_files`, `plaudcn_get_transcript`, and
+so on — the prefix follows the user's own config, so it is not predictable.
+
+**Always resolve tools from the list you were actually given, matching on the
+canonical suffix** (`…list_files`, `…get_transcript`). Never assume a bare name is
+callable, and never hard-code a prefix.
 
 ## Error semantics
 

package/plugin.json

@@ -1,8 +0,0 @@
-{
-  "name": "plaud",
-  "version": "0.3.8",
-  "description": "Access your Plaud recordings in Claude",
-  "author": {
-    "name": "Plaud AI"
-  }
-}