Skip to main content
Glama

🎓 Daily Tutor MCP

Duolingo-style daily practice on any topics you choose, as an MCP server. Spaced repetition · adaptive difficulty · 13 question types · streaks · certification tracks

CI License: MIT Python MCP Docker


What is this?

You tell your AI assistant what you want to learn, for example sysadmin, devops, network engineer, or a certification like CCNA or CKA. Every day it asks you one punchy, real-world question, grades your answer, explains it, and brings back what you got wrong at the right time.

The MCP server owns the state and the rules. The LLM only writes the questions and the explanations. That split is the whole point: the things LLMs are bad at (counting, scheduling, grading, being unbiased) are done in plain code.

You   ▸ quiz me
Tutor ▸ 🚨 3 AM pager: nginx returns 502 right after a deploy. systemctl says it is running.
        Which do you check FIRST?   A) DNS   B) upstream/app logs   C) disk quota   D) cron
        (reply with one letter)
You   ▸ b
Tutor ▸ ✅ Correct! +10 XP · 🔥 4-day streak · daily goal reached
        502 = the proxy is fine, the upstream is not. Gotcha: `proxy_next_upstream` can hide a flapping backend…

Related MCP server: Flashcard MCP

Features

🧠 Multi-topic

Any topics, each with its own level and subtopics. ~25% of questions deliberately mix two topics (a DNS fault that looks like a sysadmin problem).

🎲 13 question types

Multiple choice, multi-select, true/false, fill-the-blank, command challenge, predict-the-output, troubleshooting, ordering, match pairs, spot-the-bug, explain, design trade-off, flashcard.

✅ Exact grading

Letters, ordering, matching, true/false and accepted commands are graded by the server, not by the LLM. Free-text goes to the LLM with a rubric.

⚖️ No "always B" bias

The server dictates where the correct answer goes and rejects anything else. Duplicate wording and repeated concepts are rejected too.

🔁 Spaced repetition

Missed concepts return after 1 → 3 → 7 → 14 → 30 days, from a different angle.

📈 Adaptive difficulty

Levels go up after a strong run and down after a weak one, per topic. Lock a level any time.

🏆 Duolingo mechanics

XP, daily goal, streaks with freezes, hints (half XP), skip, 5-question sessions, weekly recap.

📜 Certification tracks

CCNA · CKA · RHCSA · AWS Solutions Architect Associate · Terraform Associate, with per-objective coverage.

📚 Your own material

Feed it notes, runbooks or postmortems and get questions grounded in your content.

🔐 Safe to host

Authenticated HTTP transport with per-user isolation, non-root Docker image, versioned DB migrations.

Quick start

git clone https://github.com/fritnes/daily-tutor-mcp.git && cd daily-tutor-mcp
cp .env.example .env                     # then set TUTOR_API_TOKENS (openssl rand -hex 32)
docker compose up -d --build
curl -i localhost:8000/mcp               # 401 = running, auth required ✅

Option B: pip

pip install git+https://github.com/fritnes/daily-tutor-mcp.git
python -m daily_tutor                    # stdio (for local clients), data in ~/.daily-tutor

Option C: from source

git clone https://github.com/fritnes/daily-tutor-mcp.git && cd daily-tutor-mcp
python -m venv .venv && source .venv/bin/activate
make install && make test

Connect your client

{
  "mcpServers": {
    "daily-tutor": {
      "command": "python",
      "args": ["-m", "daily_tutor"],
      "env": { "TUTOR_DATA_PATH": "/Users/me/.daily-tutor", "TUTOR_TZ": "Europe/Kyiv" }
    }
  }
}

Using the Docker image instead:

{
  "mcpServers": {
    "daily-tutor": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "daily-tutor-data:/data",
               "-e", "TUTOR_TRANSPORT=stdio", "-e", "TUTOR_TZ=Europe/Kyiv",
               "ghcr.io/fritnes/daily-tutor-mcp:latest"]
    }
  }
}
# local (stdio)
claude mcp add daily-tutor -e TUTOR_DATA_PATH=$HOME/.daily-tutor -- python -m daily_tutor

