# EduChain MCP Server
A Model Context Protocol (MCP) server that integrates [EduChain](https://github.com/satvik314/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:**
```bash
git clone https://github.com/yourusername/educhain-mcp.git
cd educhain-mcp
```
2. **Install dependencies:**
```bash
pip install -e .
```
Or install manually:
```bash
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:
```env
OPENAI_API_KEY=your_openai_api_key_here
```
## š Usage
### Running the Server
```bash
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`
```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:
```bash
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:**
```python
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:**
```python
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:**
```python
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
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](https://github.com/satvik314/educhain) for the educational content generation capabilities
- [Model Context Protocol](https://modelcontextprotocol.io/) for the integration framework
- [Claude Desktop](https://claude.ai/) for the AI assistant platform
## š§ Support
For issues, questions, or contributions, please:
1. Check the [Issues](https://github.com/yourusername/educhain-mcp/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
