GraphRAG Protocol

Universal GraphRAG Interoperability Protocol — standard contracts + MCP server + adapters so any agent can query any GraphRAG backend uniformly.

Every GraphRAG engine (TigerGraph, Neo4j, LightRAG, LlamaIndex, FalkorDB, Microsoft GraphRAG) reinvents retrieval, subgraph serialization, provenance, and evaluation with incompatible interfaces. This protocol fills the missing middle layer between GQL (graph query standard at the bottom) and MCP (agent connectivity standard at the top): a uniform retrieval contract any backend can implement and any agent can call.

Quick Start

# 1. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 2. Install the package (with dev dependencies)
pip install -e ".[dev]"

# 3. Copy the env template and fill in your backend credentials
cp .env.example .env
# E.g. TIGERGRAPH_HOST, TIGERGRAPH_GSQL_SECRET, GOOGLE_API_KEY

# 4. Inspect the protocol types
python -c "from mcp_server.protocol import SubgraphContext, RetrievalRequest; print('protocol OK')"

# 5. Start the MCP server (stdio transport — what agents launch)
python -m mcp_server.mcp_server      # or the `graphrag-mcp` entrypoint

# 6. Start the HTTP dashboard server (FastAPI, binds 127.0.0.1:8000)
python -m mcp_server.server          # or the `graphrag-server` entrypoint

Requires Python 3.10+. Optional extras: pip install -e ".[server,tigergraph,llm]".

Backends

• TigerGraph (Savanna): Primary enterprise graph backend (mcp_server/adapters/tigergraph_adapter.py). Connects via pyTigerGraph REST++, runs graph algorithms and installs GSQL queries idempotently.
• Neo4j (Cypher): Official Cypher backend (mcp_server/adapters/neo4j_adapter.py). Parameterized Cypher queries for neighborhood expansion, shortest paths, community detection, and schema discovery.
• SQLite Persistent Store: Embedded WAL-mode storage (mcp_server/storage.py) for query result caching, background jobs, and event journal replay.
• Demo In-Memory Adapter: Labeled in-memory adapter (mcp_server/adapters/fallback_adapter.py) with BFS/Dijkstra traversal for hermetic unit testing and offline development.

Ingesting documents (Contract 4)

Writes are real backend upserts and every counter in the report is measured from the backend (getVertexCount before/after, existence probes per entity):

# Self-test: ingest a document, read it back, delete it again
.venv/bin/python scripts/smoke_construction.py

Write operations (ingest / update / delete) require authorization (Contract 10) via admin token or signed capability token (graphrag_capability_token). Ingestion also publishes Contract 7 / Contract 18 stream events, persisted in SQLite and emitted over SSE.

Running the tests

pytest                    # hermetic unit suite (no creds, no network)
pytest -m integration     # live TigerGraph + Gemini tests (self-skip without creds)
ruff check mcp_server/ hackathon/ tests/

The 18 Contracts

JSON Schemas for Contracts 1–10 live in schemas/; tests/test_schemas.py fails if any schema drifts from its Pydantic model.

MCP Tool Surface (50 tools)

Core & Retrieval Tools (27 tools)

Analytical & Operational Tools (15 tools)

Autonomous Agentic & Advanced Tools (8 tools)

Repo Layout

graphrag-protocol/
├── SPEC.md                      # Full protocol specification
├── MCP_SERVER_AUDIT.md          # Audit report + upgrade roadmap
├── schemas/                     # JSON Schema definitions (language-agnostic)
│   ├── retrieval-request.json   # Contract 1
│   ├── subgraph-context.json    # Contract 2
│   ├── graph-schema.json        # Contract 3
│   ├── ingestion-config.json    # Contract 4 (+ IngestionReport, Triple)
│   ├── provenance.json          # Contract 5
│   ├── federation-config.json   # Contract 6
│   ├── stream-event.json        # Contract 7
│   ├── prompt-format-config.json# Contract 8
│   ├── evaluation-report.json   # Contract 9
│   └── access-policy.json       # Contract 10
├── mcp_server/                  # Reference implementation
│   ├── protocol.py              # Canonical Pydantic v2 models (contracts 1-5, 8)
│   ├── protocol_extensions.py   # Models for contracts 4, 6, 7, 9, 10
│   ├── contracts/               # 18 contracts: retrieval, schema, provenance,
│   │   ├── retrieval.py         #   construction, federation, streaming, evaluation,
│   │   ├── schema_discovery.py  #   authorization, similarity, temporal, explanation,
│   │   ├── provenance.py        #   diff, aggregate, export, batch, watch
│   │   ├── construction.py
│   │   ├── federation.py
│   │   ├── streaming.py
│   │   ├── evaluation.py
│   │   ├── authorization.py
│   │   ├── similarity.py        # Contract 11
│   │   ├── temporal.py          # Contract 12
│   │   ├── explanation.py       # Contract 13
│   │   ├── diff.py              # Contract 14
│   │   ├── aggregate.py         # Contract 15
│   │   ├── export.py            # Contract 16
│   │   ├── batch.py             # Contract 17
│   │   └── watch.py             # Contract 18
│   ├── adapters/                # TigerGraph, Neo4j (Cypher), and demo memory adapter
│   ├── storage.py               # SQLite WAL-mode persistent store
│   ├── cache.py                 # TTL query cache with LRU & auto-invalidation
│   ├── rate_limiter.py          # Token-bucket sliding window rate limiter
│   ├── formatters/              # Contract 8: Markdown / structured, token-bounded
│   ├── pipelines.py             # Shared 3-pipeline runner (server + eval harness)
│   ├── mcp_server.py            # MCP stdio server (47 tools, v0.3.0)
│   └── server.py                # FastAPI dashboard server (+ SSE event feed)
├── frontend/                    # Next.js 14 dashboard (query lab, graph, benchmark, ingest & stream)
├── hackathon/                   # TigerGraph dataset, GSQL loaders, evaluation harness
├── scripts/                     # Live smoke tests (construction, connection)
├── tests/
│   ├── test_contracts.py        # Contracts 1, 3, 5 hermetic tests
│   ├── test_new_contracts.py    # Contracts 11-18, storage, cache, neo4j tests
│   ├── test_mcp_server.py       # 47-tool MCP server hermetic tests
│   ├── test_formatters.py       # Contract 8 formatter tests
│   ├── test_schemas.py          # JSON schema drift detection
│   ├── test_server.py           # FastAPI server tests
│   └── test_tigergraph_adapter.py # TigerGraph adapter integration tests
└── pyproject.toml

License

MIT