# Universal Ontology MCP

**The Intelligent Bridge between Unstructured Data and High-Fidelity Knowledge Graphs.**

Universal Ontology MCP is a powerful tool designed for AI assistants to explore, navigate, and populate complex ontologies. It transforms raw text into structured relationships while adhering to strict semantic standards.

## 🚀 Why Universal Ontology MCP?

Existing ontology tools often struggle with semantic ambiguity and rigid keyword matching. This MCP solves these problems by providing:

- **🧠 Semantic Hybrid Search**: Don't get stuck on exact names. Find "Cloud Service" when you search for "Online Account" using state-of-the-art `all-MiniLM-L6-v2` embeddings.
- **⚡ Proactive Schema Guidance**: The server doesn't just list properties; it *teaches* the AI how to use them. It identifies mandatory fields and expected entity types for ObjectProperties in real-time.
- **🏗 Component-Based Modeling**: Simplifies complex modeling (like UCO Facets) by ranking and recommending relevant components for any given class.
- **⚖️ Built-in SHACL Validation**: Ensures data integrity from the start. It validates entities against schema constraints before you export your graph.
- **🔗 Connectivity-First Philosophy**: Encourages building deeply linked graphs rather than flat attribute lists, resulting in more useful "Reasoning-Ready" data.

## 🌟 Intelligent Tools

- `get_ontology_summary`: Quick high-level overview of the loaded schema.
- `search_classes` / `search_properties`: Semantic-aware discovery.
- `get_class_details`: Detailed usage instructions & connectivity rules.
- `list_available_facets`: Smart ranking of components for complex data grouping.
- `create_entity` / `set_property` / `attach_component`: Atomic graph construction.
- `validate_entity`: Instant SHACL compliance check.
- `export_graph`: Save your validated knowledge graph to `.ttl`.

---

## 🏗 Architecture

- `main.py`: Entry point for the MCP server.
- `mcp_server/engine.py`: Core logic for ontology parsing, caching, and vector embedding calculations.
- `mcp_server/server.py`: Tool definitions and FastMCP server configuration.
- `mcp_server/config.py`: Persona instructions and environment defaults.

## 🛠 Installation

1. Clone the repository.
2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
3. Set your ontology directory (path containing your `.ttl` files):
   ```bash
   export ONTOLOGY_DIR="/path/to/your/ontology/folder"
   ```

## 🔌 MCP Configuration

Add this configuration to your MCP-compatible client (e.g., Gemini, Claude Desktop, VS Code).

### Configuration Template
```json
{
  "mcpServers": {
    "universal-ontology-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/universal-ontology-mcp/main.py"],
      "env": {
        "ONTOLOGY_DIR": "/absolute/path/to/your/ontology/folder"
      }
    }
  }
}
```

## ⚖️ License
This project is licensed under the [MIT License](LICENSE).