How rawr-ai/mcp-graphiti works
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