# 🔭 SPARQL MCP server

[![Build](https://github.com/sib-swiss/sparql-mcp/actions/workflows/build.yml/badge.svg)](https://github.com/sib-swiss/sparql-mcp/actions/workflows/build.yml)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server to help users write SPARQL queries for open-access SPARQL endpoints, developed for the [SIB Expasy portal](https://expasy.org).

The server will automatically index metadata present in the list of SPARQL endpoints defined in a JSON config file, such as:

- [SPARQL query examples](https://github.com/sib-swiss/sparql-examples),
- Endpoints schema using the [Vocabulary of Interlinked Datasets (VoID)](https://www.w3.org/TR/void/), which can be automatically generated using the [void-generator](https://github.com/JervenBolleman/void-generator).

## 🧩 Endpoints

The HTTP API comprises 2 main endpoints:

- `/mcp`: **MCP server** that searches for relevant data to answer a user question using the EOSC Data Commons search API
  - Uses [`rmcp`](https://github.com/modelcontextprotocol/rust-sdk) with Streamable HTTP transport
  - 🧰 Available tools:
    - [x] `access_sparql_resources`: retrieve relevant information about the resources to help build a SPARQL query to answer the question (query examples, classes schema)
    - [x] `get_resources_info`: retrieve relevant information about the SPARQL endpoints resources themselves (e.g. description, list of available endpoints)
    - [x] `execute_sparql`: execute a SPARQL query against a given endpoint

- `/chat`: optional **HTTP POST** endpoint (JSON) to query the MCP server via an LLM provider
  - Uses [`axum`](https://github.com/tokio-rs/axum), [`utoipa`](https://github.com/juhaku/utoipa) for OpenAPI spec generation, [`llm`](https://github.com/graniet/llm) to interact with LLM providers (e.g. [Mistral](https://admin.mistral.ai/organization/api-keys), OpenAI)
  - Supports streaming response: tool call requested, then tool call results, and final search results.

## 🚀 Use

Use it through the `sparql-mcp` package on pip:

```sh
uvx sparql-mcp ./sparql-mcp.json
```

Or download the binary corresponding to your architecture from the releases page.

## 🛠️ Development

> [!IMPORTANT]
>
> Requirements:
>
> - [Rust](https://www.rust-lang.org/tools/install)
> - Protobuf installed (e.g. `brew install protobuf`)
> - API key for a LLM provider: [Mistral.ai](https://console.mistral.ai/api-keys) or OpenAI, you can use the free tier, you just need to login
>
> Recommend VSCode extension: [`rust-analyzer`](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)

### 📥 Install dev dependencies

```sh
rustup update
cargo install cargo-release cargo-deny cargo-watch git-cliff
```

Create a `.cargo/config.toml` file with your [Mistral API key](https://admin.mistral.ai/organization/api-keys) or OpenAI API key:

```toml
[env]
MISTRAL_API_KEY = "YOUR_API_KEY"
OPENAI_API_KEY = "YOUR_API_KEY"
GROQ_API_KEY = "YOUR_API_KEY"
```

### ⚡️ Start dev server

Start the **MCP server** in dev at http://localhost:8000/mcp, with OpenAPI UI at http://localhost:8000/docs

```sh
cargo run
```

Customize server configuration through CLI arguments:

```sh
cargo run -- --force-index --mcp-only --db-path ./data/lancedb
```

Provide a custom list of servers through a `.json` file with:

```sh
cargo run -- ./sparql-mcp.json
```

Example `sparql-mcp.json`:

```json
{
  "endpoints": [
    {
      "label": "UniProt",
      "endpoint_url": "https://sparql.uniprot.org/sparql/",
      "description": "UniProt is a comprehensive resource for protein sequence and annotation data."
    },
    {
      "label": "Bgee",
      "endpoint_url": "https://www.bgee.org/sparql/",
      "description": "Bgee is a database for retrieval and comparison of gene expression patterns across multiple animal species.",
      "homepage_url": "https://www.bgee.org/"
    }
  ]
}
```

> [!TIP]
>
> Run and reload on change to the code:
>
> ```sh
> cargo watch -x run
> ```
>

> [!NOTE]
>
> Example `curl` request:
>
> ```sh
> curl -X POST http://localhost:8000/search -H "Content-Type: application/json" -H "Authorization: SECRET_KEY" -d '{"messages": [{"role": "user", "content": "What is the HGNC symbol for the P68871 protein?"}], "model": "mistral/mistral-small-latest", "stream": true}'
> ```
>
> Recommended model per supported provider:
>
> - `openai/gpt-4.1`
> - `mistralai/mistral-large-latest`
> - `groq/moonshotai/kimi-k2-instruct`

### 🔌 Connect MCP client

Follow the instructions of your client, and use the `/mcp` URL of your deployed server (e.g. http://localhost:8000/mcp)

#### 🐙 VSCode GitHub Copilot

Add a new MCP server through the VSCode UI:

- Open the Command Palette (`ctrl+shift+p` or `cmd+shift+p`)
- Search for `MCP: Add Server...`
- Choose `HTTP`, and provide the MCP server URL http://localhost:8000/mcp

Your VSCode `mcp.json` should look like:

```json
{
    "servers": {
        "sparql-mcp-server": {
            "url": "http://localhost:8000/mcp",
            "type": "http"
        }
    },
    "inputs": []
}
```

### 📦 Build for production

Build binary in `target/release/`

```sh
cargo build --release
```

> [!NOTE]
>
> Start the server with (change flags at your convenience):
>
> ```sh
> ./target/release/sparql-mcp ./sparql-mcp.json --force-index
> ```
>
> Start using the python wheel:
>
> ```sh
> uvx --from ./target/release/sparql_mcp-0.1.0-py3-none-any.whl . sparql-mcp
> ```

## 🐍 Build python package

> Require [`uv`](https://docs.astral.sh/uv/getting-started/installation/) installed

Bundle the CLI as python package in `target/wheels`:

```sh
uvx maturin build
```

### 🐳 Deploy with Docker

Create a `keys.env` file with the API keys:

```sh
MISTRAL_API_KEY=YOUR_API_KEY
SEARCH_API_KEY=SECRET_KEY_YOU_CAN_USE_IN_FRONTEND_TO_AVOID_SPAM
```

> [!TIP]
>
> `SEARCH_API_KEY` can be used to add a layer of protection against bots that might spam the LLM, if not provided no API key will be needed to query the API.

Build and deploy the service:

```sh
docker compose up
```

### 🧼 Format & lint

Automatically format the codebase using `rustfmt`:

```sh
cargo fmt
```

Lint with `clippy`:

```sh
cargo clippy --all
```

Automatically apply possible fixes:

```sh
cargo fix
```

### ⛓️ Check supply chain

Check the dependency supply chain: licenses (only accept dependencies with OSI or FSF approved licenses), and vulnerabilities (CVE advisories).

```sh
cargo deny check
```

Update dependencies in `Cargo.lock`:

```sh
cargo update
```

### 🏷️ Release

Dry run:

```sh
cargo release patch
```

> Or `minor` / `major`

Create release:

```sh
cargo release patch --execute
```