GXtract API Reference

This section provides auto-generated API documentation for the GXtract server modules and classes.

gxtract.main.setup_logging(log_level, log_format)

Configures the root logger based on server configuration.

Return type:

None

gxtract.main.cli_entry_point()

Command-line interface entry point for the {APP_NAME}. Parses arguments, loads configuration, and starts the server.

Return type:

int

Core server logic for initializing and running the FastMCP server.

gxtract.server.run_server(config)

Initializes and runs the MCP server based on the provided configuration. Lets KeyboardInterrupt propagate to the caller (main.py) for handling.

Return type:

None

Handles server configuration from CLI arguments and environment variables.

class gxtract.config.ServerConfig(transport='http', host='127.0.0.1', port=8080, log_level='INFO', log_format='text', groundx_api_key=None, disable_cache=False, fail_on_cache_init_error=False, is_vscode=False, default_bucket_id=None, friendly_errors=True, cli_args=<factory>)

Bases: object

Holds all server configuration settings.

transport: ``'stdio'`` | 'http' = 'http'

host: str = '127.0.0.1'

port: int = 8080

log_level: ``'DEBUG'`` | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL' = 'INFO'

log_format: ``'text'`` | 'json' = 'text'

groundx_api_key: str | None = None

disable_cache: bool = False

fail_on_cache_init_error: bool = False

is_vscode: bool = False

default_bucket_id: str | None = None

friendly_errors: bool = True

cli_args: Namespace

__init__(transport='http', host='127.0.0.1', port=8080, log_level='INFO', log_format='text', groundx_api_key=None, disable_cache=False, fail_on_cache_init_error=False, is_vscode=False, default_bucket_id=None, friendly_errors=True, cli_args=<factory>)

gxtract.config.load_configuration(args)

Loads configuration, prioritizing CLI arguments over environment variables, and then defaults.

Return type:

ServerConfig

gxtract.config.get_args(literal_type)

Extracts arguments from a Literal type.

Return type:

tuple[str, ...]

Cache for GroundX metadata, such as projects and buckets.

This module provides an in-memory cache for frequently accessed GroundX metadata to reduce API calls and improve performance. The cache is populated on server startup and can be refreshed periodically or manually.

class gxtract.cache.BucketDetail

Bases: TypedDict

Structure for cached bucket details.

id: str

name: str

class gxtract.cache.ProjectDetail

Bases: TypedDict

Structure for cached project details.

id: str

name: str

buckets: list[BucketDetail]

class gxtract.cache.CacheStatistics

Bases: TypedDict

Structure for tracking cache performance metrics.

hits: int

misses: int

last_hit_time: str | None

last_miss_time: str | None

last_refresh_time: str | None

refresh_count: int

refresh_success_count: int

refresh_failure_count: int

class gxtract.cache.GroundXMetadataCache

Bases: TypedDict

Structure for the GroundX metadata cache.

projects: list[ProjectDetail]

last_refreshed: str | None

statistics: CacheStatistics

gxtract.cache.get_cache_statistics()

Returns the current cache statistics.

Returns:

A dictionary containing cache hit/miss counts and other statistics.

Return type:

Dict

async gxtract.cache.refresh_groundx_metadata_cache()

Refreshes the GroundX metadata cache by fetching projects and their buckets.

Returns:

True if the cache was refreshed successfully, False otherwise.

Return type:

bool

async gxtract.cache.get_cached_projects()

Returns the list of cached projects.

If the cache is empty (possibly because it was disabled), this will still return an empty list. The calling code should handle this appropriately.

Return type:

list[ProjectDetail]

async gxtract.cache.get_cached_project_by_id(project_id)

Returns a specific project from cache by its ID.

If the cache is disabled, this will return None. The calling code should handle this by making a direct API call if needed.

Return type:

ProjectDetail | None

async gxtract.cache.get_cached_bucket_by_id(project_id, bucket_id)

Returns a specific bucket from cache by its project ID and bucket ID.

If the cache is disabled, this will return None. The calling code should handle this by making a direct API call if needed.

Return type:

BucketDetail | None