# mcp-server-sparql

A generic [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects AI agents to any SPARQL 1.1 endpoint.

Works with **Apache Jena Fuseki · GraphDB · Stardog · Virtuoso · Amazon Neptune · Blazegraph** — or any endpoint that speaks SPARQL 1.1.

## Tools

| Tool | Description |
|------|-------------|
| `sparql_select` | Execute a SELECT query → tabular rows; paginate with `limit`/`offset`/`has_more` |
| `sparql_ask` | Execute an ASK query → boolean; fast existence/reachability checks |
| `sparql_construct` | Execute a CONSTRUCT query → RDF graph string |
| `sparql_describe` | DESCRIBE a resource URI → all triples about it |
| `sparql_update` | Any SPARQL 1.1 Update: INSERT DATA, DELETE, CLEAR, DROP, LOAD, COPY, MOVE, ADD |
| `graph_list` | List all named graphs with triple counts |
| `graph_get` | Fetch a named graph as Turtle; paginated |
| `graph_put` | Replace a named graph (inline content or remote URL via server-side LOAD) |
| `graph_post` | Append to a named graph |
| `graph_delete` | Delete a named graph |
| `validate_shacl` | Validate RDF against SHACL shapes — pure function, no endpoint needed |
| `endpoint_ping` | Check connectivity; returns response time and configured URLs |

Connection is configured **once at the server level** via environment variables. Tools take no connection parameters — the same pattern used by `mcp-server-postgres` and `mcp-server-sqlite`.

## Quickstart

```bash
git clone https://github.com/Kashif-Rabbani/mcp-server-sparql.git
cd mcp-server-sparql
pip install -e .

cp .env.example .env
# edit .env — set SPARQL_ENDPOINT (or the three explicit URL vars)

python server.py
```

Server starts on `http://0.0.0.0:8000`. The SSE endpoint is at `/sse`.

## Configuration

Copy `.env.example` to `.env` and set one of:

**Option A — single base URL** (Fuseki / Stardog):
```env
SPARQL_ENDPOINT=http://localhost:3030/myDataset
```
This auto-derives `/query`, `/update`, and `/data` suffixes.

**Option B — explicit URLs** (GraphDB, Virtuoso, Neptune, etc.):
```env
SPARQL_QUERY_URL=http://localhost:7200/repositories/myrepo
SPARQL_UPDATE_URL=http://localhost:7200/repositories/myrepo/statements
SPARQL_GRAPH_STORE_URL=http://localhost:7200/repositories/myrepo/rdf-graphs/service
```

**Auth (optional):**
```env
SPARQL_USERNAME=admin
SPARQL_PASSWORD=secret
```

## Endpoint-specific notes

| Endpoint | Option | Query URL pattern |
|----------|--------|-------------------|
| Apache Jena Fuseki | A | `http://host:3030/<dataset>` |
| Stardog | A | `http://host:5820/<database>` |
| GraphDB | B | `http://host:7200/repositories/<repo>` |
| Amazon Neptune | B | `https://<cluster>.neptune.amazonaws.com:8182/sparql` |
| Virtuoso | B | `http://host:8890/sparql` |
| Blazegraph | B | `http://host:9999/blazegraph/namespace/<ns>/sparql` |

## Connect to an MCP client

### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "sparql": {
      "command": "uvicorn",
      "args": ["server:app", "--host", "0.0.0.0", "--port", "8000"],
      "cwd": "/path/to/mcp-server-sparql",
      "env": {
        "SPARQL_ENDPOINT": "http://localhost:3030/myDataset"
      }
    }
  }
}
```

### Vectara Agent Platform
Register the server as an MCP Tool Server pointing at the public SSE URL (use [ngrok](https://ngrok.com) for local development):
```bash
ngrok http 8000
# then register https://<id>.ngrok-free.app/sse as an MCP tool server in Vectara
```

## Requirements

- Python 3.11+
- A running SPARQL 1.1 endpoint

## License

MIT