Graph RAG MCP Server


A comprehensive Model Context Protocol (MCP) server implementing advanced Graph RAG (Retrieval-Augmented Generation) architecture with sophisticated graph structures, operators, and agentic capabilities for AI agents.

🚀 Features

$3

- Directed Acyclic Graph (DAG): Workflow planning with dependency management
- Passage Graph: Document chunk relationships with semantic connections
- Trees Graph: Hierarchical knowledge representation with multi-resolution
- Knowledge Graph: Semantic relationships following subject-predicate-object patterns
- Textual Knowledge Graph: Enhanced knowledge graphs with contextual descriptions

$3

#### Node Operators
- VDB Operator: Vector similarity search for semantic relevance
- PPR Operator: Personalized PageRank for authority analysis

#### Relationship Operators
- OneHop Operator: Direct neighborhood exploration
- Aggregator Operator: Multi-relationship synthesis

#### Chunk Operators
- FromRel Operator: Trace relationships back to source chunks
- Occurrence Operator: Entity co-occurrence analysis

#### Subgraph Operators
- KHopPath Operator: Multi-step path finding between entities
- Steiner Operator: Minimal connecting networks construction

$3

- Sequential Chaining: Step-by-step operator execution
- Parallel Execution: Concurrent operator processing with result fusion
- Adaptive Execution: Intelligent operator selection and optimization

$3

- Intelligent Query Planning: Automatic operator chain creation
- Multi-Modal Fusion: Combine results from different graph types
- Adaptive Reasoning: Complex reasoning with iterative refinement
- Performance Analytics: Comprehensive metrics and optimization

📦 Installation

``bash


Install via npm

npm install zrald

Or install globally

npm install -g zrald
`

$3

`bash


Clone the repository for development

git clone https://github.com/augment-code/graph-rag-mcp-server.git
cd graph-rag-mcp-server

Install dependencies

npm install

Set up environment variables

cp .env.example .env

Edit .env with your configuration

Build the project

npm run build

Start the server

npm start
`

⚡ Quick Start

`javascript
import { GraphRAGMCPServer } from 'zrald';

// Initialize the server
const server = new GraphRAGMCPServer();

// Start the MCP server
await server.initialize();
await server.start();

console.log('Graph RAG MCP Server is running!');
`

$3

`bash


Start the server directly

graph-rag-mcp-server

Or with custom configuration

NEO4J_URI=bolt://localhost:7687 graph-rag-mcp-server
`

🔧 Configuration

$3

- Neo4j Database: For graph storage and querying
- Node.js 18+: Runtime environment
- Memory: Minimum 4GB RAM recommended

$3

See .env.example for all configuration options.

Key configurations:
- NEO4J_URI: Neo4j database connection string
- NEO4J_USERNAME/PASSWORD: Database credentials
- VECTOR_DIMENSION: Embedding dimension (default: 384)
- MAX_VECTOR_ELEMENTS: Vector store capacity

🛠️ Usage

$3


`typescript
// Create an intelligent query plan
const plan = await server.createQueryPlan(
"Find relationships between artificial intelligence and machine learning",
{ reasoning_type: "analytical" }
);

// Execute the plan
const result = await server.executeQueryPlan(plan.id);
`

$3


`typescript
// Vector similarity search
const vdbResult = await server.vdbSearch({
query_embedding: [0.1, 0.2, ...], // 384-dimensional vector
top_k: 10,
similarity_threshold: 0.7,
node_types: ["entity", "concept"]
});

// Personalized PageRank analysis
const pprResult = await server.pageRankAnalysis({
seed_nodes: ["ai_node_1", "ml_node_2"],
damping_factor: 0.85,
max_iterations: 100
});

// Multi-hop path finding
const pathResult = await server.pathFinding({
source_nodes: ["source_entity"],
target_nodes: ["target_entity"],
max_hops: 3,
path_limit: 10
});
`

$3


`typescript
// Add nodes to the knowledge graph
await server.addNodes({
nodes: [
{
id: "ai_concept",
type: "concept",
label: "Artificial Intelligence",
properties: { domain: "technology" },
embedding: [0.1, 0.2, ...] // Optional
}
]
});

