README.md
AI learning assistant for families managing game time rewards and school tasks.
Learning Hub MCP
Beta — fully functional, tested with one family. Feedback and bug reports welcome via GitHub Issues.
MCP server for student learning workflow with SQLite database. Each instance serves one student — deploy a separate instance per child for isolated, focused AI tutoring.
Features
- Subjects - school subjects with multi-country support (UA, CZ, DE, etc.)
- Grades - grade tracking with 5-point European scale (1=best, 5=worst)
- Topics - subject topics for improvement tracking
- Homework - assignment tracking with deadlines
- Bonus Tasks - motivational tasks that reward game minutes
- Game Minutes - immutable transaction ledger for tracking earned/spent game time
- Books - textbook library with markdown summaries and content indexing
- Topic Reviews - reinforcement tracking for weak topics
- Escalation - bad grade notifications for parents
- Instruction Tools - markdown algorithms that guide AI agents through workflows
- Sync Providers - pluggable sync framework (EduPage, PRONOTE)
- Secrets - secure credential storage for sync providers
Installation
# Install dependencies
poetry install
# Initialize database
poetry run alembic upgrade head
Configuration
Database defaults to ./data/learning_hub.db. Override via environment variable:
DATABASE_URL=sqlite+aiosqlite:///./data/learning_hub.db
Sync provider credentials (EduPage, PRONOTE, etc.) are stored in the secrets table and managed via MCP tools (set_secret, list_secrets).
Config System (SQLite)
Runtime configuration stored in the configs table. Managed via MCP tools (get_config, set_config, list_configs). Use check_system_readiness to verify all required configs are set.
Entries with defaults (seeded by migration)
| Key | Default | Description |
|---|---|---|
GRADE_MINUTES_MAP |
{"1":15,"2":10,"3":0,"4":-20,"5":-25} |
Grade → game minutes conversion |
TOPIC_REVIEW_THRESHOLDS |
{"2":1,"3":2,"4":3,"5":3} |
Repetitions needed per grade before TopicReview is closed |
HOMEWORK_BONUS_MINUTES_ONTIME |
10 |
Bonus minutes for on-time homework |
HOMEWORK_BONUS_MINUTES_OVERDUE |
-10 |
Penalty minutes for overdue homework |
MAX_PENDING_BONUS_TASKS |
4 |
Max concurrent pending bonus tasks |
MAX_COMPLETED_BONUS_TASKS_PER_WEEK |
15 |
Max completed bonus tasks in rolling 7 days |
DEFAULT_DEADLINE_TIME |
20:00 |
Default time when deadline has only a date |
SETUP_COMPLETED |
false |
Whether initial setup has been completed |
BASE_CRONS_INSTALLED |
false |
Whether base cron jobs have been created |
SYNC_CRON_CONFIGURED |
false |
Whether a sync cron job has been created after first successful sync |
Required entries (must be set before use)
| Key | Description |
|---|---|
TEMP_BOOK_DIR |
Folder where users place book files for processing |
BOOKS_STORAGE_DIR |
Base folder for storing processed books |
ISSUES_LOG |
Path to the issue log file |
FAMILY_LANGUAGE |
Language for communication with the family |
Usage
Run MCP Server
poetry run learning-hub-mcp
MCP Configuration
Add to your MCP client config:
{
"mcpServers": {
"learning-hub": {
"command": "poetry",
"args": ["run", "learning-hub-mcp"],
"cwd": "/path/to/learning-hub-mcp"
}
}
}
MCP Tools (78 total)
Subjects
create_subject- create a new school subjectlist_subjects- list subjects (filter: school, is_active)update_subject- update subject details
Topics
create_topic- create a topic for a subjectlist_topics- list topics (filter: subject_id, is_open)close_topic- close topic (reason: resolved/skipped/no_longer_relevant)
Grades
add_grade- add a grade (1-5 scale, 1=best), auto-creates minute transactionlist_grades- list grades (filter: subject, date range, school)
Bonus Tasks
create_bonus_task- create a bonus task linked to a topic (validates limits)list_bonus_tasks- list tasks (filter: status, topic)get_bonus_task- get a bonus task by IDget_latest_bonus_task- get the most recent bonus taskapply_bonus_task_result- complete task, record grade, and update topic reviewscancel_bonus_task- cancel a taskcheck_pending_bonus_task- check if there's a pending task to reuse
Minute Transactions
get_balance- get current game minutes balanceadd_played_minutes- record played game time (deducts from balance)create_ad_hoc_transaction- create manual bonus or penaltylist_transactions- list transactions (filter: date range, type)
Homework
create_homework- create homework assignmentlist_homeworks- list homework (filter: status, subject)complete_homework- mark homework as done
Tools (7)
create_subjectCreate a new school subject.list_subjectsList subjects with optional filtering by school or activity status.create_topicCreate a topic for a specific subject.add_gradeAdd a grade on a 1-5 scale and auto-create a minute transaction.create_bonus_taskCreate a bonus task linked to a topic with validation against limits.get_balanceGet the current game minutes balance.complete_homeworkMark a homework assignment as done.Environment Variables
DATABASE_URLDatabase connection string for the SQLite file.Configuration
claude_desktop_config.json
{"mcpServers": {"learning-hub": {"command": "poetry", "args": ["run", "learning-hub-mcp"], "cwd": "/path/to/learning-hub-mcp"}}}Try it
→What is my current game minutes balance?
→Add a grade of 1 for my Mathematics subject today.
→List all my open homework assignments for this week.
→Create a new bonus task for finishing the history chapter with a reward of 15 minutes.
→Mark the biology homework as completed.