SPECIFICATION v0.5.0RFC STANDARD20 WIRE CONTRACTS

GRIP Protocol Documentation

The comprehensive developer and architecture documentation for the Universal GraphRAG Interoperability Protocol.

Table of Contents

Connect to IDEs

Need Claude Code, Cursor, or Cline configuration files?

Go to Setup Guides →
SECTION 01

Overview & Architecture

GRIP (GraphRAG Interoperability Protocol) establishes the vendor-neutral wire protocol and tool surface for Graph-Augmented Retrieval Generation.

The Missing Middle Layer Problem

Prior to GRIP, every knowledge graph database (TigerGraph, Neo4j, Amazon Neptune, Memgraph) required proprietary query languages (GSQL, Cypher, openCypher, Gremlin) and bespoke RAG pipelines. LLMs were forced to generate complex graph query strings, leading to syntax hallucination, injection risks, and tight vendor lock-in.

Top LayerAI Agent / LLMMCP Client Interface
GRIP Middle Layer20 Standard Contracts50 Uniform MCP Tools
Bottom LayerAny Graph BackendTigerGraph, Neo4j, etc.

Architectural Guarantees

  • Live Database Execution: 100% of tools execute directly against connected enterprise graph engines without stubbed responses.
  • Cryptographic Provenance (Contract 5): Every answer is tied to source vertex IDs and chunk hashes.
  • Dynamic Token Bounding (Contract 8): Output text fits strictly within caller's token budget.
  • Multi-Backend Federation (Contract 6): Single queries fan out across hybrid TigerGraph + Neo4j clusters.
SECTION 02

Installation & Quickstart

GRIP is distributed as a lightweight Python package with optional backend extras.

1. Install via pip or pipx

terminal
# Core package (standard MCP tools + in-memory store)
pip install -U grip-protocol

# With TigerGraph Cloud adapter & Gemini LLM support (Recommended)
pip install "grip-protocol[tigergraph,llm]"

# Global CLI installation via pipx
pipx install "grip-protocol[all]"

2. Configure Environment Variables

.env
# .env file in your working directory
TIGERGRAPH_HOST="https://your-graph-endpoint.i.tgcloud.io"
TIGERGRAPH_USERNAME="tigergraph"
TIGERGRAPH_PASSWORD="your_password"
TIGERGRAPH_SECRET="your_secret_alias"
TIGERGRAPH_GRAPH_NAME="GraphragProtocol"
GOOGLE_API_KEY="AIzaSy..."
LLM_MODEL="gemini-2.5-flash"

3. Verify Installation via CLI

terminal
# Check health of active backend
grip --help

# Launch in stdio transport mode (default for IDE agents)
grip --transport stdio
SECTION 03

CLI Command Reference

`grip-protocol` registers multiple binary entry points for convenience:grip, grip-mcp, grip-server, graphrag-mcp.

FlagValuesDescription
--transportstdio | streamable-http | sseMCP communication transport. Default: stdio.
--hostIP address (e.g. 0.0.0.0)Bind address for HTTP or SSE server. Default: 127.0.0.1.
--portPort number (e.g. 8000)Port for HTTP or SSE server. Default: 8000.
--help-h, --helpDisplay usage summary and exit.
SECTION 04

Complete 50-Tool MCP Surface

Every tool returns valid JSON strings conforming to the official RFC wire specifications. Below is the full tool catalog:

CONTRACT 1: RETRIEVAL (7 TOOLS)
  • graphrag_search — Auto-routed hybrid search
  • graphrag_local_search — Multi-hop entity expansion
  • graphrag_global_search — Community summary search
  • graphrag_hybrid_search — Vector + topology fusion
  • graphrag_entity — Entity lookup by ID or name
  • graphrag_path — Shortest path discovery
  • graphrag_neighborhood — K-hop neighbor subgraph
