# rawr-ai/mcp-graphiti architecture

> Architecture diagram of the GitHub repository rawr-ai/mcp-graphiti, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rawr-ai/mcp-graphiti
- Repository: https://github.com/rawr-ai/mcp-graphiti

## Overview

##### Project Type & Purpose
- This is a hybrid tool combining:
- A CLI/Compose-generator (`graphiti_cli`) that automates Docker-Compose setup
- A microservices-style MCP server (`graphiti_mcp_server.py`) that runs multiple isolated Graphiti instances against a single Neo4j DB
- Project scaffolding (entity templates, rules) for per-project temporal knowledge graphs
- Purpose: let users spin up N Docker containers (one Neo4j + N Graphiti MCP servers), each namespaced by `group_id`, with zero-downtime tweaks and IDE auto-discovery.

##### File Structure Analysis
- Top level
- Dockerfile, base-compose.yaml, entrypoint.sh – server container build & startup
- pyproject.toml – Python packaging, dependencies
- constants.py – global settings (ports, env vars)
- .env.example – Neo4j & OpenAI credentials
- mcp-projects.yaml (user-provided) – lists all projects & their paths
- Key directories
- graphiti_cli/ – CLI entrypoint, commands (compose, up, init, reload), logic (compose_generator, project_registry), utils (config, YAML, paths)
- entities/ – Domain model classes for actions, connectors, constraints, resources, interaction models; loaded by each MCP server
- ai/graph/ – Graph schema drafts & JSON schemas for knowledge-graph ingestion
- project_assets/ – Templates for new project `ai/graph/entities`, rules, schema templates
- tests/ – Unit and functional tests for CLI and server logic

##### README Insights
- Compose generator reads mcp-projects.yaml, assigns ports (starting at 8001), mounts per-project volumes, patches `.cursor/mcp.json` for IDE auto-discovery
- entrypoint.sh bootstraps each server with `group_id`, entity rules, LLM model env vars

##### Main Components
a. CLI & Compose Generator
- Inputs: mcp-projects.yaml, .env, project directories with entity YAML
- Outputs: docker-compose.yml, updated `.cursor/mcp.json`

b. Orchestrator (Docker Compose)
- One Neo4j container
- One “root” MCP server container (port 8000)
- N project-scoped MCP server containers (ports 8001…800N)

c. MCP Server Internals
- HTTP/SSE API (fastapi/Starlette or Flask server)
- Entity ingest logic (uses `entities/`, `ai/graph/schemas`)
- OpenAI API calls to extract entities & relationships
- Writes to Neo4j (Bolt driver) in a time-stamped, namespaced (`group_id`) graph

d. Clients & External Services
- IDE or AI agent – connects via SSE (`http://localhost:800X/sse`) or HTTP (`/status`)
- Neo4j Browser/UI – connects to `bolt://neo4j:7687` or `http://localhost:7474`

##### Relationships & Data Flow
- User runs `graphiti compose` → CLI reads mcp-projects.yaml & .env → generates `docker-compose.yml` → patches `.cursor/mcp.json`
- `graphiti up -d` → Docker Compose spins up containers
- IDE/agent ↔ SSE → MCP server X (port) → Cypher queries → Neo4j → SSE responses back to client
- MCP server on startup loads entity YAMLs & rule assets from mounted project directory

##### Architectural Patterns & Principles
- Microservices-style isolation: one container = one `group_id`
- Orchestration via Docker Compose (shared network, shared DB)
- Directory-mounted volumes for per-project configs (read-only to other projects)
- Single source code image (`graphiti_mcp_server.py`) parameterized by env vars
- CLI/Infrastructure as code: generation of compose files & IDE configs

##### Technologies & Frameworks
- Python 3 + FastAPI/Flask (HTTP/SSE)
- Neo4j (temporal graph) with Bolt driver
- OpenAI / LLM API
- Docker & Docker Compose
- pipx for CLI distribution
- PyYAML for config parsing
- pytest for testing

