Semantic Data Explorer Utility v1.0.0

Overview

This Model Context Protocol (MCP) service furnishes an intuitive, chat-based mechanism for probing and dissecting Resource Description Framework (RDF) knowledge bases, which are assumed to be structured in Turtle format. It operates in two primary modes: processing a local file-based graph or interfacing directly with an external SPARQL endpoint. The core function is to bridge AI clients with complex graph data, enabling sophisticated data retrieval and analysis via SPARQL commands. It is optimally suited for advanced knowledge graph exploration and preparatory data curation for AI systems.

Available Toolset

The server component exposes capabilities for executing structured queries and searching indexed content:

execute_on_endpoint
Dispatches a SPARQL query directly to a specified remote endpoint.
Inputs:
- endpoint (String): The Uniform Resource Locator (URL) of the target SPARQL endpoint.
- query (String): The specific SPARQL text command intended for execution.
- ctx (Context): The internal context object provided by FastMCP.
Output: Results serialized as a delimited string, or an operational failure notice.
sparql_query
Executes a SPARQL statement against the currently active graph context or the configured remote endpoint.
Inputs:
- query (String): The SPARQL instruction set.
- ctx (Context): The FastMCP context reference.
- use_service (Boolean): Flag to invoke the SERVICE clause for federated queries when operating in local mode (defaults to True).
Output: Query output as a newline-delimited text block, or an error report.
graph_stats
Computes and returns comprehensive metadata regarding the graph structure, formatted as JSON.
Inputs:
- ctx (Context): The FastMCP execution context object.
Output: A JSON string detailing metrics such as total triple count and subject diversity.
count_triples
Provides a tally of all assertions (triples) contained within the loaded graph. Note: This function is non-operational when connected to a remote endpoint; users should employ custom prompts instead.
Inputs:
- ctx (Context): The MCP execution context.
Output: The numerical count as a string, or an explanatory error.
full_text_search
Initiates a comprehensive text-based search across the graph data or endpoint, designed to bypass vendor-specific query extensions.
Inputs:
- search_term (String): The sequence of characters to locate.
- ctx (Context): The FastMCP operational context.
Output: Search findings as a newline-separated string, or an error indication.
health_check
Assesses the operational status of the underlying triple store connection.
Inputs:
- ctx (Context): The context object.
Output: Returns 'Healthy' upon successful connection verification, or 'Unhealthy: ' otherwise.
get_mode
Retrieves the current operational setting of the Explorer. Valuable for semantic technology practitioners needing to confirm the data source location.
Inputs:
- ctx (Context): The context object.
Output: A descriptive message specifying the active configuration (mode and associated dataset/endpoint).

Available Data Endpoints (Resources)

The service exposes the following retrieval mechanisms: - schema://all: Fetches the defined structure information (entity classes and property types) from the knowledge graph. - Output: A newline-separated sequence representing schema elements.

queries://{template_name}: Retrieves a pre-defined SPARQL query template based on its identifier.
Input: {template_name} (String): The name of the required template.
Output: The corresponding SPARQL text command or a 'Template not found' notice.
explore://{query_name}: Executes a specialized exploratory SPARQL routine identified by name and returns the findings in JSON format.
Input: {query_name} (String): Identifier for the exploratory routine (e.g., 'entities', 'property_mappings').
Output: A JSON string containing the structured results.
explore://report: Generates a consolidated analytical summary document formatted in Markdown.
Output: A comprehensive report string rendered in Markdown syntax.

Predefined Command Prompts

The server provides several specialized conversational routines: - analyze_graph_structure: Kicks off a detailed examination of the graph's architecture utilizing available schema metadata. - Output: A sequence of instructional messages designed to guide the structural analysis process.

find_relationships: Constructs and returns a SPARQL query specifically tailored to locate associative links pertaining to a specified subject entity.
Output: A complete SPARQL query string.
text_to_sparql: Converts a natural language instruction into an executable SPARQL query, incorporating checks for token limits during translation.
Input: prompt (String): The user's textual request to be translated.
Output: The resulting query execution data, possibly including operational usage statistics, or an error message.

Deployment Instructions

Configuration Details

Integration with Claude Desktop

Ensure that Claude Desktop application is installed prior to proceeding. 1. Navigate to: Settings -> Developer -> Edit Configuration

Insert the subsequent configuration block into your claude_desktop_config.json file. The location varies by operating system: On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

For usage involving a local RDF Turtle archive, utilize the configuration below, specifying the necessary arguments:

{
  "mcpServers": {
    "rdf_explorer": {
      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\server.py", "--triple-file", "your_file.ttl"]
    }
  }
}

For operation against a SPARQL Endpoint, employ this configuration variant:

{
  "mcpServers": {
    "rdf_explorer": {
      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\server.py", "--sparql-endpoint", "https://example.com/sparql"]
    }
  }
}

Relaunch Claude Desktop to activate the new configuration, permitting immediate interaction and graph data exploration.
Example Query: "Ascertain the current operational mode of the Knowledge Graph Interrogator?"

Operational Examples

Illustration of how semantic information can be extracted using plain language commands:

Data Access in Local Archive Mode

Sample user inquiries: - "Retrieve all personnel records associated with the Marketing division." - "Identify the five oldest registered users." - "Who has initiated more than three distinct transactions in the last 30 days?" - "Enumerate all known entities." - "Querying the DBpedia repository, list ten musical compositions by Michael Jackson." - "Consulting the Wikidata repository, list five major metropolitan areas." - "Determine the total assertion count." - "Initiate a graph topology review." - "Execute a SELECT statement..." - "Perform a text search for '{term}' on the dataset." - "Map the connections originating from '{URI}'." - "Report the active configuration setting."

Data Access in Remote Endpoint Mode

Sample user inquiries: - "Using the DBpedia endpoint, retrieve ten musical compositions by Michael Jackson." - "Using the Wikidata endpoint, fetch five city records." - "Execute a SELECT query..." - "Initiate a text search for '{term}'." - "Map the entity relationships originating from '{URI}'." - "What is the current operational mode?"

Development Workflow

# Clone the source repository
git clone https://github.com/emekaokoye/mcp-rdf-explorer.git
cd mcp-rdf-explorer

# Set up an isolated Python environment
python -m venv venv
source venv/bin/activate
# For Windows users: venv\Scripts\activate

# Install necessary dependencies for development
pip install -r requirements.txt

# Run verification tests
pytest test_rdf_explorer.py -v

Licensing Information

This server component is distributed under the permissive MIT License. This license permits unrestricted use, modification, and redistribution, provided the terms stipulated in the MIT License are respected. Further particulars are detailed in the license file within the project directory.