Skip to main content
Glama

AI Tutoring RAG System

by Chukwuebuka-2003
GitHub
Python
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

ai-tutor

AI Tutoring RAG System - Setup & Testing Guide

📋 Table of Contents

🎯 Overview

This is an AI-powered tutoring system that uses RAG (Retrieval-Augmented Generation) to provide personalized learning experiences. The system consists of two main components:

  1. RAG MCP Server (Port 9000) - Provides RAG tools via MCP protocol

  2. MCP Host (Port 8000) - Agent orchestration layer with FastAPI

Key Features:

  • Personalized knowledge base for each student

  • PDF and DOCX file processing and indexing

  • Semantic search across student's learning materials

  • Intent analysis and risk detection

  • Azure Blob Storage integration

  • OpenAI GPT-4 powered responses

🔧 Prerequisites

Before you begin, ensure you have the following installed:

Install uv

# On macOS and Linux curl -LsSf https://astral.sh/uv/install.sh | sh # On Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Verify installation uv --version

Required API Keys

You'll need accounts and API keys for:

💿 Installation

1. Create Virtual Environment

# Create a virtual environment using uv uv venv # Activate the virtual environment # On macOS/Linux: source .venv/bin/activate # On Windows: .venv\Scripts\activate

2. Install Dependencies

# Install all dependencies using uv uv pip install -r pyproject.toml # Or install directly from pyproject.toml uv pip install -e .

⚙️ Configuration

1. Create Environment File

Create a .env file in the project root:

cp .env.example .env

2. Configure Environment Variables

Edit .env and add your credentials:

# OpenAI Configuration OPENAI_API_KEY=sk-your-openai-api-key-here # Pinecone Configuration PINECONE_API_KEY=your-pinecone-api-key-here PINECONE_ENVIRONMENT=us-east-1 # Azure Storage Configuration AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...

3. Generate Authentication Token

Generate a JWT token for MCP server authentication:

python get_auth_token.py

Copy the generated token and update it in mcp_host/app.py:

MCP_TOOLS = [ { "name": "turtor_rag", "transport_type": "streamable_http", "url": "http://0.0.0.0:9000/mcp", "headers": { "Authorization": "Bearer YOUR_GENERATED_TOKEN_HERE" }, } ]

🚀 Running the Services

You need to run both services in separate terminal windows.

Terminal 1: Start RAG MCP Server

# Activate virtual environment source .venv/bin/activate # or .venv\Scripts\activate on Windows # Run the RAG MCP server python rag_mcp_server.py

Expected Output:

INFO: Started server process INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:9000

Terminal 2: Start MCP Host

# Activate virtual environment (in new terminal) source .venv/bin/activate # or .venv\Scripts\activate on Windows # Run the MCP host python -m uvicorn mcp_host.app:app --host 0.0.0.0 --port 8000 --reload

Expected Output:

INFO: Will watch for changes in these directories: ['/path/to/ed_mcp'] INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) INFO: Started reloader process INFO: Started server process INFO: Waiting for application startup. Initializing TutoringRagAgent server... TutoringRagAgent server initialized successfully INFO: Application startup complete.

Verify Services are Running

Open your browser and check:

🧪 Testing the System

Test 1: Create Sample PDF

First, create a sample PDF for testing:

python create_sample_pdf.py

This creates sample.pdf with calculus study content.

Test 2: Upload a File

Use curl to upload a file:

curl -X POST "http://localhost:8000/upload-student-file" \ -F "file=@sample.pdf" \ -F "student_id=test_student_001" \ -F "subject=Mathematics" \ -F "topic=Calculus" \ -F "difficulty_level=7"

Expected Response:

{ "status": "success", "message": "Your file has been received and is being processed. You'll be able to interact with its content shortly!" }

Test 3: Chat with the Tutor

Send a chat message to query the uploaded content:

curl -X POST "http://localhost:8000/chats/tutor-rag-agent" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "What did I learn about derivatives?" } ], "session_id": "test_session_001" }'

