Added external tool integration,also with test files and documentation

README.md

@@ -127,10 +127,15 @@ tutorx-mcp/
 ├── client.py            # MCP client for calling server tools
 ├── app.py               # Gradio web interface
 ├── run.py               # Runner script for different modes
+├── tests/               # Test suite
+│   ├── test_mcp_server.py  # MCP server tests
+│   ├── test_client.py      # Client tests
+│   └── test_utils.py       # Utility function tests
 ├── utils/               # Utility modules
 │   ├── multimodal.py    # Multi-modal processing utilities
 │   └── assessment.py    # Assessment and analytics functions
 ├── pyproject.toml       # Project dependencies
+├── run_tests.py         # Script to run all tests
 └── README.md            # Project documentation
 ```
 
@@ -149,11 +154,55 @@ This separation of concerns allows:
 - The web interface to interact with the server using standard HTTP
 - Clear boundaries between presentation, business logic, and tool implementation
 
-## License
+## Testing
+
+The project includes a comprehensive test suite:
+
+```bash
+# Install test dependencies
+uv install -e ".[test]"
+
+# Run test suite
+python run_tests.py
+```
+
+### Integration with External Systems
+
+TutorX-MCP can integrate with various external educational systems:
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+1. **Learning Management Systems (LMS)**
+   - Canvas, Moodle, Blackboard
+   - Grade syncing and assignment management
+   
+2. **Open Educational Resources (OER)**
+   - Search and integration with OER repositories
+   - Access to diverse educational content
+   
+3. **Real-time Personalized Tutoring Platforms**
+   - Schedule and manage tutoring sessions
+   - Connect students with expert tutors
 
-## Acknowledgments
+## Deployment
+
+For production deployment, see [Deployment Guide](docs/deployment.md) which covers:
+
+- Docker-based deployment
+- Manual installation
+- Scaling strategies
+- Monitoring setup
+- Security considerations
+
+## Documentation
+
+- [API Documentation](docs/api.md): Complete API reference for developers
+- [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
 
-- Model Context Protocol (MCP) - https://modelcontextprotocol.io/
-- Gradio - https://gradio.app/
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

app.py

@@ -240,6 +240,102 @@ with gr.Blocks(title="TutorX Educational AI", theme=gr.themes.Soft()) as demo:
                 inputs=[submission_input, reference_input],
                 outputs=[plagiarism_output]
             )
+        
+        # Tab 6: Gamification
+        with gr.Tab("Gamification"):
+            gr.Markdown("## Student Badges")
+            
+            with gr.Row():
+                with gr.Column():
+                    badges_student_id = gr.Textbox(label="Student ID", value=student_id)
+                    get_badges_btn = gr.Button("Get Student Badges")
+                
+                with gr.Column():
+                    badges_output = gr.JSON(label="Student Badges")
+            
+            get_badges_btn.click(
+                fn=lambda sid: client.get_badges_for_student(sid),
+                inputs=[badges_student_id],
+                outputs=[badges_output]
+            )
+            
+            gr.Markdown("## Award Badge")
+            
+            with gr.Row():
+                with gr.Column():
+                    award_student_id = gr.Textbox(label="Student ID", value=student_id)
+                    badge_id = gr.Dropdown(
+                        choices=["beginner", "persistent", "math_whiz", "science_explorer", 
+                                "speed_demon", "accuracy_master", "helping_hand", 
+                                "night_owl", "early_bird", "perfect_streak"],
+                        label="Badge to Award",
+                        value="beginner"
+                    )
+                    award_badge_btn = gr.Button("Award Badge")
+                
+                with gr.Column():
+                    award_output = gr.JSON(label="Award Result")
+            
+            award_badge_btn.click(
+                fn=lambda sid, bid: client.award_student_badge(sid, bid),
+                inputs=[award_student_id, badge_id],
+                outputs=[award_output]
+            )
+            
+            gr.Markdown("## Leaderboards")
+            
+            with gr.Row():
+                with gr.Column():
+                    leaderboard_id = gr.Dropdown(
+                        choices=["weekly_points", "monthly_streak", "problem_solving_speed"],
+                        label="Leaderboard",
+                        value="weekly_points"
+                    )
+                    get_leaderboard_btn = gr.Button("Get Leaderboard")
+                
+                with gr.Column():
+                    leaderboard_output = gr.JSON(label="Leaderboard")
+            
+            get_leaderboard_btn.click(
+                fn=lambda lid: client.get_current_leaderboard(lid),
+                inputs=[leaderboard_id],
+                outputs=[leaderboard_output]
+            )
+            
+            gr.Markdown("## Track Activity")
+            
+            with gr.Row():
+                with gr.Column():
+                    track_student_id = gr.Textbox(label="Student ID", value=student_id)
+                    activity_type = gr.Dropdown(
+                        choices=["lesson_completed", "assessment_completed", "problem_solved", "forum_post", "login"],
+                        label="Activity Type",
+                        value="lesson_completed"
+                    )
+                    activity_score = gr.Slider(minimum=0, maximum=1, value=0.85, step=0.01, label="Score/Performance")
+                    activity_subject = gr.Dropdown(
+                        choices=["math", "science", "language", "history", "other"],
+                        label="Subject",
+                        value="math"
+                    )
+                    track_btn = gr.Button("Track Activity")
+                
+                with gr.Column():
+                    activity_output = gr.JSON(label="Activity Tracking Result")
+            
+            track_btn.click(
+                fn=lambda sid, atype, score, subject: client.track_student_activity(
+                    sid, 
+                    {
+                        "activity_type": atype,
+                        "score": score,
+                        "subject": subject,
+                        "time_seconds": 90  # Simulated time value
+                    }
+                ),
+                inputs=[track_student_id, activity_type, activity_score, activity_subject],
+                outputs=[activity_output]
+            )
 
 # Launch the app
 if __name__ == "__main__":

client.py

@@ -198,6 +198,89 @@ class TutorXClient:
             "submission": submission,
             "reference_sources": reference_sources
         })
+    
+    # ------------ Gamification ------------
+    
+    def award_student_badge(self, student_id: str, badge_id: str) -> Dict[str, Any]:
+        """Award a badge to a student"""
+        return self._call_tool("award_student_badge", {
+            "student_id": student_id,
+            "badge_id": badge_id
+        })
+    
+    def get_badges_for_student(self, student_id: str) -> Dict[str, Any]:
+        """Get all badges for a student"""
+        return self._call_tool("get_badges_for_student", {
+            "student_id": student_id
+        })
+    
+    def update_student_leaderboard(self, leaderboard_id: str, student_id: str, score: float) -> Dict[str, Any]:
+        """Update a leaderboard with a student's score"""
+        return self._call_tool("update_student_leaderboard", {
+            "leaderboard_id": leaderboard_id,
+            "student_id": student_id,
+            "score": score
+        })
+    
+    def get_current_leaderboard(self, leaderboard_id: str) -> Dict[str, Any]:
+        """Get current leaderboard standings"""
+        return self._call_tool("get_current_leaderboard", {
+            "leaderboard_id": leaderboard_id
+        })
+    
+    def track_student_activity(self, student_id: str, activity_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Track a student's activity and check for achievements"""
+        return self._call_tool("track_student_activity", {
+            "student_id": student_id,
+            "activity_data": activity_data
+        })
+    
+    # ------------ External Integrations ------------
+    
+    def lms_sync_grades(self, lms_type: str, api_url: str, api_key: str, 
+                      course_id: str, assignment_id: str, 
+                      grades: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Sync grades with a Learning Management System"""
+        return self._call_tool("lms_sync_grades", {
+            "lms_type": lms_type,
+            "api_url": api_url,
+            "api_key": api_key,
+            "course_id": course_id,
+            "assignment_id": assignment_id,
+            "grades": grades
+        })
+    
+    def oer_search(self, repository_url: str, query: str, 
+                  subject: Optional[str] = None, grade_level: Optional[str] = None,
+                  api_key: Optional[str] = None) -> Dict[str, Any]:
+        """Search for educational resources in OER repositories"""
+        params = {
+            "repository_url": repository_url,
+            "query": query
+        }
+        
+        if subject:
+            params["subject"] = subject
+            
+        if grade_level:
+            params["grade_level"] = grade_level
+            
+        if api_key:
+            params["api_key"] = api_key
+            
+        return self._call_tool("oer_search", params)
+    
+    def schedule_tutoring_session(self, platform_url: str, client_id: str, client_secret: str,
+                                student_id: str, subject: str, datetime_str: str) -> Dict[str, Any]:
+        """Schedule a session with a real-time personalized tutoring platform"""
+        return self._call_tool("schedule_tutoring_session", {
+            "platform_url": platform_url,
+            "client_id": client_id,
+            "client_secret": client_secret,
+            "student_id": student_id,
+            "subject": subject,
+            "datetime_str": datetime_str
+        })
 
 # Create a default client instance for easy import
 client = TutorXClient()

deployment/Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY pyproject.toml .
+RUN pip install --no-cache-dir uv && \
+    uv pip install --no-cache -e .
+
+# Copy application code
+COPY main.py .
+COPY client.py .
+COPY utils/ ./utils/
+
+# Expose port for MCP server
+EXPOSE 8000
+
+# Run MCP server
+CMD ["python", "main.py"]

deployment/Dockerfile.web

@@ -0,0 +1,19 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY pyproject.toml .
+RUN pip install --no-cache-dir uv && \
+    uv pip install --no-cache -e .
+
+# Copy application code
+COPY app.py .
+COPY client.py .
+COPY utils/ ./utils/
+
+# Expose port for Gradio interface
+EXPOSE 7860
+
+# Run Gradio interface
+CMD ["python", "app.py"]

deployment/docker-compose.yml

@@ -0,0 +1,46 @@
+version: '3'
+
+services:
+  tutorx-mcp:
+    build:
+      context: ..
+      dockerfile: deployment/Dockerfile
+    ports:
+      - "8000:8000"  # MCP server
+    environment:
+      - MCP_HOST=0.0.0.0
+      - MCP_PORT=8000
+      - LOG_LEVEL=INFO
+      - REDIS_HOST=redis
+    volumes:
+      - tutorx-data:/data
+    depends_on:
+      - redis
+    restart: unless-stopped
+
+  tutorx-web:
+    build:
+      context: ..
+      dockerfile: deployment/Dockerfile.web
+    ports:
+      - "7860:7860"  # Gradio interface
+    environment:
+      - GRADIO_SERVER_NAME=0.0.0.0
+      - GRADIO_SERVER_PORT=7860
+      - MCP_SERVER_URL=http://tutorx-mcp:8000
+    depends_on:
+      - tutorx-mcp
+    restart: unless-stopped
+
+  redis:
+    image: redis:alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis-data:/data
+    command: redis-server --appendonly yes
+    restart: unless-stopped
+
+volumes:
+  tutorx-data:
+  redis-data:

docs/api.md

@@ -0,0 +1,368 @@
+# TutorX-MCP API Documentation
+
+This document provides comprehensive documentation for the TutorX-MCP API for developers who want to integrate with the system.
+
+## API Overview
+
+The TutorX-MCP server exposes a Model Context Protocol (MCP) API that allows clients to interact with various educational tools and resources. This API follows the standard MCP protocol as defined in [MCP Specification](https://github.com/anthropics/anthropic-tools/blob/main/mcp/README.md).
+
+## Authentication
+
+For production deployments, all API requests should include an API key in the `Authorization` header:
+
+```
+Authorization: Bearer your-api-key-here
+```
+
+## Base URL
+
+Default: `http://localhost:8000`
+
+For production: See your deployment configuration
+
+## Tools API
+
+Tools represent functionality that can be invoked by MCP clients. Each tool is accessed via:
+
+```
+POST /tools/{tool_name}
+Content-Type: application/json
+
+{
+  "param1": "value1",
+  "param2": "value2"
+}
+```
+
+### Core Features
+
+#### Adaptive Learning Engine
+
+##### `assess_skill`
+
+Assess a student's skill level on a specific concept.
+
+**Request:**
+```json
+{
+  "student_id": "student123",
+  "concept_id": "math_algebra_basics"
+}
+```
+
+**Response:**
+```json
+{
+  "student_id": "student123",
+  "concept_id": "math_algebra_basics",
+  "skill_level": 0.75,
+  "confidence": 0.85,
+  "recommendations": [
+    "Practice more complex problems",
+    "Review related concept: algebra_linear_equations"
+  ],
+  "timestamp": "2025-06-07T10:30:45.123456"
+}
+```
+
+##### `generate_quiz`
+
+Generate a quiz based on specified concepts and difficulty.
+
+**Request:**
+```json
+{
+  "concept_ids": ["math_algebra_basics", "math_algebra_linear_equations"],
+  "difficulty": 2
+}
+```
+
+**Response:**
+```json
+{
+  "quiz_id": "q12345",
+  "concept_ids": ["math_algebra_basics", "math_algebra_linear_equations"],
+  "difficulty": 2,
+  "questions": [
+    {
+      "id": "q1",
+      "text": "Solve for x: 2x + 3 = 7",
+      "type": "algebraic_equation",
+      "answer": "x = 2",
+      "solution_steps": [
+        "2x + 3 = 7",
+        "2x = 7 - 3",
+        "2x = 4",
+        "x = 4/2 = 2"
+      ]
+    }
+  ]
+}
+```
+
+#### Feedback System
+
+##### `analyze_error_patterns`
+
+Analyze common error patterns for a student on a specific concept.
+
+**Request:**
+```json
+{
+  "student_id": "student123",
+  "concept_id": "math_algebra_basics"
+}
+```
+
+**Response:**
+```json
+{
+  "student_id": "student123",
+  "concept_id": "math_algebra_basics",
+  "common_errors": [
+    {
+      "type": "sign_error",
+      "frequency": 0.65,
+      "example": "2x - 3 = 5 → 2x = 5 - 3 → 2x = 2 → x = 1 (should be x = 4)"
+    }
+  ],
+  "recommendations": [
+    "Practice more sign manipulation problems"
+  ]
+}
+```
+
+### Advanced Features
+
+#### Neurological Engagement Monitor
+
+##### `analyze_cognitive_state`
+
+Analyze EEG data to determine cognitive state.
+
+**Request:**
+```json
+{
+  "eeg_data": {
+    "channels": [...],
+    "sampling_rate": 256,
+    "duration": 10.0
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "attention_level": 0.82,
+  "cognitive_load": 0.65,
+  "stress_level": 0.25,
+  "recommendations": [
+    "Student is engaged but approaching cognitive overload",
+    "Consider simplifying next problems slightly"
+  ],
+  "timestamp": "2025-06-07T10:32:15.123456"
+}
+```
+
+### External Integrations
+
+#### Learning Management Systems
+
+##### `lms_sync_grades`
+
+Sync grades with a Learning Management System.
+
+**Request:**
+```json
+{
+  "lms_type": "canvas",
+  "api_url": "https://canvas.example.com/api/v1",
+  "api_key": "your-api-key",
+  "course_id": "course123",
+  "assignment_id": "assign456",
+  "grades": [
+    {
+      "student_id": "student123",
+      "score": 85.5
+    }
+  ]
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "timestamp": "2025-06-07T10:35:22.123456",
+  "message": "Grades successfully synced"
+}
+```
+
+#### Open Educational Resources
+
+##### `oer_search`
+
+Search for educational resources in OER repositories.
+
+**Request:**
+```json
+{
+  "repository_url": "https://oer.example.com/api",
+  "query": "linear equations",
+  "subject": "mathematics",
+  "grade_level": "8"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "count": 2,
+  "results": [
+    {
+      "id": "resource123",
+      "title": "Introduction to Linear Equations",
+      "description": "A comprehensive guide to solving linear equations",
+      "url": "https://oer.example.com/resources/resource123",
+      "subject": "mathematics",
+      "grade_level": "8-9",
+      "license": "CC-BY"
+    }
+  ],
+  "timestamp": "2025-06-07T10:36:12.123456"
+}
+```
+
+#### Real-Time Personalized Tutoring
+
+##### `schedule_tutoring_session`
+
+Schedule a session with a real-time personalized tutoring platform.
+
+**Request:**
+```json
+{
+  "platform_url": "https://tutoring.example.com/api",
+  "client_id": "your-client-id",
+  "client_secret": "your-client-secret",
+  "student_id": "student123",
+  "subject": "mathematics",
+  "datetime_str": "2025-06-10T15:00:00Z"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "session_id": "session789",
+  "tutor": {
+    "id": "tutor456",
+    "name": "Dr. Jane Smith",
+    "rating": 4.9,
+    "specialization": "mathematics"
+  },
+  "datetime": "2025-06-10T15:00:00Z",
+  "join_url": "https://tutoring.example.com/session/session789",
+  "timestamp": "2025-06-07T10:37:45.123456"
+}
+```
+
+## Resources API
+
+Resources represent data that can be fetched by MCP clients. Each resource is accessed via:
+
+```
+GET /resources?uri={resource_uri}
+Accept: application/json
+```
+
+### Available Resources
+
+#### `concept-graph://`
+
+Retrieves the full knowledge concept graph.
+
+#### `learning-path://{student_id}`
+
+Retrieves the personalized learning path for a student.
+
+#### `curriculum-standards://{country_code}`
+
+Retrieves curriculum standards for a specific country.
+
+#### `student-dashboard://{student_id}`
+
+Retrieves dashboard data for a specific student.
+
+## Error Handling
+
+API errors follow a standard format:
+
+```json
+{
+  "error": {
+    "code": "error_code",
+    "message": "Human-readable error message",
+    "details": {}
+  }
+}
+```
+
+Common error codes:
+- `invalid_request`: The request was malformed
+- `authentication_error`: Authentication failed
+- `not_found`: The requested resource does not exist
+- `server_error`: Internal server error
+
+## Rate Limiting
+
+Production deployments implement rate limiting to prevent abuse. Clients should monitor the following headers:
+
+- `X-RateLimit-Limit`: Maximum requests per hour
+- `X-RateLimit-Remaining`: Remaining requests for the current hour
+- `X-RateLimit-Reset`: Timestamp when the limit will reset
+
+## SDK
+
+For easier integration, we provide client SDKs in multiple languages:
+
+- Python: `pip install tutorx-client`
+- JavaScript: `npm install tutorx-client`
+
+Example usage (Python):
+
+```python
+from tutorx_client import TutorXClient
+
+client = TutorXClient("http://localhost:8000", api_key="your-api-key")
+
+# Call a tool
+result = client.assess_skill("student123", "math_algebra_basics")
+print(result["skill_level"])
+
+# Access a resource
+concept_graph = client.get_concept_graph()
+```
+
+## Webhooks
+
+For real-time updates, you can register webhook endpoints:
+
+```
+POST /webhooks/register
+Content-Type: application/json
+Authorization: Bearer your-api-key
+
+{
+  "url": "https://your-app.example.com/webhook",
+  "events": ["assessment.completed", "badge.awarded"],
+  "secret": "your-webhook-secret"
+}
+```
+
+## Support
+
+For API support, contact us at [email protected]