CONTRACT 3: SCHEMA (4 TOOLS)
  • graphrag_schema — Complete vertex & edge types
  • graphrag_entity_types — Vertex types with counts
  • graphrag_relationship_types — Edge definitions
  • graphrag_sample — Sample entities for LLM context
CONTRACT 4: CONSTRUCTION (2 TOOLS)
  • graphrag_ingest — Document ingestion pipeline
  • graphrag_delete_document — Cascade reference deletion
CONTRACT 5: PROVENANCE (4 TOOLS)
  • graphrag_provenance — Cryptographic citation trace
  • graphrag_trajectory — Ordered traversal step replay
  • graphrag_sources — Deduplicated supporting documents
  • graphrag_audit — Visited-not-cited leak audit
CONTRACT 11-15: ANALYTICS & AGGREGATES
  • graphrag_similarity — Cosine embedding & Jaccard
  • graphrag_temporal_search — Date range filtered search
  • graphrag_explain — Natural language why-retrieved
  • graphrag_diff — SubgraphContext delta comparison
  • graphrag_count — Entity count with attribute filters
  • graphrag_group_by — Group entities by property
  • graphrag_top_n — Top-N ranked by numeric property
  • graphrag_stats_summary — Graph-level density & degree
CONTRACT 16-20: ADVANCED PROTOCOL
  • graphrag_export_subgraph — GraphML / Cypher / JSON-LD
  • graphrag_batch — Parallel execution up to 25 calls
  • graphrag_watch — Event journal & mutation stream
  • graphrag_resolve_conflicts — Temporal contradiction resolver
  • graphrag_triage_query — RAG vs GraphRAG ROI classifier
  • graphrag_agent_investigate — Multi-step reasoning agent
SECTION 05

Transport Protocols (stdio, HTTP, SSE)

GRIP implements all three official Model Context Protocol transports:

1. stdio Transport (Standard Input/Output)

Best for local desktop agents like Claude Code, Cursor, Windsurf, and Zed. The agent spawns the `grip` process and communicates over pipes.

bash
grip --transport stdio

2. Streamable HTTP Transport

Modern HTTP transport for remote microservices, multi-tenant agent gateways, and cloud deployment.

bash
grip --transport streamable-http --host 0.0.0.0 --port 8000

3. SSE (Server-Sent Events) Transport

HTTP with a continuous server-push event stream for real-time graph mutations and streaming traversal events (Contract 7).

bash
grip --transport sse --host 0.0.0.0 --port 8000
SECTION 06

Supported Graph Backends

GRIP uses a pluggable adapter architecture (`BaseGraphRAGAdapter`) supporting both production graph databases and local lightweight stores:

TigerGraph Cloud (Savanna)

Primary

Native REST++ precompiled queries for multi-hop traversals, Jaccard similarity, and vector similarity search on 512-dim embedding vertices.

Neo4j (Cypher)

Supported

Bolt driver adapter compiling Contract 1 retrieval and Contract 3 schema introspection into parameterized Cypher queries.

SQLite WAL Store

Embedded

Zero-dependency local persistence for metadata, job status, capability tokens, and mutation event journaling.

In-Memory Demo Adapter

Testing

Instant offline testing adapter pre-loaded with sample ArXiv knowledge subgraphs for hermetic test suites.

SECTION 07

Autonomous Agentic Harness

`graphrag_agent_investigate` runs an autonomous multi-step reasoning loop powered by Gemini 2.5 Flash and Automatic Function Calling (AFC).

Agentic Investigation Trajectory

  1. Hypothesis Formulation: Identifies seed entities and queries schema structure.
  2. Targeted Expansion: Traverses high-confidence relationships across up to 10 hops.
  3. Conflict Resolution: Evaluates contradictions using Contract 19 recency and citation weights.
  4. Extractive Synthesis: Formulates final grounded answer strictly backed by visited provenance paths.

Explore All 20 Wire Contracts in Detail

Review JSON schemas, architectural guarantees, and standards for all 20 contracts.

Protocol Explorer →