Expected Response: The system should retrieve relevant content from the uploaded PDF and provide a personalized response about derivatives.

Test 4: Query Knowledge Base Directly

Test the RAG retrieval directly:

curl -X POST "http://localhost:9000/mcp" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "knowledge_base_retrieval", "arguments": { "user_id": "test_student_001", "query": "What is the chain rule?", "subject": "Mathematics", "topic": "Calculus", "top_k": 3 } }, "id": 1 }'

Test 5: View Session History

Get the conversation history:

curl -X GET "http://localhost:8000/session/test_session_001/history"

Test 6: Run Complete Test Workflow

Run the automated test suite:

# Make sure both servers are running first! python test_workflow.py

This will:

  1. Upload a file to Azure

  2. Process and index the file

  3. Query the indexed content

  4. List uploaded files

Test 7: Test File Processing

Test PDF and DOCX processing:

python test_file_processor.py

📡 API Endpoints

MCP Host (Port 8000)

POST /chats/tutor-rag-agent

Start a chat session with the AI tutor.

Request:

{ "messages": [ { "role": "user", "content": "Explain quadratic equations" } ], "session_id": "session_123" }

Response: Streaming text response

POST /upload-student-file

Upload a PDF or DOCX file for processing.

Form Data:

  • file: The file to upload

  • student_id: Student identifier

  • subject: Subject category

  • topic: Specific topic

  • difficulty_level: 1-10

GET /session/{session_id}/history

Get conversation history for a session.

DELETE /session/{session_id}/memory

Clear memory for a specific session.

GET /agent/info

Get information about the agent configuration.

RAG MCP Server (Port 9000)

POST /mcp

MCP protocol endpoint for tool calls.

Available Tools:

  • knowledge_base_retrieval - Search user's knowledge base

  • upload_student_file - Process and index uploaded files

🔍 Testing with Python

Interactive Testing

Create a Python script test_interactive.py:

import requests import json # Base URLs MCP_HOST = "http://localhost:8000" RAG_SERVER = "http://localhost:9000" # Test chat def test_chat(message, session_id="test_001"): response = requests.post( f"{MCP_HOST}/chats/tutor-rag-agent", json={ "messages": [{"role": "user", "content": message}], "session_id": session_id }, stream=True ) print("Response:") for line in response.iter_lines(): if line: print(line.decode('utf-8')) # Test file upload def test_upload(file_path, student_id, subject, topic): with open(file_path, 'rb') as f: files = {'file': f} data = { 'student_id': student_id, 'subject': subject, 'topic': topic, 'difficulty_level': 5 } response = requests.post( f"{MCP_HOST}/upload-student-file", files=files, data=data ) print(json.dumps(response.json(), indent=2)) # Run tests if __name__ == "__main__": print("Testing file upload...") test_upload("sample.pdf", "student_123", "Mathematics", "Calculus") print("\nTesting chat...") test_chat("What did I learn about calculus?")

Run it:

python test_interactive.py

🐛 Troubleshooting

Port Already in Use

Error: Address already in use

Solution:

# Find and kill the process using the port # On macOS/Linux: lsof -ti:8000 | xargs kill -9 lsof -ti:9000 | xargs kill -9 # On Windows: netstat -ano | findstr :8000 taskkill /PID <PID> /F

Pinecone Connection Error

Error: Failed to connect to Pinecone

Solutions:

  • Verify your PINECONE_API_KEY is correct

  • Check your Pinecone index exists

  • Ensure PINECONE_ENVIRONMENT matches your Pinecone region

OpenAI API Error

Error: Incorrect API key provided

Solutions:

  • Verify your OPENAI_API_KEY is correct

  • Check you have credits in your OpenAI account

  • Ensure the key has the required permissions

Azure Storage Error

Error: Azure Storage connection failed

Solutions:

  • Verify your AZURE_STORAGE_CONNECTION_STRING is correct

  • Check the storage account exists and is accessible

  • Ensure the container name matches in azure_storage.py

