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

Clone the repository:

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

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

Set up environment variables: Create a .env file in the project root:
```
OPENAI_API_KEY=your_openai_api_key_here
```

🏃 Usage

Running the Server

python mcp_server.py

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

{
  "mcpServers": {
    "Educhain_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/Educhain_mcp",
        "run",
        "mcp_server.py"
      ]
    }
  }
}

MCP Inspector

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

npx @modelcontextprotocol/inspector python mcp_server.py

🛠️ 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:

result = generate_mcqs("Photosynthesis", 3)

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:

result = lesson_plan("Photosynthesis", "50 minutes", "Grade 7")

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:

result = generate_flashcards("Spanish Vocabulary - Animals", 5, "beginner")

📝 Project Structure

educhain-mcp/
├── mcp_server.py          # Main MCP server implementation
├── main.py                # Simple entry point (not used for MCP)
├── pyproject.toml         # Project configuration and dependencies
├── README.md              # This documentation
└── .env                   # Environment variables (create this)

🔍 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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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:

Check the Issues page
Create a new issue if your problem isn't already listed
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

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

Clone the repository:

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

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

Set up environment variables: Create a .env file in the project root:
```
OPENAI_API_KEY=your_openai_api_key_here
```

🏃 Usage

Running the Server

python mcp_server.py

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

{
  "mcpServers": {
    "Educhain_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/Educhain_mcp",
        "run",
        "mcp_server.py"
      ]
    }
  }
}

MCP Inspector

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

npx @modelcontextprotocol/inspector python mcp_server.py

🛠️ 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:

result = generate_mcqs("Photosynthesis", 3)

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:

result = lesson_plan("Photosynthesis", "50 minutes", "Grade 7")

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:

result = generate_flashcards("Spanish Vocabulary - Animals", 5, "beginner")

📝 Project Structure

educhain-mcp/
├── mcp_server.py          # Main MCP server implementation
├── main.py                # Simple entry point (not used for MCP)
├── pyproject.toml         # Project configuration and dependencies
├── README.md              # This documentation
└── .env                   # Environment variables (create this)

🔍 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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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:

Check the Issues page
Create a new issue if your problem isn't already listed
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