mcp-cache-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StudioMeyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# mcp-cache-kit
+
+**Correct, leak-safe caching for the new MCP cache semantics ([SEP-2549](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549)).**
+
+The MCP spec **2026-07-28 release candidate** adds [SEP-2549](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/): `tools/list`, `resources/read` (and the other list results) now carry **`ttlMs`** and **`cacheScope`** so clients, gateways, and proxies can cache them — modeled on HTTP `Cache-Control`. It is brand-new and has essentially no dedicated tooling. Generic caches store results "somehow" and ignore `cacheScope`, which is a real security trap: a result marked `cacheScope: "private"` that gets cached and served across users is a **cross-user data leak**.
+
+`mcp-cache-kit` is the small, correct layer for exactly this:
+
+- **Server side** — set the fields right (`withCacheHints`).
+- **Client / proxy side** — a cache that *honors* `ttlMs` and **never serves a `private` result across authorization contexts** (`McpResultCache`).
+- **A guard** — decide if any result may be cached for a given scope, with a clear reason (`cacheSafety` / `assertCacheSafe`).
+
+Zero runtime dependencies. TypeScript strict, ESM + CJS, Node 20+. The `@modelcontextprotocol/sdk` is an *optional* peer — the helpers also work on plain result objects, so you can use it without the SDK.
+
+> ⚠️ **The 2026-07-28 spec is a release candidate.** Field names and semantics may still shift before final. This library models them conservatively and is intentionally tolerant of missing/malformed fields (it treats anything it cannot prove safe as uncacheable).
+
+## What SEP-2549 actually says
+
+Verified against the spec source ([`schema/draft/schema.ts`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/draft/schema.ts) and [`docs/.../utilities/caching.mdx`](https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs/specification/draft/server)):
+
+Cacheable results extend a `CacheableResult` shape with two **top-level** fields:
+
+| Field        | Type                    | Meaning                                                                                                 |
+| ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------ |
+| `ttlMs`      | `number` (`@minimum 0`) | Freshness window, like `Cache-Control: max-age`. `0` = immediately stale. Absent/negative → treat as `0`. |
+| `cacheScope` | `"public" \| "private"` | Like `Cache-Control: public` vs `private`. See below.                                                  |
+
+- **`"public"`** — the response has no user-specific data. Any client or intermediary MAY cache it and serve it **across authorization contexts**.
+- **`"private"`** — the response MAY be cached and reused **only within the same authorization context**. Caches MUST NOT be shared across authorization contexts (a different access token / user / session needs a different cache entry).
+
+Applies to `tools/list`, `resources/list`, `resources/templates/list`, `prompts/list`, and `resources/read`.
+
+> The spec also warns: a `"public"` result from an *authenticated* endpoint can still be shared between callers, and you **MUST NOT rely on `cacheScope` alone** to prevent unauthorized access. This library enforces the scope boundary for you, but you still own labeling scopes honestly and authenticating at the origin. See [SECURITY.md](./SECURITY.md).
+
+## The cross-user-leak trap
+
+```
+              tools/list / resources/read
+   user A  ───────────────────────────────►  proxy (caches by request only)
+                                                   │ stores result, ignores cacheScope
+   user B  ───────── same request ──────────►  proxy
+                                                   │ returns A's cached result  ← LEAK
+```
+
+If the cached result was `cacheScope: "private"` (A's inbox, A's tenant config, …), user B just received another user's data. `mcp-cache-kit` keys every entry by the request **and** the caller's scope identity, so a `private` entry for A is structurally unreachable for B.
+
+## Install
+
+```bash
+npm install mcp-cache-kit
+# optional, only if you use the SDK result types directly:
+npm install @modelcontextprotocol/sdk
+```
+
+## Server side — set the hints
+
+Attach the fields to a result. `withCacheHints` validates them (rejects negative/non-finite `ttlMs` and any `cacheScope` other than `public`/`private`) and returns a **new** object.
+
+```ts
+import { withCacheHints, CacheScope } from "mcp-cache-kit";
+
+// tools/list rarely contains user data → public, cache for 5 minutes
+server.setRequestHandler(ListToolsRequestSchema, async () =>
+  withCacheHints({ tools }, { ttlMs: 5 * 60_000, cacheScope: CacheScope.Public }),
+);
+
+// a per-user resource → private, cache for 1 minute
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+  const contents = await loadForUser(req.params.uri);
+  return withCacheHints({ contents }, { ttlMs: 60_000, cacheScope: CacheScope.Private });
+});
+```
+
+There are shorthands too: `publicHints(ttlMs)` and `privateHints(ttlMs)`.
+
+## Client / proxy side — honor them safely
+
+`McpResultCache` stores results keyed by `(request, scope)`. Pass a `scopeId` that identifies the caller's authorization context (an access-token hash, user id, tenant id, or session id).
+
+```ts
+import { McpResultCache } from "mcp-cache-kit";
+
+const cache = new McpResultCache({ maxEntries: 5_000 });
+
+async function handleReadResource(req, ctx) {
+  const scopeId = ctx.tokenHash; // identifies the authorization context
+
+  // try the cache first
+  const hit = cache.get(req, { scopeId });
+  if (hit.hit) return hit.value;
+
+  // miss → fetch from the upstream MCP server, then offer it to the cache.
+  // set() stores it ONLY if the result is cache-safe for this scope.
+  const result = await upstream.request(req);
+  cache.set(req, result, { scopeId });
+  return result;
+}
+```
+
+Or the one-liner:
+
+```ts
+const result = await cache.getOrLoad(req, () => upstream.request(req), { scopeId });
+```
+
+What the cache guarantees:
+
+- **TTL is honored** — entries expire at `received + ttlMs` and are removed on access (or via `prune()`).
+- **`private` never leaks** — a `private` entry stored for scope A is only ever returned to scope A. A different `scopeId`, or no `scopeId`, gets a miss.
+- **`public` is shared** — stored under one shared key and returned to anyone.
+- **Fail-safe** — `set()` silently refuses (and counts as `rejected`) anything it can't prove safe: missing/partial hints, bad `cacheScope`, bad `ttlMs`, `private`-without-`scopeId`, and `ttlMs: 0` (by default).
+
+## Guard — `cacheSafety` / `assertCacheSafe`
+
+Use these in a gateway when you want to make the decision yourself:
+
+```ts
+import { cacheSafety, assertCacheSafe } from "mcp-cache-kit";
+
+const decision = cacheSafety(result, { scopeId });
+if (decision.cacheable) {
+  // decision.scopeKey is where to store it; decision.hints.ttlMs is the TTL
+  myStore.put(decision.scopeKey, result, decision.hints.ttlMs);
+} else {
+  // decision.reason: "missing-fields" | "invalid-ttl" | "invalid-scope"
+  //                | "zero-ttl" | "private-without-scope" | "not-an-object"
+  log.debug(`not caching: ${decision.message}`);
+}
+
+// or throw if "must be cacheable here" is an invariant:
+const { hints, scopeKey } = assertCacheSafe(result, { scopeId }); // throws CacheUnsafeError otherwise
+```
+
+## Low-level helpers
+
+All individually exported and tested:
+
+- `parseCacheHints(result)` → `{ ok: true, hints } | { ok: false, reason, message }` — never throws.
+- `validateCacheHints({ ttlMs, cacheScope })` → normalized hints (throws `TypeError` on bad input).
+- `isCacheScope(x)`, `isValidTtlMs(x)` — type guards.
+- `deriveScopeKey(cacheScope, scopeId?)` — the scope-key rule (`undefined` for `private` without a `scopeId`).
+- `deriveRequestKey({ method, params })` / `stableStringify(x)` — deterministic request keys (param key order doesn't matter).
+- Constants: `CacheScope`, `CACHE_SCOPE_VALUES`, `PUBLIC_SCOPE_KEY`.
+
+## Fail-safe philosophy
+
+Caching the wrong thing across users is worse than a cache miss. So the default decision is always **"do not cache"** unless the result *proves* it is safe: both fields present, both valid, and — for `private` — a `scopeId` to bind it to. SEP-2549 is still an RC, so being strict here also protects you from upstream servers that emit partial or mislabeled hints.
+
+## Testing notes
+
+`McpResultCache` takes an injectable `clock` (`() => number`), so you can test TTL behavior deterministically without real time — and it also works under `vitest` fake timers driving the default `Date.now`. Both styles are covered in the test suite, including the headline cross-user leak test.
+
+## License
+
+[MIT](./LICENSE) © StudioMeyer 2026

package/SECURITY.md

@@ -0,0 +1,75 @@
+# Security Policy
+
+`mcp-cache-kit` exists to prevent a specific, easy-to-make security bug, so the
+threat model is the whole point of the library. Please read this before deploying
+a cache in front of MCP traffic.
+
+## The threat: cross-context cache leaks
+
+[SEP-2549](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549)
+(MCP spec, 2026-07-28 release candidate) lets servers mark `tools/list`,
+`resources/read` (and the other list results) with cache hints:
+
+- `ttlMs` — how long the result stays fresh.
+- `cacheScope` — `"public"` (safe to share across users) or `"private"` (safe to
+  reuse **only within the same authorization context**).
+
+The dangerous failure mode is a gateway/proxy that caches "by request" and ignores
+`cacheScope`. If a `"private"` `resources/read` result for user A is stored under a
+request-only key, the next user B who issues the same request gets served **user
+A's private data**. That is a cross-tenant / cross-user data leak.
+
+A second trap comes straight from the spec: a `"public"` result coming out of an
+*authenticated* endpoint may still be shared across callers. Servers must not mark
+anything `"public"` that contains user-specific data, and **must not rely on
+`cacheScope` alone** for access control.
+
+## How this library mitigates it
+
+- **Scope-keyed storage.** Every cache entry is keyed by the request **and** a
+  scope key. `public` entries use one shared key (so they are shared on purpose).
+  `private` entries derive their key from the caller's authorization-context
+  identity (`scopeId` — e.g. an access-token hash, user id, tenant id, or session
+  id). A different caller derives a different key and **cannot** reach another
+  caller's private entry. There is no code path that returns a private entry to a
+  caller who did not store it.
+- **Fail-safe by default.** Anything we cannot prove is cache-safe is simply not
+  cached: missing/partial hints, an unknown `cacheScope`, a non-finite/negative
+  `ttlMs`, a `"private"` result offered without a `scopeId`, and (by default) a
+  `ttlMs` of `0`. The default decision is "do not cache", never "cache anyway".
+- **A guard you can drop anywhere.** `cacheSafety(result, { scopeId })` and
+  `assertCacheSafe(...)` give a clear allow/deny with a machine-readable reason, so
+  a proxy can decide safely without re-implementing the rules.
+- **`scopeId` must be a non-empty string.** A non-string id (number, array, object
+  — e.g. a numeric tenant PK passed by mistake) is refused rather than coerced, so
+  it can never collide with another scope's key. Isolation is then only as strong
+  as your `scopeId` being unique and unspoofable — that part is yours to guarantee.
+- **TTL uses a wall clock** (`Date.now` by default). A backward clock jump can keep
+  an entry "fresh" past its `ttlMs`; inject a monotonic `clock` if that matters.
+
+## Your responsibilities (this library cannot do these for you)
+
+1. **Pass a real `scopeId`.** It must uniquely identify the authorization context.
+   An access-token hash or an authenticated user/tenant id is good. A value an
+   attacker can spoof or that collides across users is not. If you cannot identify
+   the context, do not pass a `scopeId` — the library will then refuse to cache
+   `private` results (the safe outcome).
+2. **Mark scopes honestly on the server.** Never label user-specific data
+   `"public"`. When in doubt, use `"private"` (or omit hints entirely).
+3. **Do not use the cache as an authorization layer.** It reduces redundant
+   fetches; it does not replace authenticating each request at the origin.
+4. **Treat `cacheScope` as advisory across trust boundaries.** Per the spec, a
+   malicious or buggy upstream can mislabel results.
+
+## Supported versions
+
+`0.x` — the latest `0.x` release receives fixes. Pre-1.0, the public API may change
+as SEP-2549 itself is still a release candidate.
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities privately via GitHub Security Advisories on
+the repository (`Security` tab -> `Report a vulnerability`), or open a minimal,
+non-exploitative issue if private reporting is unavailable. Do not include working
+exploits against third-party systems. We aim to acknowledge reports within a few
+business days.

package/dist/index.cjs

@@ -0,0 +1,344 @@
+'use strict';
+
+// src/types.ts
+var CacheScope = {
+  /** Shareable across authorization contexts. */
+  Public: "public",
+  /** Only reusable within the same authorization context. */
+  Private: "private"
+};
+var CACHE_SCOPE_VALUES = Object.freeze([
+  CacheScope.Public,
+  CacheScope.Private
+]);
+
+// src/hints.ts
+function isCacheScope(value) {
+  return typeof value === "string" && CACHE_SCOPE_VALUES.includes(value);
+}
+function isValidTtlMs(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function validateCacheHints(input) {
+  if (input === null || typeof input !== "object") {
+    throw new TypeError(
+      `mcp-cache-kit: cache hints must be an object with { ttlMs, cacheScope }, got ${describe(
+        input
+      )}`
+    );
+  }
+  if (!isValidTtlMs(input.ttlMs)) {
+    throw new TypeError(
+      `mcp-cache-kit: ttlMs must be a finite number >= 0 (milliseconds), got ${describe(
+        input.ttlMs
+      )}`
+    );
+  }
+  if (!isCacheScope(input.cacheScope)) {
+    throw new TypeError(
+      `mcp-cache-kit: cacheScope must be one of ${CACHE_SCOPE_VALUES.map(
+        (v) => `"${v}"`
+      ).join(" | ")}, got ${describe(input.cacheScope)}`
+    );
+  }
+  return { ttlMs: Math.floor(input.ttlMs), cacheScope: input.cacheScope };
+}
+function withCacheHints(result, hints) {
+  if (result === null || typeof result !== "object") {
+    throw new TypeError(
+      `mcp-cache-kit: withCacheHints(result, ...) requires a result object, got ${describe(
+        result
+      )}`
+    );
+  }
+  const valid = validateCacheHints(hints);
+  return { ...result, ttlMs: valid.ttlMs, cacheScope: valid.cacheScope };
+}
+function publicHints(ttlMs) {
+  return validateCacheHints({ ttlMs, cacheScope: CacheScope.Public });
+}
+function privateHints(ttlMs) {
+  return validateCacheHints({ ttlMs, cacheScope: CacheScope.Private });
+}
+function parseCacheHints(result) {
+  if (result === null || typeof result !== "object") {
+    return {
+      ok: false,
+      reason: "not-an-object",
+      message: `result is not an object (got ${describe(result)})`
+    };
+  }
+  const r = result;
+  let ttlVal;
+  let scopeVal;
+  try {
+    ttlVal = "ttlMs" in r ? r.ttlMs : void 0;
+    scopeVal = "cacheScope" in r ? r.cacheScope : void 0;
+  } catch {
+    return {
+      ok: false,
+      reason: "not-an-object",
+      message: "reading cache hints threw (hostile getter on the result?)"
+    };
+  }
+  const hasTtl = ttlVal !== void 0;
+  const hasScope = scopeVal !== void 0;
+  if (!hasTtl && !hasScope) {
+    return {
+      ok: false,
+      reason: "missing-fields",
+      message: "result has no SEP-2549 cache hints (ttlMs / cacheScope absent)"
+    };
+  }
+  if (!hasTtl || !hasScope) {
+    return {
+      ok: false,
+      reason: "missing-fields",
+      message: "result has only one of ttlMs / cacheScope; both are required to be cacheable"
+    };
+  }
+  if (!isValidTtlMs(ttlVal)) {
+    return {
+      ok: false,
+      reason: "invalid-ttl",
+      message: `ttlMs is not a finite number >= 0 (got ${describe(ttlVal)})`
+    };
+  }
+  if (!isCacheScope(scopeVal)) {
+    return {
+      ok: false,
+      reason: "invalid-scope",
+      message: `cacheScope is not "public" | "private" (got ${describe(
+        scopeVal
+      )})`
+    };
+  }
+  return { ok: true, hints: { ttlMs: Math.floor(ttlVal), cacheScope: scopeVal } };
+}
+function describe(value) {
+  if (value === null) return "null";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return "an array";
+  return typeof value;
+}
+
+// src/safety.ts
+var PUBLIC_SCOPE_KEY = "public";
+function deriveScopeKey(cacheScope, scopeId) {
+  if (cacheScope === CacheScope.Public) return PUBLIC_SCOPE_KEY;
+  if (typeof scopeId !== "string" || scopeId === "") return void 0;
+  return `private:${scopeId.length}:${scopeId}`;
+}
+function cacheSafety(result, options = {}) {
+  const parsed = parseCacheHints(result);
+  if (!parsed.ok) {
+    return { cacheable: false, reason: parsed.reason, message: parsed.message };
+  }
+  const hints = parsed.hints;
+  if (hints.ttlMs === 0 && options.allowZeroTtl !== true) {
+    return {
+      cacheable: false,
+      reason: "zero-ttl",
+      message: "ttlMs is 0 (immediately stale); nothing to cache"
+    };
+  }
+  const scopeKey = deriveScopeKey(hints.cacheScope, options.scopeId);
+  if (scopeKey === void 0) {
+    return {
+      cacheable: false,
+      reason: "private-without-scope",
+      message: 'cacheScope is "private" but no scopeId was provided; refusing to cache to avoid cross-context leaks'
+    };
+  }
+  return { cacheable: true, hints, scopeKey };
+}
+var CacheUnsafeError = class extends Error {
+  name = "CacheUnsafeError";
+  /** Machine-readable reason, mirrors {@link CacheDecision}'s `reason`. */
+  reason;
+  constructor(decision) {
+    super(`mcp-cache-kit: result is not cache-safe (${decision.reason}): ${decision.message}`);
+    this.reason = decision.reason;
+  }
+};
+function assertCacheSafe(result, options = {}) {
+  const decision = cacheSafety(result, options);
+  if (!decision.cacheable) {
+    throw new CacheUnsafeError(decision);
+  }
+  return { hints: decision.hints, scopeKey: decision.scopeKey };
+}
+
+// src/cache.ts
+function deriveRequestKey(input) {
+  if (typeof input === "string") return input;
+  return `${input.method}\0${stableStringify(input.params)}`;
+}
+function stableStringify(value) {
+  return JSON.stringify(normalize(value));
+}
+function normalize(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(normalize);
+  const obj = value;
+  const out = {};
+  for (const key of Object.keys(obj).sort()) {
+    out[key] = normalize(obj[key]);
+  }
+  return out;
+}
+function storageKey(requestKey, scopeKey) {
+  return `${scopeKey}\0${requestKey}`;
+}
+var McpResultCache = class {
+  #maxEntries;
+  #clock;
+  #allowZeroTtl;
+  // Insertion-ordered (Map preserves order) — enables O(1) FIFO eviction.
+  #store = /* @__PURE__ */ new Map();
+  #stats = {
+    hits: 0,
+    misses: 0,
+    expired: 0,
+    stores: 0,
+    rejected: 0,
+    evictions: 0
+  };
+  constructor(options = {}) {
+    this.#maxEntries = options.maxEntries ?? 1e3;
+    this.#clock = options.clock ?? Date.now;
+    this.#allowZeroTtl = options.allowZeroTtl ?? false;
+  }
+  /**
+   * Store a result IF it is cache-safe for the given scope. Validates hints,
+   * derives the scope key (refusing `private` without a `scopeId`), and stores
+   * keyed by (request, scope). Returns whether it was stored and why not.
+   *
+   * Always safe to call on any result — non-cacheable results are silently
+   * rejected (counted in {@link CacheStats.rejected}) rather than stored.
+   */
+  set(request, result, options = {}) {
+    if (this.#maxEntries <= 0) {
+      return { stored: false, reason: "missing-fields", message: "cache disabled (maxEntries <= 0)" };
+    }
+    const decision = cacheSafety(result, {
+      ...options.scopeId !== void 0 ? { scopeId: options.scopeId } : {},
+      allowZeroTtl: this.#allowZeroTtl
+    });
+    if (!decision.cacheable) {
+      this.#stats.rejected++;
+      return { stored: false, reason: decision.reason, message: decision.message };
+    }
+    const requestKey = deriveRequestKey(request);
+    const key = storageKey(requestKey, decision.scopeKey);
+    const expiresAt = this.#clock() + decision.hints.ttlMs;
+    this.#store.delete(key);
+    this.#store.set(key, { value: result, hints: decision.hints, expiresAt });
+    this.#stats.stores++;
+    this.#evictIfNeeded();
+    return { stored: true, scopeKey: decision.scopeKey, expiresAt, hints: decision.hints };
+  }
+  /**
+   * Look up a result for the given request AND scope identity.
+   *
+   * A `private` entry is ONLY returned to the same `scopeId` that stored it: the
+   * lookup derives the scope key from the caller's `scopeId`, so another caller's
+   * lookup targets a different key and can never reach it. A `public` entry is
+   * returned to anyone (it is stored under the shared public key).
+   *
+   * Expired entries are treated as a miss and removed lazily on access.
+   */
+  get(request, options = {}) {
+    const requestKey = deriveRequestKey(request);
+    const candidateScopeKeys = [];
+    const privateKey = deriveScopeKey(CacheScope.Private, options.scopeId);
+    if (privateKey !== void 0) candidateScopeKeys.push(privateKey);
+    candidateScopeKeys.push(deriveScopeKey(CacheScope.Public));
+    for (const scopeKey of candidateScopeKeys) {
+      const key = storageKey(requestKey, scopeKey);
+      const entry = this.#store.get(key);
+      if (entry === void 0) continue;
+      if (this.#clock() >= entry.expiresAt) {
+        this.#store.delete(key);
+        this.#stats.expired++;
+        continue;
+      }
+      this.#stats.hits++;
+      return {
+        hit: true,
+        value: entry.value,
+        hints: entry.hints,
+        expiresAt: entry.expiresAt
+      };
+    }
+    this.#stats.misses++;
+    return { hit: false, reason: "miss" };
+  }
+  /**
+   * Convenience wrapper: return the cached value, or compute + store it.
+   *
+   * If a fresh entry exists it is returned. Otherwise `loader()` runs, its result
+   * is offered to {@link set} (stored only if cache-safe), and returned regardless.
+   */
+  async getOrLoad(request, loader, options = {}) {
+    const cached = this.get(request, options);
+    if (cached.hit) return cached.value;
+    const value = await loader();
+    this.set(request, value, options);
+    return value;
+  }
+  /** Remove all entries whose TTL has elapsed. Returns the count removed. */
+  prune() {
+    const now = this.#clock();
+    let removed = 0;
+    for (const [key, entry] of this.#store) {
+      if (now >= entry.expiresAt) {
+        this.#store.delete(key);
+        removed++;
+      }
+    }
+    this.#stats.expired += removed;
+    return removed;
+  }
+  /** Drop everything. Does not reset stat counters. */
+  clear() {
+    this.#store.clear();
+  }
+  /** Current live entry count (without pruning). */
+  get size() {
+    return this.#store.size;
+  }
+  /** A snapshot of counters plus current size. */
+  stats() {
+    return { ...this.#stats, size: this.#store.size };
+  }
+  #evictIfNeeded() {
+    while (this.#store.size > this.#maxEntries) {
+      const oldest = this.#store.keys().next().value;
+      if (oldest === void 0) break;
+      this.#store.delete(oldest);
+      this.#stats.evictions++;
+    }
+  }
+};
+
+exports.CACHE_SCOPE_VALUES = CACHE_SCOPE_VALUES;
+exports.CacheScope = CacheScope;
+exports.CacheUnsafeError = CacheUnsafeError;
+exports.McpResultCache = McpResultCache;
+exports.PUBLIC_SCOPE_KEY = PUBLIC_SCOPE_KEY;
+exports.assertCacheSafe = assertCacheSafe;
+exports.cacheSafety = cacheSafety;
+exports.deriveRequestKey = deriveRequestKey;
+exports.deriveScopeKey = deriveScopeKey;
+exports.isCacheScope = isCacheScope;
+exports.isValidTtlMs = isValidTtlMs;
+exports.parseCacheHints = parseCacheHints;
+exports.privateHints = privateHints;
+exports.publicHints = publicHints;
+exports.stableStringify = stableStringify;
+exports.validateCacheHints = validateCacheHints;
+exports.withCacheHints = withCacheHints;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map