# remote (HTTP + bearer token)
claude mcp add --transport http daily-tutor https://tutor.example.com/mcp \
  --header "Authorization: Bearer <your-token>"

Use stdio (python -m daily_tutor) or Streamable HTTP at /mcp with an Authorization: Bearer <token> header. Clients that only support OAuth are not supported yet (see Roadmap).

Teach your assistant the flow

Install skill/SKILL.md as an agent skill. It tells the model how to run setup, ask, evaluate and session flows, so you can simply say "quiz me". For scheduled daily questions, use the built-in daily_question prompt from a cron/scheduler.

How it works

sequenceDiagram
    participant U as You
    participant L as LLM (Claude)
    participant S as daily-tutor MCP server
    participant D as SQLite

    U->>L: "quiz me"
    L->>S: get_next_question_brief
    S->>D: topics, history, due reviews
    S-->>L: topic, subtopic, type, REQUIRED answer position
    L->>S: save_question (key must match)
    S-->>L: ok / rejected (duplicate, wrong position)
    L-->>U: the question
    U->>L: "b"
    L->>S: check_answer
    alt deterministic type
        S->>D: grade, XP, streak, review schedule, level
        S-->>L: result
    else free text
        S-->>L: rubric
        L->>S: record_result
    end
    L-->>U: explanation + XP + streak

More detail in docs/ARCHITECTURE.md.

Question types

Type

You answer with

Graded by

multiple_choice

B

server

multi_select

A,C

server (partial credit)

true_false

True, because …

server verdict + LLM reason

fill_blank

the missing word(s)

server for known variants, else LLM

command_challenge

the command

server for known variants, else LLM

ordering

3,1,4,2

server (partial credit)

match_pairs

A-2, B-1, C-4, D-3

server (partial credit)

predict_output · troubleshoot · spot_the_bug · explain · design_tradeoff · flashcard

free text

LLM with a rubric

Configuration

Variable

Default

Meaning

TUTOR_DATA_PATH

~/.daily-tutor (/data in Docker)

Folder for the SQLite database

TUTOR_TZ

system

Default IANA timezone (per-user override with set_settings). Decides when "today" starts

TUTOR_TRANSPORT

stdio (streamable-http in Docker)

stdio or streamable-http

TUTOR_API_TOKENS

none

Required for HTTP. token:user,token:user

TUTOR_HOST / TUTOR_PORT

127.0.0.1 / 8000

HTTP bind address

TUTOR_PUBLIC_URL

http://localhost:8000

Public URL when behind a proxy

TUTOR_ALLOWED_HOSTS

none

Comma-separated hostnames; enables DNS-rebinding protection

All tools are documented in docs/TOOLS.md (generated from the code).

Running it for other people

  • The user identity comes from the verified bearer token; a user_id argument is ignored over HTTP, so users cannot read each other's data.

  • Put the container behind a TLS reverse proxy (Caddy, nginx, Traefik). docker-compose.yml binds to 127.0.0.1 on purpose.

  • Use long random tokens: openssl rand -hex 32. Tokens are compared in constant time.

  • The image runs as a non-root user, with a read-only root filesystem and all capabilities dropped. State lives in the /data volume: back it up. (If you bind-mount a host folder instead of the named volume, make it writable by UID 10001.)

See SECURITY.md for the threat model and how to report a vulnerability.

Development

make install     # editable install + pytest + ruff
make test        # 42 tests
make lint        # ruff
make docs        # regenerate docs/TOOLS.md
make docker-build

Project layout:

src/daily_tutor/   server.py (tools, DB, migrations) · grading.py (pure grading) · tracks.py (exam presets)
tests/             pytest suite (grading, streaks/timezones, SRS, adaptive levels, sessions, migrations…)
skill/SKILL.md     agent skill that drives the tools
docs/              architecture + generated tool reference
.specify/ .claude/  Spec Kit templates, constitution and agent skills (spec-driven workflow)
specs/             one folder per feature: spec, plan, tasks (created by Spec Kit)

