GXtract Tools API Reference¶

This section provides auto-generated API documentation for the tools available in GXtract.

GroundX Tools for the MCP Server.

These tools provide access to search documents, query documents, and explain semantic objects within the GroundX platform, enabling AI assistance with scientific papers and technical documentation.

class gxtract.tools.groundx.SearchDocumentsParams[source]¶

Bases: TypedDict

Parameters for searching documents in GroundX.

query: str¶

projectId: str | None¶

bucketId: str | None¶

groupId: str | None¶

filter: dict[str, Any] | None¶

limit: int | None¶

class gxtract.tools.groundx.SearchDocumentsReturn[source]¶

Bases: TypedDict

Return type for search documents.

results: list[dict[str, Any]]¶

total: int¶

class gxtract.tools.groundx.QueryDocumentParams[source]¶

Bases: TypedDict

Parameters for querying a specific document.

documentId: str¶

query: str¶

projectId: str | None¶

bucketId: str | None¶

class gxtract.tools.groundx.QueryDocumentReturn[source]¶

Bases: TypedDict

Return type for document query.

answer: str¶

documentInfo: dict[str, Any]¶

confidence: float¶

class gxtract.tools.groundx.ExplainSemanticObjectParams[source]¶

Bases: TypedDict

Parameters for explaining a semantic object within a document.

documentId: str¶

semanticObjectId: str¶

projectId: str | None¶

bucketId: str | None¶

class gxtract.tools.groundx.ExplainSemanticObjectReturn[source]¶

Bases: TypedDict

Return type for semantic object explanation.

explanation: str¶

objectType: str¶

objectInfo: dict[str, Any]¶

async gxtract.tools.groundx.search_documents_handler(params)[source]¶

Searches for documents across a GroundX Project, Bucket, or Group based on a natural language query.

This tool is useful for finding relevant scientific papers, technical documentation, and other document types based on architectural patterns, algorithms, or specific technologies.

Return type:: SearchDocumentsReturn

async gxtract.tools.groundx.query_document_handler(params)[source]¶

Queries a specific document with a natural language question.

This tool allows for extracting precise implementation details, methodologies, or data points from scientific papers or technical documentation.

Return type:: QueryDocumentReturn

async gxtract.tools.groundx.explain_semantic_object_handler(params)[source]¶

Provides explanations for semantic objects (figures, tables, diagrams, etc.) within documents.

This tool is vital for understanding complex visual or structured representations in scientific papers and technical documentation, such as architectural diagrams or result tables.

Return type:: ExplainSemanticObjectReturn

gxtract.tools.groundx.get_tool_definition()[source]¶

Returns the MCP tool definition dictionary for GroundX tools.

Return type:: dict[str, Any]

Cache management tools for the MCP Server.

These tools provide operations for managing the GroundX metadata cache, such as refreshing the cache manually and retrieving cache statistics.

class gxtract.tools.cache_management.RefreshCacheParams[source]¶

Bases: TypedDict

Parameters for refreshing the cache (empty, no parameters needed).

class gxtract.tools.cache_management.RefreshCacheReturn[source]¶

Bases: TypedDict

Return type for refresh cache operation.

success: bool¶

message: str¶

class gxtract.tools.cache_management.GetCacheStatsParams[source]¶

Bases: TypedDict

Parameters for getting cache statistics (empty, no parameters needed).

class gxtract.tools.cache_management.GetCacheStatsReturn[source]¶

Bases: TypedDict

Return type for get cache statistics operation.

statistics: dict¶

class gxtract.tools.cache_management.ListCachedResourcesReturn[source]¶

Bases: TypedDict

Return type for list cached resources.

projects: list[dict[str, Any]]¶

lastRefreshed: str | None¶

class gxtract.tools.cache_management.RefreshCachedResourcesReturn[source]¶

Bases: TypedDict

Return type for refresh cached resources.

success: bool¶

lastRefreshed: str | None¶

projectCount: int¶

async gxtract.tools.cache_management.refresh_metadata_cache_handler(_params)[source]¶

Manually refreshes the GroundX metadata cache.

This tool allows you to refresh the cache when you suspect it might be stale or when you want to ensure you have the most up-to-date metadata for your operations.

Return type:: RefreshCacheReturn
Returns:: A dictionary with success status and a message describing the outcome.

async gxtract.tools.cache_management.get_cache_statistics_handler(_params)[source]¶

Retrieves statistics about the GroundX metadata cache.

This tool provides information about cache usage, hit/miss rates, and refresh history. It’s useful for monitoring cache performance and diagnosing potential issues.

Return type:: GetCacheStatsReturn
Returns:: A dictionary containing cache statistics such as hits, misses, hit rate, and refresh history.

async gxtract.tools.cache_management.list_cached_resources_handler(_=None)[source]¶

Lists available GroundX projects and buckets from the server’s cache.

This tool allows clients to discover available resources without making direct API calls to GroundX, which can be helpful for contextual matching or UI selection interfaces.

Return type:: ListCachedResourcesReturn
Returns:: A dictionary with the list of projects (including their buckets) and a timestamp indicating when the cache was last refreshed.

async gxtract.tools.cache_management.refresh_cached_resources_handler(_=None)[source]¶

Manually refreshes the GroundX projects and buckets cache.

This tool allows clients to force a refresh of the cache without restarting the server.

Return type:: RefreshCachedResourcesReturn

gxtract.tools.cache_management.get_tool_definition()[source]¶

Returns the tool definition for the cache management tools.

This function is called by the tool discovery mechanism to register the cache management tools with the MCP server.

Return type:: dict[str, Any]
Returns:: A dictionary containing the tool definition.

Example MCP Tool: EchoTool Demonstrates a basic tool with a single method.

class gxtract.tools._example.EchoParams[source]¶

Bases: TypedDict

message: str¶

class gxtract.tools._example.EchoReturn[source]¶

Bases: TypedDict

echoed_message: str¶

async gxtract.tools._example.echo_handler(params)[source]¶

Handles the ‘echo’ method call.

Return type:: EchoReturn

gxtract.tools._example.get_tool_definition()[source]¶

Returns the MCP tool definition dictionary for this tool.

Return type:: dict[str, Any]