# 🏥 Meducate MCP - Africa's AI Medical Education Assistant

> **"Your AI-powered Jarvis(let's call him Ananse) for medical education in Africa"**

**Empowering African medical students and young doctors with intelligent, context-aware assistance through natural language AI and Model Context Protocol.**

## Link to [Video Demo](https://drive.google.com/file/d/1YebO82slnzAH009dngcboatyMPnqMsd9/view?usp=sharing)
## Link to [Presentation Slides](https://docs.google.com/presentation/d/1vP2X1cLW-f1cqzeK7IMJs11FMKfN0qgmc-WkOLknOy4/edit?usp=sharing)
---

## 🌍 The African Medical Education Challenge

**Meet Serwaa**, a second-year medical student in Accra, Ghana:

- 📚 Overwhelmed with lectures, labs, and clinical rotations
- 💸 Limited budget for textbooks and study resources
- 📱 Struggles to afford consistent internet for research
- ⏰ Needs constant reminders but finds rigid apps frustrating
- 🌐 Often searches for medical information in broken English or local languages

**Serwaa's reality mirrors millions of medical students across Africa** - brilliant minds facing systemic barriers that technology should solve, not complicate.

---

## ✨ Enter Meducate MCP

**Meducate is a self-aware, AI-powered Model Context Protocol (MCP) server** that acts like a personal medical education assistant - understanding natural language, working autonomously in the background, and bridging critical gaps in African healthcare education.

### 🎯 What Makes Meducate Revolutionary

1. **🧠 Self-Aware & Autonomous**

   - Constantly monitors your schedule and study needs
   - Understands natural language: "remind me every 5 minutes" or "quiz me tomorrow morning"
   - Works in the background - no constant manual input needed

2. **🌍 African-First Design**

   - **First MCP integration with African telecoms** (MTN, Airteltigo)
   - Buy data bundles at cheap prices directly through AI in natural language.
   - Track balances, send usage stats to guardians
   - **First Hubnets MCP** for SMS/OTP in Africa

3. **📖 Medical Knowledge at Your Fingertips**

   - Scrapes trusted sources: WHO Africa, CDC, PubMed, BMJ
   - Focuses on diseases relevant to African contexts (Malaria, TB, etc.)
   - Generates quizzes tailored to your curriculum
   - Finds cheapest textbook prices across platforms

4. **🗣️ Natural Language Understanding**
   - Write in English, Twi, Pidgin, or local languages
   - AI interprets context, not just keywords
   - Accessible to non-native speakers

---

## 🚀 Key Features

### 🤖 AI-Powered Intelligence

- **Natural Language Processing** via Groq AI (Llama 3.3 70B)
- **Dynamic tool selection** - AI decides which action to take
- **Context-aware suggestions** based on your study patterns
- **Tools are automatically discovered and integrated into the AI's capabilities** - no hardcoding required!

### 📅 Smart Scheduling System

```
"Quiz me about pharmacology tomorrow morning"
"Remind me every hour to drink water"
"Send my study stats to mom every Sunday"
"buy 5gb for my data bundle when my balance is low"
"send 1gb to my sister tomorrow afternoon to thank her for helping me study`"
```

**The AI understands and executes - no rigid formats!**

### 📚 Medical Knowledge Base

- Disease information scraping (WHO, CDC, PubMed)

### 📚 Medical Knowledge Base

- Disease information scraping (WHO, CDC, PubMed)
- Quiz generation for active recall
- Study resource aggregation (videos, articles)
- Textbook price comparison

### 📱 Africa-Specific Integrations

- **Data bundle purchases** (Airteltigo, MTN)
- **SMS notifications** via Hubnets
- **Gmail notifications for reminders and updates**

### 📊 Productivity Tools

- Google Sheets integration for timetables
- Gmail notifications
- Autonomous/self-conscious reminder system

---

## 🏆 Why Meducate Wins

### ✅ Technical Excellence

- JSON-based MCP protocol implementation
- Multi-service architecture (Python + Node.js Puppeteer)
- AI-powered natural language parsing
- Dynamic tool execution system
- Robust error handling

### ✅ Innovation

- **First African telcom MCP integration**
- **First Hubnets SMS MCP**
- Natural language scheduler (vs rigid cron jobs)
- Self-aware autonomous operation
- Multi-domain integration (healthcare + telecom + education)

### ✅ African Relevance

- Solves real problems facing African medical students
- Focus on African disease contexts
- Affordable data management built-in
- Accessible natural language interface

---

## 🎬 Quick Start

### Prerequisites

- Python 3.10+
- Node.js 18+
- Google Cloud account (for Sheets/Gmail)
- Groq API key(This is free, you can get it via https://console.groq.com/keys)

### Installation

1. **Clone the repository**

```bash
git clone https://github.com/JoshNuku/meducate-mcp.git
cd meducate-mcp
```

2. **Set up Python environment**

```bash
# Install UV package manager
pip install uv

