{"id":28805909,"url":"https://github.com/cicatriiz/openedu-mcp","last_synced_at":"2026-04-30T06:32:53.375Z","repository":{"id":297057794,"uuid":"993541483","full_name":"Cicatriiz/openedu-mcp","owner":"Cicatriiz","description":"OpenEdu MCP Server for educational resources and curriculum planning, integrates with OpenLibrary, Wikipedia and arXiv","archived":false,"fork":false,"pushed_at":"2025-06-03T22:11:23.000Z","size":291,"stargazers_count":7,"open_issues_count":1,"forks_count":9,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T06:32:38.193Z","etag":null,"topics":["ai","arxiv-api","fastapi","mcp","mcp-server","mcp-servers","model-context-protocol","modelcontextprotocol","oer","oer-resources","open-education","open-educational-resources","open-library-api","python","wikipedia-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cicatriiz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-31T01:30:57.000Z","updated_at":"2026-03-22T19:41:31.000Z","dependencies_parsed_at":"2025-06-04T02:03:35.295Z","dependency_job_id":"99c85a0e-449d-4c1c-9d19-5fb191d48f2a","html_url":"https://github.com/Cicatriiz/openedu-mcp","commit_stats":null,"previous_names":["cicatriiz/openedu-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Cicatriiz/openedu-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cicatriiz%2Fopenedu-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cicatriiz%2Fopenedu-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cicatriiz%2Fopenedu-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cicatriiz%2Fopenedu-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cicatriiz","download_url":"https://codeload.github.com/Cicatriiz/openedu-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cicatriiz%2Fopenedu-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32457110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","arxiv-api","fastapi","mcp","mcp-server","mcp-servers","model-context-protocol","modelcontextprotocol","oer","oer-resources","open-education","open-educational-resources","open-library-api","python","wikipedia-api"],"created_at":"2025-06-18T10:43:44.918Z","updated_at":"2026-04-30T06:32:53.368Z","avatar_url":"https://github.com/Cicatriiz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenEdu MCP Server\n\nA 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.\n\n## 🎓 Features\n\n### Complete API Integration Suite\n- **📚 Open Library Integration**: Educational book search, recommendations, and metadata\n- **🌐 Wikipedia Integration**: Educational article analysis with grade-level filtering\n- **📖 Dictionary Integration**: Vocabulary analysis and language learning support\n- **🔬 arXiv Integration**: Academic paper search with educational relevance scoring\n\n### Educational Intelligence\n- **Grade Level Filtering**: K-2, 3-5, 6-8, 9-12, College level content\n- **Subject Classification**: Mathematics, Science, ELA, Social Studies, Arts, PE, Technology\n- **Curriculum Alignment**: Common Core, NGSS, State Standards support\n- **Educational Metadata**: Complexity scoring, reading levels, educational value assessment\n\n### Performance \u0026 Reliability\n- **Intelligent Caching**: SQLite-based caching with TTL support\n- **Rate Limiting**: Built-in rate limiting to respect API quotas\n- **Usage Analytics**: Comprehensive usage tracking and performance metrics\n- **Error Handling**: Robust error handling with educational context preservation\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.9 or higher\n- pip package manager\n\n### Installation\n\n1. **Clone the repository:**\n```bash\ngit clone https://github.com/Cicatriiz/openedu-mcp.git\ncd openedu-mcp\n```\n\n2. **Install dependencies:**\n```bash\npip install -r requirements.txt\n```\n\n3. **Set up configuration:**\n```bash\ncp .env.example .env\n# Edit .env with your preferred settings if needed\n```\n\n4. **Run the server:**\n```bash\npython -m src.main\n```\n\n5. **Test the installation:**\n```bash\n   python run_validation_tests.py\n```\n\n### Development Setup\n\nFor development, install additional dependencies:\n```bash\npip install -r requirements-dev.txt\n```\n\nRun tests:\n```bash\n# Unit tests\npytest tests/\n\n# Integration tests\npytest tests/test_integration/\n\n# Performance tests\npytest tests/test_performance.py\n```\n\nFormat code:\n```bash\nblack src tests\nisort src tests\n```\n\n## 🛠️ MCP Tools Reference\n\nThe Education MCP Server provides **21+ MCP tools** across four API integrations:\n\n### 📚 Open Library Tools (4 tools)\n\n#### `search_educational_books`\nSearch for educational books with grade-level and subject filtering.\n```python\nsearch_educational_books(\n    query=\"mathematics\",\n    subject=\"Mathematics\", \n    grade_level=\"6-8\",\n    limit=10\n)\n```\n\n#### `get_book_details_by_isbn`\nGet detailed book information by ISBN with educational metadata.\n```python\nget_book_details_by_isbn(\n    isbn=\"9780134685991\",\n    include_cover=True\n)\n```\n\n#### `search_books_by_subject`\nSearch books by educational subject with curriculum alignment.\n```python\nsearch_books_by_subject(\n    subject=\"Science\",\n    grade_level=\"3-5\",\n    limit=10\n)\n```\n\n#### `get_book_recommendations`\nGet curated book recommendations for specific grade levels.\n```python\nget_book_recommendations(\n    grade_level=\"9-12\",\n    subject=\"Physics\",\n    limit=5\n)\n```\n\n### 🌐 Wikipedia Tools (5 tools)\n\n#### `search_educational_articles`\nSearch Wikipedia articles with educational filtering and analysis.\n```python\nsearch_educational_articles(\n    query=\"photosynthesis\",\n    grade_level=\"3-5\",\n    subject=\"Science\",\n    limit=5\n)\n```\n\n#### `get_article_summary`\nGet article summaries with educational metadata and complexity analysis.\n```python\nget_article_summary(\n    title=\"Solar System\",\n    include_educational_analysis=True\n)\n```\n\n#### `get_article_content`\nGet full article content with educational enrichment.\n```python\nget_article_content(\n    title=\"Photosynthesis\",\n    include_images=True\n)\n```\n\n#### `get_featured_article`\nGet Wikipedia's featured article with educational analysis.\n```python\nget_featured_article(\n    date=\"2024/01/15\",\n    language=\"en\"\n)\n```\n\n#### `get_articles_by_subject`\nGet articles by educational subject with grade-level filtering.\n```python\nget_articles_by_subject(\n    subject=\"Mathematics\",\n    grade_level=\"6-8\",\n    limit=10\n)\n```\n\n### 📖 Dictionary Tools (5 tools)\n\n#### `get_word_definition`\nGet educational word definitions with grade-appropriate complexity.\n```python\nget_word_definition(\n    word=\"ecosystem\",\n    grade_level=\"6-8\",\n    include_pronunciation=True\n)\n```\n\n#### `get_vocabulary_analysis`\nAnalyze word complexity and educational value.\n```python\nget_vocabulary_analysis(\n    word=\"photosynthesis\",\n    context=\"plant biology lesson\"\n)\n```\n\n#### `get_word_examples`\nGet educational examples and usage contexts for vocabulary.\n```python\nget_word_examples(\n    word=\"fraction\",\n    grade_level=\"3-5\",\n    subject=\"Mathematics\"\n)\n```\n\n#### `get_pronunciation_guide`\nGet phonetic information and pronunciation guides.\n```python\nget_pronunciation_guide(\n    word=\"photosynthesis\",\n    include_audio=True\n)\n```\n\n#### `get_related_vocabulary`\nGet synonyms, antonyms, and related educational terms.\n```python\nget_related_vocabulary(\n    word=\"democracy\",\n    relationship_type=\"related\",\n    grade_level=\"9-12\",\n    limit=10\n)\n```\n\n### 🔬 arXiv Tools (5 tools)\n\n#### `search_academic_papers`\nSearch academic papers with educational relevance filtering.\n```python\nsearch_academic_papers(\n    query=\"machine learning education\",\n    academic_level=\"Undergraduate\",\n    subject=\"Computer Science\",\n    max_results=10\n)\n```\n\n#### `get_paper_summary`\nGet paper summaries with educational analysis and accessibility scoring.\n```python\nget_paper_summary(\n    paper_id=\"2301.00001\",\n    include_educational_analysis=True\n)\n```\n\n#### `get_recent_research`\nGet recent research papers by educational subject.\n```python\nget_recent_research(\n    subject=\"Physics\",\n    days=30,\n    academic_level=\"High School\",\n    max_results=5\n)\n```\n\n#### `get_research_by_level`\nGet research papers appropriate for specific academic levels.\n```python\nget_research_by_level(\n    academic_level=\"Graduate\",\n    subject=\"Mathematics\",\n    max_results=10\n)\n```\n\n#### `analyze_research_trends`\nAnalyze research trends for educational insights.\n```python\nanalyze_research_trends(\n    subject=\"Artificial Intelligence\",\n    days=90\n)\n```\n\n### 🖥️ Server Tools (1 tool)\n\n#### `get_server_status`\nGet comprehensive server status and performance metrics.\n```python\nget_server_status()\n```\n\n## 🔌 Connectivity Endpoints\n\nThis 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.\n\n### Stdio Tool (`handle_stdio_input`)\n\nThe server includes a tool designed for direct command-line or piped input.\n\n- **Tool Name**: `handle_stdio_input`\n- **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.\n- **Signature**: `async def handle_stdio_input(ctx: Context, input_string: str) -\u003e str`\n- **Example Interaction**:\n    ```\n    Tool: handle_stdio_input\n    Input: \"your text here\"\n    Output: \"Processed: YOUR TEXT HERE\"\n    ```\n\n### HTTP Endpoint for MCP Tools\n\nAll 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.\n\n- **Endpoint**: `POST /mcp` (This is a common convention for FastMCP servers supporting JSON RPC)\n- **Request Method**: `POST`\n- **Headers**: `Content-Type: application/json`\n- **Request Body Structure (JSON RPC)**:\n    ```json\n    {\n        \"jsonrpc\": \"2.0\",\n        \"method\": \"\u003ctool_name\u003e\",\n        \"params\": {\"param1\": \"value1\", ...},\n        \"id\": \"your_request_id\"\n    }\n    ```\n\n- **Example `curl` call to `handle_stdio_input`**:\n    ```bash\n    curl -X POST -H \"Content-Type: application/json\" \\\n         -d '{\"jsonrpc\": \"2.0\", \"method\": \"handle_stdio_input\", \"params\": {\"input_string\": \"hello from http\"}, \"id\": 1}' \\\n         http://localhost:8000/mcp\n    ```\n\n- **Expected Response**:\n    ```json\n    {\n        \"jsonrpc\": \"2.0\",\n        \"result\": \"Processed: HELLO FROM HTTP\",\n        \"id\": 1\n    }\n    ```\n    If an error occurs, the `result` field will be replaced by an `error` object containing `code` and `message`.\n\n### Server-Sent Events (SSE) Endpoint\n\nThe server provides an SSE endpoint for real-time notifications. This is useful for clients that need to stay updated with server-initiated events.\n\n- **Endpoint**: `GET /events`\n- **Description**: Streams events from the server to the client.\n- **Event Format**: Each event is sent as a block of text:\n    ```\n    event: \u003cevent_type\u003e\n    data: \u003cjson_payload_of_the_event_data\u003e\n    id: \u003coptional_event_id\u003e\n\n    ```\n    (Note: An empty line separates events.)\n\n- **Known Events**:\n    - **`connected`**: Sent once when the client successfully connects to the SSE stream.\n        - `data`: `{\"message\": \"Successfully connected to SSE stream\"}`\n    - **`ping`**: Sent periodically as a heartbeat to keep the connection alive and indicate server health.\n        - `data`: `{\"heartbeat\": \u003cloop_count\u003e, \"message\": \"ping\"}` (loop_count increments)\n    - **`error`**: Sent if an error occurs within the SSE generation stream.\n        - `data`: `{\"error\": \"\u003cerror_message\u003e\"}`\n\n\n- **Example: Connecting with JavaScript's `EventSource`**:\n    ```javascript\n    const evtSource = new EventSource(\"http://localhost:8000/events\");\n\n    evtSource.onopen = function() {\n        console.log(\"Connection to SSE opened.\");\n    };\n\n    evtSource.onmessage = function(event) {\n        // Generic message handler if no specific event type is matched\n        console.log(\"Generic message:\", event.data);\n        try {\n            const parsedData = JSON.parse(event.data);\n            console.log(\"Parsed generic data:\", parsedData);\n        } catch (e) {\n            // Data might not be JSON\n        }\n    };\n\n    evtSource.addEventListener(\"connected\", function(event) {\n        console.log(\"Event: connected\");\n        console.log(\"Data:\", JSON.parse(event.data));\n    });\n\n    evtSource.addEventListener(\"ping\", function(event) {\n        console.log(\"Event: ping\");\n        console.log(\"Data:\", JSON.parse(event.data));\n    });\n\n    evtSource.addEventListener(\"error\", function(event) {\n        if (event.target.readyState === EventSource.CLOSED) {\n            console.error(\"SSE Connection was closed.\", event);\n        } else if (event.target.readyState === EventSource.CONNECTING) {\n            console.error(\"SSE Connection is reconnecting...\", event);\n        } else {\n            // An error occurred while streaming, data might be available\n            console.error(\"SSE Error:\", event);\n             if (event.data) {\n                try {\n                    console.error(\"Error Data:\", JSON.parse(event.data));\n                } catch (e) {\n                    console.error(\"Error Data (raw):\", event.data);\n                }\n            }\n        }\n    });\n    ```\n\n- **Example: Connecting with `curl`**:\n    ```bash\n    curl -N -H \"Accept:text/event-stream\" http://localhost:8000/events\n    ```\n    *(Note: `curl` will keep the connection open and print events as they arrive.)*\n\n\n## 💻 Editor \u0026 AI Tool Integration\n\nYou 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.\n\nBelow 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.\n\n### Cursor\n\nTo add this server to Cursor IDE:\n\n1.  Go to `Cursor Settings \u003e MCP`.\n2.  Click `+ Add new Global MCP Server`.\n3.  Alternatively, add the following configuration to your global `.cursor/mcp.json` file (ensure `cwd` points to the root directory of this project):\n\n```json\n{\n  \"mcpServers\": {\n    \"openedu-mcp-server\": {\n      \"command\": \"python\",\n      \"args\": [\n        \"-m\",\n        \"src.main\"\n      ],\n      \"cwd\": \"/path/to/your/openedu-mcp\" // Replace with the actual path to this project's root\n    }\n  }\n}\n```\nSee the Cursor documentation for more details.\n\n### Windsurf\n\nTo set up MCP with Windsurf (formerly Cascade):\n\n1.  Navigate to `Windsurf - Settings \u003e Advanced Settings` or use the Command Palette to `Open Windsurf Settings Page`.\n2.  Scroll down to the Cascade section and add the OpenEdu MCP server directly in `mcp_config.json` (ensure `cwd` points to the root directory of this project):\n\n```json\n{\n  \"mcpServers\": {\n    \"openedu-mcp-server\": {\n      \"command\": \"python\",\n      \"args\": [\n        \"-m\",\n        \"src.main\"\n      ],\n      \"cwd\": \"/path/to/your/openedu-mcp\" // Replace with the actual path to this project's root\n    }\n  }\n}\n```\n\n### Cline\n\nAdd the following JSON manually to your `cline_mcp_settings.json` via Cline's MCP Server setting (ensure `cwd` points to the root directory of this project):\n\n```json\n{\n  \"mcpServers\": {\n    \"openedu-mcp-server\": {\n      \"command\": \"python\",\n      \"args\": [\n        \"-m\",\n        \"src.main\"\n      ],\n      \"cwd\": \"/path/to/your/openedu-mcp\" // Replace with the actual path to this project's root\n    }\n  }\n}\n```\n\n### Roo Code\n\nAccess the MCP settings by clicking `Edit MCP Settings` in Roo Code settings or using the `Roo Code: Open MCP Config` command in VS Code's command palette (ensure `cwd` points to the root directory of this project):\n\n```json\n{\n  \"mcpServers\": {\n    \"openedu-mcp-server\": {\n      \"command\": \"python\",\n      \"args\": [\n        \"-m\",\n        \"src.main\"\n      ],\n      \"cwd\": \"/path/to/your/openedu-mcp\" // Replace with the actual path to this project's root\n    }\n  }\n}\n```\n\n### Claude\n\nAdd the following to your `claude_desktop_config.json` file (ensure `cwd` points to the root directory of this project):\n\n```json\n{\n  \"mcpServers\": {\n    \"openedu-mcp-server\": {\n      \"command\": \"python\",\n      \"args\": [\n        \"-m\",\n        \"src.main\"\n      ],\n      \"cwd\": \"/path/to/your/openedu-mcp\" // Replace with the actual path to this project's root\n    }\n  }\n}\n```\nSee the Claude Desktop documentation for more details if available.\n\n## 📋 Educational Use Cases\n\n### Elementary Education (K-2)\n```python\n# Find age-appropriate books\nbooks = await search_educational_books(\n    query=\"animals\", \n    grade_level=\"K-2\", \n    subject=\"Science\"\n)\n\n# Get simple definitions\ndefinition = await get_word_definition(\n    word=\"habitat\", \n    grade_level=\"K-2\"\n)\n\n# Find educational articles\narticles = await search_educational_articles(\n    query=\"animal homes\", \n    grade_level=\"K-2\"\n)\n```\n\n### Middle School STEM (6-8)\n```python\n# Get math textbooks\nbooks = await search_books_by_subject(\n    subject=\"Mathematics\", \n    grade_level=\"6-8\"\n)\n\n# Analyze vocabulary complexity\nanalysis = await get_vocabulary_analysis(\n    word=\"equation\", \n    context=\"solving math problems\"\n)\n\n# Find related terms\nrelated = await get_related_vocabulary(\n    word=\"algebra\", \n    grade_level=\"6-8\"\n)\n```\n\n### High School Advanced (9-12)\n```python\n# Get physics recommendations\nbooks = await get_book_recommendations(\n    grade_level=\"9-12\", \n    subject=\"Physics\"\n)\n\n# Get detailed articles\narticle = await get_article_content(\n    title=\"Quantum mechanics\"\n)\n\n# Find accessible research\npapers = await search_academic_papers(\n    query=\"climate change\", \n    academic_level=\"High School\"\n)\n```\n\n### College Research\n```python\n# Find academic textbooks\nbooks = await search_educational_books(\n    query=\"calculus\", \n    grade_level=\"College\"\n)\n\n# Get recent research\nresearch = await get_recent_research(\n    subject=\"Computer Science\", \n    academic_level=\"Graduate\"\n)\n\n# Analyze trends\ntrends = await analyze_research_trends(\n    subject=\"Machine Learning\"\n)\n```\n\n## ⚙️ Configuration\n\n### Configuration Files\nThe server uses YAML configuration files in the `config/` directory:\n\n```yaml\n# config/default.yaml\nserver:\n  name: \"openedu-mcp-server\"\n  version: \"1.0.0\"\n\neducation:\n  grade_levels:\n    - \"K-2\"\n    - \"3-5\" \n    - \"6-8\"\n    - \"9-12\"\n    - \"College\"\n  \n  subjects:\n    - \"Mathematics\"\n    - \"Science\"\n    - \"English Language Arts\"\n    - \"Social Studies\"\n    - \"Arts\"\n    - \"Physical Education\"\n    - \"Technology\"\n\napis:\n  open_library:\n    rate_limit: 100  # requests per minute\n  wikipedia:\n    rate_limit: 200  # requests per minute\n  dictionary:\n    rate_limit: 450  # requests per hour\n  arxiv:\n    rate_limit: 3    # requests per second\n```\n\n### Environment Variables\nOverride configuration with environment variables:\n```bash\nexport OPENEDU_MCP_CACHE_TTL=7200\nexport OPENEDU_MCP_LOG_LEVEL=DEBUG\nexport OPENEDU_MCP_RATE_LIMIT_WIKIPEDIA=300\n```\n\n## 🏗️ Architecture\n\n```\nEducation MCP Server\n├── API Layer (FastMCP)\n│   ├── 20+ MCP Tools\n│   └── Request/Response Handling\n├── Service Layer\n│   ├── Cache Service (SQLite)\n│   ├── Rate Limiting Service\n│   └── Usage Tracking Service\n├── Tool Layer\n│   ├── Open Library Tools\n│   ├── Wikipedia Tools\n│   ├── Dictionary Tools\n│   └── arXiv Tools\n├── API Layer\n│   ├── Open Library API\n│   ├── Wikipedia API\n│   ├── Dictionary API\n│   └── arXiv API\n└── Data Layer\n    ├── Educational Models\n    ├── Cache Database\n    └── Usage Analytics\n```\n\n## 📊 Performance\n\n### Caching Strategy\n- **Cache Hit Rate**: \u003e70% for repeated queries\n- **Response Time**: \u003c500ms for cached requests, \u003c2000ms for uncached\n- **Cache Size**: Configurable with automatic cleanup\n- **TTL Management**: Intelligent expiration based on content type\n\n### Rate Limiting\n- **Open Library**: 100 requests/minute\n- **Wikipedia**: 200 requests/minute  \n- **Dictionary**: 450 requests/hour\n- **arXiv**: 3 requests/second\n\n### Concurrent Handling\n- **Async Operations**: Non-blocking I/O for all API calls\n- **Connection Pooling**: Efficient HTTP connection management\n- **Resource Limits**: Configurable memory and disk usage limits\n\n## 🧪 Testing\n\n### Run All Tests\n```bash\n# Unit tests\npytest tests/test_tools/ -v\n\n# Integration tests\npytest tests/test_integration/ -v\n\n# Performance tests\npytest tests/test_performance.py -v\n\n# Real API tests (requires internet)\nmake validate\n```\n\n### Test Coverage\n```bash\npytest --cov=src --cov-report=html\nopen htmlcov/index.html\n```\n\n### Validation Tests\n```bash\nmake validate\n```\n\n## 🧪 Real API Validation Tests\n\nWe've implemented comprehensive real-world validation tests to ensure production readiness. These tests verify functionality against live services, not mocks.\n\n### Features\n- Tests all 20+ MCP tools against their respective live APIs\n- Validates educational workflows for different grade levels\n- Measures performance metrics (response times, cache rates, error rates)\n- Tests error handling with invalid inputs and edge cases\n- Verifies caching behavior with real API responses\n\n### Running Validation Tests\n```bash\npython run_validation_tests.py\n```\n\nThe script will:\n1. Test all API integrations (Open Library, Wikipedia, Dictionary, arXiv)\n2. Validate educational workflows:\n   - Elementary Education (K-2)\n   - High School STEM (9-12)\n   - College Research\n   - Educator Resources\n3. Measure performance metrics:\n   - Response times for each API\n   - Cache hit/miss rates\n   - Rate limiting effectiveness\n   - Educational filtering processing time\n4. Generate a detailed JSON report with test results and performance statistics\n\n### Test Cases\n1. **Open Library**:\n   - Search for \"Harry Potter\" with grade-level filtering\n   - Get book details by ISBN (e.g., 9780439064866)\n   - Check availability for a known book\n   - Verify educational metadata enrichment\n\n2. **Wikipedia**:\n   - Search for \"Quantum Mechanics\" with academic level filtering\n   - Get article summary for \"Albert Einstein\"\n   - Retrieve featured article of the day\n   - Verify content analysis and complexity scoring\n\n3. **Dictionary API**:\n   - Get definition for \"photosynthesis\" with educational context\n   - Test pronunciation guide for \"quinoa\"\n   - Verify vocabulary analysis for STEM terms\n   - Test grade-level appropriate definitions\n\n4. **arXiv**:\n   - Search for \"machine learning\" papers with educational filtering\n   - Get recent AI research papers\n   - Verify academic level assessment\n   - Test research trend analysis\n\n## 📚 Documentation\n\n- **[Educational Features Guide](docs/EDUCATIONAL_FEATURES.md)**: Complete educational capabilities\n- **[API Reference](docs/API_REFERENCE.md)**: Detailed MCP tool documentation\n- **[Performance Benchmarks](docs/PERFORMANCE.md)**: Real-world test results and metrics\n- **[Deployment Guide](docs/DEPLOYMENT.md)**: Production deployment instructions\n- **[Performance Guide](docs/PERFORMANCE.md)**: Optimization and monitoring\n\n## 🔧 Development Status\n\n**✅ COMPLETE - All Features Implemented**\n\n### Core Infrastructure ✅\n- [x] Project structure and configuration\n- [x] Core services (caching, rate limiting, usage tracking)\n- [x] Base models and validation\n- [x] FastMCP server setup\n- [x] Educational filtering framework\n\n### API Integrations ✅\n- [x] Open Library API integration (4 tools)\n- [x] Wikipedia API integration (5 tools)\n- [x] Dictionary API integration (5 tools)\n- [x] arXiv API integration (5 tools)\n- [x] Educational content filtering\n- [x] Cross-API educational workflows\n\n### Testing \u0026 Documentation ✅\n- [x] Comprehensive unit tests\n- [x] Integration test suite\n- [x] Performance benchmarks\n- [x] Demo script with all features\n- [x] Complete documentation\n- [x] API reference guide\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite (`pytest`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n### Development Guidelines\n- Follow PEP 8 style guidelines\n- Add type hints for all functions\n- Include docstrings for all public methods\n- Write tests for new features\n- Update documentation as needed\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n\n## 🆘 Support\n\nFor questions, issues, or contributions:\n\n- **Issues**: Create an issue in the repository\n- **Documentation**: Check the `docs/` directory\n- **Discussions**: Use GitHub Discussions for questions\n- **Email**: Contact the maintainers\n\n## 🙏 Acknowledgments\n\n- Built with [FastMCP](https://github.com/jlowin/fastmcp) framework\n- Integrates with Open Library, Wikipedia, Dictionary API, and arXiv\n- Designed for educational use cases and curriculum planning\n- Inspired by the need for accessible educational technology\n\n---\n\n**OpenEdu MCP Server** - Empowering educators with intelligent educational resource discovery and curriculum planning tools.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcicatriiz%2Fopenedu-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcicatriiz%2Fopenedu-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcicatriiz%2Fopenedu-mcp/lists"}