Caching Strategies
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Caching in the MCP Games monorepo is a critical performance optimization layer designed to reduce latency and minimize redundant semantic queries to Model Context Protocol (MCP) servers such as GitHub, Linear, and Notion. By storing results of expensive data retrieval operations, the system ensures a fluid narrative experience in the CYOA engine.
The strategy encompasses local client-side caching within the mcp-sdk, service-level caching in the mcp-connector, and configurable policies that allow developers to balance data freshness with system responsiveness.
Sources: README.md:38-40, packages/mcp-sdk/README.md:10
Client-Side Semantic Query Caching
The mcp-sdk implements a primary caching mechanism within the MCPClient class. This layer intercepts semantic queries before they are dispatched to remote servers, checking for previously stored results based on a unique cache key.
Cache Key Generation
To ensure accuracy, cache keys are generated deterministically using the target server ID, the query string, and a stringified representation of the query filters.
private getCacheKey(query: SemanticQuery): string {
return `${query.server}:${query.query}:${JSON.stringify(query.filters)}`;
}
Sources: packages/mcp-sdk/src/index.ts:114-116
Execution Logic
When executeQuery is called, the client checks the cacheEnabled configuration. If enabled, it attempts to retrieve data from an internal Map<string, QueryResult>. If the data is absent (a "cache miss"), the query is executed, and the result is stored for future use.
The following diagram illustrates the internal logic flow for a cached semantic query:
The diagram shows the decision path between returning a stored result and performing a network fetch.
Sources: packages/mcp-sdk/src/index.ts:63-95
Caching Policies and Configuration
The system provides granular control over how data is cached through QueryOptions and global client configuration.
Cache Policies
The shared-types package defines a cachePolicy property within QueryOptions, allowing individual queries to specify their behavior:
| Policy | Description |
|---|---|
cache-first | Returns cached data if available, otherwise queries the network. |
network-first | Attempts to query the network, falling back to cache on failure (Implementation pending). |
no-cache | Bypasses the cache entirely to ensure fresh data. |
Sources: packages/shared-types/src/index.ts:40-44, packages/mcp-sdk/src/index.ts:143-149
Global Configuration
The MCPClient is initialized with a MCPClientConfig object that governs default caching behavior for all operations performed by that instance.
| Option | Type | Default | Description |
|---|---|---|---|
cacheEnabled | boolean | true | Globally toggles the caching mechanism on or off. |
defaultTimeout | number | 5000 | Default timeout for network requests in milliseconds. |
Sources: packages/mcp-sdk/src/index.ts:25-30, packages/mcp-sdk/src/index.ts:159-163
Connector Service Caching
The mcp-connector service acts as the aggregation layer and implements its own caching strategy to optimize performance for the cyoa-engine frontend. It utilizes environment variables to control Time-to-Live (TTL) settings for cached MCP context.
Context Aggregation
The connector is responsible for "Context Aggregation," which involves merging data from multiple MCP sources. This aggregated view is cached to prevent expensive re-calculation during rapid narrative transitions.
- Endpoint:
GET /api/mcp/context/:userId - Default TTL: 3600 seconds (configurable via
MCP_CACHE_TTL)
Sources: apps/mcp-connector/src/index.ts:47-57, apps/mcp-connector/README.md:36
Data Structures
The caching system relies on the QueryResult interface to track the provenance and age of data. This allows the system to distinguish between fresh and cached results in the UI.
export interface QueryResult<T = unknown> {
data: T;
metadata: {
source: string;
timestamp: string;
cached: boolean;
};
}
Sources: packages/shared-types/src/index.ts:46-53
Cache Management Methods
The MCPClient provides a utility to flush all stored queries, which is essential when user credentials change or when the application requires a hard refresh of all integrated data.
clearCache(): Clears the internalMapof query results.
Sources: packages/mcp-sdk/src/index.ts:110-112
Conclusion
The caching strategies within the MCP Games monorepo are implemented as a multi-tier system. By combining local client-side storage in the mcp-sdk with service-level aggregation caching in the mcp-connector, the architecture minimizes external API calls. This results in faster narrative generation and a more responsive user interface while providing developers with the flexibility to override these behaviors via specific cache policies.