# Install dependencies
uv sync
```

3. **Set up Puppeteer server**

```bash
cd puppeteer-server
npm install
```

4. **Configure environment**

```bash
# Copy example environment file
cp .env.example .env

# Edit .env with your credentials
# Add GROQ_API_KEY, Gmail credentials, etc.
```

5. **Set up Google Sheets API**

   - Create a project in [Google Cloud Console](https://console.cloud.google.com/)
   - Enable Google Sheets API
   - Create service account and download `credentials.json`
   - Place `credentials.json` in the root directory

6. **Run the servers**

```bash
# Terminal 1: Start Puppeteer server
cd puppeteer-server
npm start

# Terminal 2: Start MCP server
cd ..
python main.py
```

---

## 📖 Usage Examples

### Natural Language Reminders

```
"Remind me to review anatomy every morning at 8am"
"Quiz me about cardiology tomorrow afternoon"
"Send my study hours to dad every Sunday"
"Drink water every 30 minutes"
```

### Medical Information

```
"Get latest WHO guidelines on malaria treatment"
"Find recent research on tuberculosis in Africa"
"What are common symptoms of typhoid fever?"
```

### Data Management

```
"Buy 5GB data bundle for my MTN number"
"Check my data balance"
```

### Study Resources

```
"Find YouTube videos about pharmacology"
"Compare prices for Gray's Anatomy textbook"
"Generate 10 quiz questions on neurology"
```

---

## 🌍 African Language Support

Meducate understands context in multiple languages:

**English (Standard)**

```
"Remind me to study at 6pm everyday"
```

**Pidgin (Nigeria)**

```
"Make you remind me say make I read book for evening time"
```

**Twi (Ghana)**

```
"kai me s3 mefa "(Remind)
```

**Swahili (East Africa)**

```
"Nikumbushe kusoma saa kumi na mbili usiku"
```

The AI interprets intent, not just exact phrasing!

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────┐
│          User (AI Assistant/LLM)                │
└────────────────┬────────────────────────────────┘
                 │ MCP Protocol (JSON-RPC)
                 ▼
┌─────────────────────────────────────────────────┐
│         Meducate MCP Server (Python)            │
│  ┌──────────────────────────────────────────┐  │
│  │  AI Decision Engine (Groq/Llama 3.3)     │  │
│  │  - Natural language parsing              │  │
│  │  - Dynamic tool selection                │  │
│  │  - Context-aware reasoning               │  │
│  └──────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────┐  │
│  │  Tools Layer                             │  │
│  │  • Medical scraping  • Reminders         │  │
│  │  • Telecom APIs      • Payments          │  │
│  │  • Notifications     • Scheduling        │  │
│  └──────────────────────────────────────────┘  │
└──┬──────────────┬──────────────┬───────────────┘
   │              │              │
   ▼              ▼              ▼
┌──────────┐  ┌──────────┐  ┌──────────────┐
│Puppeteer │  │  Google  │  │   African    │
│ Server   │  │ Services │  │   Telecom    │
│(Node.js) │  │(Sheets,  │  │    APIs      │
│          │  │ Gmail)   │  │ (MTN, etc.)  │
└──────────┘  └──────────┘  └──────────────┘
     │
     ▼
┌─────────────────────────────────────┐
│  Medical Websites                   │
│  • WHO Africa  • CDC  • PubMed      │
│  • BMJ  • UpToDate  • Book Stores   │
└─────────────────────────────────────┘
```

