Skip to main content
Glama
Chukwuebuka-2003

AI Tutoring RAG System

by Chukwuebuka-2003
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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:

  • MCP Host API Docs: http://localhost:8000/docs

  • RAG MCP Server: http://localhost:9000/

🧪 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?

Resources

Latest Blog Posts

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