mcp-cache-kit 0.1.0

package/dist/index.d.ts

@@ -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 };