Caching

Cache management utilities for MCPClient objects.

This module provides functions for efficient type-annotated retrieval and caching of MCPClient querysets. It includes utilities to:

  • Retrieve and cache MCPClients owned by a user profile

  • Retrieve and cache MCPClients shared with a user profile

  • Retrieve and cache MCPClients available to a user profile (owned or shared)

  • Invalidate caches for owned, shared, and available MCPClients

  • Invalidate all MCPClient-related caches for a user profile

Functions:

  • get_cached_mcpclients_owned_by_user_profile(user_profile)

  • invalidate_cached_mcpclients_owned_by_user_profile(user_profile)

  • get_cached_mcpclients_shared_with_user_profile(user_profile)

  • invalidate_cached_mcpclients_shared_with_user_profile(user_profile)

  • get_cached_mcpclients_available_to_user_profile(user_profile)

  • invalidate_cached_mcpclients_available_to_user_profile(user_profile)

  • invalidate_all_cached_mcpclients_for_user_profile(user_profile)

  • get_cached_catalog(mcpclient, refresh=False)

  • invalidate_cached_catalog(mcpclient)

MCP server catalogs, i.e. each server’s tools, instructions and capabilities, are cached for the MCPClient’s cache_ttl seconds, so that prompts do not connect to the server to list its tools. The cache key includes MCPClient.fingerprint, so that changing how the MCPClient connects, or what it allows, invalidates its catalog. A failure to connect is cached for FAILURE_CACHE_TTL seconds, so that an unreachable server does not delay every prompt by its timeout.

The results of tool calls that the MCP server marks read-only (its readOnlyHint), and of resource reads, are cached for cache_ttl seconds too, by the call and its arguments, with smarter.lib.cache.tool_results.cached_tool_call(). Other tools may change something on every call, so their calls are never cached.

Dependencies:

  • Django ORM

  • cache_results.cache_results

  • smarter.apps.account.models.user_profile.UserProfile

  • smarter.apps.mcpclient.models.MCPClient

smarter.apps.mcpclient.caching.FAILURE_CACHE_TTL = 60

Seconds to remember that an MCP server could not be reached.

smarter.apps.mcpclient.caching.cached_catalog_functions(mcpclient)[source]

Return the cached functions behind an MCPClient’s catalog.

Both are called with the MCPClient’s id and MCPClient.fingerprint, so that changing how the MCPClient connects, or what it allows, changes their cache keys. Their timeouts come from the MCPClient, and do not affect their cache keys, so the functions returned for any instance of an MCPClient share its cache entries.

  • get_cached_connection_result connects to the server, and caches the catalog, or the error, for FAILURE_CACHE_TTL seconds, or cache_ttl if less.

  • get_cached_catalog_data caches the catalog for cache_ttl seconds. It raises, and so caches nothing, when the connection result is an error.

Parameters:

mcpclient (MCPClient) – The MCPClient.

Return type:

tuple[Callable[[int, str], dict[str, Any]], Callable[[int, str], dict[str, Any]]]

Returns:

(get_cached_catalog_data, get_cached_connection_result)

smarter.apps.mcpclient.caching.connect(mcpclient)[source]

Connect to an MCPClient’s server, and return its catalog, without caching.

The result is recorded in the MCPClient’s status fields, and mcpclient_connected or mcpclient_connection_failed is sent.

Parameters:

mcpclient (MCPClient) – The MCPClient.

Returns:

The catalog.

Return type:

MCPServerCatalog

Raises:
smarter.apps.mcpclient.caching.get_cached_catalog(mcpclient, refresh=False)[source]

Return an MCPClient’s catalog: its MCP server’s tools, instructions and capabilities.

The catalog is cached for the MCPClient’s cache_ttl seconds. On a cache miss, Smarter connects to the server, records the result in the MCPClient’s status fields, and sends mcpclient_connected or mcpclient_connection_failed.

Parameters:
  • mcpclient (MCPClient) – The MCPClient.

  • refresh (bool) – Connect to the server even if the catalog, or a recent failure, is cached.

Returns:

The catalog.

Return type:

MCPServerCatalog

Raises:
smarter.apps.mcpclient.caching.get_cached_mcpclients_available_to_user_profile(user_profile)[source]

Retrieve the MCPClients available to the given UserProfile, using caching to optimize performance.

This function returns a queryset of MCPClient objects that are available to the specified user profile, which may include both owned and shared MCPClients. The results are cached to reduce database queries and improve performance. If the cache is invalidated, the queryset is fetched from the database again and re-cached.

Parameters:

user_profile (UserProfile) – The user profile whose available MCPClients should be retrieved.

Returns:

A Django queryset containing the MCPClient objects available to the user.

Return type:

QuerySet

>>> user_profile = UserProfile.objects.get(pk=1)
>>> available_mcpclients = get_cached_mcpclients_available_to_user_profile(user_profile)
>>> for bot in available_mcpclients:
...     print(bot.name)

See also

smarter.apps.mcpclient.caching.get_cached_mcpclients_owned_by_user_profile(user_profile)[source]

Retrieve the MCPClients owned by the given UserProfile, using caching to optimize performance.

This function returns a queryset of MCPClient objects that are owned by the specified user profile. The results are cached to reduce database queries and improve performance. If the cache is invalidated, the queryset is fetched from the database again and re-cached.

Parameters:

user_profile (UserProfile) – The user profile whose owned MCPClients should be retrieved.

Returns:

A Django queryset containing the MCPClient objects owned by the user.

Return type:

QuerySet

>>> user_profile = UserProfile.objects.get(pk=1)
>>> mcpclients = get_cached_mcpclients_owned_by_user_profile(user_profile)
>>> for bot in mcpclients:
...     print(bot.name)

See also

smarter.apps.mcpclient.caching.get_cached_mcpclients_shared_with_user_profile(user_profile)[source]

Retrieve the MCPClients shared with the given UserProfile, using caching to optimize performance.

This function returns a queryset of MCPClient objects that are shared with the specified user profile. The results are cached to reduce database queries and improve performance. If the cache is invalidated, the queryset is fetched from the database again and re-cached.

Parameters:

user_profile (UserProfile) – The user profile whose shared MCPClients should be retrieved.

Returns:

A Django queryset containing the MCPClient objects shared with the user.

Return type:

QuerySet

>>> user_profile = UserProfile.objects.get(pk=1)
>>> shared_mcpclients = get_cached_mcpclients_shared_with_user_profile(user_profile)
>>> for bot in shared_mcpclients:
...     print(bot.name)

See also

smarter.apps.mcpclient.caching.invalidate_all_cached_mcpclients_for_user_profile(user_profile)[source]

Invalidate all cached MCPClient querysets related to the given UserProfile.

This function invalidates the caches for all MCPClient querysets that are related to the specified user profile, including owned, shared, and available MCPClients. This is useful when a change occurs that may affect any of these querysets, ensuring that subsequent calls will fetch fresh data from the database.

Parameters:

user_profile (UserProfile) – The user profile for which to invalidate cached MCPClient querysets.

Returns:

None

Return type:

None

>>> user_profile = UserProfile.objects.get(pk=1)
>>> invalidate_all_cached_mcpclients_for_user_profile(user_profile)

See also

smarter.apps.mcpclient.caching.invalidate_cached_catalog(mcpclient)[source]

Invalidate an MCPClient’s cached catalog, and any cached connection failure.

Catalogs cached under a previous MCPClient.fingerprint are no longer used, and expire with their cache_ttl.

Parameters:

mcpclient (MCPClient) – The MCPClient.

Return type:

None

smarter.apps.mcpclient.caching.invalidate_cached_mcpclients_available_to_user_profile(user_profile)[source]

Drop the cached queryset of MCPClients available to (owned or shared) a user profile.

The next get_cached_mcpclients_available_to_user_profile() call queries the database again.

Parameters:

user_profile (UserProfile) – The user profile whose cached queryset is dropped.

Return type:

None

smarter.apps.mcpclient.caching.invalidate_cached_mcpclients_owned_by_user_profile(user_profile)[source]

Drop the cached queryset of MCPClients owned by a user profile.

The next get_cached_mcpclients_owned_by_user_profile() call queries the database again.

Parameters:

user_profile (UserProfile) – The user profile whose cached queryset is dropped.

Return type:

None

smarter.apps.mcpclient.caching.invalidate_cached_mcpclients_shared_with_user_profile(user_profile)[source]

Drop the cached queryset of MCPClients shared with a user profile.

The next get_cached_mcpclients_shared_with_user_profile() call queries the database again.

Parameters:

user_profile (UserProfile) – The user profile whose cached queryset is dropped.

Return type:

None

smarter.apps.mcpclient.caching.record_connection(mcpclient, catalog)[source]

Record a successful connection in the MCPClient’s status fields.

The fields are updated with a queryset update, which neither changes updated_at nor sends post_save, because this is a status change, not a configuration change.

Parameters:
Return type:

None

smarter.apps.mcpclient.caching.record_connection_failure(mcpclient, error)[source]

Record a failed connection in the MCPClient’s status fields.

Parameters:
  • mcpclient (MCPClient) – The MCPClient.

  • error (str) – A description of the error.

Return type:

None