---

## 📁 Project Structure

```
meducate_mcp/
├── main.py                      # Entry point & MCP server
├── .env.example                 # Environment template
├── credentials.json             # Google API credentials
├── pyproject.toml               # Python dependencies
│
├── Tools/                       # MCP tool implementations
│   ├── disease_tools.py         # Medical info scraping
│   ├── quiz_tools.py            # Quiz generation
│   ├── study_tools.py           # Study resources
│   ├── notification_tools.py    # Email/SMS alerts
│   ├── reminder.py              # Reminder system
│   └── buy_internet_bundle.py   # Data bundle purchases
│
├── utils/                       # Core utilities
│   ├── ai_decision_engine.py    # Groq AI integration
│   ├── scheduler.py             # Background scheduler
│   ├── tool_extractor.py        # Dynamic tool discovery
│   └── message_formatter.py     # AI message formatting
│
├── Helpers/                     # Business logic(functions for tools)
│   ├── scheduler_helper.py      # Scheduling functions
│   ├── notification_helpers.py  # Notification logic
│   └── reminder_helpers.py      # Reminder helpers
│
├── puppeteer-server/            # Web scraping service
│   ├── src/
│   │   ├── controllers/         # Scraping controllers
│   │   ├── services/            # Browser service
│   │   └── utils/               # Page utilities
│   └── package.json
│
└── at root/                        # Documentation
    ├── NOTIFICATION_DOCS.md
    ├── PUPPETEER_TOOLS_README.md
    └── REMINDER_DOCS.md
```

---

## 🎯 MCP Hackathon Africa 2025

### Tracks Covered

- 🏥 **Healthcare Systems** (Primary)
- 📚 **Education & Learning** (Primary)
- 📡 **Telecommunications** (Secondary)

### Unique Value Propositions

1. **Only MCP with African telecom integration**

   - Direct data bundle purchases- no stress of dialing ussd codes
   - Balance tracking and alerts
   - Guardian notifications
   - email sending- the course rep who has to announce to the class about rescheduled lectures can do so via gmail notification tool integrated into the mcp

2. **First Unofficial MCP with Hubnets SMS**

   - OTP verification
   - SMS reminders for no-internet scenarios
   - Wider accessibility

3. **Natural Language AI Scheduler**

   - Not just keyword matching
   - True context understanding
   - Works in multiple languages

4. **Self-Aware Operation**

   - Autonomous background monitoring
   - Proactive suggestions
   - Contextual awareness

5. **Medical Education Focus**
   - African disease contexts
   - Affordable resource discovery
   - Quiz generation for active learning

---

## 📚 Documentation

- [📧 Notification System](./NOTIFICATION_DOCS.md) - Email and SMS integration
- [🤖 Puppeteer Scraping](./PUPPETEER_TOOLS_README.md) - Web scraping architecture
- [⏰ AI Reminder System](./REMINDER_DOCS.md) - Self-aware scheduling system
- [👨‍💻 Contributing Guide](./CONTRIBUTING.md) - Developer documentation

---

## 🌟 Impact & Vision

### Current Impact

✅ **Reduces study costs** by aggregating free medical resources  
✅ **Saves data expenses** through affordable bundle integration  
✅ **Increases efficiency** with AI-powered autonomous reminders  
✅ **Improves accessibility** via natural language understanding  
✅ **Bridges telecom gap** with first-of-its-kind African MCP integrations

### Future Vision

🚀 Expand to more African countries and telecom providers  
🎙️ Add voice interface for hands-free, low-literacy operation  
🏥 Integrate with hospital systems for clinical rotation management  
📚 Build community knowledge base of African medical cases  
🤝 Partner with medical schools across Africa  
🌍 Support more local languages (Yoruba, Igbo, Amharic, etc.)  
💡 AI-powered study group matching and collaboration

---

## 🤝 Contributing

We welcome contributions! This is an open-source project for African impact.

**See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed developer guidelines.**