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 subject
list_subjects - list subjects (filter: school, is_active)
update_subject - update subject details

Topics

create_topic - create a topic for a subject
list_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 transaction
list_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 ID
get_latest_bonus_task - get the most recent bonus task
apply_bonus_task_result - complete task, record grade, and update topic reviews
cancel_bonus_task - cancel a task
check_pending_bonus_task - check if there's a pending task to reuse

Minute Transactions

get_balance - get current game minutes balance
add_played_minutes - record played game time (deducts from balance)
create_ad_hoc_transaction - create manual bonus or penalty
list_transactions - list transactions (filter: date range, type)

Homework

create_homework - create homework assignment
list_homeworks - list homework (filter: status, subject)
complete_homework - mark homework as done
update_homework - update homework details
close_overdue_homeworks - close overdue homework, auto-creates penalty transaction
get_pending_homework_reminders - get reminders due (D-1, D-2)
mark_homework_reminders_sent - mark reminders as sent

Books

add_book - add a book to the library
list_books - list books (filter: subject, has_summary)
get_book - get a book by ID
update_book - update book details
delete_book - delete a book

Topic Reviews

list_topic_reviews - list topic reviews (filter: subject, status)
get_pending_reviews_for_topic - get pending reviews for a topic
mark_topic_reinforced - mark review as reinforced
increment_topic_repeat_count - increment repeat count for a review
get_priority_topic_for_review - pick a priority topic from top-4

Family Members

create_family_member - add a family member (student/parent/tutor/admin)
list_family_members - list members (filter: role)
update_family_member - update member details
delete_family_member - delete a member
get_student - get the student record

Gateways

create_gateway - register a messaging channel (Telegram, etc.)
list_gateways - list gateways (filter: family_member, channel)
update_gateway - update gateway details
delete_gateway - delete a gateway
lookup_gateway - find gateway by platform + external ID

Configs

get_config - get a config value by key
set_config - set a config value (existing keys only)
list_configs - list all config entries

Secrets

set_secret - set a secret value (credentials, API keys)
list_secrets - list secrets (keys only, values never exposed)

Sync Providers

list_sync_providers - list all sync providers with status
update_sync_provider - activate/deactivate, link to school
run_sync - run sync for all active providers (or a specific one)
find_edupage_subdomain - detect EduPage school subdomain from stored credentials

Readiness

check_system_readiness - check if the system is properly configured (active schools, required configs)

Escalation

get_grades_pending_escalation - get grades needing parent notification
mark_grades_escalated - mark grades as escalated (parent was notified)

Instruction Tools

get_grade_escalation_instructions - escalate bad grades to tutor/admin
get_learning_system_instructions - master instruction: full system rules
get_student_request_router_instructions - classify student request (A/B/C scenarios)
get_bonus_task_assignment_instructions - assign a new bonus task
get_submission_routing_instructions - route submitted work to evaluator
get_bonus_task_evaluation_instructions - evaluate completed bonus task
get_homework_evaluation_instructions - evaluate homework submission
get_book_lookup_instructions - find and deliver textbook pages
get_books_workflow_instructions - process and register new books
get_homework_manual_instructions - manually add homework (parent only)
get_grade_manual_instructions - manually add a grade (adult only)
get_student_content_policy_instructions - content safety filtering for external student content
get_topic_review_curation_instructions - curate and close stale topic reviews
get_base_crons_setup_instructions - instructions for setting up base cron jobs

OpenClaw Bridge Plugin

The learning-hub-bridge/ directory contains a TypeScript plugin that makes all MCP tools available as native OpenClaw agent tools.

Why

OpenClaw doesn't support MCP servers natively. Without the bridge, the agent would need exec + mcporter — slow (~3s per call), buggy (mcporter serialization issues with lists), and invisible to the model (tools not in tool list).

How it works

On gateway startup, the bridge spawns the Python MCP server as a child process (STDIO)
Discovers all tools via client.listTools() (MCP protocol)
Registers each as a native OpenClaw tool via api.registerTool() with prefix learning_hub_
Proxies execute() → client.callTool(), merging multiple TextContent blocks into a single JSON array
Auto-reconnects if the Python process dies

After this, the model sees learning_hub_list_subjects, learning_hub_add_grade, etc. directly in its tool list.

Deployment

The bridge must be installed as an OpenClaw extension. The source lives in learning-hub-bridge/ inside this repo, but OpenClaw loads plugins from ~/.openclaw/extensions/<pluginId>/.

Step 1. Copy the bridge to extensions:

cp -r /path/to/learning-hub-mcp/learning-hub-bridge ~/.openclaw/extensions/learning-hub

Step 2. Install dependencies:

cd ~/.openclaw/extensions/learning-hub
npm install

Step 3. Add plugin config to openclaw.json:

{
  "plugins": {
    "entries": {
      "learning-hub": {
        "enabled": true,
        "config": {
          "command": "/bin/bash",
          "args": ["-lc", "cd /path/to/learning-hub-mcp && exec .venv/bin/learning-hub-mcp"],
          "cwd": "/path/to/learning-hub-mcp",
          "toolPrefix": "learning_hub"
        }
      }
    }
  }
}

Step 4. Allow tools for the agent in openclaw.json:

{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "alsoAllow": ["learning-hub"]
        }
      }
    ]
  }
}

Step 5. Restart gateway:

openclaw gateway restart

Config options

Option	Description	Default
`command`	Command to start MCP server	(required)
`args`	Arguments for the command	(required)
`cwd`	Working directory for MCP server process	—
`toolPrefix`	Prefix for registered tool names	`learning_hub`

Updating after MCP changes

When new tools are added to the MCP server, the bridge picks them up automatically on gateway restart — no bridge code changes needed. Just restart:

openclaw gateway restart

Development

# Run tests
poetry run pytest

# Run tests with coverage
poetry run pytest --cov=learning_hub

# Lint code
poetry run ruff check .

# Fix lint issues
poetry run ruff check --fix .

Known Limitations

Tested with a single family (one student, two schools: EduPage CZ + UA)
PRONOTE sync implemented but minimally tested
SQLite only — designed for single-family self-hosted use
Requires OpenClaw as the AI agent runtime
Edge cases with diverse school configurations are likely not yet covered

License

PolyForm Noncommercial 1.0.0

Learning Hub