SOLVRO MCP - Knowledge Graph RAG System
A production-ready Model Context Protocol (MCP) server implementing a Retrieval-Augmented Generation (RAG) system with Neo4j graph database backend. The system intelligently converts natural language queries into Cypher queries, retrieves relevant information from a knowledge graph, and provides contextual answers about Wroclaw University of Science and Technology.
Table of Contents
- Architecture Overview
- Features
- Prerequisites
- Installation
- Configuration
- Usage
- Project Structure
- Development
- API Reference
- Observability
- Contributing
Architecture Overview
The system consists of three main components:
- MCP Server - FastMCP-based server exposing knowledge graph tools
- MCP Client - CLI interface for querying the knowledge graph
- Data Pipeline - Multi-threaded ETL pipeline for loading documents into Neo4j
Data Flow
User Query → MCP Client → MCP Server → RAG System → Neo4j Graph DB
↓
Langfuse Observability
↓
LLM Processing → Response
Key Technologies
- FastMCP: Model Context Protocol server implementation
- LangChain: LLM orchestration and chaining
- LangGraph: State machine for RAG pipeline
- Neo4j: Graph database for knowledge storage
- Langfuse: Observability and tracing
- OpenAI/DeepSeek: LLM providers for query generation and answering
Features
Intelligent Query Routing
- Guardrails System: Automatically determines if queries are relevant to the knowledge base
- Fallback Mechanism: Returns graceful responses for out-of-scope queries
- Session Tracking: Full trace tracking across the entire query lifecycle
Advanced RAG Pipeline
- Multi-Stage Processing: Guardrails → Cypher Generation → Retrieval → Response
- State Machine Architecture: Built with LangGraph for predictable execution flow
- Error Handling: Robust error recovery with fallback strategies
- Caching: Schema caching for improved performance
Dual LLM Strategy
- Fast LLM (gpt-5-nano): Quick decision-making for guardrails
- Accurate LLM (gpt-5-mini): Precise Cypher query generation
Observability
- Langfuse Integration: Complete trace and session tracking
- Mermaid Visualization: Graph flow visualization for debugging
- Structured Logging: Comprehensive logging throughout the pipeline
Data Pipeline
- Multi-threaded Processing: Configurable thread pool for parallel document processing
- PDF Support: Extract and process PDF documents
- Dynamic Graph Schema: Configurable nodes and relationships via yaml
- Database Management: Built-in database clearing and initialization
Data Pipeline Diagram
- Diagram: Displays the pipeline flow for document ingestion and processing. See the image below:
Prerequisites
- Python 3.12 or higher
- Neo4j database instance (local or cloud)
- OpenAI API key or DeepSeek API key
- Langfuse account (for observability)
uvpackage manager (recommended) orpip
Installation
1. Clone the Repository
git clone <repository-url>
cd SOLVRO_MCP
2. Install Dependencies
Using uv (recommended):
uv sync
Using pip:
pip install -e .
Quick Setup (installs dependencies and generates models):
just setup
3. Generate Configuration Models
Generate Pydantic models from graph_config.yaml for type-safe configuration access:
just generate-models
# OR
uv run python src/scripts/config/generate_models.py
This creates src/config/config_models.py with auto-generated type definitions. Re-run this command whenever you modify graph_config.yaml.
4. Set Up Neo4j
Option A: Docker Compose
cd db
docker-compose up -d
Option B: Neo4j Desktop or Aura
Follow Neo4j's installation guide for your platform.
5. Configure Environment Variables
Create a .env file in the project root:
# LLM Provider (choose one)
OPENAI_API_KEY=your_openai_api_key
# OR
DEEPSEEK_API_KEY=your_deepseek_api_key
# CLARIN Polish LLM (optional, for Polish language support)
CLARIN_API_KEY=your_clarin_api_key
# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password
# Langfuse Observability
LANGFUSE_SECRET_KEY=your_langfuse_secret_key
LANGFUSE_PUBLIC_KEY=your_langfuse_public_key
LANGFUSE_HOST=https://cloud.langfuse.com
Configuration
Centralized Configuration (graph_config.yaml)
All application settings are centralized in graph_config.yaml, including:
- Server Configuration: MCP server and ToPWR API ports, hosts, and transport
- LLM Models: Model names and temperatures for fast and accurate operations
- RAG Settings: Max results, debug mode
- Data Pipeline: Chunk sizes, overlaps, token limits
- Neo4j Database: Connection settings (with environment variable support)
- Observability: Langfuse configuration
- Graph Schema: Node types and relationship types
- Prompts: All prompt templates used throughout the system
Example Configuration
servers:
mcp:
transport: "http"
port: 8005
host: "127.0.0.1"
topwr_api:
host: "0.0.0.0"
port: 8000
cors_origins: "*"
llm:
fast_model:
name: "gpt-5-nano"
temperature: 0.1
accurate_model:
name: "gpt-5-mini"
temperature: 0
rag:
max_results: 5
enable_debug: false
data_pipeline:
max_chunk_size: 30000
chunk_overlap: 200
token_limit: 65536
nodes:
- Document
- Article
- Student
- Course
# ... more node types
relations:
- teaches
- enrolls_in
- attends
# ... more relationship types
prompts:
final_answer: |
Otrzymujesz informacje w postaci JSON...
cypher_search: |
Generate ONLY valid Cypher query...
guardrails: |
Is this about university...
Using Configuration in Code
The configuration is accessed via the config module:
from src.config.config import get_config
# Get configuration instance
config = get_config()
# Access configuration values with full autocomplete
model_name = config.llm.fast_model.name
max_results = config.rag.max_results
server_port = config.servers.mcp.port
# Access nodes and relations
nodes = config.nodes # List of all node types
relations = config.relations # List of all relationship types
# Format prompts with variables
prompt = config.prompts.final_answer.format(
user_input="What is AI?",
data="Artificial Intelligence..."
)
Environment Variables
Sensitive credentials are still managed via environment variables (.env file):
neo4j:
uri: ${NEO4J_URI}
username: ${NEO4J_USER}
password: ${NEO4J_PASSWORD}
Usage
Running the MCP Server
Start the FastMCP server on port 8005:
just mcp-server
# OR
uv run server
The server will initialize the RAG system and expose the knowledge_graph_tool.
Querying via CLI Client
Query the knowledge graph using natural language:
just mcp-client "Czym jest nagroda dziekana?"
# OR
uv run kg "What is the dean's award?"
Example queries:
# Polish queries
uv run kg "Jakie są wymagania dla stypendium rektora?"
uv run kg "Kiedy są terminy egzaminów?"
# English queries
uv run kg "What are the scholarship requirements?"
uv run kg "When are the exam dates?"
Data Pipeline
Load Documents into Neo4j
just pipeline
# OR
uv run pipeline
Clear Database and Reload
just pipeline-clear
# OR
uv run pipeline --clear-db
Manual Pipeline Execution
uv run python src/scripts/data_pipeline/main.py \
data/ \
graph_config.yaml \
4 \
--clear-db
Parameters:
data/- Input directory containing PDF filesgraph_config.yaml- Graph schema configuration (YAML format)4- Number of parallel threads--clear-db- (Optional) Clear database before loading
Project Structure
SOLVRO_MCP/
├── src/
│ ├── mcp_server/ # MCP server implementation
│ │ ├── server.py # FastMCP server entry point
│ │ └── tools/
│ │ └── knowledge_graph/
│ │ ├── rag.py # RAG system core logic
│ │ ├── state.py # LangGraph state definitions
│ │ └── graph_visualizer.py # Mermaid visualization
│ │
│ ├── mcp_client/ # CLI client
│ │ └── client.py # Client implementation with Langfuse integration
│ │
│ ├── config/ # Configuration management
│ │ ├── config.py # Configuration loader (singleton)
│ │ └── config_models.py # Auto-generated Pydantic models
│ │
│ └── scripts/
│ ├── config/
│ │ └── generate_models.py # Config model generator
│ └── data_pipeline/ # ETL pipeline
│ ├── main.py # Pipeline orchestrator
│ ├── data_pipe.py # Data processing logic
│ ├── llm_pipe.py # LLM-based entity extraction
│ └── pdf_loader.py # PDF document loader
│
├── db/
│ └── docker-compose.yaml # Neo4j container configuration
│
├── data/ # Input documents directory
├── graph_config.yaml # Centralized configuration file
├── pyproject.toml # Project dependencies and metadata
├── justfile # Task runner configuration
└── README.md # This file
Development
Code Quality
The project uses Ruff for linting and formatting:
just lint
# OR
uv run ruff format src
uv run ruff check src
Configuration Management
Regenerating Configuration Models:
When you modify graph_config.yaml, regenerate the Pydantic models for type safety:
just generate-models
# OR
uv run python src/scripts/config/generate_models.py
This creates src/config/config_models.py with auto-generated type definitions and enables full IDE autocomplete.
Configuration Structure (in pyproject.toml):
Ruff Settings (in pyproject.toml):
- Line length: 100 characters
- Target: Python 3.13
- Selected rules: E, F, I, N, W
Configuration Models:
When you modify graph_config.yaml, regenerate the Pydantic models:
just generate-models
This ensures type safety and IDE autocomplete for configuration access.
Adding New Tools
To add a new MCP tool:
- Create a new function in
src/mcp_server/server.py - Decorate with
@mcp.tool - Add documentation and type hints
- Update the README
Example:
@mcp.tool
async def new_tool(param: str) -> str:
"""
Tool description.
Args:
param: Parameter description
Returns:
Result description
"""
# Implementation
return result
API Reference
MCP Server
knowledge_graph_tool
Query the knowledge graph with natural language.
Parameters:
user_input(str): User's question or querytrace_id(str, optional): Trace ID for observability
Returns:
str: JSON string containing retrieved context or "W bazie danych nie ma informacji"
Example:
result = await client.call_tool(
"knowledge_graph_tool",
{
"user_input": "What are the scholarship requirements?",
"trace_id": "unique-trace-id"
}
)
RAG System
RAG.ainvoke()
Async method to query the RAG system.
Parameters:
message(str): User's questionsession_id(str): Session identifier (default: "default")trace_id(str): Trace identifier (default: "default")callback_handler(CallbackHandler): Langfuse callback handler
Returns:
Dict[str, Any]: Dictionary containing:answer(str): JSON context or "W bazie danych nie ma informacji"metadata(dict):guardrail_decision(str): Routing decisioncypher_query(str): Generated Cypher querycontext(list): Retrieved data from Neo4j
Data Pipeline
DataPipe.load_data_from_directory()
Load and process PDF documents from a directory.
Parameters:
directory(str): Path to directory containing PDF files
Returns:
- None (processes documents in-place)
Observability
Langfuse Integration
The system provides comprehensive observability through Langfuse:
- Session Tracking: All queries within a session are grouped together
- Trace Hierarchy: Multi-level traces showing:
- Guardrails decision
- Cypher generation
- Neo4j retrieval
- Final answer generation
- Metadata Tagging: Traces tagged with component identifiers
- Performance Metrics: Latency and token usage tracking
Viewing Traces
- Log in to your Langfuse dashboard
- Navigate to "Sessions" to see grouped queries
- Click on individual traces for detailed execution flow
- Use filters to search by tags:
mcp_client,knowledge_graph,guardrails, etc.
Graph Visualization
The RAG system includes Mermaid graph visualization:
print(rag.visualizer.draw_mermaid())
This outputs a Mermaid diagram showing the state machine flow.
Error Handling
Common Issues
1. Connection Refused (Neo4j)
Error: Could not connect to Neo4j at bolt://localhost:7687
Solution: Ensure Neo4j is running:
cd db && docker-compose up -d
2. API Key Issues
Error: Missing required environment variables
Solution: Check your .env file contains all required keys.
3. Import Errors
ImportError: cannot import name 'langfuse_context'
Solution: This import is not available in standard Langfuse. Use session tracking through function parameters.
Performance Tuning
Thread Configuration
Adjust parallel processing threads in the pipeline:
uv run python src/scripts/data_pipeline/main.py data/ graph_config.yaml 8
Recommended thread counts:
- CPU-bound: Number of CPU cores
- I/O-bound: 2-4x CPU cores
Neo4j Optimization
- Indexing: Create indexes on frequently queried properties
- LIMIT Clauses: Pipeline automatically adds LIMIT to queries
- Connection Pooling: FastMCP handles connection management
LLM Configuration
LLM settings are configured in graph_config.yaml:
llm:
fast_model:
name: "gpt-5-nano" # Quick decisions (guardrails)
temperature: 0.1 # Slightly creative
accurate_model:
name: "gpt-5-mini" # Precise Cypher generation
temperature: 0 # Fully deterministic
To use different models or adjust parameters, edit the YAML file - no code changes needed.
AI Coding Guidelines
For AI coding assistants and developers, see .github/agents.md for detailed coding guidelines and patterns.
ToPWR Integration API
The project now includes a FastAPI service for integrating with the ToPWR application. This provides:
- RESTful API endpoints for chat functionality
- Conversation state management with memory
- User tracking and session management
- Thread-safe in-memory storage (database integration pending)
Running the ToPWR API
# Start the API server
just topwr-api
# OR
uv run topwr-api
The API will be available at http://localhost:8000
API Endpoints
POST /api/chat- Send a message and get AI responseGET /api/sessions/{session_id}- Get session informationGET /api/sessions/{session_id}/history- Get conversation historyGET /api/users/{user_id}/sessions- Get all user sessionsGET /api/stats- Get system statisticsGET /health- Health check
Example API Usage
# Start a new conversation
curl -X POST http://localhost:8000/api/chat \
-H "Content-Type: application/json" \
-d '{
"user_id": "user123",
"message": "Czym jest nagroda dziekana?"
}'
# Continue conversation with session_id
curl -X POST http://localhost:8000/api/chat \
-H "Content-Type: application/json" \
-d '{
"user_id": "user123",
"session_id": "abc123...",
"message": "A jakie są wymagania?"
}'
For complete API documentation, see src/topwr_api/README.md
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/new-feature - Make changes and ensure tests pass
- Run linting:
just lint - Commit changes:
git commit -m "Add new feature" - Push to branch:
git push origin feature/new-feature - Open a Pull Request
License
[Add your license here]
Acknowledgments
- Built for Wroclaw University of Science and Technology
- Powered by FastMCP, LangChain, and Neo4j
- Observability by Langfuse
Support
For issues and questions:
- Open an issue on GitHub
- Contact the development team
- Check the documentation at [link]