AI Tutoring RAG System

{ "info": { "name": "Ebuka MCP Heroku Deployment", "description": "Test collection for MCP Host and RAG Server deployed on Heroku\n\n🤖 **AI-Powered Subject Detection:**\nThe system now automatically detects academic subjects from:\n- Chat interactions (user questions + AI responses)\n- Uploaded documents (PDF/DOCX content)\n\nSupported subjects: Mathematics, Physics, Chemistry, Biology, Computer Science, English, History, Geography, Economics, Psychology, Philosophy, Art, Music, Engineering, Business, and General.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "variable": [ { "key": "mcp_host_url", "value": "https://ebuka-mcp-host-2699dda7effc.herokuapp.com", "type": "string" }, { "key": "rag_server_url", "value": "https://ebuka-rag-mcp-server-24bf42af15c0.herokuapp.com", "type": "string" }, { "key": "access_token", "value": "", "type": "string" }, { "key": "user_id", "value": "", "type": "string" }, { "key": "chat_session_id", "value": "", "type": "string" } ], "item": [ { "name": "1. Health Checks", "item": [ { "name": "MCP Host - Health Check", "request": { "method": "GET", "header": [], "url": { "raw": "{{mcp_host_url}}/", "host": ["{{mcp_host_url}}"], "path": [""] } }, "response": [] }, { "name": "MCP Host - Health Endpoint", "request": { "method": "GET", "header": [], "url": { "raw": "{{mcp_host_url}}/health", "host": ["{{mcp_host_url}}"], "path": ["health"] } }, "response": [] }, { "name": "RAG Server - Health Check", "request": { "method": "GET", "header": [], "url": { "raw": "{{rag_server_url}}/", "host": ["{{rag_server_url}}"], "path": [""] } }, "response": [] } ] }, { "name": "2. Authentication", "item": [ { "name": "Sign Up", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200 || pm.response.code === 201) {", " var jsonData = pm.response.json();", " pm.collectionVariables.set(\"access_token\", jsonData.access_token);", " if (jsonData.user && jsonData.user.id) {", " pm.collectionVariables.set(\"user_id\", jsonData.user.id);", " }", " pm.environment.set(\"access_token\", jsonData.access_token);", " console.log(\"Token saved:\", jsonData.access_token);", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Test User\",\n \"email\": \"test@example.com\",\n \"phone_number\": \"+1234567890\",\n \"password\": \"Test123!@#\"\n}" }, "url": { "raw": "{{mcp_host_url}}/auth/signup", "host": ["{{mcp_host_url}}"], "path": ["auth", "signup"] } }, "response": [] }, { "name": "Login", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " pm.collectionVariables.set(\"access_token\", jsonData.access_token);", " pm.environment.set(\"access_token\", jsonData.access_token);", " console.log(\"Token saved:\", jsonData.access_token);", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/x-www-form-urlencoded" } ], "body": { "mode": "urlencoded", "urlencoded": [ { "key": "email", "value": "test@example.com", "type": "text" }, { "key": "password", "value": "Test123!@#", "type": "text" } ] }, "url": { "raw": "{{mcp_host_url}}/auth/token", "host": ["{{mcp_host_url}}"], "path": ["auth", "token"] } }, "response": [] }, { "name": "Get Current User", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/auth/me", "host": ["{{mcp_host_url}}"], "path": ["auth", "me"] } }, "response": [] } ] }, { "name": "3. Chat/Tutoring", "item": [ { "name": "Start Chat Session", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.chat_session_id) {", " pm.collectionVariables.set(\"chat_session_id\", jsonData.chat_session_id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"chat_session_id\": \"test-session-{{$timestamp}}\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Can you help me understand calculus derivatives?\"\n }\n ]\n}" }, "url": { "raw": "{{mcp_host_url}}/chats/tutor-rag-agent", "host": ["{{mcp_host_url}}"], "path": ["chats", "tutor-rag-agent"] }, "description": "Start a chat session with the AI tutor. The subject will be automatically detected from your question using AI.\n\n**Example questions and detected subjects:**\n- \"Explain Newton's laws\" → Physics\n- \"How do I implement a binary search?\" → Computer Science\n- \"What caused World War II?\" → History\n- \"Explain photosynthesis\" → Biology\n\nThe AI analyzes both your question and the tutor's response to accurately classify the subject." }, "response": [] }, { "name": "Test AI Subject Detection - Math", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"chat_session_id\": \"ai-test-math-{{$timestamp}}\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do I solve quadratic equations using the quadratic formula?\"\n }\n ]\n}" }, "url": { "raw": "{{mcp_host_url}}/chats/tutor-rag-agent", "host": ["{{mcp_host_url}}"], "path": ["chats", "tutor-rag-agent"] }, "description": "Test AI subject detection with a Mathematics question. After completion, check /progress/subjects to verify 'Mathematics' was detected." }, "response": [] }, { "name": "Test AI Subject Detection - Programming", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"chat_session_id\": \"ai-test-cs-{{$timestamp}}\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"How do I implement a binary search tree in Python?\"\n }\n ]\n}" }, "url": { "raw": "{{mcp_host_url}}/chats/tutor-rag-agent", "host": ["{{mcp_host_url}}"], "path": ["chats", "tutor-rag-agent"] }, "description": "Test AI subject detection with a Computer Science question. After completion, check /progress/subjects to verify 'Computer Science' was detected." }, "response": [] }, { "name": "Test AI Subject Detection - History", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"chat_session_id\": \"ai-test-history-{{$timestamp}}\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"What were the main causes of World War II?\"\n }\n ]\n}" }, "url": { "raw": "{{mcp_host_url}}/chats/tutor-rag-agent", "host": ["{{mcp_host_url}}"], "path": ["chats", "tutor-rag-agent"] }, "description": "Test AI subject detection with a History question. After completion, check /progress/subjects to verify 'History' was detected." }, "response": [] }, { "name": "Get All Chat Sessions", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/chats/", "host": ["{{mcp_host_url}}"], "path": ["chats", ""] } }, "response": [] }, { "name": "Get Chat History", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/chats/{{chat_session_id}}/history", "host": ["{{mcp_host_url}}"], "path": ["chats", "{{chat_session_id}}", "history"] }, "description": "Get all messages in a chat conversation. Returns message history with:\n- role: user/assistant/system\n- content: Message text\n- message_metadata: Additional data (for system messages, includes upload info)\n- created_at: Message timestamp\n\nSystem messages are created for file uploads when chat_session_id is provided. These include:\n- event_type: 'file_upload'\n- file_id, filename, document_title\n- subject, topic\n- upload_date (custom or current)" }, "response": [] }, { "name": "Get Agent Info", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/chats/agent/info", "host": ["{{mcp_host_url}}"], "path": ["chats", "agent", "info"] } }, "response": [] }, { "name": "Upload Student File (PDF/DOCX)", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.file_id) {", " pm.collectionVariables.set(\"file_id\", jsonData.file_id);", " console.log(\"File ID saved:\", jsonData.file_id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "formdata", "formdata": [ { "key": "file", "type": "file", "src": [], "description": "PDF or DOCX file to upload" }, { "key": "student_id", "value": "{{user_id}}", "type": "text", "description": "User ID of the student" }, { "key": "subject", "value": "General", "type": "text", "description": "Subject category - Set to 'General' to let AI auto-detect from document content, or specify: Mathematics, Physics, Chemistry, Biology, Computer Science, English, History, etc." }, { "key": "topic", "value": "Calculus", "type": "text", "description": "Specific topic within the subject" }, { "key": "difficulty_level", "value": "5", "type": "text", "description": "Difficulty level from 1 (easy) to 10 (hard)" }, { "key": "document_title", "value": "Calculus Study Notes - Chapter 1", "type": "text", "description": "Optional: Custom document title for citations (defaults to filename if not provided)" }, { "key": "upload_date", "value": "2022-09-15T10:30:00Z", "type": "text", "description": "Optional: Custom upload date in ISO format (e.g., '2022-09-15T10:30:00Z' for September 2022). Defaults to current date if not provided. Useful for uploading historical study materials." }, { "key": "chat_session_id", "value": "", "type": "text", "description": "Optional: Link this upload to a chat session. If provided, the upload will appear as a system message in the chat history with full document metadata." } ] }, "url": { "raw": "{{mcp_host_url}}/chats/upload-student-file", "host": ["{{mcp_host_url}}"], "path": ["chats", "upload-student-file"] }, "description": "Upload a PDF or DOCX file to be processed and indexed in the RAG system.\n\n🤖 **AI-Powered Subject Detection:**\nSet 'subject' to 'General' and the AI will automatically detect the subject from the document content:\n- Math textbook PDF → Mathematics\n- Physics notes → Physics \n- Programming tutorial → Computer Science\n- History essay → History\n\n**Processing steps:**\n1. Stored in Azure Blob Storage\n2. Text extracted automatically\n3. **Subject auto-detected from content** (if 'General')\n4. Indexed for future knowledge retrieval\n\n**NEW Features:**\n\n📅 **Custom Upload Dates:**\n- Set 'upload_date' to specify when the material was created/studied (e.g., '2022-09-15T10:30:00Z' for September 2022)\n- Leave empty to use current date\n- Perfect for uploading historical study materials with accurate timestamps\n\n💬 **Chat Integration:**\n- Set 'chat_session_id' to link this upload to a conversation\n- Upload appears as a system message in chat history\n- Message includes filename, title, subject, topic, and upload date\n- Maintains conversation context when sharing documents\n\n**Response includes:**\n- file_id: Unique identifier for tracking\n- document_info: Complete metadata (filename, title, subject, topic, upload_date)\n- detected_subject: The AI-detected or provided subject\n- processing_info: Chunks stored and character count\n\nThe document_title parameter is optional and helps with better citation tracking. If not provided, the filename will be used." }, "response": [] }, { "name": "Upload Historical Document (Custom Date)", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.file_id) {", " pm.collectionVariables.set(\"file_id\", jsonData.file_id);", " console.log(\"File ID saved:\", jsonData.file_id);", " }", " if (jsonData.document_info) {", " console.log(\"Document uploaded with date:\", jsonData.document_info.upload_date);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "formdata", "formdata": [ { "key": "file", "type": "file", "src": [], "description": "PDF or DOCX file to upload" }, { "key": "student_id", "value": "{{user_id}}", "type": "text" }, { "key": "subject", "value": "Mathematics", "type": "text" }, { "key": "topic", "value": "Linear Algebra", "type": "text" }, { "key": "difficulty_level", "value": "7", "type": "text" }, { "key": "document_title", "value": "Linear Algebra Notes - Fall 2022", "type": "text" }, { "key": "upload_date", "value": "2022-09-15T14:30:00Z", "type": "text", "description": "September 15, 2022 at 2:30 PM UTC" } ] }, "url": { "raw": "{{mcp_host_url}}/chats/upload-student-file", "host": ["{{mcp_host_url}}"], "path": ["chats", "upload-student-file"] }, "description": "Example: Upload a document from September 2022 with a custom upload date.\n\nThis demonstrates:\n- Setting upload_date to a past date (September 2022)\n- Backend will store this custom date instead of current date\n- Useful for organizing historical study materials by actual study date\n- Progress tracking will reflect when material was actually studied" }, "response": [] }, { "name": "Upload During Chat Session", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.file_id) {", " pm.collectionVariables.set(\"file_id\", jsonData.file_id);", " console.log(\"File ID saved:\", jsonData.file_id);", " }", " console.log(\"Document linked to chat session:\", pm.collectionVariables.get(\"chat_session_id\"));", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "formdata", "formdata": [ { "key": "file", "type": "file", "src": [], "description": "PDF or DOCX file to upload" }, { "key": "student_id", "value": "{{user_id}}", "type": "text" }, { "key": "subject", "value": "Physics", "type": "text" }, { "key": "topic", "value": "Quantum Mechanics", "type": "text" }, { "key": "difficulty_level", "value": "9", "type": "text" }, { "key": "document_title", "value": "Quantum Mechanics Lecture Notes", "type": "text" }, { "key": "chat_session_id", "value": "{{chat_session_id}}", "type": "text", "description": "Links upload to current chat session" } ] }, "url": { "raw": "{{mcp_host_url}}/chats/upload-student-file", "host": ["{{mcp_host_url}}"], "path": ["chats", "upload-student-file"] }, "description": "Example: Upload a document during an active chat session.\n\nThis demonstrates:\n- Linking upload to chat_session_id\n- Upload appears as system message in chat history\n- Use 'Get Chat History' endpoint to see the upload event\n- System message includes: filename, title, subject, topic, upload_date\n- Maintains conversation context when sharing documents" }, "response": [] }, { "name": "Check File Upload Status", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/chats/files/{{file_id}}/status", "host": ["{{mcp_host_url}}"], "path": ["chats", "files", "{{file_id}}", "status"] }, "description": "Check the processing status of an uploaded file. Returns:\n- id: File upload ID\n- filename: Original filename\n- subject & topic: Categorization\n- status: pending | processing | completed | failed\n- chunks_processed: Number of text chunks processed\n- error_message: Error details if status is 'failed'\n- created_at & updated_at: Timestamps (created_at reflects custom upload_date if provided)\n\nUse this endpoint to poll for completion after uploading a file." }, "response": [] } ] }, { "name": "4. Progress Tracking", "item": [ { "name": "Get User Subjects", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/progress/subjects", "host": ["{{mcp_host_url}}"], "path": ["progress", "subjects"] }, "description": "Get all subjects the user has studied with metadata:\n- subject: Subject name\n- session_count: Number of learning sessions\n- total_minutes: Total study time in minutes\n- last_studied: Most recent session date\n- topics_count: Number of distinct topics studied\n\nUse this to populate subject dropdowns or display learning overview." }, "response": [] }, { "name": "Create Learning Session", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"subject\": \"Mathematics\",\n \"topic\": \"Calculus - Derivatives\",\n \"duration_minutes\": 45,\n \"concepts_covered\": [\"limits\", \"derivatives\", \"chain rule\"]\n}" }, "url": { "raw": "{{mcp_host_url}}/progress/sessions", "host": ["{{mcp_host_url}}"], "path": ["progress", "sessions"] } }, "response": [] }, { "name": "Get Learning Sessions", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/progress/sessions", "host": ["{{mcp_host_url}}"], "path": ["progress", "sessions"] } }, "response": [] }, { "name": "Create Milestone", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"title\": \"Completed Calculus Module 1\",\n \"subject\": \"Mathematics\",\n \"milestone_type\": \"completed_topic\"\n}" }, "url": { "raw": "{{mcp_host_url}}/progress/milestones", "host": ["{{mcp_host_url}}"], "path": ["progress", "milestones"] } }, "response": [] }, { "name": "Get Milestones", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/progress/milestones", "host": ["{{mcp_host_url}}"], "path": ["progress", "milestones"] } }, "response": [] }, { "name": "Get Progress Report", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/progress/report/Mathematics", "host": ["{{mcp_host_url}}"], "path": ["progress", "report", "Mathematics"] } }, "response": [] }, { "name": "Get Learning Timeline", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/progress/timeline/Mathematics", "host": ["{{mcp_host_url}}"], "path": ["progress", "timeline", "Mathematics"] } }, "response": [] }, { "name": "Get Weekly Digest", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/progress/weekly-digest", "host": ["{{mcp_host_url}}"], "path": ["progress", "weekly-digest"] } }, "response": [] }, { "name": "Get Stats Summary", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/progress/stats/summary", "host": ["{{mcp_host_url}}"], "path": ["progress", "stats", "summary"] } }, "response": [] } ] }, { "name": "5. Consent Management", "item": [ { "name": "Get Consent Status", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/consent/status", "host": ["{{mcp_host_url}}"], "path": ["consent", "status"] } }, "response": [] }, { "name": "Update Consent", "request": { "method": "PUT", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"consent_level\": \"full_profile\",\n \"data_retention_days\": 365\n}" }, "url": { "raw": "{{mcp_host_url}}/consent/update", "host": ["{{mcp_host_url}}"], "path": ["consent", "update"] }, "description": "Update consent level. Valid values: 'full_profile', 'limited_anonymized', 'minimal_pseudonymous'" }, "response": [] }, { "name": "Get Consent Audit Log", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/consent/audit-log", "host": ["{{mcp_host_url}}"], "path": ["consent", "audit-log"] } }, "response": [] }, { "name": "Export User Data", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_host_url}}/consent/export-data", "host": ["{{mcp_host_url}}"], "path": ["consent", "export-data"] } }, "response": [] } ] } ] }