docs/deployment.md

@@ -0,0 +1,85 @@
+# TutorX-MCP Deployment Guide
+
+This guide provides instructions for deploying the TutorX-MCP server in production environments.
+
+## Deployment Options
+
+### 1. Docker Deployment (Recommended)
+
+The easiest way to deploy TutorX-MCP is using Docker and Docker Compose:
+
+```bash
+# Navigate to the deployment directory
+cd deployment
+
+# Start the services
+docker-compose up -d
+```
+
+This will start:
+- The MCP server at http://localhost:8000
+- The Gradio web interface at http://localhost:7860
+- A Redis instance for caching and session management
+
+### 2. Manual Deployment
+
+#### Prerequisites
+
+- Python 3.12 or higher
+- Redis (optional, but recommended for production)
+
+#### Steps
+
+1. Install dependencies:
+   ```bash
+   uv install -e .
+   ```
+
+2. Configure environment variables:
+   ```bash
+   # Server configuration
+   export MCP_HOST=0.0.0.0
+   export MCP_PORT=8000
+   
+   # Redis configuration (if using)
+   export REDIS_HOST=localhost
+   export REDIS_PORT=6379
+   ```
+
+3. Run the server:
+   ```bash
+   python run.py --mode both --host 0.0.0.0
+   ```
+
+## Scaling
+
+For high-traffic deployments, consider:
+
+1. Using a reverse proxy like Nginx or Traefik in front of the services
+2. Implementing load balancing for multiple MCP server instances
+3. Scaling the Redis cache using Redis Sentinel or Redis Cluster
+
+## Monitoring
+
+We recommend setting up:
+
+1. Prometheus for metrics collection
+2. Grafana for visualization
+3. ELK stack for log management
+
+## Security Considerations
+
+1. In production, always use HTTPS
+2. Implement proper authentication for API access
+3. Keep dependencies updated
+4. Follow least privilege principles for service accounts
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| MCP_HOST | Host address for MCP server | 127.0.0.1 |
+| MCP_PORT | Port for MCP server | 8000 |
+| REDIS_HOST | Redis host address | localhost |
+| REDIS_PORT | Redis port | 6379 |
+| LOG_LEVEL | Logging level (DEBUG, INFO, WARNING, ERROR) | INFO |

