TutorX

Meetpatel006/TutorX

3.2

If you are the rightful owner of TutorX and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

TutorX-MCP is a comprehensive Model Context Protocol server designed for educational AI tutoring, providing personalized and adaptive learning experiences.

Tools
8
Resources
0
Prompts
0

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.

Hackathon Submission

This project is submitted under Track 3: Agentic Demo Showcase.

Tag: agent-demo-track

Video Overview: Link to video overview of the app explaining the usage of the application

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.

  • : Outlines the standards for behavior within the TutorX community.
  • : Summarizes improvements made to the user interface and user experience.
  • : Details specific enhancements implemented for the UI/UX.
  • : Introduces new features and updates related to the adaptive learning system.
  • : Documents fixes and adjustments made to the Gradio theme and colors.
  • : A summary of various bug fixes and resolved issues.
  • : Explores the enhancements to the adaptive learning system through Gemini integration.
  • : 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

# 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 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:

# 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:

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:

# Install test dependencies
uv install -e ".[test]"

# Run test suite
python run_tests.py

Documentation

  • : āœØ NEW - Detailed guide to contextualized AI tutoring and content generation
  • : Details about the Model Context Protocol
  • : Original requirements document
  • : Client SDK usage

Contributing

We welcome contributions to the TutorX-MCP project! Please read our 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 file for details.