# OWL MCP

[![npm version](https://img.shields.io/npm/v/owl-mcp.svg)](https://www.npmjs.com/package/owl-mcp)
[![CI](https://github.com/Minitour/owl-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Minitour/owl-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Rust](https://img.shields.io/badge/rust-1.88%2B-orange.svg)](https://www.rust-lang.org/)
[![Node](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org/)

A high-performance [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server **and CLI** for OWL ontology management, written in Rust.

Built as a drop-in replacement for [ai4curation/owl-mcp](https://github.com/ai4curation/owl-mcp), designed to eliminate the crashes and timeouts inherent to the Python implementation. Axioms are expressed in [OWL Functional Syntax](https://www.w3.org/TR/owl2-syntax/).

## Features

- **18 MCP tools** — add, remove, search, and inspect axioms; add structured assertions (data/annotation/object property, class) with the literal value as a separate field; manage prefixes, labels, and ontology IRIs; scan for modeling pitfalls; evaluate ontology quality; check logical consistency with an OWL 2 EL reasoner; run SPARQL queries; verbalize OWL into Controlled Natural Language
- **CLI mode** — every tool is also available as a direct CLI subcommand (`owl-mcp find-axioms ...`)
- **2 transport modes** — `stdio` (default, for Cursor/Claude Desktop) and `http` (Streamable HTTP, MCP 2026-07-28, sessionless)
- **Disk as source of truth** — each tool call takes `owl_file_path`; the in-memory cache reloads when the file's mtime changes. `resource://active` lists files currently cached in this process (not durable state)
- **Live file watching** — a 5s watcher is a local optimization; mtime-on-access is what keeps the cache correct
- **OFN and RDF/XML support** — reads and writes both formats; format is auto-detected from file extension and content
- **Never crashes** — errors are returned as MCP tool failures, not panics

## Installation

### via npx (recommended)

```bash
npx owl-mcp serve
```

### via npm (global install)

```bash
npm install -g owl-mcp
owl-mcp --help
```

### Build from source

Requires [Rust](https://rustup.rs) 1.88+.

```bash
git clone https://github.com/Minitour/owl-mcp
cd owl-mcp
cargo build --release
./target/release/owl-mcp --help
```

## Usage

owl-mcp has two modes: **serve** (MCP server) and **CLI** (direct commands).

### MCP server mode

```bash
owl-mcp serve [OPTIONS]

Options:
  --transport <stdio|http>   Transport to use [default: stdio]
  --host <HOST>              Host to bind (HTTP only) [default: 127.0.0.1]
  --port <PORT>              Port to bind (HTTP only) [default: 8080]
```

### CLI mode

Every MCP tool is available as a subcommand:

```bash
owl-mcp add-axiom --file ontology.owl --axiom "SubClassOf(:Dog :Animal)"
owl-mcp add-data-property-assertion --file ontology.owl --property :metaprops --subject :Plan1 --value-file ./long-value.txt
owl-mcp add-axioms --file ontology.owl --axioms-file ./axioms.json
owl-mcp find-axioms --file ontology.owl --pattern "Dog" --limit 50
owl-mcp get-all-axioms --file ontology.owl --include-labels
owl-mcp test-pitfalls --file ontology.owl
owl-mcp test-quality --file ontology.owl
owl-mcp sparql --file ontology.owl --query "SELECT ?c WHERE { ?c a owl:Class }"
owl-mcp sparql --file schema.owl --file data.owl --query "ASK { ?i a :Plan }"
owl-mcp reason --file ontology.owl
owl-mcp reason --file schema.owl --file data.owl --output reasoned.ofn
owl-mcp verbalize --file ontology.owl
owl-mcp verbalize --file ontology.owl --iri http://example.org/pizza#Margherita --limit 10
```

Run `owl-mcp --help` for a full list of commands, or `owl-mcp <command> --help` for details on a specific command.

## Cursor / Claude Desktop integration

Add the server to your MCP client configuration.

**Cursor** (`~/.cursor/mcp.json` or `.cursor/mcp.json` in your project):

```json
{
  "mcpServers": {
    "owl-mcp": {
      "command": "npx",
      "args": ["-y", "owl-mcp", "serve"]
    }
  }
}
```

**HTTP transport** (useful for remote/shared setups):

```json
{
  "mcpServers": {
    "owl-mcp": {
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

Start the server with:

```bash
owl-mcp serve --transport http --port 8080
```

## Tools

All tools operate on OWL files by absolute path. The manager lazily loads files on first access and caches them in this process. Each access reloads from disk if the file's modification time has changed, so the cache is not protocol or session state.

### Axiom operations

| Tool | Description |
|---|---|
| `add_axiom` | Add a single axiom in OWL Functional Syntax |
| `add_axioms` | Add multiple axioms in one call |
| `add_data_property_assertion` | Assert a data property value (value passed as a separate field — no escaping) |
| `add_annotation_assertion` | Assert an annotation value (value passed as a separate field — no escaping) |
| `add_object_property_assertion` | Link two individuals via an object property |
| `add_class_assertion` | Assert that an individual is an instance of a class |
| `remove_axiom` | Remove an axiom |
| `find_axioms` | Search axioms with a regex pattern |
| `get_all_axioms` | List all axioms (up to a limit) |

For long or special-character literal values (containing `;`, `=`, `/`, `,`, quotes, or newlines), prefer the structured assertion tools over hand-writing a quoted `add_axiom` string: they take the `value` as a separate field and build the axiom server-side, so no escaping is needed. In CLI mode, `add-axioms` also accepts `--axioms-file <path>` (a JSON array of strings, or NUL/newline-delimited; `-` for stdin), and the structured commands accept `--value-file <path>`, both of which bypass shell quoting entirely. `add_axiom`/`add_axioms` now return a hard error (instead of a silent warning) when an input parses to no axiom.

### Metadata and labels

| Tool | Description |
|---|---|
| `add_prefix` | Add a prefix mapping (`ex:` → `http://example.org/`) |
| `ontology_metadata` | Return ontology-level annotation axioms |
| `get_labels_for_iri` | Look up `rdfs:label` (or custom property) values for an IRI |
| `set_ontology_iri` | Set or update the ontology IRI and version IRI |

### Quality checks

| Tool | Description |
|---|---|
| `test_pitfalls` | Scan for 31 common modeling pitfalls (inspired by OOPS!) |
| `test_quality` | Evaluate ontology quality using the OQuaRE framework (ISO/IEC 25000 SQuaRE) |

`find_axioms` and `get_all_axioms` accept `include_labels: true` to annotate each axiom with human-readable labels appended as `## <IRI> # label` comments.

`test_quality` uses the [whelk](https://github.com/INCATools/whelk-rs) OWL EL reasoner to compute inferred class hierarchy and returns a JSON report containing 19 raw and scaled metrics (ANOnto, AROnto, CBOOnto, CROnto, DITOnto, INROnto, LCOMOnto, NACOnto, NOCOnto, NOMOnto, RFCOnto, RROnto, TMOnto, WMCOnto, and variants), 22 subcharacteristics, 7 quality characteristics (Structural, Functional Adequacy, Maintainability, Operability, Reliability, Transferability, Compatibility), and an overall OQuaRE score on a 1–5 scale.

### Querying and reasoning

| Tool | Description |
|---|---|
| `sparql_query` | Run a SPARQL query over one or more OWL files |
| `check_consistency` | Run an OWL 2 EL reasoner and report consistency / unsatisfiable classes |

`sparql_query` takes `owl_file_paths` (one or more absolute paths) and a `query` string. Each file is serialized to RDF and loaded together into an in-memory [oxigraph](https://github.com/oxigraph/oxigraph) store, so passing several paths merges a schema with its ABox or imports before the query runs. `SELECT` and `ASK` return the standard [SPARQL 1.1 JSON results](https://www.w3.org/TR/sparql11-results-json/) format; `CONSTRUCT` and `DESCRIBE` return a list of N-Triples. By default queries run over asserted triples only. Set `with_reasoning: true` to materialize OWL 2 EL entailments (via [whelk](https://github.com/INCATools/whelk-rs)) before querying so inferred subclass relationships are visible.

`check_consistency` (CLI: `owl-mcp reason`) takes `owl_file_paths` (merged like `sparql_query`), an optional `reasoner` (`whelk` default; `elk` is accepted as a synonym), and an optional `output_path` to write a materialized ontology (asserted + inferred `SubClassOf` axioms). It returns JSON with `consistent`, `unsatisfiable_classes`, optional `inferred_axioms_count`, and `reasoner`. **Profile limitation:** whelk/ELK reason within **OWL 2 EL** only — full OWL 2 DL inconsistency (cardinality restrictions, complex disjointness outside EL, etc.) is **not** detected. This is a faithful replacement for `robot reason --reasoner ELK`, not a DL-complete reasoner.

### Verbalization

| Tool | Description |
|---|---|
| `verbalize` | Convert OWL axioms into Controlled Natural Language (pseudo-text) plus a Turtle fragment |

`verbalize` (CLI: `owl-mcp verbalize --file ontology.owl [--iri ...] [--limit N]`) takes `owl_file_path`, an optional `iri` (CURIE or full IRI), and an optional `limit` (default 100). If `iri` is omitted, it verbalizes `owl:Class` and `owl:NamedIndividual` entities, skipping `owl:deprecated`. The result is a JSON array of `{root, fragment, text, statements, unique_concepts, unique_relationships}`. CNL uses the same default ignore/rephrase maps as [ontology-verbalizer](https://github.com/Minitour/ontology-verbalizer) (`rdfs:subClassOf` → "is a type of", `owl:disjointWith` → "is different from", `owl:unionOf` → "any of", etc.). There is no LLM paraphrasing.

The MCP HTTP transport is Streamable HTTP at `/mcp` (protocol `2026-07-28`, no `Mcp-Session-Id`). stdio remains compatible with the 2025-11-25 handshake used by Cursor and Claude Desktop.

## Development

```bash
# Run tests
cargo test

# Check formatting and lints
cargo fmt --check
cargo clippy --all-targets -- -D warnings

# Build release binary
cargo build --release
```

## License

MIT