EduChain MCP Server

A Model Context Protocol (MCP) server that integrates EduChain's educational content generation capabilities with Claude Desktop and other MCP-compatible clients.

🎯 Overview

The EduChain MCP Server provides three powerful educational tools accessible through Claude Desktop:

• 📝 Multiple Choice Questions (MCQs): Generate well-structured questions with plausible distractors

• 📚 Lesson Plans: Create comprehensive, structured lesson plans with objectives, activities, and assessments

• 🗂️ Flashcards: Generate educational flashcards optimized for spaced repetition learning

🚀 Features

• Claude Desktop Integration: Seamless integration with Claude Desktop via MCP protocol

• Type-Safe Implementation: Full type hints and comprehensive docstrings

• Error Handling: Robust error handling and graceful degradation

• Logging: Comprehensive logging for debugging and monitoring

• Input Validation: Thorough validation of all input parameters

• Environment Configuration: Support for environment variables

• MCP Inspector Compatible: Works with MCP Inspector for debugging

📋 Requirements

• Python 3.10 or higher

• OpenAI API key (for EduChain functionality)

• Claude Desktop (for MCP integration)

🔧 Installation

1. Clone the repository:

   git clone https://github.com/yourusername/educhain-mcp.git cd educhain-mcp

2. Install dependencies:

   pip install -e .

   Or install manually:

   pip install educhain>=0.3.10 httpx>=0.28.1 "mcp[cli]>=1.10.1" python-dotenv

3. Set up environment variables: Create a .env file in the project root:

   OPENAI_API_KEY=your_openai_api_key_here

🏃 Usage

Running the Server

The server will start and listen for MCP connections via stdio transport, making it compatible with Claude Desktop.

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

MCP Inspector

For debugging and development, you can use the MCP Inspector:

🛠️ Available Tools

1. Generate MCQs

Function: generate_mcqs(topic: str, num_questions: int = 5)

Description: Generate multiple-choice questions for a given educational topic.

Parameters:

• topic (str): The educational topic (e.g., "Photosynthesis", "World War II")

• num_questions (int, optional): Number of questions to generate (1-20, default: 5)

Example:

2. Lesson Plan

Function: lesson_plan(topic: str, duration: Optional[str] = None, grade_level: Optional[str] = None)

Description: Generate a comprehensive, structured lesson plan.

Parameters:

• topic (str): The lesson topic (e.g., "Introduction to Fractions")

• duration (str, optional): Lesson duration (e.g., "45 minutes", "1 hour")

• grade_level (str, optional): Target grade level (e.g., "Grade 5", "High School")

Example:

3. Generate Flashcards

Function: generate_flashcards(topic: str, num_cards: int = 10, difficulty: Optional[str] = None)

Description: Generate educational flashcards for study and memorization.

Parameters:

• topic (str): The subject area (e.g., "Spanish Vocabulary - Animals")

• num_cards (int, optional): Number of flashcards to generate (1-50, default: 10)

• difficulty (str, optional): Difficulty level ("beginner", "intermediate", "advanced")

Example:

📝 Project Structure

🔍 Logging

The server includes comprehensive logging to help with debugging and monitoring:

• INFO Level: Server startup, tool execution, and success messages

• WARNING Level: Missing environment variables and non-critical issues

• ERROR Level: Tool execution failures and server errors

Logs are formatted with timestamps and include the module name for easy identification.

🛡️ Error Handling

The server implements robust error handling:

• Input Validation: All parameters are validated before processing

• Graceful Degradation: Errors are returned as structured responses

• Logging: All errors are logged with detailed messages

• Type Safety: Full type hints prevent common runtime errors

🤝 Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

🙏 Acknowledgments

• EduChain for the educational content generation capabilities

• Model Context Protocol for the integration framework

• Claude Desktop for the AI assistant platform

📧 Support

For issues, questions, or contributions, please:

1. Check the Issues page

2. Create a new issue if your problem isn't already listed

3. Provide detailed information about your environment and the issue

🔄 Changelog

v0.1.0

• Initial release

• Basic MCP server implementation

• Three educational tools: MCQs, lesson plans, flashcards

• Claude Desktop integration

• Comprehensive documentation and error handling