# MCP Academic Structure Server

A powerful Model Context Protocol (MCP) server that provides intelligent access to your Google Drive-based academic structure. This server allows AI assistants like Claude to navigate, search, and analyze your academic materials organized in cycles, semesters, and modules.

## Overview

The MCP Academic Structure Server transforms your Google Drive academic folders into an intelligent, searchable knowledge base that AI assistants can interact with. It provides:

- **Hierarchical Navigation**: Browse through academic cycles, semesters, and modules
- **Intelligent Search**: Find specific content across your entire academic structure
- **Path Validation**: Verify and navigate to specific academic paths
- **Module Comparison**: Compare different modules to understand relationships
- **Subject Discovery**: Find all modules related to specific subjects

## Project Structure

```
MCP-ENSIA/
├── src/
│   ├── clients/
│   │   └── drive_client.py          # Enhanced Google Drive API client
│   ├── core/
│   │   ├── academic_structure.py    # Main academic processor
│   │   ├── cycle_manager.py         # Cycle processing logic
│   │   ├── semester_manager.py      # Semester processing logic
│   │   ├── module_manager.py        # Module processing logic
│   │   └── category_manager.py      # Category processing logic
│   ├── models/
│   │   ├── academic_models.py       # Data models for academic structure
│   │   └── search_models.py         # Search-related models
│   ├── services/
│   │   ├── search_service.py        # Search functionality
│   │   ├── navigation_service.py    # Navigation services
│   │   └── comparison_service.py    # Module comparison services
│   ├── utils/
│   │   └── validation_utils.py      # Validation utilities
│   ├── server.py                    # Main MCP server
├── config/
│   ├── .env                        # Environment variables
│   ├── credentials.json            # Google Drive credentials (user-specific)
│   └── token.json                  # OAuth token (auto-generated)
├── tests/                          # Comprehensive test suite
├── requirements.txt                # Python dependencies
└── README.md                       # This file
```

## MCP Tools Available

| Tool | Description | Parameters |
|------|-------------|------------|
| `get_academic_overview` | Complete overview with statistics | `max_depth` (optional) |
| `search_academic_content` | Search across academic structure | `query`, `scope`, filters |
| `navigate_to_path` | Navigate to specific academic path | `path` |
| `list_cycles` | List all academic cycles | None |
| `list_semesters` | List semesters in a cycle | `cycle` |
| `list_modules` | List modules in a semester | `cycle`, `semester` |
| `compare_modules` | Compare two modules | `module1_path`, `module2_path` |
| `find_modules_by_subject` | Find modules by subject | `subject`, `exact_match` |
| `get_structure_overview` | Detailed structure information | None |
| `validate_path` | Validate academic path format | `path` |

## Prerequisites

- **Python 3.8+**
- **Google Drive API access**: Access is exclusive for now. Help is welcomed in hosting this server for public access.
- **MCP-compatible AI assistant** (like Claude Desktop)
- **Academic structure in Google Drive** following the expected format

## Installation & Setup

### 1. Clone the Repository

```bash
git clone <repository-url>
cd MCP-ENSIA
```

### 2. Install Dependencies

```bash
pip install -r requirements.txt
```

### 3. Test the Setup

```bash
# Test imports and basic functionality
python -c "
import sys
sys.path.append('src')
from src.clients.drive_client import EnhancedGoogleDriveClient
from src.core.academic_structure import AcademicStructureProcessor
print('All imports successful!')
"
```

## Usage

### Running the MCP Server

```bash
# Start the MCP server
python -m src.server
```

### Integration with Claude Desktop

Add to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "academic-structure": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/MCP-ENSIA",
      "env": {
        "PYTHONPATH": "/path/to/MCP-ENSIA"
      }
    }
  }
}
```

### Example Commands in Claude

Once integrated, you can ask Claude:

```
"Get an overview of my academic structure"
"List all my academic cycles" 
"Show me modules in First Superior Cycle, Semester 1"
"Search for automata theory content"
"Navigate to 3. First Superior Cycle/Semester 1/Theory of Computation"
"Compare Mathematics I from different semesters"
"Find all modules that teach machine learning"
```

## Testing

### Run Test Suite

```bash
# Install test dependencies
pip install pytest pytest-asyncio pytest-mock pytest-cov

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src --cov-report=html

# Run specific test categories
pytest tests/test_imports.py -v           # Import tests
pytest tests/unit/ -v                     # Unit tests
pytest tests/integration/ -v              # Integration tests
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

This project was made possible thanks to [ETC club](https://etc-club.vercel.app/) for the Google Drive content that they collected under [Ensia Hub](https://ensia-hub.netlify.app/).

## Related Links

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Google Drive API Documentation](https://developers.google.com/drive/api)
- [Claude Desktop MCP Setup](https://docs.anthropic.com/claude/docs/mcp)

## Support

For questions, issues, or contributions:

1. **Check existing issues** in the repository
2. **Create a new issue** with detailed description
3. **Join discussions** in repository discussions
4. **Contact maintainers** via repository contacts

---

**Made with ❤️ for the academic community**