New features follow spec-driven development with GitHub Spec Kit: the project principles live in .specify/memory/constitution.md and the workflow is described in CONTRIBUTING.md.

AI-assisted workflow

This project is maintained by fritnes, with AI agents supporting different parts of development:

  • Hermes reviews how the MCP is used and proposes features based on that usage.

  • Claude assists with creating and refining code for proposed features.

  • GitHub Copilot is the primary coding agent in the main repository, coordinating implementation and integrating code changes.

  • GitHub Spec Kit organizes the spec-driven development (SDD) workflow through specifications, plans, and task lists.

This is currently a small personal experiment maintained by fritnes. External contributions and pull requests are not being accepted at this time. This may change in the future.

Roadmap

  • OAuth for remote mode (claude.ai custom connectors)

  • More tracks (Security+, LFCS, Azure AZ-104, CKAD)

  • Optional web dashboard for streaks and coverage

  • Leaderboards for teams (shared instance)

  • PyPI release

License

MIT. Track objective lists are study outlines based on public exam domains; always check the official exam guide for the current blueprint.

Available Tools

26 tools
add_materialB

Store the user's own material (notes, runbook, postmortem, docs) so some questions are grounded in it. Content is split into chunks of about 1500 characters. topics = which of the user's topics it belongs to (empty = any).

Inputs: title (required), content (required), topics, user_id.

check_answerA

EVALUATE step 1: ALWAYS call this first with the user's raw reply. For letters, ordering, matching, true/false verdicts and accepted commands it grades exactly and records XP/streak itself (auto_graded=true): then just explain. Otherwise (auto_graded=false) it tells you how to judge, and you finish with record_result. bad_format=true means ask the user to reformat; the question stays open.

Inputs: question_id (required), user_answer (required), user_id.

get_coverageB

Objective coverage for one topic (great for certification tracks): which subtopics are untouched, which are weak, and the overall coverage %.

Inputs: topic (required), user_id.

get_due_reviewsC

Spaced-repetition queue: what is due now and what is coming in the next 7 days.

Inputs: user_id.

get_next_question_briefA

ASK step 1. Returns exactly what to write: topic(s), subtopic, level, question TYPE, writing instructions, the REQUIRED answer position, and what to avoid. Overdue spaced-repetition reviews are served first (alternating with new questions). Optional: topic = user asked for one topic now; from_material = ground the question in the user's own material. Write ONE question, then store it with save_question. Never reveal the answer.

Inputs: topic, user_id, session_id, from_material.

get_pending_questionB

The latest unanswered question with its answer key and grading guide (for you, not the user).

Inputs: user_id.

get_preferencesC

Topics (level, auto-adjust, subtopics), question types, goal, timezone, data location. If configured is false, run SETUP: ask which topics (any, several allowed) and level.

Inputs: user_id.

get_progressB

XP, streak (with freezes), daily goal, accuracy per topic and per question type, weakest topic/type, review queue. Use for 'how am I doing?' / 'where is my progress?'.

Inputs: user_id.

get_sessionC

Progress of a session (and its summary once finished).

Inputs: session_id (required), user_id.

list_materialsC

The user's stored materials.

Inputs: user_id. Returns: result

list_question_typesB

All question types: how to write them, how the user answers, how they are graded.

Inputs: no named parameters.

list_tracksA

Certification/learning tracks the user can start (exam objectives become subtopics).

Inputs: no named parameters.

record_resultA

EVALUATE step 2 (only when check_answer said auto_graded=false): record 'correct', 'partial' or 'wrong'. Awards XP, updates streak, schedules spaced repetition, adapts the level. Then explain why the right answer is right, why the tempting wrong one fails, and add one real-world gotcha.

Inputs: result (required), question_id (required), user_id, user_answer.

remove_materialC

Delete a stored material.

