Universal Ontology MCP

# Universal Ontology MCP v0.1

**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:

- **🧠 Balanced Semantic Search**: Don't get stuck on exact names. We use state-of-the-art embeddings (default: `all-MiniLM-L6-v2`) with a **50/50 weighted scoring** between Class Names and Descriptions for maximum intuitive accuracy.
- **⚡ 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.
- **🔍 ASCII Graph Visualization**: Preview your knowledge graph structure directly in the chat interface before exporting, with support for both clean and detailed (full URI) modes.
- **⚖️ Built-in SHACL Validation**: Ensures data integrity from the start. It validates entities against schema constraints before you export your graph.
- **� Session Control & Sanitization**: surgically remove entities, reset the session environment, and enjoy automatic URI sanitization for complex IDs (like file paths or registry keys).

## 🌟 Intelligent Tools

- `get_ontology_summary`: Quick high-level overview of the loaded schema.
- `search_classes` / `search_properties`: Weighted semantic 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 with auto URI sanitization.
- `remove_entity` / `reset_graph`: Surgical modification or full session cleanup.
- `validate_entity`: Instant SHACL compliance check.
- `visualize_graph`: ASCII tree preview of the current graph (supports `verbose` mode).
- `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
1. gemini-cli, claude(Desktop,Code)
```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",
        "EMBEDDING_MODEL": "all-MiniLM-L6-v2"
      }
    }
  }
}
```

2. OpenCode
```json
{
  "mcp": {
    "universal-ontology-mcp": {
      "type": "local",
      "command": ["python","/Users/seonwookim/Documents/Programming/Security/cyber-ontology/ontology-mapper/universal-ontology-mcp/main.py"],
      "environment": {
        "ONTOLOGY_DIR": "/Users/seonwookim/Documents/Programming/Security/cyber-ontology/ontology-mapper/ontology",
        "EMBEDDING_MODEL": "all-MiniLM-L6-v2"
      }
    }
  }
}
```

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