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) is the primary backend. The adapter (mcp_server/adapters/tigergraph_adapter.py) talks to a live workspace over pyTigerGraph REST++ and installs its GSQL queries idempotently on first use. mcp_server/adapters/fallback_adapter.py is a clearly-labeled in-memory adapter for tests and offline development — it is read-only, never presented as TigerGraph, and never used to fabricate an answer.

Ingesting documents (Contract 4)

Writes are real TigerGraph 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 the admin token (Contract 10, GRAPHRAG_ADMIN_TOKEN); without it they fail closed with 403. Ingestion also publishes Contract 7 events at the mutation point, which the dashboard consumes over SSE at /stream/events.

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 15 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 (42 tools)

Original 27 tools

New 15 tools (v0.2.0)

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/               # 15 contracts: retrieval, schema, provenance,
│   │   ├── retrieval.py         #   construction, federation, streaming, evaluation,
│   │   ├── schema_discovery.py  #   authorization, similarity, temporal, explanation,
│   │   ├── provenance.py        #   diff, aggregate
│   │   ├── construction.py
│   │   ├── federation.py
│   │   ├── streaming.py
│   │   ├── evaluation.py
│   │   ├── authorization.py
│   │   ├── similarity.py        # NEW: Contract 11
│   │   ├── temporal.py          # NEW: Contract 12
│   │   ├── explanation.py       # NEW: Contract 13
│   │   ├── diff.py              # NEW: Contract 14
│   │   └── aggregate.py         # NEW: Contract 15
│   ├── adapters/                # TigerGraph (real) + labeled in-memory demo adapter
│   ├── formatters/              # Contract 8: Markdown / structured, token-bounded
│   ├── pipelines.py             # Shared 3-pipeline runner (server + eval harness)
│   ├── mcp_server.py            # MCP stdio server (42 tools, v0.2.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-15 hermetic tests (NEW)
│   ├── test_mcp_server.py       # 42-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