Inputs: material_id (required), user_id. Returns: result

remove_topicB

Drop one topic (history is kept).

Inputs: name (required), user_id. Returns: result

review_mistakesC

Past wrong/partial answers with the right answer and explanation, newest first.

Inputs: limit, topic, user_id. Returns: result

save_questionA

ASK step 2: store the question you wrote. Use the topics/qtype from the brief and put the correct answer where the brief REQUIRED it (answer_key must match required_answer_key). concept = 2-6 word tag of the single idea tested. correct_answer = readable answer text. key_points = what a good free-text answer contains. The server rejects duplicates and wrong answer positions: fix and resend. Then show the user ONLY the question + reply format.

Inputs: qtype (required), topics (required), concept (required), question (required), +10 more.

set_preferencesB

SETUP: replace the user's topic list. Topics are chosen BY THE USER, can be anything and several at once (e.g. ["sysadmin", "devops", "network engineer"]). All get the same starting level (it adapts later). Afterwards propose 6-10 subtopics per topic and save them with set_topic, or offer a certification track (list_tracks).

Inputs: topics (required), level, user_id. Returns: result

set_question_typesC

Choose which question types the user wants (empty list = all).

Inputs: enabled (required), user_id. Returns: result

set_settingsB

Set the daily XP goal (default 20) and/or the user's IANA timezone (e.g. 'Europe/Kyiv'). The timezone decides when 'today' starts, which matters for streaks.

Inputs: user_id, daily_goal_xp, timezone_name. Returns: result

set_topicA

Add or update ONE topic: its level, its subtopics (replaces the list), and whether the level adapts automatically (auto_adjust). Setting a level manually restarts adaptation from now.

Inputs: name (required), level, user_id, subtopics, +1 more. Returns: result

skip_questionC

The user skipped the question: no XP, no streak. Counts toward a session's length.

Inputs: question_id (required), user_id.

start_sessionA

Start a lesson of n questions (default 5, max 20) asked one at a time, ending with a summary. Then loop: get_next_question_brief(session_id) -> write -> save_question -> user answers -> check_answer/record_result -> next, until the session reports done.

Inputs: n, user_id.

start_trackA

Add a certification track as a topic; its objectives become subtopics so get_coverage can show which objectives are still untouched.

Inputs: track_id (required), level, user_id. Returns: result

use_hintB

The user asked for a hint. Returns it; XP for this question is halved.

Inputs: question_id (required), user_id.

weekly_recapB

Data for a weekly recap: this week vs last week (questions, accuracy, XP, active days), topic deltas, improved/weakest areas, streak, reviews mastered. Write the recap yourself.

Inputs: user_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 26 tools

    Disambiguation4/5

    Most tools map to a clearly distinct step in a well-signposted workflow (SETUP, ASK step 1/2, EVALUATE step 1/2), and descriptions explicitly say when to use which. The main friction points are the config cluster (set_preferences vs. set_topic vs. set_settings) and the analytics cluster (get_progress vs. get_coverage vs. weekly_recap), where boundaries are clear only after reading the detailed descriptions.

    Naming Consistency4/5

    Predominantly a consistent snake_case verb_noun pattern (set_topic, get_session, save_question, check_answer, remove_material). A few deviations exist, notably use_hint and weekly_recap which lack a clarifying verb, and the very long get_next_question_brief, but nothing is ambiguous or chaotically mixed.

    Tool Count3/5

    26 tools is on the heavy side; while the domain (setup, materials, sessions, question authoring, grading, spaced repetition, analytics) legitimately spans many stages, several tools are fine-grained splits that could be consolidated. The check_answer/record_result and get_next_question_brief/save_question pairs in particular feel like protocol steps rather than standalone capabilities.

    Completeness4/5

    The lifecycle is well covered: onboarding, topic/track management, material ingestion, session flow, question generation, grading, spaced repetition, mistakes review, and analytics. Minor gaps exist, such as no way to abandon/reset a session or edit a previously saved question, but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers