README.md

---
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.