SOLVRO MCP - Knowledge Graph RAG System

# 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](#architecture-overview) - [Features](#features) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Configuration](#configuration) - [Usage](#usage) - [Project Structure](#project-structure) - [Development](#development) - [API Reference](#api-reference) - [Observability](#observability) - [Contributing](#contributing) ## Architecture Overview The system consists of three main components: 1. **MCP Server** - FastMCP-based server exposing knowledge graph tools 2. **MCP Client** - CLI interface for querying the knowledge graph 3. **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 JSON - **Database Management**: Built-in database clearing and initialization ## Prerequisites - Python 3.12 or higher - Neo4j database instance (local or cloud) - OpenAI API key or DeepSeek API key - Langfuse account (for observability) - `uv` package manager (recommended) or `pip` ## Installation ### 1. Clone the Repository ```bash git clone <repository-url> cd SOLVRO_MCP ``` ### 2. Install Dependencies Using `uv` (recommended): ```bash uv sync ``` Using `pip`: ```bash pip install -e . ``` ### 3. Set Up Neo4j **Option A: Docker Compose** ```bash cd db docker-compose up -d ``` **Option B: Neo4j Desktop or Aura** Follow Neo4j's installation guide for your platform. ### 4. Configure Environment Variables Create a `.env` file in the project root: ```env # 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 ### Graph Schema Configuration Edit `graph_config.json` to define your knowledge graph structure: ```json { "nodes": [ { "name": "Student", "properties": ["name", "id", "year"] }, { "name": "Course", "properties": ["title", "code", "credits"] } ], "relationships": [ { "type": "ENROLLED_IN", "source": "Student", "target": "Course", "properties": ["semester", "grade"] } ] } ``` ## Usage ### Running the MCP Server Start the FastMCP server on port 8005: ```bash 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: ```bash just mcp-client "Czym jest nagroda dziekana?" # OR uv run kg "What is the dean's award?" ``` Example queries: ```bash # 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 ```bash just pipeline # OR uv run pipeline ``` #### Clear Database and Reload ```bash just pipeline-clear # OR uv run pipeline --clear-db ``` #### Manual Pipeline Execution ```bash uv run python src/scripts/data_pipeline/main.py \ data/ \ graph_config.json \ 4 \ --clear-db ``` Parameters: - `data/` - Input directory containing PDF files - `graph_config.json` - Graph schema configuration - `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 │ │ │ └── scripts/ │ └── 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.json # Graph schema definition ├── 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: ```bash just lint # OR uv run ruff format src uv run ruff check src ``` ### Configuration **Ruff Settings** (in `pyproject.toml`): - Line length: 100 characters - Target: Python 3.13 - Selected rules: E, F, I, N, W ### Adding New Tools To add a new MCP tool: 1. Create a new function in `src/mcp_server/server.py` 2. Decorate with `@mcp.tool` 3. Add documentation and type hints 4. Update the README Example: ```python @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 query - `trace_id` (str, optional): Trace ID for observability **Returns:** - `str`: JSON string containing retrieved context or "W bazie danych nie ma informacji" **Example:** ```python 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 question - `session_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 decision - `cypher_query` (str): Generated Cypher query - `context` (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: 1. **Session Tracking**: All queries within a session are grouped together 2. **Trace Hierarchy**: Multi-level traces showing: - Guardrails decision - Cypher generation - Neo4j retrieval - Final answer generation 3. **Metadata Tagging**: Traces tagged with component identifiers 4. **Performance Metrics**: Latency and token usage tracking ### Viewing Traces 1. Log in to your Langfuse dashboard 2. Navigate to "Sessions" to see grouped queries 3. Click on individual traces for detailed execution flow 4. Use filters to search by tags: `mcp_client`, `knowledge_graph`, `guardrails`, etc. ### Graph Visualization The RAG system includes Mermaid graph visualization: ```python 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: ```bash 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: ```bash uv run python src/scripts/data_pipeline/main.py data/ graph_config.json 8 ``` Recommended thread counts: - CPU-bound: Number of CPU cores - I/O-bound: 2-4x CPU cores ### Neo4j Optimization 1. **Indexing**: Create indexes on frequently queried properties 2. **LIMIT Clauses**: Pipeline automatically adds LIMIT to queries 3. **Connection Pooling**: FastMCP handles connection management ### LLM Configuration Adjust model parameters in `rag.py`: ```python self.fast_llm = BaseChatOpenAI( model="gpt-5-nano", temperature=0.1, # Lower = more deterministic ) ``` ## AI Coding Guidelines For AI coding assistants and developers, see [.github/agents.md](.github/agents.md) for detailed coding guidelines and patterns. 1. Fork the repository 2. Create a feature branch: `git checkout -b feature/new-feature` 3. Follow the coding guidelines in `.github/agents.md` 4. Make changes and ensure tests pass 5. Run linting: `just lint` 6. Commit changes: `git commit -m "feat: Add new feature"` 7. Push to branch: `git push origin feature/new-feature` 8. Open a Pull Request // ...existing code... ## Contributing 1. Fork the repository 2. Create a feature branch: `git checkout -b feature/new-feature` 3. Make changes and ensure tests pass 4. Run linting: `just lint` 5. Commit changes: `git commit -m "Add new feature"` 6. Push to branch: `git push origin feature/new-feature` 7. 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]