MCP SPARQL Server

🌟 Overview

MCP SPARQL Server is a high-performance, configurable server that connects to any SPARQL endpoint and provides enhanced functionality including result formatting and caching. It's built on top of the MCP (Message Carrying Protocol) framework to provide a seamless, language-agnostic interface for querying semantic data.

✨ Features

• Universal Endpoint Support: Connect to any SPARQL-compliant endpoint
• Full SPARQL Support: Execute any valid SPARQL query (SELECT, ASK, CONSTRUCT, DESCRIBE)
• Intelligent Result Formatting:
  • Standard JSON (compatible with standard SPARQL clients)
  • Simplified JSON (easier to work with in applications)
  • Tabular format (ready for display in UI tables)
• High-Performance Caching:
  • Multiple cache strategies (LRU, LFU, FIFO)
  • Configurable TTL (time-to-live)
  • Cache management tools
• Flexible Deployment Options:
  • Run in foreground mode
  • Run as a background daemon
  • Deploy as a systemd service
• Comprehensive Configuration:
  • Command-line arguments
  • Environment variables
  • No hardcoded values

📋 Requirements

• Python 3.8 or newer
• SPARQLWrapper library
• mcp framework
• pydantic for configuration
• python-daemon for background execution

🚀 Installation

From Source

# Clone the repository
git clone https://github.com/yet-ai/mcp-server-sparql.git
cd mcp-server-sparql

# Install the package
pip install -e .

From PyPI

pip install mcp-server-sparql

Using the Installation Script

For a full installation with systemd service setup:

# Download the repository
git clone https://github.com/yet-ai/mcp-server-sparql.git
cd mcp-server-sparql

# Run the installation script (as root for systemd service)
sudo ./install.sh

🔍 Usage

Basic Usage

Start the server by specifying a SPARQL endpoint:

mcp-server-sparql --endpoint https://dbpedia.org/sparql

Running as a Daemon

To run the server as a background process:

mcp-server-sparql --endpoint https://dbpedia.org/sparql --daemon \
  --log-file /var/log/mcp-sparql.log \
  --pid-file /var/run/mcp-sparql.pid

Using with Systemd

If installed with systemd support:

1. Configure your endpoint in the environment file:

   sudo nano /etc/mcp-sparql/env
   

2. Start the service:

   sudo systemctl start sparql-server
   

3. Enable on boot:

   sudo systemctl enable sparql-server
   

Client Query Examples

After starting the server, you can query it using the MCP client:

Basic Query

echo '{"query_string": "SELECT * WHERE { ?s ?p ?o } LIMIT 5"}' | mcp claude

Query with Specific Format

echo '{"query_string": "SELECT * WHERE { ?s ?p ?o } LIMIT 5", "format": "tabular"}' | mcp claude

Complex Query Example

echo '{
  "query_string": "PREFIX foaf: <http://xmlns.com/foaf/0.1/> SELECT ?name ?email WHERE { ?person foaf:name ?name . OPTIONAL { ?person foaf:mbox ?email } } LIMIT 5",
  "format": "simplified"
}' | mcp claude

Cache Management

# Get cache statistics
echo '{"action": "stats"}' | mcp cache

# Clear the cache
echo '{"action": "clear"}' | mcp cache

⚙️ Configuration

Command-line Arguments

Environment Variables

📊 Result Formats

The server supports three different output formats:

1. JSON Format (default)

Returns the standard SPARQL JSON results format with optional metadata.

{
  "head": {
    "vars": ["s", "p", "o"]
  },
  "results": {
    "bindings": [
      {
        "s": { "type": "uri", "value": "http://example.org/resource" },
        "p": { "type": "uri", "value": "http://example.org/property" },
        "o": { "type": "literal", "value": "Example Value" }
      }
    ]
  },
  "metadata": {
    "variables": ["s", "p", "o"],
    "count": 1,
    "query": "SELECT * WHERE { ?s ?p ?o } LIMIT 1"
  }
}

2. Simplified Format

Returns a simplified JSON structure that's easier to work with, converting variable bindings into simple key-value objects.

{
  "type": "SELECT",
  "results": [
    {
      "s": "http://example.org/resource",
      "p": "http://example.org/property",
      "o": "Example Value"
    }
  ],
  "metadata": {
    "variables": ["s", "p", "o"],
    "count": 1,
    "query": "SELECT * WHERE { ?s ?p ?o } LIMIT 1"
  }
}

3. Tabular Format

Returns results in a tabular format with columns and rows, suitable for table display.

