OpenEdu MCP Server

A comprehensive Model Context Protocol (MCP) server designed to provide educational resources and support curriculum planning for educators. This server integrates with multiple educational APIs to provide access to books, articles, definitions, and research papers with intelligent educational filtering and grade-level appropriateness.

🎓 Features

Complete API Integration Suite

📚 Open Library Integration: Educational book search, recommendations, and metadata
🌐 Wikipedia Integration: Educational article analysis with grade-level filtering
📖 Dictionary Integration: Vocabulary analysis and language learning support
🔬 arXiv Integration: Academic paper search with educational relevance scoring

Educational Intelligence

Grade Level Filtering: K-2, 3-5, 6-8, 9-12, College level content
Subject Classification: Mathematics, Science, ELA, Social Studies, Arts, PE, Technology
Curriculum Alignment: Common Core, NGSS, State Standards support
Educational Metadata: Complexity scoring, reading levels, educational value assessment

Performance & Reliability

Intelligent Caching: SQLite-based caching with TTL support
Rate Limiting: Built-in rate limiting to respect API quotas
Usage Analytics: Comprehensive usage tracking and performance metrics
Error Handling: Robust error handling with educational context preservation

🚀 Quick Start

Prerequisites

Python 3.9 or higher
pip package manager

Installation

Clone the repository:

git clone https://github.com/Cicatriiz/openedu-mcp.git cd openedu-mcp

Install dependencies:

pip install -r requirements.txt

Set up configuration:

cp .env.example .env # Edit .env with your preferred settings if needed

Run the server:

python -m src.main

Test the installation:

python run_validation_tests.py

Development Setup

For development, install additional dependencies:

pip install -r requirements-dev.txt

Run tests:

# Unit tests pytest tests/ # Integration tests pytest tests/test_integration/ # Performance tests pytest tests/test_performance.py

Format code:

black src tests isort src tests

🛠️ MCP Tools Reference

The Education MCP Server provides 21+ MCP tools across four API integrations:

📚 Open Library Tools (4 tools)

`search_educational_books`

Search for educational books with grade-level and subject filtering.

search_educational_books( query="mathematics", subject="Mathematics", grade_level="6-8", limit=10 )

`get_book_details_by_isbn`

Get detailed book information by ISBN with educational metadata.

get_book_details_by_isbn( isbn="9780134685991", include_cover=True )

`search_books_by_subject`

Search books by educational subject with curriculum alignment.

search_books_by_subject( subject="Science", grade_level="3-5", limit=10 )

`get_book_recommendations`

Get curated book recommendations for specific grade levels.

get_book_recommendations( grade_level="9-12", subject="Physics", limit=5 )

🌐 Wikipedia Tools (5 tools)

`search_educational_articles`

Search Wikipedia articles with educational filtering and analysis.

search_educational_articles( query="photosynthesis", grade_level="3-5", subject="Science", limit=5 )

`get_article_summary`

Get article summaries with educational metadata and complexity analysis.

get_article_summary( title="Solar System", include_educational_analysis=True )

`get_article_content`

Get full article content with educational enrichment.

get_article_content( title="Photosynthesis", include_images=True )

`get_featured_article`

Get Wikipedia's featured article with educational analysis.

get_featured_article( date="2024/01/15", language="en" )

`get_articles_by_subject`

Get articles by educational subject with grade-level filtering.

get_articles_by_subject( subject="Mathematics", grade_level="6-8", limit=10 )

📖 Dictionary Tools (5 tools)

`get_word_definition`

Get educational word definitions with grade-appropriate complexity.

get_word_definition( word="ecosystem", grade_level="6-8", include_pronunciation=True )

`get_vocabulary_analysis`

Analyze word complexity and educational value.

get_vocabulary_analysis( word="photosynthesis", context="plant biology lesson" )

`get_word_examples`

Get educational examples and usage contexts for vocabulary.

get_word_examples( word="fraction", grade_level="3-5", subject="Mathematics" )

`get_pronunciation_guide`

Get phonetic information and pronunciation guides.

get_pronunciation_guide( word="photosynthesis", include_audio=True )

`get_related_vocabulary`

Get synonyms, antonyms, and related educational terms.

get_related_vocabulary( word="democracy", relationship_type="related", grade_level="9-12", limit=10 )

🔬 arXiv Tools (5 tools)

`search_academic_papers`

Search academic papers with educational relevance filtering.

search_academic_papers( query="machine learning education", academic_level="Undergraduate", subject="Computer Science", max_results=10 )

`get_paper_summary`

Get paper summaries with educational analysis and accessibility scoring.

get_paper_summary( paper_id="2301.00001", include_educational_analysis=True )

`get_recent_research`

