Skip to main content
Glama

Local MCP Semantic Agent with OWL, HermiT & Ollama

A fully local execution architecture on macOS for deterministic inspection, mutation, Description Logic (DL) reasoning, and SPARQL querying of banking ontologies (OWL/RDF) using LLM agents and the Model Context Protocol (MCP) over STDIO.

Core Capabilities

  • HermiT DL Reasoning: Integrated Description Logic reasoner (sync_reasoner_hermit) to verify ontology consistency, compute inferred class hierarchies, and detect unsatisfiable classes.

  • SPARQL Query Engine: Direct W3C SPARQL query execution over the RDF knowledge graph via RDFLib, allowing complex semantic queries, filtering, and aggregations.

  • Taxonomy & Instance Mutation (TBox/ABox): Dynamic insertion of OWL classes, subclass hierarchies, and named individual assertions.

  • Interactive Force-Directed Visualizations: Automatic export of the knowledge graph into interactive PyVis HTML networks.

  • Dual Execution Modes: Automated batch pipeline (agente.py) and persistent conversational REPL (agent_interactive.py).

Related MCP server: OWL-MCP

Architecture

The system decouples model reasoning from graph execution across four core layers:

  1. Agent Orchestrator:

    • agente.py: Automated pipeline executing batch agent goals end-to-end.

    • agent_interactive.py: Multi-turn conversational REPL maintaining state and executing dynamic multi-step semantic workflows.

  2. LLM Engine (Ollama): Executes local models (e.g., glm-5.2:cloud, qwen2.5-coder) to perform intent decomposition and parameter formatting without direct file access.

  3. MCP Server (server.py): JSON-RPC 2.0 interface communicating over STDIO, translating model tool calls into deterministic semantic graph operations via Owlready2 and RDFLib.

  4. Semantic Layer (core.owl): Persistent W3C RDF/XML ontology graph verified with the HermiT DL reasoner.


🛡️ The 5 Neuro-Symbolic Layers

Layer

Standard / Engine

Responsibility

Rejection Mode / Behavior

1. Validation

W3C SHACL Core (pyshacl)

Enforces schema constraints, datatypes (xsd:decimal), term boundaries ($6 \le \text{term} \le 120$), and currency enums (EUR, USD, GBP).

Pre-execution rejection (SHACLShapeViolation).

2. Reasoning

OWL 2 DL HermiT (CommandLine -c)

Mathematical DL consistency check. Intercepts contradictions, disjointness clashes, and unsatisfiable concepts.

Transaction rollback (LogicalInconsistency).

3. Calculation

SHACL-AF (sh:SPARQLRule)

Runs deterministic construct rules to materialize derived facts in-memory (e.g., auto-classifying high-risk exposure).

In-place triple materialization (inplace=True).

4. Terminology

W3C SKOS (skos:Concept)

Standardizes banking taxonomy concepts and enforces required multilingual labels (@es, @en).

Terminology rejection (SKOSTerminologyError).

5. Provenance

W3C PROV-O (prov:Agent)

Automatically binds entity lineage, agent identity, and ISO UTC timestamps to committed individuals.

Auto-injected prior to disk persistence.


📂 Repository Structure

  • core.owl: Persistent banking knowledge graph serialized in W3C OWL 2 RDF/XML.

  • shapes.ttl: W3C SHACL validation shapes and SHACL-AF SPARQL construct rules.

  • server.py: Native JSON-RPC 2.0 MCP server over STDIO implementing the transactional staging engine and 5-layer guardrail pipeline.

  • test_suite.py: End-to-end regression test suite validating static schema conformity and the live 5-layer MCP server integration.

  • agente.py: Batch agent executing end-to-end ontology goals via Ollama.

  • agent_interactive.py: Interactive conversational REPL for real-time ontology inspection and mutation with autonomous error recovery.

  • requirements.txt: Project dependencies (owlready2, rdflib, pyshacl, pyvis).

  • graph.html: Exported interactive force-directed network diagram (generated on demand).


Prerequisites

  • OS: macOS (Apple Silicon or Intel)

  • Python: 3.10 or higher

  • Ollama: Installed and running locally

  • Java: OpenJDK / JRE (required by Owlready2 for the HermiT reasoner)

Installation & Environment Setup

  1. Clone the repository and navigate to the project directory:

