Module result_cache 

Result-cache layer for large MCP tool outputs.

Large tool results (long search hit lists, document corpora, scraped pages) don’t belong in the model window. This module provides a deterministic, transport-neutral way to:

1. Cache an oversized JSON array under an opaque handle.
2. Envelope what the model actually sees: the handle, the total item count, the page size, and a deterministic first page.
3. Page through the remaining items on demand via follow-up tools that read from the cache.
4. Release the handle when the caller is done so memory bounds stay deterministic.

rig-mcp keeps raw transports lossless. Callers can invoke cache_if_large directly, or opt into CachedResultsTransport and the page/release tools from the cache_tools module at the model boundary.

Example

use rig_mcp::result_cache::{
    CachedResultEnvelope, MemoryResultCache, ResultCache, cache_if_large,
};
use serde_json::{Value, json};
use std::sync::Arc;

let cache: Arc<dyn ResultCache> = Arc::new(MemoryResultCache::new());
let big = json!([{"id": 1}, {"id": 2}, {"id": 3}]);
let envelope = cache_if_large(big, cache.as_ref(), 16, 1);
// The first page is a tiny preview; the rest are paged through the cache.
let env: CachedResultEnvelope = serde_json::from_value(envelope).unwrap();
assert_eq!(env.total_items, 3);

Structs

CachedResultEnvelope

JSON envelope returned to the model in place of an oversized array.

CachedResultHandle

Opaque, unique handle for a cached result. Stable for the lifetime of the ResultCache entry; invalidated by ResultCache::release.

MemoryResultCache

Process-local, in-memory ResultCache.

Traits

ResultCache

Transport-neutral cache for paged tool results.

Functions

cache_if_large

If value is a JSON array whose serialized form exceeds threshold_bytes, store it in cache and return a JSON CachedResultEnvelope. Otherwise return value unchanged.