Get recent research papers by educational subject.

get_recent_research( subject="Physics", days=30, academic_level="High School", max_results=5 )

`get_research_by_level`

Get research papers appropriate for specific academic levels.

get_research_by_level( academic_level="Graduate", subject="Mathematics", max_results=10 )

`analyze_research_trends`

Analyze research trends for educational insights.

analyze_research_trends( subject="Artificial Intelligence", days=90 )

🖥️ Server Tools (1 tool)

`get_server_status`

Get comprehensive server status and performance metrics.

get_server_status()

🔌 Connectivity Endpoints

This section details how to interact with the OpenEdu MCP Server through various interfaces, including direct standard I/O, HTTP for tool execution, and Server-Sent Events for real-time updates.

Stdio Tool (`handle_stdio_input`)

The server includes a tool designed for direct command-line or piped input.

Tool Name: handle_stdio_input
Description: Processes a single line of text input and returns a transformed version. This is useful for basic interaction or scripting with the MCP server if it's configured to listen to stdin.
Signature: async def handle_stdio_input(ctx: Context, input_string: str) -> str
Example Interaction:
Tool: handle_stdio_input Input: "your text here" Output: "Processed: YOUR TEXT HERE"

HTTP Endpoint for MCP Tools

All registered MCP tools (including handle_stdio_input and the 20+ tools listed above) are accessible via HTTP. This allows integration with various applications and services. The server likely uses a JSON RPC style for these interactions.

Endpoint: POST /mcp (This is a common convention for FastMCP servers supporting JSON RPC)
Request Method: POST
Headers: Content-Type: application/json
Request Body Structure (JSON RPC):
{ "jsonrpc": "2.0", "method": "<tool_name>", "params": {"param1": "value1", ...}, "id": "your_request_id" }
Example :
curl -X POST -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "method": "handle_stdio_input", "params": {"input_string": "hello from http"}, "id": 1}' \ http://localhost:8000/mcp
Expected Response:
{ "jsonrpc": "2.0", "result": "Processed: HELLO FROM HTTP", "id": 1 }
If an error occurs, the result field will be replaced by an error object containing code and message.

Server-Sent Events (SSE) Endpoint

The server provides an SSE endpoint for real-time notifications. This is useful for clients that need to stay updated with server-initiated events.

Endpoint: GET /events
Description: Streams events from the server to the client.
Event Format: Each event is sent as a block of text:
event: <event_type> data: <json_payload_of_the_event_data> id: <optional_event_id>
(Note: An empty line separates events.)
Known Events:
- connected: Sent once when the client successfully connects to the SSE stream.
  - data: {"message": "Successfully connected to SSE stream"}
- ping: Sent periodically as a heartbeat to keep the connection alive and indicate server health.
  - data: {"heartbeat": <loop_count>, "message": "ping"} (loop_count increments)
- error: Sent if an error occurs within the SSE generation stream.
  - data: {"error": "<error_message>"}
Example: Connecting with JavaScript's :
const evtSource = new EventSource("http://localhost:8000/events"); evtSource.onopen = function() { console.log("Connection to SSE opened."); }; evtSource.onmessage = function(event) { // Generic message handler if no specific event type is matched console.log("Generic message:", event.data); try { const parsedData = JSON.parse(event.data); console.log("Parsed generic data:", parsedData); } catch (e) { // Data might not be JSON } }; evtSource.addEventListener("connected", function(event) { console.log("Event: connected"); console.log("Data:", JSON.parse(event.data)); }); evtSource.addEventListener("ping", function(event) { console.log("Event: ping"); console.log("Data:", JSON.parse(event.data)); }); evtSource.addEventListener("error", function(event) { if (event.target.readyState === EventSource.CLOSED) { console.error("SSE Connection was closed.", event); } else if (event.target.readyState === EventSource.CONNECTING) { console.error("SSE Connection is reconnecting...", event); } else { // An error occurred while streaming, data might be available console.error("SSE Error:", event); if (event.data) { try { console.error("Error Data:", JSON.parse(event.data)); } catch (e) { console.error("Error Data (raw):", event.data); } } } });
Example: Connecting with :
curl -N -H "Accept:text/event-stream" http://localhost:8000/events
(Note:

💻 Editor & AI Tool Integration

You can integrate the OpenEdu MCP Server with various AI-assisted coding tools and IDE plugins. This allows these tools to leverage the server's educational functionalities directly within your development environment. Configuration typically involves telling the editor how to start and communicate with the OpenEdu MCP server. The server is run using python -m src.main from the root of this project.

Below are example configurations for some popular tools. You may need to adjust paths (e.g., for cwd or if you have a specific Python environment) based on your local setup.