Hugging Face's logo

Spaces:
RedRepter
/
TutorX-MCP
Sleeping

App Files Community
TutorX-MCP / docs /api.md
Meet Patel
Added external tool integration,also with test files and documentation
411f252
preview code
|
raw
history blame
7.38 kB

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.

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:

{
  "student_id": "student123",
  "concept_id": "math_algebra_basics"
}

Response:

{
  "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:

{
  "concept_ids": ["math_algebra_basics", "math_algebra_linear_equations"],
  "difficulty": 2
}

Response:

{
  "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:

{
  "student_id": "student123",
  "concept_id": "math_algebra_basics"
}

Response:

{
  "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:

{
  "eeg_data": {
    "channels": [...],
    "sampling_rate": 256,
    "duration": 10.0
  }
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "repository_url": "https://oer.example.com/api",
  "query": "linear equations",
  "subject": "mathematics",
  "grade_level": "8"
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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):

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]