main.py

@@ -1,6 +1,7 @@
 # TutorX MCP Server
 from mcp.server.fastmcp import FastMCP
 import json
+import os
 from typing import List, Dict, Any, Optional
 from datetime import datetime
 
@@ -17,6 +18,18 @@ from utils.assessment import (
     generate_performance_analytics,
     detect_plagiarism
 )
+from utils.gamification import (
+    award_badge,
+    get_student_badges,
+    update_leaderboard,
+    get_leaderboard,
+    check_achievements
+)
+from utils.integrations import (
+    LMSIntegration,
+    OERIntegration,
+    RTPTIntegration
+)
 
 # Create the TutorX MCP server
 mcp = FastMCP("TutorX")
@@ -579,5 +592,200 @@ def check_submission_originality(submission: str, reference_sources: List[str])
     """
     return detect_plagiarism(submission, reference_sources)
 
+# ------------------ Gamification Features ------------------
+
+@mcp.tool()
+def award_student_badge(student_id: str, badge_id: str) -> Dict[str, Any]:
+    """
+    Award a badge to a student
+    
+    Args:
+        student_id: The student's unique identifier
+        badge_id: The badge ID to award
+        
+    Returns:
+        Badge information
+    """
+    return award_badge(student_id, badge_id)
+
+@mcp.tool()
+def get_badges_for_student(student_id: str) -> Dict[str, Any]:
+    """
+    Get all badges for a student
+    
+    Args:
+        student_id: The student's unique identifier
+        
+    Returns:
+        Badge information
+    """
+    return get_student_badges(student_id)
+
+@mcp.tool()
+def update_student_leaderboard(leaderboard_id: str, student_id: str, score: float) -> Dict[str, Any]:
+    """
+    Update a leaderboard with a student's score
+    
+    Args:
+        leaderboard_id: ID of the leaderboard to update
+        student_id: The student's unique identifier
+        score: The score to record
+        
+    Returns:
+        Leaderboard information
+    """
+    return update_leaderboard(leaderboard_id, student_id, score)
+
+@mcp.tool()
+def get_current_leaderboard(leaderboard_id: str) -> Dict[str, Any]:
+    """
+    Get current leaderboard standings
+    
+    Args:
+        leaderboard_id: ID of the leaderboard to get
+        
+    Returns:
+        Leaderboard information
+    """
+    return get_leaderboard(leaderboard_id)
+
+@mcp.tool()
+def track_student_activity(student_id: str, activity_data: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Track a student's activity and check for achievements
+    
+    Args:
+        student_id: The student's unique identifier
+        activity_data: Data about the activity
+        
+    Returns:
+        Tracking information and any new badges
+    """
+    new_badges = check_achievements(student_id, activity_data)
+    
+    return {
+        "student_id": student_id,
+        "activity_tracked": True,
+        "activity_data": activity_data,
+        "new_badges": new_badges,
+        "timestamp": datetime.now().isoformat()
+    }
+
+# ------------------ External Integrations ------------------
+
+@mcp.tool()
+def lms_sync_grades(lms_type: str, api_url: str, api_key: str, 
+                  course_id: str, assignment_id: str, 
+                  grades: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """
+    Sync grades with a Learning Management System
+    
+    Args:
+        lms_type: Type of LMS ('canvas', 'moodle', 'blackboard')
+        api_url: URL for the LMS API
+        api_key: API key for authentication
+        course_id: ID of the course
+        assignment_id: ID of the assignment
+        grades: List of grade data to sync
+        
+    Returns:
+        Status of the sync operation
+    """
+    try:
+        lms = LMSIntegration(lms_type, api_url, api_key)
+        success = lms.sync_grades(course_id, assignment_id, grades)
+        return {
+            "success": success,
+            "timestamp": datetime.now().isoformat(),
+            "message": "Grades successfully synced" if success else "Failed to sync grades"
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+            "timestamp": datetime.now().isoformat()
+        }
+
+@mcp.tool()
+def oer_search(repository_url: str, query: str, 
+              subject: Optional[str] = None, grade_level: Optional[str] = None,
+              api_key: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Search for educational resources in OER repositories
+    
+    Args:
+        repository_url: URL of the OER repository
+        query: Search query
+        subject: Optional subject filter
+        grade_level: Optional grade level filter
+        api_key: Optional API key if required
+        
+    Returns:
+        List of matching resources
+    """
+    try:
+        oer = OERIntegration(repository_url, api_key)
+        results = oer.search_resources(query, subject, grade_level)
+        return {
+            "success": True,
+            "count": len(results),
+            "results": results,
+            "timestamp": datetime.now().isoformat()
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+            "timestamp": datetime.now().isoformat()
+        }
+
+@mcp.tool()
+def schedule_tutoring_session(platform_url: str, client_id: str, client_secret: str,
+                            student_id: str, subject: str, datetime_str: str) -> Dict[str, Any]:
+    """
+    Schedule a session with a real-time personalized tutoring platform
+    
+    Args:
+        platform_url: URL of the tutoring platform
+        client_id: OAuth client ID
+        client_secret: OAuth client secret
+        student_id: ID of the student
+        subject: Subject for tutoring
+        datetime_str: ISO format datetime for the session
+        
+    Returns:
+        Session details
+    """
+    try:
+        # Find an available tutor
+        rtpt = RTPTIntegration(platform_url, client_id, client_secret)
+        tutors = rtpt.get_available_tutors(subject, "intermediate")
+        
+        if not tutors:
+            return {
+                "success": False,
+                "message": "No tutors available for this subject",
+                "timestamp": datetime.now().isoformat()
+            }
+        
+        # Schedule with first available tutor
+        tutor_id = tutors[0]["id"]
+        session = rtpt.schedule_session(student_id, tutor_id, subject, datetime_str)
+        
+        return {
+            "success": True,
+            "session_id": session.get("id"),
+            "tutor": session.get("tutor"),
+            "datetime": session.get("datetime"),
+            "join_url": session.get("join_url"),
+            "timestamp": datetime.now().isoformat()
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+            "timestamp": datetime.now().isoformat()
+        }
+
 if __name__ == "__main__":
     mcp.run()

pyproject.toml

@@ -11,3 +11,13 @@ dependencies = [
     "pillow>=10.0.0",
     "requests>=2.31.0",
 ]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"

run_tests.py

@@ -0,0 +1,37 @@
+"""
+Script to run all tests for the TutorX MCP server
+"""
+import sys
+import os
+import unittest
+import pytest
+
+def run_tests():
+    """Run all tests"""
+    print("Running TutorX-MCP Tests...")
+    
+    # First run unittest tests
+    unittest_loader = unittest.TestLoader()
+    test_directory = os.path.join(os.path.dirname(__file__), "tests")
+    test_suite = unittest_loader.discover(test_directory)
+    
+    test_runner = unittest.TextTestRunner(verbosity=2)
+    unittest_result = test_runner.run(test_suite)
+    
+    # Then run pytest tests (with coverage)
+    pytest_args = [
+        "tests", 
+        "--cov=.",
+        "--cov-report=term",
+        "--cov-report=html:coverage_html",
+        "-v"
+    ]
+    
+    pytest_result = pytest.main(pytest_args)
+    
+    # Return success if both test runners succeeded
+    return unittest_result.wasSuccessful() and pytest_result == 0
+
+if __name__ == "__main__":
+    success = run_tests()
+    sys.exit(0 if success else 1)

tests/__init__.py

@@ -0,0 +1,3 @@
+"""
+Test package for TutorX MCP Server
+"""

tests/test_client.py

@@ -0,0 +1,131 @@
+"""
+Tests for the TutorX MCP client
+"""
+
+import sys
+import os
+import unittest
+from unittest.mock import patch, MagicMock
+import json
+import requests
+
+# Add parent directory to path to import modules
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from client import TutorXClient
+
+
+class TestTutorXClient(unittest.TestCase):
+    """Test cases for the TutorX MCP client"""
+
+    def setUp(self):
+        """Set up test fixtures"""
+        self.client = TutorXClient("http://localhost:8000")
+        self.student_id = "test_student_123"
+        self.concept_id = "math_algebra_basics"
+    
+    @patch('client.requests.post')
+    def test_call_tool(self, mock_post):
+        """Test _call_tool method"""
+        # Setup mock response
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"result": "success"}
+        mock_response.raise_for_status = MagicMock()
+        mock_post.return_value = mock_response
+        
+        # Call method
+        result = self.client._call_tool("test_tool", {"param": "value"})
+        
+        # Assertions
+        self.assertEqual(result, {"result": "success"})
+        mock_post.assert_called_once_with(
+            "http://localhost:8000/tools/test_tool",
+            json={"param": "value"},
+            headers={"Content-Type": "application/json"}
+        )
+        mock_response.raise_for_status.assert_called_once()
+        
+    @patch('client.requests.get')
+    def test_get_resource(self, mock_get):
+        """Test _get_resource method"""
+        # Setup mock response
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"resource": "data"}
+        mock_response.raise_for_status = MagicMock()
+        mock_get.return_value = mock_response
+        
+        # Call method
+        result = self.client._get_resource("test-resource://identifier")
+        
+        # Assertions
+        self.assertEqual(result, {"resource": "data"})
+        mock_get.assert_called_once_with(
+            "http://localhost:8000/resources?uri=test-resource://identifier",
+            headers={"Accept": "application/json"}
+        )
+        mock_response.raise_for_status.assert_called_once()
+        
+    @patch('client.TutorXClient._call_tool')
+    def test_assess_skill(self, mock_call_tool):
+        """Test assess_skill method"""
+        # Setup mock return value
+        mock_call_tool.return_value = {"skill_level": 0.75}
+        
+        # Call method
+        result = self.client.assess_skill(self.student_id, self.concept_id)
+        
+        # Assertions
+        self.assertEqual(result, {"skill_level": 0.75})
+        mock_call_tool.assert_called_once_with("assess_skill", {
+            "student_id": self.student_id,
+            "concept_id": self.concept_id
+        })
+        
+    @patch('client.TutorXClient._get_resource')
+    def test_get_concept_graph(self, mock_get_resource):
+        """Test get_concept_graph method"""
+        # Setup mock return value
+        mock_get_resource.return_value = {"nodes": [], "edges": []}
+        
+        # Call method
+        result = self.client.get_concept_graph()
+        
+        # Assertions
+        self.assertEqual(result, {"nodes": [], "edges": []})
+        mock_get_resource.assert_called_once_with("concept-graph://")
+        
+    @patch('client.TutorXClient._call_tool')
+    def test_generate_quiz(self, mock_call_tool):
+        """Test generate_quiz method"""
+        # Setup mock return value
+        mock_call_tool.return_value = {"questions": []}
+        
+        # Call method
+        concept_ids = [self.concept_id]
+        difficulty = 3
+        result = self.client.generate_quiz(concept_ids, difficulty)
+        
+        # Assertions
+        self.assertEqual(result, {"questions": []})
+        mock_call_tool.assert_called_once_with("generate_quiz", {
+            "concept_ids": concept_ids,
+            "difficulty": difficulty
+        })
+        
+    @patch('client.requests.post')
+    def test_error_handling(self, mock_post):
+        """Test error handling in _call_tool"""
+        # Setup mock to raise exception
+        mock_post.side_effect = requests.RequestException("Connection error")
+        
+        # Call method
+        result = self.client._call_tool("test_tool", {})
+        
+        # Assertions
+        self.assertIn("error", result)
+        self.assertIn("Connection error", result["error"])
+        self.assertIn("timestamp", result)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_mcp_server.py

@@ -0,0 +1,89 @@
+"""
+Tests for the TutorX MCP server
+"""
+
+import sys
+import os
+import unittest
+import json
+from datetime import datetime
+from unittest.mock import patch, MagicMock
+
+# Add parent directory to path to import modules
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from main import assess_skill, generate_quiz, get_concept_graph
+
+
+class TestMCPServer(unittest.TestCase):
+    """Test cases for the TutorX MCP server"""
+
+    def setUp(self):
+        """Set up test fixtures"""
+        self.student_id = "test_student_123"
+        self.concept_id = "math_algebra_basics"
+        
+    def test_assess_skill(self):
+        """Test assess_skill tool"""
+        result = assess_skill(self.student_id, self.concept_id)
+        
+        # Verify the structure of the result
+        self.assertIsInstance(result, dict)
+        self.assertEqual(result["student_id"], self.student_id)
+        self.assertEqual(result["concept_id"], self.concept_id)
+        self.assertIsInstance(result["skill_level"], float)
+        self.assertIsInstance(result["confidence"], float)
+        self.assertIsInstance(result["recommendations"], list)
+        self.assertIn("timestamp", result)
+        
+    def test_generate_quiz(self):
+        """Test generate_quiz tool"""
+        concept_ids = [self.concept_id]
+        difficulty = 2
+        
+        result = generate_quiz(concept_ids, difficulty)
+        
+        # Verify the structure of the result
+        self.assertIsInstance(result, dict)
+        self.assertIn("quiz_id", result)
+        self.assertEqual(result["concept_ids"], concept_ids)
+        self.assertEqual(result["difficulty"], difficulty)
+        self.assertIsInstance(result["questions"], list)
+        self.assertGreater(len(result["questions"]), 0)
+        
+        # Check question structure
+        question = result["questions"][0]
+        self.assertIn("id", question)
+        self.assertIn("text", question)
+        self.assertIn("type", question)
+        self.assertIn("answer", question)
+        self.assertIn("solution_steps", question)
+        
+    def test_get_concept_graph(self):
+        """Test get_concept_graph resource"""
+        result = get_concept_graph()
+        
+        # Verify the structure of the result
+        self.assertIsInstance(result, dict)
+        self.assertIn("nodes", result)
+        self.assertIn("edges", result)
+        self.assertIsInstance(result["nodes"], list)
+        self.assertIsInstance(result["edges"], list)
+        self.assertGreater(len(result["nodes"]), 0)
+        self.assertGreater(len(result["edges"]), 0)
+        
+        # Check node structure
+        node = result["nodes"][0]
+        self.assertIn("id", node)
+        self.assertIn("name", node)
+        self.assertIn("difficulty", node)
+        
+        # Check edge structure
+        edge = result["edges"][0]
+        self.assertIn("from", edge)
+        self.assertIn("to", edge)
+        self.assertIn("weight", edge)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_utils.py

@@ -0,0 +1,158 @@
+"""
+Tests for TutorX MCP utility functions
+"""
+
+import sys
+import os
+import unittest
+from unittest.mock import patch, MagicMock
+
+# Add parent directory to path to import modules
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from utils.multimodal import process_text_query, process_voice_input, process_handwriting
+from utils.assessment import generate_question, evaluate_student_answer
+
+
+class TestMultimodalUtils(unittest.TestCase):
+    """Test cases for multimodal utility functions"""
+    
+    def test_process_text_query(self):
+        """Test text query processing"""
+        # Test with a "solve" query
+        solve_query = "Please solve this equation: 2x + 3 = 7"
+        result = process_text_query(solve_query)
+        
+        self.assertIsInstance(result, dict)
+        self.assertEqual(result["query"], solve_query)
+        self.assertEqual(result["response_type"], "math_solution")
+        self.assertIn("response", result)
+        self.assertIn("confidence", result)
+        self.assertIn("timestamp", result)
+        
+        # Test with "what is" query
+        what_is_query = "What is a quadratic equation?"
+        result = process_text_query(what_is_query)
+        
+        self.assertIsInstance(result, dict)
+        self.assertEqual(result["query"], what_is_query)
+        self.assertEqual(result["response_type"], "definition")
+        self.assertIn("response", result)
+        
+        # Test with unknown query
+        unknown_query = "Something completely different"
+        result = process_text_query(unknown_query)
+        
+        self.assertIsInstance(result, dict)
+        self.assertEqual(result["query"], unknown_query)
+        self.assertEqual(result["response_type"], "general")
+        self.assertIn("response", result)
+        
+    def test_process_voice_input(self):
+        """Test voice input processing"""
+        mock_audio_data = "bW9jayBhdWRpbyBkYXRh"  # Base64 for "mock audio data"
+        
+        result = process_voice_input(mock_audio_data)
+        
+        self.assertIsInstance(result, dict)
+        self.assertIn("transcription", result)
+        self.assertIn("confidence", result)
+        self.assertIn("detected_emotions", result)
+        self.assertIn("timestamp", result)
+        
+    def test_process_handwriting(self):
+        """Test handwriting recognition"""
+        mock_image_data = "bW9jayBpbWFnZSBkYXRh"  # Base64 for "mock image data"
+        
+        result = process_handwriting(mock_image_data)
+        
+        self.assertIsInstance(result, dict)
+        self.assertIn("transcription", result)
+        self.assertIn("confidence", result)
+        self.assertIn("detected_content_type", result)
+        self.assertIn("equation_type", result)
+        self.assertIn("parsed_latex", result)
+        self.assertIn("timestamp", result)
+
+
+class TestAssessmentUtils(unittest.TestCase):
+    """Test cases for assessment utility functions"""
+    
+    def test_generate_question_algebra_basics(self):
+        """Test question generation for algebra basics"""
+        concept_id = "math_algebra_basics"
+        difficulty = 2
+        
+        question = generate_question(concept_id, difficulty)
+        
+        self.assertIsInstance(question, dict)
+        self.assertIn("id", question)
+        self.assertEqual(question["concept_id"], concept_id)
+        self.assertEqual(question["difficulty"], difficulty)
+        self.assertIn("text", question)
+        self.assertIn("solution", question)
+        self.assertIn("answer", question)
+        self.assertIn("variables", question)
+    
+    def test_generate_question_linear_equations(self):
+        """Test question generation for linear equations"""
+        concept_id = "math_algebra_linear_equations"
+        difficulty = 3
+        
+        question = generate_question(concept_id, difficulty)
+        
+        self.assertIsInstance(question, dict)
+        self.assertEqual(question["concept_id"], concept_id)
+        self.assertEqual(question["difficulty"], difficulty)
+        self.assertIn("text", question)
+        self.assertIn("solution", question)
+        self.assertIn("answer", question)
+    
+    def test_evaluate_student_answer_correct(self):
+        """Test student answer evaluation - correct answer"""
+        question = {
+            "id": "q_test_123",
+            "concept_id": "math_algebra_basics",
+            "difficulty": 2,
+            "text": "Solve: x + 5 = 8",
+            "solution": "x + 5 = 8\nx = 8 - 5\nx = 3",
+            "answer": "x = 3",
+            "variables": {"a": 5, "b": 8}
+        }
+        
+        # Test correct answer
+        correct_answer = "x = 3"
+        result = evaluate_student_answer(question, correct_answer)
+        
+        self.assertIsInstance(result, dict)
+        self.assertEqual(result["question_id"], question["id"])
+        self.assertTrue(result["is_correct"])
+        self.assertIsNone(result["error_type"])
+        self.assertEqual(result["correct_answer"], question["answer"])
+        self.assertEqual(result["student_answer"], correct_answer)
+        
+    def test_evaluate_student_answer_incorrect(self):
+        """Test student answer evaluation - incorrect answer"""
+        question = {
+            "id": "q_test_456",
+            "concept_id": "math_algebra_linear_equations",
+            "difficulty": 3,
+            "text": "Solve: 2x + 3 = 9",
+            "solution": "2x + 3 = 9\n2x = 9 - 3\n2x = 6\nx = 6/2\nx = 3",
+            "answer": "x = 3",
+            "variables": {"a": 2, "b": 3, "c": 9}
+        }
+        
+        # Test incorrect answer
+        incorrect_answer = "x = 4"
+        result = evaluate_student_answer(question, incorrect_answer)
+        
+        self.assertIsInstance(result, dict)
+        self.assertEqual(result["question_id"], question["id"])
+        self.assertFalse(result["is_correct"])
+        self.assertEqual(result["correct_answer"], question["answer"])
+        self.assertEqual(result["student_answer"], incorrect_answer)
+
+
+if __name__ == "__main__":
+    unittest.main()

utils/gamification.py

@@ -0,0 +1,306 @@
+"""
+Gamification utilities for the TutorX MCP server
+"""
+
+from typing import Dict, Any, List, Optional
+from datetime import datetime
+import random
+
+
+# Dictionary to store badges for students
+# In a real application, this would be stored in a database
+BADGES_DB = {}
+
+# Dictionary to store leaderboards
+# In a real application, this would be stored in a database
+LEADERBOARDS_DB = {
+    "weekly_points": {},
+    "monthly_streak": {},
+    "problem_solving_speed": {}
+}
+
+# Badge definitions
+BADGES = {
+    "beginner": {
+        "name": "Beginner",
+        "description": "Completed your first lesson",
+        "icon": "🔰",
+        "points": 10
+    },
+    "persistent": {
+        "name": "Persistent Learner",
+        "description": "Completed 5 lessons in a row",
+        "icon": "🔄",
+        "points": 25
+    },
+    "math_whiz": {
+        "name": "Math Whiz",
+        "description": "Scored 100% on a math assessment",
+        "icon": "🧮",
+        "points": 50
+    },
+    "science_explorer": {
+        "name": "Science Explorer",
+        "description": "Completed 10 science modules",
+        "icon": "🔬",
+        "points": 50
+    },
+    "speed_demon": {
+        "name": "Speed Demon",
+        "description": "Solved 5 problems in under 2 minutes each",
+        "icon": "⚡",
+        "points": 35
+    },
+    "accuracy_master": {
+        "name": "Accuracy Master",
+        "description": "Maintained 90% accuracy over 20 problems",
+        "icon": "🎯",
+        "points": 40
+    },
+    "helping_hand": {
+        "name": "Helping Hand",
+        "description": "Helped 5 other students in the forum",
+        "icon": "🤝",
+        "points": 30
+    },
+    "night_owl": {
+        "name": "Night Owl",
+        "description": "Studied for 3 hours after 8 PM",
+        "icon": "🌙",
+        "points": 20
+    },
+    "early_bird": {
+        "name": "Early Bird",
+        "description": "Studied for 3 hours before 9 AM",
+        "icon": "🌅",
+        "points": 20
+    },
+    "perfect_streak": {
+        "name": "Perfect Streak",
+        "description": "Logged in for 7 days straight",
+        "icon": "🔥",
+        "points": 45
+    }
+}
+
+
+def award_badge(student_id: str, badge_id: str) -> Dict[str, Any]:
+    """
+    Award a badge to a student
+    
+    Args:
+        student_id: The student's unique identifier
+        badge_id: The badge's unique identifier
+        
+    Returns:
+        Badge information
+    """
+    if badge_id not in BADGES:
+        return {
+            "error": "Invalid badge ID",
+            "timestamp": datetime.now().isoformat()
+        }
+    
+    if student_id not in BADGES_DB:
+        BADGES_DB[student_id] = {}
+    
+    # Check if student already has the badge
+    if badge_id in BADGES_DB[student_id]:
+        return {
+            "message": "Badge already awarded",
+            "badge": BADGES[badge_id],
+            "timestamp": BADGES_DB[student_id][badge_id]["timestamp"]
+        }
+    
+    # Award the badge
+    BADGES_DB[student_id][badge_id] = {
+        "timestamp": datetime.now().isoformat()
+    }
+    
+    return {
+        "message": "Badge awarded!",
+        "badge": BADGES[badge_id],
+        "timestamp": datetime.now().isoformat()
+    }
+
+
+def get_student_badges(student_id: str) -> Dict[str, Any]:
+    """
+    Get all badges for a student
+    
+    Args:
+        student_id: The student's unique identifier
+        
+    Returns:
+        Dictionary of badges and points
+    """
+    if student_id not in BADGES_DB or not BADGES_DB[student_id]:
+        return {
+            "student_id": student_id,
+            "badges": [],
+            "total_points": 0,
+            "timestamp": datetime.now().isoformat()
+        }
+    
+    badges_list = []
+    total_points = 0
+    
+    for badge_id in BADGES_DB[student_id]:
+        if badge_id in BADGES:
+            badge_info = BADGES[badge_id].copy()
+            badge_info["awarded_at"] = BADGES_DB[student_id][badge_id]["timestamp"]
+            badges_list.append(badge_info)
+            total_points += badge_info["points"]
+    
+    return {
+        "student_id": student_id,
+        "badges": badges_list,
+        "total_points": total_points,
+        "timestamp": datetime.now().isoformat()
+    }
+
+
+def update_leaderboard(leaderboard_id: str, student_id: str, score: float) -> Dict[str, Any]:
+    """
+    Update a leaderboard with a new score for a student
+    
+    Args:
+        leaderboard_id: The leaderboard to update
+        student_id: The student's unique identifier
+        score: The score to record
+        
+    Returns:
+        Updated leaderboard information
+    """
+    if leaderboard_id not in LEADERBOARDS_DB:
+        return {
+            "error": "Invalid leaderboard ID",
+            "timestamp": datetime.now().isoformat()
+        }
+    
+    # Update student's score
+    LEADERBOARDS_DB[leaderboard_id][student_id] = {
+        "score": score,
+        "timestamp": datetime.now().isoformat()
+    }
+    
+    # Get top 10 students
+    top_students = sorted(
+        LEADERBOARDS_DB[leaderboard_id].items(),
+        key=lambda x: x[1]["score"],
+        reverse=True
+    )[:10]
+    
+    # Format leaderboard
+    leaderboard = []
+    for i, (sid, data) in enumerate(top_students):
+        leaderboard.append({
+            "rank": i + 1,
+            "student_id": sid,
+            "score": data["score"],
+            "last_updated": data["timestamp"]
+        })
+    
+    # Find student's rank
+    student_rank = next(
+        (i + 1 for i, (sid, _) in enumerate(top_students) if sid == student_id),
+        len(LEADERBOARDS_DB[leaderboard_id]) + 1
+    )
+    
+    return {
+        "leaderboard_id": leaderboard_id,
+        "leaderboard": leaderboard,
+        "student_rank": student_rank,
+        "student_score": score,
+        "timestamp": datetime.now().isoformat()
+    }
+
+
+def get_leaderboard(leaderboard_id: str) -> Dict[str, Any]:
+    """
+    Get the current state of a leaderboard
+    
+    Args:
+        leaderboard_id: The leaderboard to get
+        
+    Returns:
+        Leaderboard information
+    """
+    if leaderboard_id not in LEADERBOARDS_DB:
+        return {
+            "error": "Invalid leaderboard ID",
+            "timestamp": datetime.now().isoformat()
+        }
+    
+    # Get top 10 students
+    top_students = sorted(
+        LEADERBOARDS_DB[leaderboard_id].items(),
+        key=lambda x: x[1]["score"],
+        reverse=True
+    )[:10]
+    
+    # Format leaderboard
+    leaderboard = []
+    for i, (sid, data) in enumerate(top_students):
+        leaderboard.append({
+            "rank": i + 1,
+            "student_id": sid,
+            "score": data["score"],
+            "last_updated": data["timestamp"]
+        })
+    
+    return {
+        "leaderboard_id": leaderboard_id,
+        "leaderboard": leaderboard,
+        "total_students": len(LEADERBOARDS_DB[leaderboard_id]),
+        "timestamp": datetime.now().isoformat()
+    }
+
+
+def check_achievements(student_id: str, activity_data: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """
+    Check if a student's activity unlocks any new badges
+    
+    Args:
+        student_id: The student's unique identifier
+        activity_data: Data about the student's activity
+        
+    Returns:
+        List of newly awarded badges
+    """
+    new_badges = []
+    
+    # Initialize student badge record if needed
+    if student_id not in BADGES_DB:
+        BADGES_DB[student_id] = {}
+    
+    # Check for potential badge earnings based on activity
+    if "activity_type" in activity_data:
+        activity_type = activity_data["activity_type"]
+        
+        # Beginner badge - first lesson
+        if activity_type == "lesson_completed" and "beginner" not in BADGES_DB[student_id]:
+            badge_result = award_badge(student_id, "beginner")
+            if "error" not in badge_result:
+                new_badges.append(badge_result)
+        
+        # Math Whiz - perfect math assessment
+        if (activity_type == "assessment_completed" and 
+            activity_data.get("subject") == "math" and 
+            activity_data.get("score") == 1.0 and
+            "math_whiz" not in BADGES_DB[student_id]):
+            badge_result = award_badge(student_id, "math_whiz")
+            if "error" not in badge_result:
+                new_badges.append(badge_result)
+        
+        # Speed Demon - fast problem solving
+        if (activity_type == "problem_solved" and 
+            activity_data.get("time_seconds", 999) < 120):
+            # In a real system, we'd track the count over time
+            # Here we'll simulate it
+            if random.random() < 0.2 and "speed_demon" not in BADGES_DB[student_id]:
+                badge_result = award_badge(student_id, "speed_demon")
+                if "error" not in badge_result:
+                    new_badges.append(badge_result)
+    
+    return new_badges

utils/integrations.py

@@ -0,0 +1,251 @@
+"""
+Integration utilities for connecting TutorX-MCP with external educational systems
+"""
+
+import requests
+import json
+import os
+from typing import Dict, Any, List, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+class LMSIntegration:
+    """Integration with Learning Management Systems (Canvas, Moodle, etc.)"""
+    
+    def __init__(self, lms_type: str, api_url: str, api_key: str):
+        """
+        Initialize LMS integration
+        
+        Args:
+            lms_type: Type of LMS ('canvas', 'moodle', 'blackboard', etc.)
+            api_url: Base URL for LMS API
+            api_key: API key or token for authentication
+        """
+        self.lms_type = lms_type.lower()
+        self.api_url = api_url.rstrip('/')
+        self.api_key = api_key
+        
+    def get_courses(self) -> List[Dict[str, Any]]:
+        """Get list of courses from LMS"""
+        if self.lms_type == 'canvas':
+            return self._canvas_get_courses()
+        elif self.lms_type == 'moodle':
+            return self._moodle_get_courses()
+        else:
+            raise ValueError(f"Unsupported LMS type: {self.lms_type}")
+            
+    def _canvas_get_courses(self) -> List[Dict[str, Any]]:
+        """Get courses from Canvas LMS"""
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        response = requests.get(f"{self.api_url}/courses", headers=headers)
+        response.raise_for_status()
+        return response.json()
+        
+    def _moodle_get_courses(self) -> List[Dict[str, Any]]:
+        """Get courses from Moodle"""
+        params = {
+            "wstoken": self.api_key,
+            "wsfunction": "core_course_get_courses",
+            "moodlewsrestformat": "json"
+        }
+        response = requests.get(f"{self.api_url}/webservice/rest/server.php", params=params)
+        response.raise_for_status()
+        return response.json()
+        
+    def sync_grades(self, course_id: str, assignment_id: str, grades: List[Dict[str, Any]]) -> bool:
+        """
+        Sync grades to LMS
+        
+        Args:
+            course_id: ID of the course
+            assignment_id: ID of the assignment
+            grades: List of grade data to sync
+            
+        Returns:
+            Success status
+        """
+        try:
+            if self.lms_type == 'canvas':
+                return self._canvas_sync_grades(course_id, assignment_id, grades)
+            elif self.lms_type == 'moodle':
+                return self._moodle_sync_grades(course_id, assignment_id, grades)
+            else:
+                raise ValueError(f"Unsupported LMS type: {self.lms_type}")
+        except Exception as e:
+            logger.error(f"Error syncing grades: {e}")
+            return False
+            
+    def _canvas_sync_grades(self, course_id: str, assignment_id: str, grades: List[Dict[str, Any]]) -> bool:
+        """Sync grades to Canvas LMS"""
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+        
+        for grade in grades:
+            data = {
+                "submission": {
+                    "posted_grade": grade["score"]
+                }
+            }
+            
+            url = f"{self.api_url}/courses/{course_id}/assignments/{assignment_id}/submissions/{grade['student_id']}"
+            response = requests.put(url, json=data, headers=headers)
+            
+            if response.status_code != 200:
+                logger.error(f"Failed to sync grade for student {grade['student_id']}: {response.text}")
+                return False
+                
+        return True
+        
+    def _moodle_sync_grades(self, course_id: str, assignment_id: str, grades: List[Dict[str, Any]]) -> bool:
+        """Sync grades to Moodle"""
+        # Implementation specific to Moodle's API
+        # This would use the Moodle grade update API
+        return True  # Placeholder
+        
+class OERIntegration:
+    """Integration with Open Educational Resources repositories"""
+    
+    def __init__(self, repository_url: str, api_key: Optional[str] = None):
+        """
+        Initialize OER repository integration
+        
+        Args:
+            repository_url: Base URL for OER repository API
+            api_key: Optional API key if required by the repository
+        """
+        self.repository_url = repository_url.rstrip('/')
+        self.api_key = api_key
+        
+    def search_resources(self, query: str, subject: Optional[str] = None, 
+                        grade_level: Optional[str] = None) -> List[Dict[str, Any]]:
+        """
+        Search for educational resources
+        
+        Args:
+            query: Search query
+            subject: Optional subject filter
+            grade_level: Optional grade level filter
+            
+        Returns:
+            List of matching resources
+        """
+        params = {"q": query}
+        
+        if subject:
+            params["subject"] = subject
+            
+        if grade_level:
+            params["grade"] = grade_level
+            
+        headers = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+            
+        response = requests.get(f"{self.repository_url}/search", params=params, headers=headers)
+        response.raise_for_status()
+        
+        return response.json().get("results", [])
+        
+    def get_resource(self, resource_id: str) -> Dict[str, Any]:
+        """
+        Get details for a specific resource
+        
+        Args:
+            resource_id: ID of the resource to fetch
+            
+        Returns:
+            Resource details
+        """
+        headers = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+            
+        response = requests.get(f"{self.repository_url}/resources/{resource_id}", headers=headers)
+        response.raise_for_status()
+        
+        return response.json()
+        
+
+class RTPTIntegration:
+    """Integration with real-time personalized tutoring platforms"""
+    
+    def __init__(self, platform_url: str, client_id: str, client_secret: str):
+        """
+        Initialize RTPT integration
+        
+        Args:
+            platform_url: Base URL for RTPT platform API
+            client_id: OAuth client ID
+            client_secret: OAuth client secret
+        """
+        self.platform_url = platform_url.rstrip('/')
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self._access_token = None
+        
+    def _get_access_token(self) -> str:
+        """Get OAuth access token"""
+        if self._access_token:
+            return self._access_token
+            
+        data = {
+            "grant_type": "client_credentials",
+            "client_id": self.client_id,
+            "client_secret": self.client_secret
+        }
+        
+        response = requests.post(f"{self.platform_url}/oauth/token", data=data)
+        response.raise_for_status()
+        
+        token_data = response.json()
+        self._access_token = token_data["access_token"]
+        return self._access_token
+        
+    def get_available_tutors(self, subject: str, level: str) -> List[Dict[str, Any]]:
+        """
+        Get available tutors for a subject and level
+        
+        Args:
+            subject: Academic subject
+            level: Academic level
+            
+        Returns:
+            List of available tutors
+        """
+        headers = {"Authorization": f"Bearer {self._get_access_token()}"}
+        params = {
+            "subject": subject,
+            "level": level
+        }
+        
+        response = requests.get(f"{self.platform_url}/tutors/available", params=params, headers=headers)
+        response.raise_for_status()
+        
+        return response.json()
+        
+    def schedule_session(self, student_id: str, tutor_id: str, 
+                        subject: str, datetime_str: str) -> Dict[str, Any]:
+        """
+        Schedule a tutoring session
+        
+        Args:
+            student_id: ID of the student
+            tutor_id: ID of the tutor
+            subject: Subject for tutoring
+            datetime_str: ISO format datetime for the session
+            
+        Returns:
+            Session details
+        """
+        headers = {"Authorization": f"Bearer {self._get_access_token()}"}
+        data = {
+            "student_id": student_id,
+            "tutor_id": tutor_id,
+            "subject": subject,
+            "datetime": datetime_str
+        }
+        
+        response = requests.post(f"{self.platform_url}/sessions", json=data, headers=headers)
+        response.raise_for_status()
+        
+        return response.json()