1. **User/CLI Layer** – graphiti CLI, mcp-projects.yaml, .env → compose generation
2. **Orchestration Layer** – Docker Compose → containers + shared network
3. **Runtime Layer** – IDE/Agent, MCP servers, Neo4j, OpenAI API
- Include:
- Arrowheads for data flow (SSE vs HTTP vs Cypher)
- Notes on volume mounts & env vars

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/CLI Layer
    subgraph "User/CLI Layer"
        direction TB
        File_yaml["mcp-projects.yaml"]:::config
        File_env[".env.example"]:::config
        CLI_main["main.py"]:::cli
        CLI_docker["docker.py"]:::cli
        CLI_project["project.py"]:::cli
        CLI_compose_gen["compose_generator.py"]:::logic
        CLI_registry["project_registry.py"]:::logic
        CLI_yaml["yaml_utils.py"]:::util
        CLI_cursor["cursor_utils.py"]:::util
        CLI_config["config.py"]:::util
        File_baseCompose["base-compose.yaml"]:::config
    end

    File_yaml -->|reads| CLI_main
    File_env -->|reads| CLI_main
    CLI_main -->|invokes| CLI_compose_gen
    CLI_main -->|invokes| CLI_registry
    CLI_compose_gen -->|writes| File_baseCompose
    CLI_compose_gen -->|patches| CLI_cursor

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        DockerCompose["Docker Compose"]:::orch
        Dockerfile["Dockerfile"]:::orch
        Entrypoint["entrypoint.sh"]:::orch
        Constants_orch["constants.py"]:::orch
    end

    File_baseCompose -->|input| DockerCompose
    DockerCompose -->|build| Dockerfile
    DockerCompose -->|set env| Constants_orch
    DockerCompose -->|run entrypoint| Entrypoint

    %% Runtime Layer
    subgraph "Runtime Layer"
        direction TB

        subgraph "Containers"
            direction TB
            Neo4jC["Neo4j Container"]:::db
            RootSrv["MCP Server<br/>(group_id=root, port=8000)"]:::srv
            ProjA["MCP Server<br/>(group_id=proj-A, port=8001)"]:::srv
        end

        IDE["IDE/Agent"]:::client
        OpenAI["OpenAI API"]:::ext

        %% MCP Internals Assets
        Entities["entities/"]:::asset
        Schemas["ai/graph/schemas"]:::asset
        AssetsTemplates["project_assets/entity_templates"]:::asset
        AssetsRules["project_assets/rules"]:::asset
        SchemaTemplate["project_assets/rules/templates/schema_template.py"]:::asset
    end

    DockerCompose -->|starts| Neo4jC
    DockerCompose -->|starts| RootSrv
    DockerCompose -->|starts| ProjA

    IDE -->|SSE/HTTP| RootSrv
    IDE -->|SSE/HTTP| ProjA

    RootSrv -->|Bolt/Cypher| Neo4jC
    ProjA -->|Bolt/Cypher| Neo4jC

    RootSrv -->|LLM calls| OpenAI
    ProjA -->|LLM calls| OpenAI

    Entities -->|mount| RootSrv
    Entities -->|mount| ProjA
    Schemas -->|mount| RootSrv
    Schemas -->|mount| ProjA
    AssetsTemplates -->|mount| RootSrv
    AssetsTemplates -->|mount| ProjA
    AssetsRules -->|mount| RootSrv
    AssetsRules -->|mount| ProjA
    SchemaTemplate -->|mount| RootSrv
    SchemaTemplate -->|mount| ProjA

    %% Click Events
    click CLI_main "https://github.com/rawr-ai/mcp-graphiti/blob/main/graphiti_cli/main.py"
    click CLI_docker "https://github.com/rawr-ai/mcp-graphiti/blob/main/graphiti_cli/commands/docker.py"
    click CLI_project "https://github.com/rawr-ai/mcp-graphiti/blob/main/graphiti_cli/commands/project.py"
    click CLI_compose_gen "https://github.com/rawr-ai/mcp-graphiti/blob/main/graphiti_cli/logic/compose_generator.py"
    click CLI_registry "https://github.com/rawr-ai/mcp-graphiti/blob/main/graphiti_cli/logic/project_registry.py"
    click CLI_yaml "https://github.com/rawr-ai/mcp-graphiti/blob/main/graphiti_cli/utils/yaml_utils.py"
    click CLI_cursor "https://github.com/rawr-ai/mcp-graphiti/blob/main/graphiti_cli/utils/cursor_utils.py"
    click CLI_config "https://github.com/rawr-ai/mcp-graphiti/blob/main/graphiti_cli/utils/config.py"
    click File_baseCompose "https://github.com/rawr-ai/mcp-graphiti/blob/main/base-compose.yaml"
    click File_env "https://github.com/rawr-ai/mcp-graphiti/blob/main/.env.example"
    click File_yaml "https://github.com/rawr-ai/mcp-graphiti/blob/main/mcp-projects.yaml"
    click Dockerfile "https://github.com/rawr-ai/mcp-graphiti/tree/main/Dockerfile"
    click Entrypoint "https://github.com/rawr-ai/mcp-graphiti/blob/main/entrypoint.sh"
    click Constants_orch "https://github.com/rawr-ai/mcp-graphiti/blob/main/constants.py"
    click Neo4jC "https://github.com/rawr-ai/mcp-graphiti/tree/main/Dockerfile"
    click RootSrv "https://github.com/rawr-ai/mcp-graphiti/blob/main/graphiti_mcp_server.py"
    click ProjA "https://github.com/rawr-ai/mcp-graphiti/blob/main/graphiti_mcp_server.py"
    click Entities "https://github.com/rawr-ai/mcp-graphiti/tree/main/entities/"
    click Schemas "https://github.com/rawr-ai/mcp-graphiti/tree/main/ai/graph/schemas"
    click AssetsTemplates "https://github.com/rawr-ai/mcp-graphiti/tree/main/project_assets/entity_templates"
    click AssetsRules "https://github.com/rawr-ai/mcp-graphiti/tree/main/project_assets/rules"
    click SchemaTemplate "https://github.com/rawr-ai/mcp-graphiti/blob/main/project_assets/rules/templates/schema_template.py"

    %% Styles
    classDef cli fill:#a8e6cf,stroke:#379683,color:#000;
    classDef logic fill:#dcedc1,stroke:#558b2f,color:#000;
    classDef util fill:#ffd3b6,stroke:#d35400,color:#000;
    classDef config fill:#ffd3b6,stroke:#d35400,color:#000;
    classDef orch fill:#ffcc80,stroke:#ef6c00,color:#000;
    classDef srv fill:#80deea,stroke:#006064,color:#000;
    classDef db fill:#e0e0e0,stroke:#9e9e9e,color:#000;
    classDef client fill:#b3e5fc,stroke:#0288d1,color:#000;
    classDef ext fill:#c5cae9,stroke:#3f51b5,color:#000;
    classDef asset fill:#f8bbd0,stroke:#c2185b,color:#000
```
