# RDF4J MCP Server

**Explore knowledge graphs with Claude** - A Model Context Protocol (MCP) server that enables AI-powered exploration of RDF data and SPARQL querying.

## Quick Demo

Try it out in under 2 minutes:

```bash
# 1. Clone and install
git clone https://github.com/your-org/rdf4j-mcp.git
cd rdf4j-mcp
uv sync  # or: pip install -e .

# 2. Start RDF4J + load sample data
./examples/setup-demo.sh

# 3a. Run as local MCP server (stdio)
rdf4j-mcp --server-url http://localhost:8081/rdf4j-server --repository demo

# 3b. Or run as remote HTTP server
rdf4j-mcp-server --port 3000 --server-url http://localhost:8081/rdf4j-server --repository demo
```

Then try these prompts with Claude:

> "What classes and properties are in this knowledge graph?"

> "Find all people and the projects they work on"

> "Show me the project with the highest budget"

## Installation

**Prerequisites:** Python 3.11+, Docker (for RDF4J)

```bash
git clone https://github.com/your-org/rdf4j-mcp.git
cd rdf4j-mcp
uv sync  # or: pip install -e .
```

## Two Ways to Run

| Command | Transport | Use Case |
|---------|-----------|----------|
| `rdf4j-mcp` | stdio | MCP client spawns locally (Claude Desktop, VS Code) |
| `rdf4j-mcp-server` | HTTP/SSE | Standalone remote server, multiple clients |

### Option 1: Local Mode (stdio)

The MCP client spawns the server as a local process:

```bash
rdf4j-mcp --server-url http://localhost:8080/rdf4j-server --repository my-repo
```

### Option 2: Remote Mode (HTTP/SSE)

Run as a standalone HTTP server:

```bash
# Start the server
rdf4j-mcp-server --port 3000 \
  --server-url http://localhost:8080/rdf4j-server \
  --repository my-repo

# Or with environment variables
export RDF4J_MCP_RDF4J_SERVER_URL=http://localhost:8080/rdf4j-server
export RDF4J_MCP_DEFAULT_REPOSITORY=my-repo
rdf4j-mcp-server --port 3000

# Or with uvicorn (production)
uvicorn rdf4j_mcp.main:app --host 0.0.0.0 --port 3000 --workers 4
```

**Endpoints:**
- `GET /sse` - SSE endpoint for MCP clients
- `GET /health` - Health check
- `GET /info` - Server configuration

## Client Configuration

### Claude Desktop

Config file locations:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**Local mode (stdio):**
```json
{
  "mcpServers": {
    "rdf4j": {
      "command": "rdf4j-mcp",
      "args": ["--server-url", "http://localhost:8080/rdf4j-server", "--repository", "my-repo"]
    }
  }
}
```

**Remote mode (HTTP):**
```json
{
  "mcpServers": {
    "rdf4j": {
      "url": "http://your-server:3000/sse"
    }
  }
}
```

### VS Code

Create `.vscode/mcp.json` in your workspace:

**Local mode:**
```json
{
  "servers": {
    "rdf4j": {
      "command": "rdf4j-mcp",
      "args": ["--server-url", "http://localhost:8080/rdf4j-server", "--repository", "my-repo"]
    }
  }
}
```

**Remote mode:**
```json
{
  "servers": {
    "rdf4j": {
      "url": "http://your-server:3000/sse"
    }
  }
}
```

For GitHub Copilot, use `@mcp` in chat:
```
@mcp What classes are in the knowledge graph?
```

## Features

### MCP Tools

| Tool | Description |
|------|-------------|
| `sparql_select` | Execute SELECT queries, returns JSON |
| `sparql_construct` | Execute CONSTRUCT/DESCRIBE, returns Turtle |
| `sparql_ask` | Execute ASK queries, returns boolean |
| `describe_resource` | Get all triples about an IRI |
| `search_classes` | Find classes by name pattern |
| `search_properties` | Find properties by pattern/domain/range |
| `find_instances` | Find instances of a class |
| `get_schema_summary` | Ontology overview with statistics |
| `list_repositories` | List available repositories |
| `get_namespaces` | Get namespace prefix mappings |
| `get_statistics` | Statement/class/property counts |
| `select_repository` | Switch active repository |

### MCP Resources

| URI | Description |
|-----|-------------|
| `rdf4j://repositories` | List of repositories |
| `rdf4j://repository/{id}/schema` | Schema summary |
| `rdf4j://repository/{id}/namespaces` | Namespace prefixes |
| `rdf4j://repository/{id}/statistics` | Repository statistics |

### MCP Prompts

| Prompt | Description |
|--------|-------------|
| `explore_knowledge_graph` | Guided exploration with schema context |
| `write_sparql_query` | Natural language to SPARQL |
| `explain_ontology` | Explain classes and relationships |

## Configuration

### CLI Options

**rdf4j-mcp (stdio mode):**
```
--server-url URL    RDF4J server URL (default: http://localhost:8080/rdf4j-server)
--repository ID     Default repository ID
--debug             Enable debug logging
```

**rdf4j-mcp-server (HTTP mode):**
```
--host HOST         Bind address (default: 0.0.0.0)
--port PORT         Listen port (default: 3000)
--server-url URL    RDF4J server URL
--repository ID     Default repository ID
--reload            Auto-reload for development
--debug             Enable debug logging
```

### Environment Variables

All use the `RDF4J_MCP_` prefix:

| Variable | Default | Description |
|----------|---------|-------------|
| `RDF4J_SERVER_URL` | `http://localhost:8080/rdf4j-server` | RDF4J server URL |
| `DEFAULT_REPOSITORY` | - | Default repository ID |
| `QUERY_TIMEOUT` | `30` | Query timeout (seconds) |
| `DEFAULT_LIMIT` | `100` | Default query LIMIT |
| `MAX_LIMIT` | `10000` | Maximum query LIMIT |

## Running RDF4J Server

Using Docker:
```bash
docker run -d -p 8080:8080 eclipse/rdf4j-workbench
```

Then create a repository at http://localhost:8080/rdf4j-workbench.

Or use the demo setup script which handles everything:
```bash
./examples/setup-demo.sh
```

## Development

```bash
uv sync --dev

# Run tests
pytest

# Lint and format
ruff check src tests
ruff format src tests

# Type check
ty check src
```

## License

MIT