zrald/README.md

Advanced Graph RAG MCP Server with sophisticated graph structures, operators, and agentic capabilities for AI agents

# Graph RAG MCP Server

[![npm version](https://badge.fury.io/js/zrald.svg)](https://badge.fury.io/js/zrald)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

### Core Graph Structures
- **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

### Operator Ecosystem

#### 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

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

### Advanced Capabilities
- **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
```

### Development Installation

```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!');
```

### Using as a CLI

```bash
# Start the server directly
graph-rag-mcp-server

# Or with custom configuration
NEO4J_URI=bolt://localhost:7687 graph-rag-mcp-server
```

## 🔧 Configuration

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

### Environment Variables
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

### Basic Query Planning
```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);
```

### Individual Operators
```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
});
```

### Graph Management
```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
    }
  ]
});
```

### Advanced Features
```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

### Core Components
```
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
```

### Data Flow
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

### Query Planning & Execution
- `create_query_plan`: Generate intelligent execution plans
- `execute_query_plan`: Execute pre-created plans
- `execute_operator_chain`: Run custom operator chains

### Individual Operators
- `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

### Graph Management
- `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

### Analytics & Insights
- `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

### Benchmarks
- **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

### Optimization Features
- **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.