MCP Authentication Error

Error: Unauthorized: token verification failed

Solutions:

  1. Generate a new token: python get_auth_token.py

  2. Update the token in mcp_host/app.py

  3. Restart both servers

Dependencies Not Found

Error: ModuleNotFoundError: No module named 'X'

Solution:

# Reinstall dependencies uv pip install -r pyproject.toml --force-reinstall # Or install specific package uv pip install <package-name>

File Processing Fails

Error: Failed to extract text from PDF

Solutions:

  • Ensure PDF is not password-protected

  • Check file is not corrupted

  • Verify PyMuPDF is installed: uv pip install pymupdf

📊 Monitoring and Logs

View Detailed Logs

Both servers print detailed logs. To save logs:

# RAG MCP Server python rag_mcp_server.py > rag_server.log 2>&1 # MCP Host python -m uvicorn mcp_host.app:app --host 0.0.0.0 --port 8000 > mcp_host.log 2>&1

Check System Health

# Check MCP Host curl http://localhost:8000/agent/info # Check if services respond curl -I http://localhost:8000/docs curl -I http://localhost:9000/

🎓 Example Workflows

Workflow 1: Complete Student Onboarding

# 1. Create sample study materials python create_sample_pdf.py # 2. Upload student's notes curl -X POST "http://localhost:8000/upload-student-file" \ -F "file=@sample.pdf" \ -F "student_id=student_123" \ -F "subject=Mathematics" \ -F "topic=Calculus" \ -F "difficulty_level=7" # 3. Wait a few seconds for processing sleep 5 # 4. Start tutoring session curl -X POST "http://localhost:8000/chats/tutor-rag-agent" \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role": "user", "content": "Help me understand derivatives"}], "session_id": "session_123" }'

Workflow 2: Multi-Subject Learning

# Upload multiple files for different subjects curl -X POST "http://localhost:8000/upload-student-file" \ -F "file=@math_notes.pdf" \ -F "student_id=student_123" \ -F "subject=Mathematics" \ -F "topic=Algebra" \ -F "difficulty_level=6" curl -X POST "http://localhost:8000/upload-student-file" \ -F "file=@history_notes.pdf" \ -F "student_id=student_123" \ -F "subject=History" \ -F "topic=World War II" \ -F "difficulty_level=5" # Query across subjects curl -X POST "http://localhost:8000/chats/tutor-rag-agent" \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role": "user", "content": "What have I been studying?"}], "session_id": "session_123" }'

📚 Additional Resources

🤝 Support

If you encounter issues:

  1. Check the Troubleshooting section

  2. Review logs from both servers

  3. Ensure all environment variables are set correctly

  4. Verify all prerequisites are installed

📝 Notes

  • The system uses JWT authentication between services

  • Files are stored in Azure Blob Storage and indexed in Pinecone

  • Each student has an isolated knowledge base

  • Sessions maintain conversation history

  • The agent autonomously decides when to use RAG tools

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables personalized AI tutoring by allowing students to upload PDF/DOCX study materials that are processed and indexed for semantic search. Provides intelligent responses based on the student's own learning materials using RAG technology.

  1. AI Tutoring RAG System - Setup & Testing Guide
    1. 📋 Table of Contents
    2. 🎯 Overview
    3. 🔧 Prerequisites
    4. 💿 Installation
    5. ⚙️ Configuration
    6. 🚀 Running the Services
    7. 🧪 Testing the System
    8. 📡 API Endpoints
    9. 🔍 Testing with Python
    10. 🐛 Troubleshooting
    11. 📊 Monitoring and Logs
    12. 🎓 Example Workflows
    13. 📚 Additional Resources
    14. 🤝 Support
    15. 📝 Notes

New MCP Servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Chukwuebuka-2003/ebuka_mcps'

If you have feedback or need assistance with the MCP directory API, please join our Discord server