# 🧠 MCP Knowledge Graph Architecture Manifest (Final)

## 0. Purpose

Define a **strict, minimal, and general architecture** for MCP systems that operate on knowledge graphs.

This architecture separates:

* graph execution
* semantic intelligence (enrichment)
* domain-specific operations

It is **deliberately rigid** to ensure:

* clarity for agents
* composability of systems
* long-term scalability

---

# 1. Core Principles

### 1.1 Absolute Separation

Each layer has one responsibility:

* execution
* intelligence
* application

These MUST NOT overlap.

---

### 1.2 Enrichment is Abstract

Enrichment is NOT:

* geography-specific
* ontology-specific
* domain-specific

Enrichment IS:

> **the discovery of related entities under defined constraints**

---

### 1.3 Ontologies are Data

* Ontologies are inputs
* Ontologies are not hardcoded logic
* Ontologies can vary per system

---

### 1.4 Everything is a Graph

* entities
* relations
* ontologies
* queries

---

# 2. System Architecture

```text
[ Domain-Specific MCPs ]
            ↓
        [ Atlas MCP ]
            ↓
     [ Virtuoso MCP ]
```

---

# 3. Layer Definitions

---

## 3.1 Virtuoso MCP

(Virtuoso MCP)

### Role

> **Graph execution layer**

---

### Responsibilities

* store RDF triples
* execute SPARQL queries
* provide graph primitives

---

### Capabilities

* traversal by predicate
* node description
* relation enumeration
* path queries
* prefix handling (technical)
* named graph management

---

### MUST NOT

* interpret meaning
* resolve entities
* enrich data
* depend on external sources

---

### Philosophy

> “Executes graph operations without understanding them.”

---

## 3.2 Atlas MCP

### Role

> **Semantic intelligence layer**

Atlas is the **only layer allowed to interpret and enrich data**.

---

# 4. Enrichment (Formal Definition)

Enrichment is defined as:

> **The controlled expansion of an entity into a set of related entities based on structural, semantic, or constraint-based relationships.**

---

## 4.1 Enrichment Dimensions

Atlas MUST support enrichment along arbitrary axes:

### Structural

* hierarchy (parent, child)
* adjacency
* graph distance

---

### Semantic

* type similarity
  (e.g. “musicians”)

* shared attributes
  (e.g. “born 1965”)

---

### Constraint-based

* filtered relations
* query-defined sets

---

## 4.2 Examples (All Equivalent Forms of Enrichment)

* “Find parent regions of Kumasi”
* “Find musicians born in 1965 in Ghana”
* “Find entities with same profession as X”
* “Find all siblings in a pedigree graph”
* “Find all servers connected via health routes”

👉 These are NOT different features
👉 They are **instances of the same abstraction**

---

## 4.3 Core Enrichment Operation

```text
expand(entity, constraints, depth) → subgraph
```

Where:

* `entity` = starting node
* `constraints` = predicates, types, filters
* `depth` = traversal boundary

---

## 4.4 Key Rule

> Atlas provides the mechanism of enrichment
> Domain-specific MCPs define what is relevant

---

# 5. Ontology Handling

---

## 5.1 Ontology Layers

Atlas operates on three ontology types:

### External Ontologies

* Wikidata
* other knowledge graphs

---

### Canonical Ontology (REQUIRED)

Atlas MUST define a **minimal internal schema**

Purpose:

* normalize external data
* provide stable structure

---

### Domain Ontologies

Defined by domain-specific MCPs:

* facts-mcp
* garden-mcp
* news-mcp
* etc.

---

## 5.2 Core Rule

> Atlas translates between ontologies but owns none of them

---

## 5.3 Ontology Mapping

Atlas MUST:

* ingest ontologies
* map external → canonical
* optionally map canonical → domain

Atlas MUST NOT:

* assume domain semantics
* enforce domain schemas

---

# 6. Atlas Responsibilities

### 6.1 Entity Resolution

* text → entity identifiers

---

### 6.2 Graph Acquisition

* retrieve data from:

  * external knowledge graphs
  * internal graph store

---

### 6.3 Ontology Mediation

* align different schemas
* normalize representations

---

### 6.4 Enrichment Execution

* perform expansion queries
* apply constraints
* return structured subgraphs

---

### 6.5 Persistence

* store results via Virtuoso MCP

---

### 6.6 Data Layers (MANDATORY)

Atlas MUST maintain:

#### Raw Layer

* source-aligned data
* full provenance

#### Canonical Layer

* normalized structure

#### Derived Layer

* enrichment results
* computed relations

---

### Philosophy

> “Atlas turns graphs into usable knowledge.”

---

## 3.3 Domain-Specific MCPs

### Definition

> A **domain-specific MCP** is any MCP that:

* serves a specific purpose
* defines its own ontology
* uses Atlas and/or Virtuoso to operate on graph data

---

### Examples

* Facts MCP
* Garden MCP
* News MCP

---

### Role

> **Application and decision layer**

---

### Responsibilities

* define domain ontology
* define relevance and constraints
* invoke Atlas for enrichment
* store/query via Virtuoso MCP

---

### Capabilities

* tagging
* classification
* domain-specific inference
* state representation

---

### MUST NOT

* resolve entities independently
* perform enrichment logic outside Atlas
* duplicate ontology mapping logic

---

### Key Rule

> Domain-specific MCPs define *what to ask*
> Atlas defines *how to answer*

---

# 7. Facts MCP (Clarified)

### Role

> **Domain-specific MCP for authoritative state**

---

### Responsibilities

* define “current truth” in its domain
* maintain state using its ontology
* query enriched data via Atlas

---

### Example

```text
:ServerA :isOperational true
```

---

### Key Rule

> “Fact” is a domain concept, not a system concept

---

# 8. Prefix Handling

| Layer                | Responsibility                     |
| -------------------- | ---------------------------------- |
| Virtuoso MCP         | technical prefix resolution        |
| Atlas MCP            | namespace interpretation & mapping |
| Domain-Specific MCPs | domain-specific prefixes           |

---

# 9. Data Flow

```text
Input (text / entity / query)
        ↓
Domain-Specific MCP
        ↓
Atlas MCP
    - resolve
    - enrich
    - map ontologies
        ↓
Virtuoso MCP
    - execute
    - persist
        ↓
Domain-Specific MCP
    - apply domain logic
```

---

# 10. Hard Rules

### Rule 1

Virtuoso MCP MUST remain purely operational

---

### Rule 2

Atlas MCP is the ONLY semantic intelligence layer

---

### Rule 3

All enrichment MUST go through Atlas

---

### Rule 4

All ontology mapping MUST go through Atlas

---

### Rule 5

Domain-specific MCPs MUST NOT duplicate enrichment logic

---

### Rule 6

Domain-specific MCPs define relevance, not mechanisms

---

# 11. Final Model

```text
Virtuoso MCP  → executes graph operations
Atlas MCP     → performs semantic expansion
Domain-Specific MCPs → define purpose and meaning
```

---

# 12. Final Statement

> Build systems where:
>
> * the graph layer executes
> * the semantic layer expands
> * the domain-specific layer decides
>
> and no layer crosses its boundary.

---