{
  "type": "SELECT",
  "columns": [
    { "name": "s", "label": "s" },
    { "name": "p", "label": "p" },
    { "name": "o", "label": "o" }
  ],
  "rows": [
    [
      "http://example.org/resource",
      "http://example.org/property",
      "Example Value"
    ]
  ],
  "metadata": {
    "variables": ["s", "p", "o"],
    "count": 1,
    "query": "SELECT * WHERE { ?s ?p ?o } LIMIT 1"
  }
}

🔄 Cache Strategies

The server supports three cache replacement strategies:

1. LRU (Least Recently Used)

Evicts the least recently accessed items first. This is the default strategy and works well for most scenarios, as it prioritizes keeping recently accessed items in the cache.

2. LFU (Least Frequently Used)

Evicts the least frequently accessed items first. This strategy is good for scenarios where some queries are much more common than others, as it prioritizes keeping frequently accessed items in the cache.

3. FIFO (First In First Out)

Evicts the oldest items first, regardless of access patterns. This strategy is simpler and can be useful when you want a purely time-based caching approach.

🔍 Advanced SPARQL Examples

The server supports all SPARQL features. Here are some example queries you can try:

Basic Triple Pattern

SELECT * WHERE { ?s ?p ?o } LIMIT 10

Filtering by Property Type

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?subject ?label
WHERE {
    ?subject rdf:type rdfs:Class ;
             rdfs:label ?label .
}
LIMIT 10

Using Regular Expressions

PREFIX foaf: <http://xmlns.com/foaf/0.1/>

SELECT ?person ?name
WHERE {
    ?person foaf:name ?name .
    FILTER(REGEX(?name, "Smith", "i"))
}
LIMIT 10

Complex Query with Multiple Patterns

PREFIX dbo: <http://dbpedia.org/ontology/>
PREFIX dbp: <http://dbpedia.org/property/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?city ?name ?population ?country ?countryName
WHERE {
    ?city a dbo:City ;
          rdfs:label ?name ;
          dbo:population ?population ;
          dbo:country ?country .
    ?country rdfs:label ?countryName .
    FILTER(?population > 1000000)
    FILTER(LANG(?name) = 'en')
    FILTER(LANG(?countryName) = 'en')
}
ORDER BY DESC(?population)
LIMIT 10

⚠️ Troubleshooting

Common Issues

• Connection refused: Check that the SPARQL endpoint URL is correct and accessible
• Query timeout: Increase the timeout value with --timeout option
• Memory issues with large result sets: Add LIMIT clause to your queries or reduce cache size
• Permission denied for log/pid files: Check directory permissions or run with appropriate privileges

Logging

When running in foreground mode, logs are output to the console. When running as a daemon, logs are written to the specified log file (default: /var/log/mcp-sparql-server.log).

To increase verbosity, you can set the Python logging level in the source code.

🛠️ Development

Project Structure

mcp-server-sparql/
├── sparql_server/             # Main package
│   ├── core/                  # Core functionality
│   │   ├── __init__.py        # Package exports
│   │   ├── config.py          # Configuration management
│   │   └── server.py          # Main SPARQL server
│   ├── formatters/            # Result formatters
│   │   ├── __init__.py        # Package exports
│   │   ├── formatter.py       # Base formatter class
│   │   ├── json_formatter.py  # JSON formatter
│   │   ├── simplified_formatter.py # Simplified JSON formatter
│   │   └── tabular_formatter.py # Tabular formatter
│   ├── cache/                 # Caching implementation
│   │   ├── __init__.py        # Package exports
│   │   ├── query_cache.py     # Base cache interface
│   │   ├── lru_cache.py       # LRU cache implementation
│   │   ├── lfu_cache.py       # LFU cache implementation
│   │   └── fifo_cache.py      # FIFO cache implementation
│   └── __init__.py            # Package exports
├── server.py                  # Main entry point
├── setup.py                   # Package setup
├── install.sh                 # Installation script
├── requirements.txt           # Python dependencies
├── sparql-server.service      # Systemd service file
├── README.md                  # This file
└── LICENSE                    # License file

Running Tests

python test_server.py

🔒 Security Considerations

• The server doesn't implement authentication or authorization - it relies on the security of the underlying SPARQL endpoint
• For production use, consider deploying behind a secure proxy
• Be careful with untrusted queries as they could potentially be resource-intensive

📄 License

This project is licensed under a dual-license model:

• Open Source: GNU Affero General Public License v3.0 (AGPL-3.0) for open source use
• Commercial: Proprietary commercial license available for commercial or proprietary use

See the LICENSE file for complete details.

This software was imagined and developed by Temkit Sid-Ali for Yet.lu.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📬 Contact

• GitHub Issues: https://github.com/yet-market/yet-sparql-mcp-server/issues
• Email: contact@yet.lu