--- title: TutorX MCP emoji: 🏆 colorFrom: indigo colorTo: yellow sdk: gradio sdk_version: 5.33.0 app_file: app.py pinned: false short_description: MCP that deliver personalized AI-powered tutoring . --- # TutorX-MCP Server A comprehensive Model Context Protocol (MCP) server for educational AI tutoring as specified in the Product Requirements Document (PRD). ## Overview TutorX-MCP is an adaptive, multi-modal, and collaborative AI tutoring platform that leverages the Model Context Protocol (MCP) for tool integration and Gradio for user-friendly interfaces. It provides a range of educational features accessible via both MCP clients and a dedicated web interface. ## Additional Documentation Beyond this README, the TutorX project is accompanied by a suite of detailed documentation files, each offering deeper insights into specific aspects of the platform. - **[CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md)**: Outlines the standards for behavior within the TutorX community. - **[UI_UX_IMPROVEMENTS_SUMMARY.md](docs/UI_UX_IMPROVEMENTS_SUMMARY.md)**: Summarizes improvements made to the user interface and user experience. - **[UI_UX_ENHANCEMENTS.md](docs/UI_UX_ENHANCEMENTS.md)**: Details specific enhancements implemented for the UI/UX. - **[NEW_ADAPTIVE_LEARNING_README.md](docs/NEW_ADAPTIVE_LEARNING_README.md)**: Introduces new features and updates related to the adaptive learning system. - **[GRADIO_THEME_COLOR_FIXES.md](docs/GRADIO_THEME_COLOR_FIXES.md)**: Documents fixes and adjustments made to the Gradio theme and colors. - **[FIXES_SUMMARY.md](docs/FIXES_SUMMARY.md)**: A summary of various bug fixes and resolved issues. - **[ENHANCED_ADAPTIVE_LEARNING_GEMINI.md](docs/ENHANCED_ADAPTIVE_LEARNING_GEMINI.md)**: Explores the enhancements to the adaptive learning system through Gemini integration. - **[AI_INTEGRATION_FEATURES.md](docs/AI_INTEGRATION_FEATURES.md)**: Details the features and capabilities related to AI integration within the platform. ## ✨ New: Enhanced AI Integration & Capabilities **🤖 Contextualized AI Tutoring:** - **Session-based tutoring** with persistent context and memory - **Step-by-step guidance** that breaks complex concepts into manageable steps - **Alternative explanations** using multiple approaches (visual, analogy, real-world) - **Adaptive responses** that adjust to student understanding levels **🎨 Advanced Automated Content Generation:** - **Interactive exercises** with multiple components and adaptive features - **Scenario-based learning** with realistic contexts and decision points - **Gamified content** with game mechanics and progressive difficulty - **Multi-modal content** supporting different learning styles [TutorX-MCP] ## Version History ### Current Version - **v0.1.0** (June 2025) - Initial release of core MCP server with SSE transport - Implementation of concept graph and curriculum standards resources - Integration with Google Gemini Flash models (with fallback mechanism) - Addition of Mistral OCR for document processing - Core educational tools: concepts, quizzes, lessons, learning paths - Basic testing framework with pytest and unittest ### Upcoming Release - **v0.2.0** (Planned - July 2025) - Memory Bank implementation for persistent context storage - Enhanced multi-modal support with voice recognition - Improved testing coverage and CI/CD pipeline - User dashboard implementation - Role-based access control and security enhancements ## Features ### Core Features - **Adaptive Learning Engine** - Comprehensive concept graph - Dynamic skill assessment and tracking - Personalized learning paths - **Assessment Suite** - Automated quiz and problem generation - Step-by-step solution analysis - Plagiarism and similarity detection - **Feedback System** - Contextual error analysis and suggestions - Error pattern recognition - **Multi-Modal Interaction** - Text-based Q&A with error pattern recognition - Voice recognition with analysis - Handwriting recognition and digital ink processing ### Advanced Features - **Neurological Engagement Monitor** - Attention, cognitive load, and stress detection - **Cross-Institutional Knowledge Fusion** - Curriculum alignment with national standards - Content reconciliation - **Automated Lesson Authoring** - AI-powered content generation ## Getting Started ### Prerequisites - Python 3.12 or higher - Dependencies as listed in pyproject.toml: - mcp[cli] >= 1.9.3 - fastapi >= 0.109.0 - uvicorn >= 0.27.0 - gradio >= 4.19.0 - numpy >= 1.24.0 - pillow >= 10.0.0 - google-generativeai (for Gemini integration) - mistralai (for OCR capabilities) ### Installation ```powershell # Clone the repository git clone https://github.com/Meetpatel006/TutorX.git cd tutorx-mcp # Using uv (recommended) uv install ``` ### Required API Keys For full functionality, you'll need to set up the following API keys: - **Google AI API Key**: For Gemini Flash model integration - **Mistral API Key**: For document OCR capabilities These can be set as environment variables or in an `.env` file: ```powershell # PowerShell example $env:GOOGLE_API_KEY="your-google-api-key" $env:MISTRAL_API_KEY="your-mistral-api-key" ``` ### Running the Server You can run the server in different modes: ```powershell # MCP server only python run.py --mode mcp # Gradio interface only python run.py --mode gradio # Both MCP server and Gradio interface (default) python run.py --mode both # Custom host and port python run.py --mode mcp --host 0.0.0.0 --mcp-port 8000 --gradio-port 7860 ``` By default: - The MCP server runs at http://localhost:8000 - SSE transport is available at http://localhost:8000/sse - The Gradio interface runs at http://127.0.0.1:7860 ## MCP Tool Integration The server exposes the following MCP tools and resources: ### Tools - **Concept Tools** (concept_tools.py) - `get_concept_tool`: Retrieve detailed information about educational concepts - `assess_skill_tool`: Evaluate student's understanding of specific concepts - **Quiz Tools** (quiz_tools.py) - `generate_quiz_tool`: Create LLM-generated quizzes for specific concepts with customizable difficulty - **Lesson Tools** (lesson_tools.py) - `generate_lesson_tool`: Create complete lesson plans with objectives, activities, and assessments - **Interaction Tools** (interaction_tools.py) - `text_interaction`: Process student text queries and provide educational responses - `check_submission_originality`: Analyze student submissions for potential plagiarism - **OCR Tools** (ocr_tools.py) - `mistral_document_ocr`: Extract and process text from documents using Mistral OCR - **Learning Path Tools** (learning_path_tools.py) - `get_learning_path`: Generate personalized learning paths based on student level and target concepts - **AI Tutoring Tools** (ai_tutor_tools.py) ✨ **NEW** - `start_tutoring_session`: Start contextualized AI tutoring sessions with memory - `ai_tutor_chat`: Interactive chat with AI tutor providing personalized responses - `get_step_by_step_guidance`: Break down complex concepts into manageable steps - `get_alternative_explanations`: Multiple explanation approaches for different learning styles - `update_student_understanding`: Track and adapt to student understanding levels - `end_tutoring_session`: Generate comprehensive session summaries - **Content Generation Tools** (content_generation_tools.py) ✨ **NEW** - `generate_interactive_exercise`: Create engaging interactive exercises with multiple components - `generate_adaptive_content_sequence`: Build adaptive content that adjusts to student performance - `generate_scenario_based_learning`: Create realistic scenario-based learning experiences - `generate_multimodal_content`: Generate content for different learning modalities - `generate_adaptive_assessment`: Create assessments that adapt based on student responses - `generate_gamified_content`: Generate game-based learning content with mechanics - `validate_generated_content`: Quality-check and validate educational content - **Memory Tools** (v0.2.0) - `read_memory_tool`: Retrieve stored context from the Memory Bank - `write_memory_tool`: Store new contextual information in the Memory Bank - `update_memory_tool`: Modify existing context in the Memory Bank - `clear_memory_tool`: Remove stored context from the Memory Bank ### Resources - `concept-graph://`: Knowledge concept graph with concept relationships - `curriculum-standards://{country_code}`: National curricular standards by country - `learning-path://{student_id}`: Personalized student learning paths ## Project Structure ``` tutorx-mcp/ ├── main.py # MCP server entry point ├── app.py # Gradio web interface ├── run.py # Runner script for different modes ├── mcp_server/ # Core server implementation │ ├── server.py # FastAPI application │ ├── mcp_instance.py # Shared MCP instance │ ├── model/ # AI model integrations │ │ └── gemini_flash.py # Google Gemini integration │ ├── resources/ # Educational resources │ │ ├── concept_graph.py # Concept graph implementation │ │ └── curriculum_standards.py # Curriculum standards │ ├── tools/ # MCP tool implementations │ │ ├── concept_tools.py # Concept-related tools │ │ ├── quiz_tools.py # Quiz generation tools │ │ ├── lesson_tools.py # Lesson generation tools │ │ ├── ocr_tools.py # Document OCR tools │ │ ├── interaction_tools.py # Student interaction tools │ │ ├── learning_path_tools.py # Learning path tools │ │ ├── ai_tutor_tools.py # ✨ Contextualized AI tutoring │ │ └── content_generation_tools.py # ✨ Advanced content generation │ └── prompts/ # LLM prompt templates ├── tests/ # Test suite │ ├── test_mcp_server.py # MCP server tests │ ├── test_client.py # Client tests │ ├── test_tools_integration.py # Tool integration tests │ └── test_utils.py # Utility function tests ├── docs/ # Documentation │ ├── API.md # API documentation │ ├── mcp.md # MCP protocol details │ ├── prd.md # Product requirements document │ └── sdk.md # Client SDK documentation ├── pyproject.toml # Project dependencies ├── run_tests.py # Script to run all tests ├── ARCHITECTURE.md # Detailed architecture documentation ├── PROJECT_ANALYSIS.md # Comprehensive project analysis └── README.md # Project documentation ``` ## Architecture TutorX-MCP implements a modular, layered architecture designed for extensibility and maintainability: ### Key Components 1. **MCP Server (mcp_server/server.py)**: - Core FastAPI application that exposes educational tools and resources - Registers tools with the shared MCP instance - Provides HTTP endpoints and SSE transport for client connections 2. **Shared MCP Instance (mcp_server/mcp_instance.py)**: - Central registration point for all MCP tools - Avoids circular import issues and ensures tool availability 3. **AI Model Integration (mcp_server/model/)**: - Integrates Google Gemini Flash models with automatic fallback mechanisms - Provides uniform interface for text generation and content structuring 4. **Tool Modules (mcp_server/tools/)**: - Modular implementation of educational features - Each tool is registered with the MCP instance via decorators - Designed for independent development and testing 5. **Resource Modules (mcp_server/resources/)**: - Manages educational data like concept graphs and curriculum standards - Provides data for adaptive learning and standards alignment 6. **Gradio Interface (app.py)**: - Web-based user interface - Communicates with the MCP server via the MCP client protocol This separation of concerns allows: - MCP clients (like Claude Desktop App) to directly connect to the MCP server via SSE transport - The web interface to interact with the server using the MCP protocol - Clear boundaries between presentation, API gateway, tool implementations, and resources - Easy extension through the addition of new tool modules For more detailed architecture information, see the documentation in the docs/ folder. ## Testing The project includes a comprehensive test suite: ```bash # Install test dependencies uv install -e ".[test]" # Run test suite python run_tests.py ``` ## Documentation - [AI Integration Features](docs/AI_INTEGRATION_FEATURES.md): ✨ **NEW** - Detailed guide to contextualized AI tutoring and content generation - [MCP Protocol](docs/mcp.md): Details about the Model Context Protocol - [Product Requirements](docs/prd.md): Original requirements document - [SDK Documentation](docs/sdk.md): Client SDK usage ## Contributing We welcome contributions to the TutorX-MCP project! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.