git clone [https://github.com/jairorodriguezarias/mcp-ontology-layer.git](https://github.com/jairorodriguezarias/mcp-ontology-layer.git)
cd mcp-ontology-layer
  1. Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate
  1. Install required dependencies:

pip install -r requirements.txt

4 . Download the model in Ollama:

ollama pull glm-5.2:cloud
  1. Run the agent demo:

python3 agente.py

6 .

python3 agent_interactive.py
  1. Visualizing the Knowledge Graph

open graph.html
  1. Create specific example

python3 interative_agent.py

You > Create a 'PersonalLoan' under 'Loan', instantiate 'Loan_Auto_2026_01', set principal to 24500.00 EUR at 5.75% for 60 months, and verify via SPARQL. 

You > Attach properties to Loan_Auto_2026_01: principal 24500.00 EUR, rate 5.75%, term 60 months. Then list all personal loans with 60 months.

  ⚙️ [MCP Tool Call] list_classes({})
  📥 [MCP Output] Ontology classes: ['FinancialProduct', 'Loan', 'PrestamoHipotecario', 'PersonalLoan']

  ⚙️ [MCP Tool Call] execute_sparql({
      "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o . FILTER(CONTAINS(STR(?s), 'Loan_Auto_2026_01')) } LIMIT 50"
    })
  📥 [MCP Output] [
    ["[http://banco.es/ontologies/core#Loan_Auto_2026_01](http://banco.es/ontologies/core#Loan_Auto_2026_01)", "[http://www.w3.org/1999/02/22-rdf-syntax-ns#type](http://www.w3.org/1999/02/22-rdf-syntax-ns#type)", "[http://www.w3.org/2002/07/owl#NamedIndividual](http://www.w3.org/2002/07/owl#NamedIndividual)"],
    ["[http://banco.es/ontologies/core#Loan_Auto_2026_01](http://banco.es/ontologies/core#Loan_Auto_2026_01)", "[http://www.w3.org/1999/02/22-rdf-syntax-ns#type](http://www.w3.org/1999/02/22-rdf-syntax-ns#type)", "[http://banco.es/ontologies/core#PersonalLoan](http://banco.es/ontologies/core#PersonalLoan)"]
  ]

  ⚙️ [MCP Tool Call] execute_sparql({
      "query": "PREFIX core: [http://banco.es/ontologies/core#](http://banco.es/ontologies/core#)\nPREFIX xsd:  [http://www.w3.org/2001/XMLSchema#](http://www.w3.org/2001/XMLSchema#)\n\nINSERT DATA {\n  core:Loan_Auto_2026_01 core:principal  \"24500.00\"^^xsd:decimal ;\n                         core:currency   \"EUR\" ;\n                         core:rate       \"5.75\"^^xsd:decimal ;\n                         core:term       \"60\"^^xsd:integer .\n}"
    })
  📥 [MCP Output] SPARQL Update executed successfully and changes persisted to core.owl.

  ⚙️ [MCP Tool Call] execute_sparql({
      "query": "PREFIX core: [http://banco.es/ontologies/core#](http://banco.es/ontologies/core#)\n\nSELECT ?loan ?principal ?currency ?rate ?term WHERE {\n  ?loan a core:PersonalLoan ;\n        core:term ?term ;\n        core:principal ?principal ;\n        core:currency ?currency ;\n        core:rate ?rate .\n  FILTER(?term = 60)\n}"
    })
  📥 [MCP Output] [
    ["[http://banco.es/ontologies/core#Loan_Auto_2026_01](http://banco.es/ontologies/core#Loan_Auto_2026_01)", "24500.00", "EUR", "5.75", "60"]
  ]

Agent > Summary of operations:
- Attached properties to 'Loan_Auto_2026_01' (Principal: 24,500.00 EUR, Rate: 5.75%, Term: 60 months).
- Verified graph persistence in core.owl.
- Filtered personal loans matching a 60-month term: 1 result found (Loan_Auto_2026_01).

you >  Export the current graph visualization.


9. Layer 1 (SHACL Violation)

you > Create a PersonalLoan named 'Loan_BadTerm_01' with principal 15000.00 EUR at 6.00% for 240 months.

you > Run a SPARQL query to retrieve all properties, types, and PROV-O attribution metadata for 'Loan_Auto_2026_99'.

10. Layer 2 (HermiT Violation)

you > First, add a new class 'DepositAccount' under 'FinancialProduct'. Next, assert via SPARQL that 'DepositAccount' is disjoint with 'PersonalLoan'. Finally, instantiate a single individual named 'Hybrid_Product_01' that is typed as BOTH a 'PersonalLoan' and a 'DepositAccount' with principal 5000.00 EUR, rate 3.50%, and term 24 months.


11. Layer 3 (Derived Rule & Cascading Constraint Clash (SHACL-AF))
 you > Create a PersonalLoan named 'Loan_RiskCapped_01' with principal 50000.00 EUR, an interest rate of 16.50%, and a term of 84 months.

12. Layer 4 (SKOS Taxonomy & Missing Multilingual Metadata)
you > Create a new loan category concept called 'PeerToPeerLending' with no labels, then instantiate a PersonalLoan named 'Loan_P2P_02' linked to this category with principal 10000.00 EUR, rate 4.50%, and term 24 months.

13. Layer 5 (PROV-O Audit Lineage Spoofing & Tampering=)
you > Insert a PersonalLoan named 'Loan_SpoofedAudit_03' with principal 15000.00 EUR, rate 5.00%, term 36 months, and manually set prov:wasAttributedTo to 'Executive_Admin_Bypass' with prov:generatedAtTime '2020-01-01T00:00:00Z'.

## KG

# 1. Export graph
python3 visualize_graph.py

# 2. View in browser
open graph.html


Available MCP Tools
* **list_classes**
* **Parameters:** None
* **Description:** Loads `core.owl` and returns all registered ontology classes.


* **add_subclass**
* **Parameters:** `new_class` (string, required), `parent_class` (string, required)
* **Description:** Inserts a new class under an existing parent class and saves the updated RDF/XML graph to disk.


* **create_individual**
* **Parameters:** `class_name` (string, required), `individual_id` (string, required)
* **Description:** Instantiates a concrete ABox individual belonging to a specific class.


* **check_consistency**
* **Parameters:** None
* **Description:** Runs the HermiT Description Logic (DL) reasoner to verify logical consistency and detect unsatisfiable classes.


* **execute_sparql**
* **Parameters:** `query` (string, required)
* **Description:** Executes a standard W3C SPARQL query against the RDF knowledge graph.


* **export_graph**
* **Parameters:** `output_html` (string, optional; default: `graph.html`)
* **Description:** Generates an interactive force-directed HTML graph visualization of the ontology using PyVis.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that connects GraphDB's SPARQL endpoints and Ollama models to Claude, enabling Claude to query and manipulate ontology data while leveraging various AI models.
      28
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for building and exploring OWL 2 ontologies using AI agents, with tools for axiom management, structural pattern matching, and persistent selections.
      25
      BSD 3-Clause