Cache Management Tools for GXtract

GXtract includes a set of tools for inspecting and managing its internal cache of GroundX metadata. This cache primarily stores information like GroundX Project IDs and their associated Bucket IDs to optimize interactions with the GroundX API by reducing redundant calls.

The cache has a Time-To-Live (TTL) associated with its entries and is refreshed periodically in the background. These tools allow you to monitor its status and manually trigger refreshes if needed.

Available Tools

1. cache/getCacheStatistics

Retrieves statistics about the current state of the GroundX metadata cache.

Parameters:

  • None.

Returns:

An object containing cache statistics, such as:

  • hits (integer): The total number of successful cache lookups.

  • misses (integer): The total number of cache lookups that didn’t find the requested item.

  • last_hit_time (string, ISO 8601 format): The timestamp of the last successful cache lookup. null if never accessed.

  • last_miss_time (string, ISO 8601 format): The timestamp of the last cache miss. null if no misses.

  • last_refresh_time (string, ISO 8601 format): The timestamp of when the cache was last refreshed. null if never refreshed.

  • refresh_count (integer): The total number of times the cache refresh has been attempted.

  • refresh_success_count (integer): The number of successful cache refresh operations.

  • refresh_failure_count (integer): The number of failed cache refresh operations.

Example MCP Request:

{
  "jsonrpc": "2.0",
  "method": "cache/getCacheStatistics",
  "params": {},
  "id": "cache-stats-req-001"
}

2. cache/listCachedResources

Lists the project and bucket resources currently stored in the GroundX metadata cache. This can be useful for debugging or understanding what metadata the server is currently working with.

Parameters:

  • None.

Returns:

An object containing:

  • projects (array): A list of project objects, each containing:

    • id (string): The project ID.

    • name (string): The project name.

    • buckets (array): A list of bucket objects associated with the project, each containing:

      • id (string): The bucket ID.

      • name (string): The bucket name.

Example MCP Request:

{
  "jsonrpc": "2.0",
  "method": "cache/listCachedResources",
  "params": {},
  "id": "list-cache-req-001"
}

3. cache/refreshMetadataCache

Manually triggers a refresh of the GroundX metadata cache. This can be useful if you know that new projects or buckets have been created in GroundX and want the server to recognize them immediately without waiting for the automatic refresh.

Parameters:

  • None.

Returns:

An object containing:

  • success (boolean): Whether the refresh operation was successful.

  • details (string, optional): Additional details about the refresh operation, especially if it failed.

Example MCP Request:

{
  "jsonrpc": "2.0",
  "method": "cache/refreshMetadataCache",
  "params": {},
  "id": "refresh-cache-req-001"
}

4. cache/refreshCachedResources

An alternative name for cache/refreshMetadataCache that may be used for backward compatibility or clarity.

Parameters and Returns are identical to cache/refreshMetadataCache.

Notes

The cache is automatically populated when the GXtract server starts and periodically refreshed in the background. However, there are situations where manually refreshing the cache is necessary.

Troubleshooting Cache Issues

Common Warning Messages

When using GXtract, you might encounter the following warning messages related to cache operations:

1. “No projects (groups) found or ‘groups’ attribute missing in API response”

This warning appears when the cache refresh operation did not find any projects in your GroundX account.

Possible causes:

  • Your API key doesn’t have access to any projects

  • There are no projects created in your GroundX account yet

  • There’s an issue with the GroundX API response format

  • Network connectivity issues between GXtract and GroundX servers

Solutions:

  • Verify you have projects created in your GroundX account

  • Check your API key permissions

  • Ensure there are no network issues preventing access to GroundX

  • Try refreshing the cache after resolving these issues

2. “GroundX metadata cache population failed. Check logs for details”

This warning appears during server startup if the initial cache population attempt failed.

Solutions:

  • Review the full server logs for more detailed error information

  • Check your API key is correctly set in the environment variables

  • Verify network connectivity to GroundX API endpoints

  • Use the manual cache refresh tools described above to retry the operation

Verifying Cache Status

After refreshing the cache, you can verify its status using the following steps:

  1. Call cache/getCacheStatistics to check if the cache has been successfully refreshed.

  2. Call cache/listCachedResources to see what projects and buckets are currently cached.

The last_refreshed timestamp in the listCachedResources response should be recent, and the projects list should contain the expected projects and buckets.

Using Cache Tools from VS Code MCP Chat Interface

If your version of VS Code supports MCP chat interfaces, you can use the cache tools directly through chat:

  1. Open VS Code’s chat interface.

  2. Begin typing with an @ mention of your MCP server (e.g., @GXtract).

  3. Enter your command to refresh the cache or get statistics.

Examples:

  • @GXtract please refresh the metadata cache - This will trigger the cache/refreshMetadataCache tool.

  • @GXtract show me the cache statistics - This will trigger the cache/getCacheStatistics tool.

  • @GXtract list the cached resources - This will trigger the cache/listCachedResources tool.

Differences Between Cache Refresh Tools

GXtract provides two tools for refreshing the cache:

  1. cache/refreshMetadataCache: The primary tool for refreshing the GroundX metadata cache. It fetches the latest projects and buckets from the GroundX API.

  2. cache/refreshCachedResources: Functionally equivalent to refreshMetadataCache. It’s provided as an alternative name for clarity or backward compatibility.

Both tools perform the same operation internally and will refresh the entire cache, including projects and their associated buckets.

Best Practices

  • After Account Setup: Always manually refresh the cache after setting up new projects or buckets in your GroundX account to ensure GXtract can immediately use them.

  • Periodic Verification: Periodically check the cache statistics to ensure the cache is functioning correctly, especially if you encounter unexpected behavior.

  • Before Important Operations: Consider refreshing the cache before important operations to ensure you’re working with the most up-to-date project and bucket information.