// Add relationships
await server.addRelationships({
relationships: [
{
id: "rel_1",
source_id: "ai_concept",
target_id: "ml_concept",
type: "INCLUDES",
weight: 0.9,
confidence: 0.95
}
]
});
`

$3


`typescript
// Adaptive reasoning
const reasoningResult = await server.adaptiveReasoning({
reasoning_query: "How does machine learning enable artificial intelligence?",
reasoning_type: "causal",
max_iterations: 5,
confidence_threshold: 0.8
});

// Multi-modal fusion
const fusionResult = await server.multiModalFusion({
fusion_query: "Compare AI approaches across different domains",
graph_types: ["knowledge", "passage", "trees"],
fusion_strategy: "weighted_average"
});
`

🏗️ Architecture

$3


`
src/
├── core/ # Core infrastructure
│ ├── graph-database.ts # Neo4j integration
│ └── vector-store.ts # Vector embeddings store
├── operators/ # Graph RAG operators
│ ├── base-operator.ts # Base operator class
│ ├── node-operators.ts # VDB, PPR operators
│ ├── relationship-operators.ts # OneHop, Aggregator
│ ├── chunk-operators.ts # FromRel, Occurrence
│ └── subgraph-operators.ts # KHopPath, Steiner
├── execution/ # Execution engine
│ └── operator-executor.ts # Orchestration logic
├── planning/ # Query planning
│ └── query-planner.ts # Intelligent planning
├── utils/ # Utilities
│ ├── embedding-generator.ts # Text embeddings
│ └── graph-builders.ts # Graph construction
├── types/ # Type definitions
│ └── graph.ts # Core types
├── mcp-server.ts # MCP server implementation
└── index.ts # Entry point
`

$3

1. Query Input → Query Planner analyzes intent and complexity
2. Plan Creation → Intelligent operator chain generation
3. Execution → Operator orchestration with chosen pattern
4. Result Fusion → Combine results using fusion strategy
5. Response → Structured output with metadata

🔍 MCP Tools Reference

$3

- create_query_plan: Generate intelligent execution plans
- execute_query_plan: Execute pre-created plans
- execute_operator_chain: Run custom operator chains

$3

- vdb_search: Vector similarity search
- pagerank_analysis: Authority analysis
- neighborhood_exploration: Direct relationship exploration
- relationship_aggregation: Multi-relationship synthesis
- chunk_tracing: Source chunk identification
- co_occurrence_analysis: Entity co-occurrence patterns
- path_finding: Multi-hop path discovery
- steiner_tree: Minimal connecting networks

$3

- create_knowledge_graph: Build new graph structures
- add_nodes: Insert nodes into graphs
- add_relationships: Create relationships
- add_chunks: Add text chunks to vector store

$3

- graph_analytics: Comprehensive graph statistics
- operator_performance: Performance metrics
- adaptive_reasoning: Complex reasoning capabilities
- multi_modal_fusion: Cross-graph analysis

🔗 MCP Resources

- graph://knowledge-graph: Access to graph structure
- graph://vector-store: Vector embeddings information
- graph://operator-registry: Available operators
- graph://execution-history: Performance history

🧪 Testing

`bash


Run tests

npm test

Run with coverage

npm run test:coverage

Lint code

npm run lint

Format code

npm run format
`

📊 Performance

$3

- Vector Search: Sub-100ms for 10K embeddings
- PageRank: Converges in <50 iterations for most graphs
- Path Finding: Handles graphs with 100K+ nodes
- Parallel Execution: 3-5x speedup over sequential

$3

- Intelligent Caching: Query plan and result caching
- Batch Processing: Efficient bulk operations
- Adaptive Thresholds: Dynamic parameter adjustment
- Resource Management: Memory and CPU optimization

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

- Documentation: See /docs` directory
- Issues: GitHub Issues
- Discussions: GitHub Discussions

🔮 Roadmap

- [ ] Real-time graph updates
- [ ] Distributed execution
- [ ] Advanced ML integration
- [ ] Custom operator development SDK
- [ ] Graph visualization tools
- [ ] Performance dashboard

---

Built with ❤️ for the AI agent ecosystem. Empowering intelligent systems with sophisticated graph-based reasoning capabilities.