mcp-cache-kit 0.1.0

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/hints.ts","../src/safety.ts","../src/cache.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Core types for mcp-cache-kit, modeled on MCP SEP-2549.\n *\n * SEP-2549 (MCP spec, 2026-07-28 release candidate) adds two top-level fields to\n * cacheable results (`tools/list`, `resources/list`, `resources/templates/list`,\n * `prompts/list`, `resources/read`):\n *\n *   - `ttlMs: number`   — how long the client MAY treat the result as fresh,\n *                          analogous to HTTP `Cache-Control: max-age`. `@minimum 0`.\n *   - `cacheScope: \"public\" | \"private\"` — analogous to HTTP\n *                          `Cache-Control: public` vs `private`.\n *\n * Source of truth (verified):\n *   https://github.com/modelcontextprotocol/modelcontextprotocol (schema/draft/schema.ts,\n *   docs/specification/draft/server/utilities/caching.mdx) and\n *   https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/\n *\n * NOTE: the 2026-07-28 spec is a release candidate. These field names/semantics\n * may still shift before final. This library is intentionally tolerant of missing\n * or malformed fields and treats anything it cannot prove safe as uncacheable.\n */\n\n/**\n * The allowed values of `cacheScope` per SEP-2549.\n *\n * - `\"public\"`  — the response does not contain user-specific data. Any client or\n *   intermediary MAY cache it and serve it across authorization contexts.\n * - `\"private\"` — the response MAY be cached and reused only within the SAME\n *   authorization context. Caches MUST NOT be shared across authorization contexts\n *   (a different access token/user/session requires a different cache entry).\n */\nexport const CacheScope = {\n  /** Shareable across authorization contexts. */\n  Public: \"public\",\n  /** Only reusable within the same authorization context. */\n  Private: \"private\",\n} as const;\n\n/** Union of the valid `cacheScope` string values: `\"public\" | \"private\"`. */\nexport type CacheScope = (typeof CacheScope)[keyof typeof CacheScope];\n\n/** Immutable list of valid scope values, handy for validation/iteration. */\nexport const CACHE_SCOPE_VALUES: readonly CacheScope[] = Object.freeze([\n  CacheScope.Public,\n  CacheScope.Private,\n]);\n\n/**\n * The SEP-2549 cache hint fields as they appear (top-level) on a cacheable result.\n */\nexport interface CacheHints {\n  /**\n   * How long (ms) the client MAY treat the result as fresh. `>= 0`.\n   * `0` means \"immediately stale\". See {@link CacheScope} for scope semantics.\n   */\n  ttlMs: number;\n  /** Whether the result is safe to share across authorization contexts. */\n  cacheScope: CacheScope;\n}\n\n/**\n * Minimal structural shape of an MCP result that MAY carry cache hints.\n *\n * Kept deliberately loose (`Record<string, unknown>`) so the helpers work on plain\n * result objects WITHOUT a hard dependency on `@modelcontextprotocol/sdk`. If you\n * do use the SDK, its `ListToolsResult` / `ReadResourceResult` (etc.) structurally\n * satisfy this type.\n */\nexport interface MaybeCacheableResult extends Record<string, unknown> {\n  ttlMs?: unknown;\n  cacheScope?: unknown;\n}\n\n/**\n * A result that carries valid, fully-typed SEP-2549 cache hints.\n * `T` is the underlying result type so callers keep their concrete shape.\n */\nexport type WithCacheHints<T extends object> = T & CacheHints;\n\n/** Options accepted by {@link withCacheHints}. */\nexport interface CacheHintsInput {\n  /** Time-to-live in milliseconds. Must be a finite number `>= 0`. */\n  ttlMs: number;\n  /** One of {@link CacheScope}. */\n  cacheScope: CacheScope;\n}\n\n/**\n * Result of parsing the cache hints off an unknown result object.\n *\n * `ok: true` only when BOTH fields are present and valid per spec. Otherwise\n * `ok: false` with a machine-readable `reason` and human-readable `message`.\n */\nexport type ParsedCacheHints =\n  | { ok: true; hints: CacheHints }\n  | { ok: false; reason: UncacheableReason; message: string };\n\n/** Machine-readable reasons a result is considered uncacheable. */\nexport type UncacheableReason =\n  /** The result was null/undefined or not an object. */\n  | \"not-an-object\"\n  /** `ttlMs` or `cacheScope` was absent. Fail-safe: don't cache. */\n  | \"missing-fields\"\n  /** `ttlMs` was present but not a finite number `>= 0`. */\n  | \"invalid-ttl\"\n  /** `cacheScope` was present but not `\"public\" | \"private\"`. */\n  | \"invalid-scope\"\n  /** `ttlMs` was `0` — explicitly \"immediately stale\", so nothing to store. */\n  | \"zero-ttl\"\n  /** A `private` result was offered without a scope identity to key it by. */\n  | \"private-without-scope\";\n\n/**\n * The decision returned by {@link cacheSafety} / used by the cache: may this result\n * be stored for the given scope identity, and if not, why.\n */\nexport type CacheDecision =\n  | {\n      cacheable: true;\n      hints: CacheHints;\n      /**\n       * The scope key the entry MUST be stored under. For `public` results this is\n       * a shared constant; for `private` results it is derived from the caller's\n       * authorization-context identity.\n       */\n      scopeKey: string;\n    }\n  | { cacheable: false; reason: UncacheableReason; message: string };\n","/**\n * Server-side helpers: attach and read SEP-2549 cache hints on results.\n */\n\nimport {\n  CACHE_SCOPE_VALUES,\n  CacheScope,\n  type CacheHints,\n  type CacheHintsInput,\n  type MaybeCacheableResult,\n  type ParsedCacheHints,\n  type WithCacheHints,\n} from \"./types.js\";\n\n/** Type guard for the `cacheScope` enum. */\nexport function isCacheScope(value: unknown): value is CacheScope {\n  return (\n    typeof value === \"string\" &&\n    (CACHE_SCOPE_VALUES as readonly string[]).includes(value)\n  );\n}\n\n/**\n * True if `ttlMs` is a valid SEP-2549 TTL: a finite, non-negative number.\n *\n * The spec annotates `ttlMs` with `@minimum 0` and treats negative/absent values\n * as `0`. We require a real finite number here (NaN / Infinity are rejected).\n */\nexport function isValidTtlMs(value: unknown): value is number {\n  return typeof value === \"number\" && Number.isFinite(value) && value >= 0;\n}\n\n/**\n * Validate a {@link CacheHintsInput}, throwing a descriptive `TypeError` on bad input.\n * Returns the normalized {@link CacheHints} (ttlMs floored to an integer ms).\n *\n * @throws {TypeError} if `ttlMs` is not a finite number `>= 0`, or `cacheScope`\n *   is not `\"public\" | \"private\"`.\n */\nexport function validateCacheHints(input: CacheHintsInput): CacheHints {\n  if (input === null || typeof input !== \"object\") {\n    throw new TypeError(\n      `mcp-cache-kit: cache hints must be an object with { ttlMs, cacheScope }, got ${describe(\n        input,\n      )}`,\n    );\n  }\n  if (!isValidTtlMs(input.ttlMs)) {\n    throw new TypeError(\n      `mcp-cache-kit: ttlMs must be a finite number >= 0 (milliseconds), got ${describe(\n        input.ttlMs,\n      )}`,\n    );\n  }\n  if (!isCacheScope(input.cacheScope)) {\n    throw new TypeError(\n      `mcp-cache-kit: cacheScope must be one of ${CACHE_SCOPE_VALUES.map(\n        (v) => `\"${v}\"`,\n      ).join(\" | \")}, got ${describe(input.cacheScope)}`,\n    );\n  }\n  // Normalize to integer milliseconds — fractional ms is meaningless and keeps\n  // the value JSON-clean for the wire.\n  return { ttlMs: Math.floor(input.ttlMs), cacheScope: input.cacheScope };\n}\n\n/**\n * Server-side: attach SEP-2549 cache hints to a `tools/list` / `resources/read`\n * (etc.) result so clients and proxies can cache it correctly.\n *\n * Returns a NEW object (does not mutate the input) with `ttlMs` and `cacheScope`\n * set as top-level fields, exactly where the spec places them.\n *\n * @example\n * ```ts\n * server.setRequestHandler(ListToolsRequestSchema, () =>\n *   withCacheHints({ tools }, { ttlMs: 60_000, cacheScope: CacheScope.Public }),\n * );\n * ```\n *\n * @throws {TypeError} via {@link validateCacheHints} on invalid hints.\n */\nexport function withCacheHints<T extends object>(\n  result: T,\n  hints: CacheHintsInput,\n): WithCacheHints<T> {\n  if (result === null || typeof result !== \"object\") {\n    throw new TypeError(\n      `mcp-cache-kit: withCacheHints(result, ...) requires a result object, got ${describe(\n        result,\n      )}`,\n    );\n  }\n  const valid = validateCacheHints(hints);\n  return { ...result, ttlMs: valid.ttlMs, cacheScope: valid.cacheScope };\n}\n\n/**\n * Convenience: a `public` result fresh for `ttlMs`. Safe to share across users.\n */\nexport function publicHints(ttlMs: number): CacheHints {\n  return validateCacheHints({ ttlMs, cacheScope: CacheScope.Public });\n}\n\n/**\n * Convenience: a `private` result fresh for `ttlMs`. Reusable only within the\n * same authorization context — the cache will refuse to share it across scopes.\n */\nexport function privateHints(ttlMs: number): CacheHints {\n  return validateCacheHints({ ttlMs, cacheScope: CacheScope.Private });\n}\n\n/**\n * Client/proxy-side: read and validate the cache hints off an unknown result.\n *\n * Returns `{ ok: true, hints }` only when BOTH fields are present and valid.\n * Anything else returns `{ ok: false, reason, message }` — this is the fail-safe\n * primitive the cache builds on: if we cannot prove the hints, we don't cache.\n *\n * This never throws. It is safe to call on arbitrary JSON-RPC result payloads.\n */\nexport function parseCacheHints(result: unknown): ParsedCacheHints {\n  if (result === null || typeof result !== \"object\") {\n    return {\n      ok: false,\n      reason: \"not-an-object\",\n      message: `result is not an object (got ${describe(result)})`,\n    };\n  }\n  const r = result as MaybeCacheableResult;\n  // Read the two fields once, defensively: a live JS object could carry a\n  // throwing getter on ttlMs/cacheScope. We promise never to throw, so a hostile\n  // getter is treated as \"cannot read hints\" → uncacheable (fail safe).\n  let ttlVal: unknown;\n  let scopeVal: unknown;\n  try {\n    ttlVal = \"ttlMs\" in r ? r.ttlMs : undefined;\n    scopeVal = \"cacheScope\" in r ? r.cacheScope : undefined;\n  } catch {\n    return {\n      ok: false,\n      reason: \"not-an-object\",\n      message: \"reading cache hints threw (hostile getter on the result?)\",\n    };\n  }\n  const hasTtl = ttlVal !== undefined;\n  const hasScope = scopeVal !== undefined;\n\n  if (!hasTtl && !hasScope) {\n    return {\n      ok: false,\n      reason: \"missing-fields\",\n      message: \"result has no SEP-2549 cache hints (ttlMs / cacheScope absent)\",\n    };\n  }\n  // Per the caching spec, absent ttlMs defaults to 0; but a partially-hinted\n  // result (one field present, the other missing) is malformed — fail safe.\n  if (!hasTtl || !hasScope) {\n    return {\n      ok: false,\n      reason: \"missing-fields\",\n      message:\n        \"result has only one of ttlMs / cacheScope; both are required to be cacheable\",\n    };\n  }\n  if (!isValidTtlMs(ttlVal)) {\n    return {\n      ok: false,\n      reason: \"invalid-ttl\",\n      message: `ttlMs is not a finite number >= 0 (got ${describe(ttlVal)})`,\n    };\n  }\n  if (!isCacheScope(scopeVal)) {\n    return {\n      ok: false,\n      reason: \"invalid-scope\",\n      message: `cacheScope is not \"public\" | \"private\" (got ${describe(\n        scopeVal,\n      )})`,\n    };\n  }\n  return { ok: true, hints: { ttlMs: Math.floor(ttlVal), cacheScope: scopeVal } };\n}\n\n/** Short, safe description of an unknown value for error messages. */\nfunction describe(value: unknown): string {\n  if (value === null) return \"null\";\n  if (typeof value === \"string\") return JSON.stringify(value);\n  if (typeof value === \"number\" || typeof value === \"boolean\") return String(value);\n  if (Array.isArray(value)) return \"an array\";\n  return typeof value;\n}\n","/**\n * The safety layer: decide whether a result may be cached for a given\n * authorization-context identity, and derive the scope key it must be stored under.\n *\n * This is where the cross-user-leak trap is closed. SEP-2549 says a `private`\n * result \"MAY be cached and reused only within the same authorization context\".\n * We enforce that by KEYING private entries with the caller's scope identity, so a\n * `private` entry stored for user A is structurally unreachable for user B.\n */\n\nimport { parseCacheHints } from \"./hints.js\";\nimport {\n  CacheScope,\n  type CacheDecision,\n  type CacheHints,\n} from \"./types.js\";\n\n/**\n * The single, shared scope key used for `public` results. Chosen to be a value\n * that cannot collide with any real scope identity (which is escaped, see below).\n */\nexport const PUBLIC_SCOPE_KEY = \"public\";\n\n/** Options for {@link cacheSafety} / {@link assertCacheSafe}. */\nexport interface CacheSafetyOptions {\n  /**\n   * Identity of the caller's authorization context — e.g. an access-token hash,\n   * user id, tenant id, or session id. REQUIRED to cache `private` results.\n   * Pass it for `public` results too if you have it; it will simply be ignored.\n   */\n  scopeId?: string;\n  /**\n   * If true, a `ttlMs` of `0` is reported as cacheable (with `zero-ttl` being a\n   * non-fatal note). Default `false`: a 0 TTL means \"immediately stale\", so there\n   * is nothing worth storing and we report it uncacheable. The cache uses the\n   * default.\n   */\n  allowZeroTtl?: boolean;\n}\n\n/**\n * Derive the scope key an entry must be stored under.\n *\n * - `public`  → {@link PUBLIC_SCOPE_KEY} (shared across all callers).\n * - `private` → a key derived from `scopeId`, namespaced so it can never collide\n *   with the public bucket or with another scope id.\n *\n * Returns `undefined` for a `private` result when no `scopeId` is supplied —\n * the caller MUST treat that as \"do not cache\".\n */\nexport function deriveScopeKey(\n  cacheScope: CacheScope,\n  scopeId?: string,\n): string | undefined {\n  if (cacheScope === CacheScope.Public) return PUBLIC_SCOPE_KEY;\n  // private — fail closed on anything that is not a non-empty string. A JS caller\n  // can pass a number/array/object (e.g. a numeric tenant PK straight from the DB),\n  // and `(123).length` is `undefined`, which would void the length-prefix collision\n  // defense below and leak a private entry across scopes. So we never coerce an\n  // unexpected type into a cache key — we refuse to cache it.\n  if (typeof scopeId !== \"string\" || scopeId === \"\") return undefined;\n  // Namespace + length-prefix the id so distinct ids cannot be confused with one\n  // another or with the literal public key (e.g. a scopeId of \"public\").\n  return `private:${scopeId.length}:${scopeId}`;\n}\n\n/**\n * Decide whether `result` may be cached for the given scope identity.\n *\n * Returns a {@link CacheDecision}: when `cacheable: true` it includes the validated\n * hints and the `scopeKey` to store the entry under; when `cacheable: false` it\n * includes a machine-readable `reason` and a human-readable `message`.\n *\n * Fail-safe by construction: missing/invalid hints, an unrecognized scope, a\n * `private` result without a `scopeId`, and (by default) a `0` TTL all return\n * `cacheable: false`. Never throws.\n *\n * Use this as a guard anywhere in a proxy/gateway:\n * ```ts\n * const d = cacheSafety(result, { scopeId: tokenHash });\n * if (d.cacheable) store(key, d.scopeKey, result, d.hints.ttlMs);\n * ```\n */\nexport function cacheSafety(\n  result: unknown,\n  options: CacheSafetyOptions = {},\n): CacheDecision {\n  const parsed = parseCacheHints(result);\n  if (!parsed.ok) {\n    return { cacheable: false, reason: parsed.reason, message: parsed.message };\n  }\n  const hints = parsed.hints;\n\n  if (hints.ttlMs === 0 && options.allowZeroTtl !== true) {\n    return {\n      cacheable: false,\n      reason: \"zero-ttl\",\n      message: \"ttlMs is 0 (immediately stale); nothing to cache\",\n    };\n  }\n\n  const scopeKey = deriveScopeKey(hints.cacheScope, options.scopeId);\n  if (scopeKey === undefined) {\n    return {\n      cacheable: false,\n      reason: \"private-without-scope\",\n      message:\n        'cacheScope is \"private\" but no scopeId was provided; refusing to cache to avoid cross-context leaks',\n    };\n  }\n\n  return { cacheable: true, hints, scopeKey };\n}\n\n/** Error thrown by {@link assertCacheSafe} when a result may not be cached. */\nexport class CacheUnsafeError extends Error {\n  override readonly name = \"CacheUnsafeError\";\n  /** Machine-readable reason, mirrors {@link CacheDecision}'s `reason`. */\n  readonly reason: Extract<CacheDecision, { cacheable: false }>[\"reason\"];\n  constructor(decision: Extract<CacheDecision, { cacheable: false }>) {\n    super(`mcp-cache-kit: result is not cache-safe (${decision.reason}): ${decision.message}`);\n    this.reason = decision.reason;\n  }\n}\n\n/**\n * Assert that `result` may be cached for the given scope identity, throwing a\n * {@link CacheUnsafeError} otherwise. Returns the validated hints + scopeKey.\n *\n * Prefer {@link cacheSafety} when you want to branch without exceptions; use this\n * when \"must be cacheable here\" is an invariant you want to enforce loudly.\n */\nexport function assertCacheSafe(\n  result: unknown,\n  options: CacheSafetyOptions = {},\n): { hints: CacheHints; scopeKey: string } {\n  const decision = cacheSafety(result, options);\n  if (!decision.cacheable) {\n    throw new CacheUnsafeError(decision);\n  }\n  return { hints: decision.hints, scopeKey: decision.scopeKey };\n}\n","/**\n * Client / proxy-side cache that honors SEP-2549 hints — and never leaks a\n * `private` result across authorization contexts.\n *\n * Safety model (the whole point of this package):\n *   - Every stored entry is keyed by `requestKey` AND `scopeKey`.\n *   - `public` results use a single shared scopeKey, so they ARE shared.\n *   - `private` results use a scopeKey derived from the caller's `scopeId`, so a\n *     lookup by a different caller derives a different key and structurally cannot\n *     hit another caller's entry.\n *   - Anything we cannot prove safe (missing/invalid hints, private-without-scope,\n *     0 TTL) is simply not stored. `get` of such a thing is always a miss.\n */\n\nimport { cacheSafety, deriveScopeKey } from \"./safety.js\";\nimport {\n  CacheScope,\n  type CacheDecision,\n  type CacheHints,\n  type UncacheableReason,\n} from \"./types.js\";\n\n/** Monotonic-ish clock returning epoch milliseconds. Injectable for tests. */\nexport type Clock = () => number;\n\n/** A request identity: either a precomputed string key, or the raw JSON-RPC request. */\nexport type RequestKeyInput = string | { method: string; params?: unknown };\n\n/** Options for {@link McpResultCache}. */\nexport interface McpResultCacheOptions {\n  /** Max number of live entries. Oldest-inserted entries are evicted first. Default 1000. `0`/negative disables caching. */\n  maxEntries?: number;\n  /** Clock for TTL math. Default `Date.now`. Override with fake timers in tests. */\n  clock?: Clock;\n  /** Treat a `0` TTL as cacheable. Default `false` (0 = immediately stale). */\n  allowZeroTtl?: boolean;\n}\n\n/** Per-lookup options. */\nexport interface LookupOptions {\n  /**\n   * Identity of the caller's authorization context (token hash / user / tenant /\n   * session id). REQUIRED to read or write `private` entries; ignored for `public`.\n   */\n  scopeId?: string;\n}\n\n/** Outcome of {@link McpResultCache.set}. */\nexport type SetOutcome =\n  | { stored: true; scopeKey: string; expiresAt: number; hints: CacheHints }\n  | { stored: false; reason: UncacheableReason; message: string };\n\n/** Outcome of {@link McpResultCache.get}. */\nexport type GetOutcome<T> =\n  | { hit: true; value: T; hints: CacheHints; expiresAt: number }\n  | { hit: false; reason: GetMissReason };\n\n/** Why a {@link McpResultCache.get} missed. */\nexport type GetMissReason =\n  /** No entry for this (request, scope). */\n  | \"miss\"\n  /** An entry existed but its TTL had elapsed (it has been evicted). */\n  | \"expired\";\n\n/** Snapshot counters for observability. Read via {@link McpResultCache.stats}. */\nexport interface CacheStats {\n  hits: number;\n  misses: number;\n  expired: number;\n  stores: number;\n  /** `set` calls rejected because the result was not cache-safe. */\n  rejected: number;\n  evictions: number;\n  /** Current number of live (not-yet-pruned) entries. */\n  size: number;\n}\n\ninterface Entry<T> {\n  value: T;\n  hints: CacheHints;\n  /** Absolute epoch-ms expiry. */\n  expiresAt: number;\n}\n\n/**\n * Build a stable cache key from a request. If given a string, it is used as-is.\n * If given `{ method, params }`, params are deterministically serialized (object\n * keys sorted recursively) so that semantically equal requests collide.\n */\nexport function deriveRequestKey(input: RequestKeyInput): string {\n  if (typeof input === \"string\") return input;\n  return `${input.method}\u0000${stableStringify(input.params)}`;\n}\n\n/** Deterministic JSON: object keys sorted recursively. Arrays keep order. */\nexport function stableStringify(value: unknown): string {\n  return JSON.stringify(normalize(value));\n}\n\nfunction normalize(value: unknown): unknown {\n  if (value === null || typeof value !== \"object\") return value;\n  if (Array.isArray(value)) return value.map(normalize);\n  const obj = value as Record<string, unknown>;\n  const out: Record<string, unknown> = {};\n  for (const key of Object.keys(obj).sort()) {\n    out[key] = normalize(obj[key]);\n  }\n  return out;\n}\n\n/** Compose the internal storage key from request key + scope key. */\nfunction storageKey(requestKey: string, scopeKey: string): string {\n  return `${scopeKey}\u0000${requestKey}`;\n}\n\n/**\n * A small, dependency-free, SEP-2549-aware result cache safe for use in MCP\n * clients, gateways, and proxies.\n */\nexport class McpResultCache {\n  readonly #maxEntries: number;\n  readonly #clock: Clock;\n  readonly #allowZeroTtl: boolean;\n  // Insertion-ordered (Map preserves order) — enables O(1) FIFO eviction.\n  readonly #store = new Map<string, Entry<unknown>>();\n  #stats: Omit<CacheStats, \"size\"> = {\n    hits: 0,\n    misses: 0,\n    expired: 0,\n    stores: 0,\n    rejected: 0,\n    evictions: 0,\n  };\n\n  constructor(options: McpResultCacheOptions = {}) {\n    this.#maxEntries = options.maxEntries ?? 1000;\n    this.#clock = options.clock ?? Date.now;\n    this.#allowZeroTtl = options.allowZeroTtl ?? false;\n  }\n\n  /**\n   * Store a result IF it is cache-safe for the given scope. Validates hints,\n   * derives the scope key (refusing `private` without a `scopeId`), and stores\n   * keyed by (request, scope). Returns whether it was stored and why not.\n   *\n   * Always safe to call on any result — non-cacheable results are silently\n   * rejected (counted in {@link CacheStats.rejected}) rather than stored.\n   */\n  set<T extends object>(\n    request: RequestKeyInput,\n    result: T,\n    options: LookupOptions = {},\n  ): SetOutcome {\n    if (this.#maxEntries <= 0) {\n      return { stored: false, reason: \"missing-fields\", message: \"cache disabled (maxEntries <= 0)\" };\n    }\n    const decision: CacheDecision = cacheSafety(result, {\n      ...(options.scopeId !== undefined ? { scopeId: options.scopeId } : {}),\n      allowZeroTtl: this.#allowZeroTtl,\n    });\n    if (!decision.cacheable) {\n      this.#stats.rejected++;\n      return { stored: false, reason: decision.reason, message: decision.message };\n    }\n\n    const requestKey = deriveRequestKey(request);\n    const key = storageKey(requestKey, decision.scopeKey);\n    const expiresAt = this.#clock() + decision.hints.ttlMs;\n\n    // Refresh insertion order on overwrite so re-stored hot entries aren't the\n    // first to be evicted.\n    this.#store.delete(key);\n    this.#store.set(key, { value: result, hints: decision.hints, expiresAt });\n    this.#stats.stores++;\n\n    this.#evictIfNeeded();\n    return { stored: true, scopeKey: decision.scopeKey, expiresAt, hints: decision.hints };\n  }\n\n  /**\n   * Look up a result for the given request AND scope identity.\n   *\n   * A `private` entry is ONLY returned to the same `scopeId` that stored it: the\n   * lookup derives the scope key from the caller's `scopeId`, so another caller's\n   * lookup targets a different key and can never reach it. A `public` entry is\n   * returned to anyone (it is stored under the shared public key).\n   *\n   * Expired entries are treated as a miss and removed lazily on access.\n   */\n  get<T>(request: RequestKeyInput, options: LookupOptions = {}): GetOutcome<T> {\n    const requestKey = deriveRequestKey(request);\n\n    // Prefer the caller's OWN private bucket (more specific) over the shared\n    // public bucket for the same request, then fall back to public. We never try\n    // another caller's private key — there is no way to construct it without their\n    // scopeId, so private-first cannot leak.\n    const candidateScopeKeys: string[] = [];\n    const privateKey = deriveScopeKey(CacheScope.Private, options.scopeId);\n    if (privateKey !== undefined) candidateScopeKeys.push(privateKey);\n    candidateScopeKeys.push(deriveScopeKey(CacheScope.Public)!);\n\n    for (const scopeKey of candidateScopeKeys) {\n      const key = storageKey(requestKey, scopeKey);\n      const entry = this.#store.get(key);\n      if (entry === undefined) continue;\n\n      if (this.#clock() >= entry.expiresAt) {\n        this.#store.delete(key);\n        this.#stats.expired++;\n        // Keep scanning other candidate buckets — a fresh public entry might\n        // still satisfy this lookup even if a private one expired.\n        continue;\n      }\n      this.#stats.hits++;\n      return {\n        hit: true,\n        value: entry.value as T,\n        hints: entry.hints,\n        expiresAt: entry.expiresAt,\n      };\n    }\n\n    this.#stats.misses++;\n    return { hit: false, reason: \"miss\" };\n  }\n\n  /**\n   * Convenience wrapper: return the cached value, or compute + store it.\n   *\n   * If a fresh entry exists it is returned. Otherwise `loader()` runs, its result\n   * is offered to {@link set} (stored only if cache-safe), and returned regardless.\n   */\n  async getOrLoad<T extends object>(\n    request: RequestKeyInput,\n    loader: () => Promise<T> | T,\n    options: LookupOptions = {},\n  ): Promise<T> {\n    const cached = this.get<T>(request, options);\n    if (cached.hit) return cached.value;\n    const value = await loader();\n    this.set(request, value, options);\n    return value;\n  }\n\n  /** Remove all entries whose TTL has elapsed. Returns the count removed. */\n  prune(): number {\n    const now = this.#clock();\n    let removed = 0;\n    for (const [key, entry] of this.#store) {\n      if (now >= entry.expiresAt) {\n        this.#store.delete(key);\n        removed++;\n      }\n    }\n    this.#stats.expired += removed;\n    return removed;\n  }\n\n  /** Drop everything. Does not reset stat counters. */\n  clear(): void {\n    this.#store.clear();\n  }\n\n  /** Current live entry count (without pruning). */\n  get size(): number {\n    return this.#store.size;\n  }\n\n  /** A snapshot of counters plus current size. */\n  stats(): CacheStats {\n    return { ...this.#stats, size: this.#store.size };\n  }\n\n  #evictIfNeeded(): void {\n    while (this.#store.size > this.#maxEntries) {\n      const oldest = this.#store.keys().next().value;\n      if (oldest === undefined) break;\n      this.#store.delete(oldest);\n      this.#stats.evictions++;\n    }\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,394 @@
+/**
+ * Core types for mcp-cache-kit, modeled on MCP SEP-2549.
+ *
+ * SEP-2549 (MCP spec, 2026-07-28 release candidate) adds two top-level fields to
+ * cacheable results (`tools/list`, `resources/list`, `resources/templates/list`,
+ * `prompts/list`, `resources/read`):
+ *
+ *   - `ttlMs: number`   — how long the client MAY treat the result as fresh,
+ *                          analogous to HTTP `Cache-Control: max-age`. `@minimum 0`.
+ *   - `cacheScope: "public" | "private"` — analogous to HTTP
+ *                          `Cache-Control: public` vs `private`.
+ *
+ * Source of truth (verified):
+ *   https://github.com/modelcontextprotocol/modelcontextprotocol (schema/draft/schema.ts,
+ *   docs/specification/draft/server/utilities/caching.mdx) and
+ *   https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/
+ *
+ * NOTE: the 2026-07-28 spec is a release candidate. These field names/semantics
+ * may still shift before final. This library is intentionally tolerant of missing
+ * or malformed fields and treats anything it cannot prove safe as uncacheable.
+ */
+/**
+ * The allowed values of `cacheScope` per SEP-2549.
+ *
+ * - `"public"`  — the response does not contain 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 requires a different cache entry).
+ */
+declare const CacheScope: {
+    /** Shareable across authorization contexts. */
+    readonly Public: "public";
+    /** Only reusable within the same authorization context. */
+    readonly Private: "private";
+};
+/** Union of the valid `cacheScope` string values: `"public" | "private"`. */
+type CacheScope = (typeof CacheScope)[keyof typeof CacheScope];
+/** Immutable list of valid scope values, handy for validation/iteration. */
+declare const CACHE_SCOPE_VALUES: readonly CacheScope[];
+/**
+ * The SEP-2549 cache hint fields as they appear (top-level) on a cacheable result.
+ */
+interface CacheHints {
+    /**
+     * How long (ms) the client MAY treat the result as fresh. `>= 0`.
+     * `0` means "immediately stale". See {@link CacheScope} for scope semantics.
+     */
+    ttlMs: number;
+    /** Whether the result is safe to share across authorization contexts. */
+    cacheScope: CacheScope;
+}
+/**
+ * Minimal structural shape of an MCP result that MAY carry cache hints.
+ *
+ * Kept deliberately loose (`Record<string, unknown>`) so the helpers work on plain
+ * result objects WITHOUT a hard dependency on `@modelcontextprotocol/sdk`. If you
+ * do use the SDK, its `ListToolsResult` / `ReadResourceResult` (etc.) structurally
+ * satisfy this type.
+ */
+interface MaybeCacheableResult extends Record<string, unknown> {
+    ttlMs?: unknown;
+    cacheScope?: unknown;
+}
+/**
+ * A result that carries valid, fully-typed SEP-2549 cache hints.
+ * `T` is the underlying result type so callers keep their concrete shape.
+ */
+type WithCacheHints<T extends object> = T & CacheHints;
+/** Options accepted by {@link withCacheHints}. */
+interface CacheHintsInput {
+    /** Time-to-live in milliseconds. Must be a finite number `>= 0`. */
+    ttlMs: number;
+    /** One of {@link CacheScope}. */
+    cacheScope: CacheScope;
+}
+/**
+ * Result of parsing the cache hints off an unknown result object.
+ *
+ * `ok: true` only when BOTH fields are present and valid per spec. Otherwise
+ * `ok: false` with a machine-readable `reason` and human-readable `message`.
+ */
+type ParsedCacheHints = {
+    ok: true;
+    hints: CacheHints;
+} | {
+    ok: false;
+    reason: UncacheableReason;
+    message: string;
+};
+/** Machine-readable reasons a result is considered uncacheable. */
+type UncacheableReason = 
+/** The result was null/undefined or not an object. */
+"not-an-object"
+/** `ttlMs` or `cacheScope` was absent. Fail-safe: don't cache. */
+ | "missing-fields"
+/** `ttlMs` was present but not a finite number `>= 0`. */
+ | "invalid-ttl"
+/** `cacheScope` was present but not `"public" | "private"`. */
+ | "invalid-scope"
+/** `ttlMs` was `0` — explicitly "immediately stale", so nothing to store. */
+ | "zero-ttl"
+/** A `private` result was offered without a scope identity to key it by. */
+ | "private-without-scope";
+/**
+ * The decision returned by {@link cacheSafety} / used by the cache: may this result
+ * be stored for the given scope identity, and if not, why.
+ */
+type CacheDecision = {
+    cacheable: true;
+    hints: CacheHints;
+    /**
+     * The scope key the entry MUST be stored under. For `public` results this is
+     * a shared constant; for `private` results it is derived from the caller's
+     * authorization-context identity.
+     */
+    scopeKey: string;
+} | {
+    cacheable: false;
+    reason: UncacheableReason;
+    message: string;
+};
+
+/**
+ * Server-side helpers: attach and read SEP-2549 cache hints on results.
+ */
+
+/** Type guard for the `cacheScope` enum. */
+declare function isCacheScope(value: unknown): value is CacheScope;
+/**
+ * True if `ttlMs` is a valid SEP-2549 TTL: a finite, non-negative number.
+ *
+ * The spec annotates `ttlMs` with `@minimum 0` and treats negative/absent values
+ * as `0`. We require a real finite number here (NaN / Infinity are rejected).
+ */
+declare function isValidTtlMs(value: unknown): value is number;
+/**
+ * Validate a {@link CacheHintsInput}, throwing a descriptive `TypeError` on bad input.
+ * Returns the normalized {@link CacheHints} (ttlMs floored to an integer ms).
+ *
+ * @throws {TypeError} if `ttlMs` is not a finite number `>= 0`, or `cacheScope`
+ *   is not `"public" | "private"`.
+ */
+declare function validateCacheHints(input: CacheHintsInput): CacheHints;
+/**
+ * Server-side: attach SEP-2549 cache hints to a `tools/list` / `resources/read`
+ * (etc.) result so clients and proxies can cache it correctly.
+ *
+ * Returns a NEW object (does not mutate the input) with `ttlMs` and `cacheScope`
+ * set as top-level fields, exactly where the spec places them.
+ *
+ * @example
+ * ```ts
+ * server.setRequestHandler(ListToolsRequestSchema, () =>
+ *   withCacheHints({ tools }, { ttlMs: 60_000, cacheScope: CacheScope.Public }),
+ * );
+ * ```
+ *
+ * @throws {TypeError} via {@link validateCacheHints} on invalid hints.
+ */
+declare function withCacheHints<T extends object>(result: T, hints: CacheHintsInput): WithCacheHints<T>;
+/**
+ * Convenience: a `public` result fresh for `ttlMs`. Safe to share across users.
+ */
+declare function publicHints(ttlMs: number): CacheHints;
+/**
+ * Convenience: a `private` result fresh for `ttlMs`. Reusable only within the
+ * same authorization context — the cache will refuse to share it across scopes.
+ */
+declare function privateHints(ttlMs: number): CacheHints;
+/**
+ * Client/proxy-side: read and validate the cache hints off an unknown result.
+ *
+ * Returns `{ ok: true, hints }` only when BOTH fields are present and valid.
+ * Anything else returns `{ ok: false, reason, message }` — this is the fail-safe
+ * primitive the cache builds on: if we cannot prove the hints, we don't cache.
+ *
+ * This never throws. It is safe to call on arbitrary JSON-RPC result payloads.
+ */
+declare function parseCacheHints(result: unknown): ParsedCacheHints;
+
+/**
+ * The safety layer: decide whether a result may be cached for a given
+ * authorization-context identity, and derive the scope key it must be stored under.
+ *
+ * This is where the cross-user-leak trap is closed. SEP-2549 says a `private`
+ * result "MAY be cached and reused only within the same authorization context".
+ * We enforce that by KEYING private entries with the caller's scope identity, so a
+ * `private` entry stored for user A is structurally unreachable for user B.
+ */
+
+/**
+ * The single, shared scope key used for `public` results. Chosen to be a value
+ * that cannot collide with any real scope identity (which is escaped, see below).
+ */
+declare const PUBLIC_SCOPE_KEY = "public";
+/** Options for {@link cacheSafety} / {@link assertCacheSafe}. */
+interface CacheSafetyOptions {
+    /**
+     * Identity of the caller's authorization context — e.g. an access-token hash,
+     * user id, tenant id, or session id. REQUIRED to cache `private` results.
+     * Pass it for `public` results too if you have it; it will simply be ignored.
+     */
+    scopeId?: string;
+    /**
+     * If true, a `ttlMs` of `0` is reported as cacheable (with `zero-ttl` being a
+     * non-fatal note). Default `false`: a 0 TTL means "immediately stale", so there
+     * is nothing worth storing and we report it uncacheable. The cache uses the
+     * default.
+     */
+    allowZeroTtl?: boolean;
+}
+/**
+ * Derive the scope key an entry must be stored under.
+ *
+ * - `public`  → {@link PUBLIC_SCOPE_KEY} (shared across all callers).
+ * - `private` → a key derived from `scopeId`, namespaced so it can never collide
+ *   with the public bucket or with another scope id.
+ *
+ * Returns `undefined` for a `private` result when no `scopeId` is supplied —
+ * the caller MUST treat that as "do not cache".
+ */
+declare function deriveScopeKey(cacheScope: CacheScope, scopeId?: string): string | undefined;
+/**
+ * Decide whether `result` may be cached for the given scope identity.
+ *
+ * Returns a {@link CacheDecision}: when `cacheable: true` it includes the validated
+ * hints and the `scopeKey` to store the entry under; when `cacheable: false` it
+ * includes a machine-readable `reason` and a human-readable `message`.
+ *
+ * Fail-safe by construction: missing/invalid hints, an unrecognized scope, a
+ * `private` result without a `scopeId`, and (by default) a `0` TTL all return
+ * `cacheable: false`. Never throws.
+ *
+ * Use this as a guard anywhere in a proxy/gateway:
+ * ```ts
+ * const d = cacheSafety(result, { scopeId: tokenHash });
+ * if (d.cacheable) store(key, d.scopeKey, result, d.hints.ttlMs);
+ * ```
+ */
+declare function cacheSafety(result: unknown, options?: CacheSafetyOptions): CacheDecision;
+/** Error thrown by {@link assertCacheSafe} when a result may not be cached. */
+declare class CacheUnsafeError extends Error {
+    readonly name = "CacheUnsafeError";
+    /** Machine-readable reason, mirrors {@link CacheDecision}'s `reason`. */
+    readonly reason: Extract<CacheDecision, {
+        cacheable: false;
+    }>["reason"];
+    constructor(decision: Extract<CacheDecision, {
+        cacheable: false;
+    }>);
+}
+/**
+ * Assert that `result` may be cached for the given scope identity, throwing a
+ * {@link CacheUnsafeError} otherwise. Returns the validated hints + scopeKey.
+ *
+ * Prefer {@link cacheSafety} when you want to branch without exceptions; use this
+ * when "must be cacheable here" is an invariant you want to enforce loudly.
+ */
+declare function assertCacheSafe(result: unknown, options?: CacheSafetyOptions): {
+    hints: CacheHints;
+    scopeKey: string;
+};
+
+/**
+ * Client / proxy-side cache that honors SEP-2549 hints — and never leaks a
+ * `private` result across authorization contexts.
+ *
+ * Safety model (the whole point of this package):
+ *   - Every stored entry is keyed by `requestKey` AND `scopeKey`.
+ *   - `public` results use a single shared scopeKey, so they ARE shared.
+ *   - `private` results use a scopeKey derived from the caller's `scopeId`, so a
+ *     lookup by a different caller derives a different key and structurally cannot
+ *     hit another caller's entry.
+ *   - Anything we cannot prove safe (missing/invalid hints, private-without-scope,
+ *     0 TTL) is simply not stored. `get` of such a thing is always a miss.
+ */
+
+/** Monotonic-ish clock returning epoch milliseconds. Injectable for tests. */
+type Clock = () => number;
+/** A request identity: either a precomputed string key, or the raw JSON-RPC request. */
+type RequestKeyInput = string | {
+    method: string;
+    params?: unknown;
+};
+/** Options for {@link McpResultCache}. */
+interface McpResultCacheOptions {
+    /** Max number of live entries. Oldest-inserted entries are evicted first. Default 1000. `0`/negative disables caching. */
+    maxEntries?: number;
+    /** Clock for TTL math. Default `Date.now`. Override with fake timers in tests. */
+    clock?: Clock;
+    /** Treat a `0` TTL as cacheable. Default `false` (0 = immediately stale). */
+    allowZeroTtl?: boolean;
+}
+/** Per-lookup options. */
+interface LookupOptions {
+    /**
+     * Identity of the caller's authorization context (token hash / user / tenant /
+     * session id). REQUIRED to read or write `private` entries; ignored for `public`.
+     */
+    scopeId?: string;
+}
+/** Outcome of {@link McpResultCache.set}. */
+type SetOutcome = {
+    stored: true;
+    scopeKey: string;
+    expiresAt: number;
+    hints: CacheHints;
+} | {
+    stored: false;
+    reason: UncacheableReason;
+    message: string;
+};
+/** Outcome of {@link McpResultCache.get}. */
+type GetOutcome<T> = {
+    hit: true;
+    value: T;
+    hints: CacheHints;
+    expiresAt: number;
+} | {
+    hit: false;
+    reason: GetMissReason;
+};
+/** Why a {@link McpResultCache.get} missed. */
+type GetMissReason = 
+/** No entry for this (request, scope). */
+"miss"
+/** An entry existed but its TTL had elapsed (it has been evicted). */
+ | "expired";
+/** Snapshot counters for observability. Read via {@link McpResultCache.stats}. */
+interface CacheStats {
+    hits: number;
+    misses: number;
+    expired: number;
+    stores: number;
+    /** `set` calls rejected because the result was not cache-safe. */
+    rejected: number;
+    evictions: number;
+    /** Current number of live (not-yet-pruned) entries. */
+    size: number;
+}
+/**
+ * Build a stable cache key from a request. If given a string, it is used as-is.
+ * If given `{ method, params }`, params are deterministically serialized (object
+ * keys sorted recursively) so that semantically equal requests collide.
+ */
+declare function deriveRequestKey(input: RequestKeyInput): string;
+/** Deterministic JSON: object keys sorted recursively. Arrays keep order. */
+declare function stableStringify(value: unknown): string;
+/**
+ * A small, dependency-free, SEP-2549-aware result cache safe for use in MCP
+ * clients, gateways, and proxies.
+ */
+declare class McpResultCache {
+    #private;
+    constructor(options?: McpResultCacheOptions);
+    /**
+     * 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<T extends object>(request: RequestKeyInput, result: T, options?: LookupOptions): SetOutcome;
+    /**
+     * 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<T>(request: RequestKeyInput, options?: LookupOptions): GetOutcome<T>;
+    /**
+     * 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.
+     */
+    getOrLoad<T extends object>(request: RequestKeyInput, loader: () => Promise<T> | T, options?: LookupOptions): Promise<T>;
+    /** Remove all entries whose TTL has elapsed. Returns the count removed. */
+    prune(): number;
+    /** Drop everything. Does not reset stat counters. */
+    clear(): void;
+    /** Current live entry count (without pruning). */
+    get size(): number;
+    /** A snapshot of counters plus current size. */
+    stats(): CacheStats;
+}
+
+export { CACHE_SCOPE_VALUES, type CacheDecision, type CacheHints, type CacheHintsInput, type CacheSafetyOptions, CacheScope, type CacheStats, CacheUnsafeError, type Clock, type GetMissReason, type GetOutcome, type LookupOptions, type MaybeCacheableResult, McpResultCache, type McpResultCacheOptions, PUBLIC_SCOPE_KEY, type ParsedCacheHints, type RequestKeyInput, type SetOutcome, type UncacheableReason, type WithCacheHints, assertCacheSafe, cacheSafety, deriveRequestKey, deriveScopeKey, isCacheScope, isValidTtlMs, parseCacheHints, privateHints, publicHints, stableStringify, validateCacheHints, withCacheHints };