Course QK — Test Bank & Timetable MCP

An MCP server for Course QK. Two modules:

• Test bank (/bank) — subjects, topics, questions (create, read, update, delete), and publishing subjects in the UBT Battle mobile app. See UBT Battle app below.
• Timetable (/timetable) — subjects, teachers, classes, rooms, lessons, scheduling rules, and async schedule generation (Timefold solver). See Timetable below.

How the test bank works

Group (subject)  ─┬─►  Topic  ─┬─►  Question
   name, color    │    name    │    type, difficulty, grade, body,
   icon, subject  │    grade   │    options, correctAnswer, explanation,
                  │    tags    │    hints, score, timeLimitSec

All ids are UUIDs. Deletes are soft (deletedAt). REST base: /api/bank/*.

LaTeX / KaTeX storage format

Rich fields (body, explanation, option texts) are stored as Quill Delta JSON ({ ops: [...] }). Math is a Quill formula embed op:

{ "insert": { "formula": "x^2 + 1 = 0" } }

The frontend renders it via quill-delta-to-html → <span class="ql-formula">…</span> → KaTeX.

You do not author Delta by hand. Tools accept LaTeX-aware plain text and this server builds the Delta for you:

| Syntax | Meaning | Stored as | | ------------- | ------------------------------------ | ---------------------------------------------------- | | $x^2$ | inline formula | {insert:{formula:"x^2"}} inline | | $$\frac ab$$| display formula (own line, centered) | embed + {insert:"\n",attributes:{align:"center"}} | | plain text | text run | {insert:"…"} |

Raw Delta ({ops:[…]} object or JSON string) is accepted too, as an escape hatch.

Question types

| Type | Inputs | | ---------- | ------------------------------------------------------------------------------- | | SINGLE | options: string[], correct: [i] (one index) | | MULTIPLE | options: string[], correct: number[] (one or more indices) | | MATCHING | lefts: string[], rights: string[], matches: [{left:i, rights:[j,…]}] |

Call the bank_format_guide tool at runtime for the same reference plus a worked example.

Auth

Authentication is via an API key created in the web app (Admin → API кілттер). The key travels in the X-API-Key header; the backend maps it to its owner, so tools require the owner to hold the matching permission:

| Tool prefix | Read permission | Write permission | | ----------- | ----------------- | ------------------- | | bank_* | any valid key | bank.write | | tt_* | timetable.read | timetable.write |

Organization (X-Org-Id)

Timetable data is org-scoped (a school = an organization). Pick the org per call:

1. tt_list_orgs → the orgs the key owner belongs to.
2. Pass the chosen orgId to any tt_* tool (sent as the X-Org-Id header).

If the owner belongs to exactly one org, the backend defaults to it and orgId may be omitted. Generation and job polling always require an active org.

Setup

Published on npm as @innlabkz/qk-mcp — run it directly with npx, no clone needed.

Set QK_API_KEY (see .env.example). Optionally set QK_BASE_URL (defaults to https://qk.oqai.org; use http://localhost:7070 for local dev).

Register with Claude Code

claude mcp add qk-mcp \
  --env QK_API_KEY=qk_your_key_here \
  -- npx -y @innlabkz/qk-mcp@latest

Or add to .mcp.json / client config manually:

{
  "mcpServers": {
    "qk-mcp": {
      "command": "npx",
      "args": ["-y", "@innlabkz/qk-mcp@latest"],
      "env": { "QK_API_KEY": "qk_your_key_here" }
    }
  }
}

From source

cd mcp
npm install
npm run build
# then point the client at node /absolute/path/to/course-qk/mcp/dist/index.js

Updating

The client loads the server and its tool list once, at startup. After any update, restart the client (in Claude Code, start a new session or reconnect in /mcp). How to update depends on how the server is registered:

• npx -y @innlabkz/qk-mcp@latest: restart the client; npx fetches the newest version. Without @latest, npx may keep running an older copy from its cache. To fix that, add @latest (or pin a version such as @0.4.1) to the args.
• Global install ("command": "qk-mcp"): run npm i -g @innlabkz/qk-mcp@latest.
• From source: run git pull, then npm install && npm run build in mcp/.

npm i @innlabkz/qk-mcp in a project folder does not update the server: it installs into that folder's node_modules, which the client does not use.

To check the version, ask the agent to call a tool from the latest release, for example bank_list_ubt_subjects (added in 0.4.0). Release notes: Changelog.

Tools

| Tool | Purpose | | --------------------- | ---------------------------------------------------- | | bank_list_groups | List subjects with topic counts | | bank_create_group | Create a subject (bank.write) | | bank_update_group | Update a subject (bank.write) | | bank_delete_group | Soft-delete a subject (bank.write) | | bank_list_ubt_subjects | UBT subject codes + exact titles for the UBT Battle app | | bank_publish_group | Publish a group in the UBT Battle app, or withdraw it (super-admin) | | bank_group_readiness| Topic/question counts and where the subject will show up in the app | | bank_list_topics | List topics in a group | | bank_get_topic | Get one topic | | bank_create_topic | Create a topic (bank.write) | | bank_update_topic | Update a topic (bank.write) | | bank_delete_topic | Soft-delete a topic (bank.write) | | bank_list_questions | List questions in a topic (+ body preview) | | bank_get_question | Get one question (full Delta payload) | | bank_create_question| Create a question, LaTeX-aware (bank.write) | | bank_update_question| Replace a question's content (bank.write) | | bank_delete_question| Soft-delete a question (bank.write) | | bank_list_question_groups | List passage groups in a topic | | bank_get_question_group | Get a passage group + its sub-questions | | bank_create_question_group | Create a passage (shared stimulus) (bank.write) | | bank_update_question_group | Update a passage (bank.write) | | bank_delete_question_group | Soft-delete a passage + sub-questions (bank.write) | | bank_upload_image | Upload a local image to S3, get its URL + Quill op (bank.write) | | bank_format_guide | Explain the storage/LaTeX contract at runtime |

UBT Battle app (mobile catalog)

A group is shown in the UBT Battle app once it has a ubtCode. There is no other "published" status. The app shows the subject under the fixed title of that code, not under the group's name, so the title always matches the app. Each code can belong to one group only. Publishing serves the group to every app user, so only a super-admin can do it.

1. bank_list_ubt_subjects lists the codes (CHEMISTRY → «Химия», …).
2. bank_group_readiness with the group id shows what the app will show. The app serves only live SINGLE questions. A topic opens in the trainer with ≥1 of them. Diagnostic needs ≥10. Battle and group challenges need ≥5. Battle also needs ≥2 such topics, and the code must be in the server's MOBILE_BATTLE_SUBJECTS list.
3. bank_publish_group with { id, ubtCode: "CHEMISTRY" } publishes the group. Add shortTitle: "Мат. сауаттылық" for a short battle label. Pass ubtCode: null to withdraw it.

Images

bank_upload_image uploads a local file (png/jpg/gif/webp/svg) to S3 via a presigned PUT and returns publicUrl plus a ready imageOp ({insert:{image:url}}). Drop that op into a body's Delta ops array to embed the picture in a question or passage.

Group (passage) questions

A question group is one shared passage/stimulus with several sub-questions (reading-comprehension style). Create the passage first, then create questions with groupId set to attach them:

1. bank_create_question_group → returns the group id
2. bank_create_question with groupId: "<that id>" (and optional groupOrder) per sub-question

Sub-questions keep their own type/difficulty/options; they just render under the shared passage. Questions without groupId stay standalone.

Example

Create a single-choice algebra question:

// bank_create_question
{
  "topicId": "…uuid…",
  "type": "SINGLE",
  "body": "Теңдеуді шеш: $x^2 - 4 = 0$",
  "options": ["$x = 2$", "$x = \\pm 2$", "$x = -2$", "Шешімі жоқ"],
  "correct": [1],
  "difficulty": "MEDIUM",
  "grade": 8,
  "score": 1
}

Timetable

Build and solve a school schedule. Everything is scoped to one timetable dataset; create it first, then fill it in.

Timetable ─┬─► Periods (bell schedule)
           ├─► Subjects · Teachers · Classrooms
           ├─► Classes ─► Divisions ─► Groups
           ├─► Lessons  (subject + teacher(s) + class(es)/group(s) + cards)
           ├─► Constraints  (Шектеулер — 16 rule types, HARD/SOFT)
           └─► Availability (working-time grid per teacher/class/room/subject)
     generate ─► job ─► poll ─► grid / matrix

All ids are UUIDs. A lesson decomposes into cards ([{count, length}]); the solver places each card on a day+period(+room). Unplaced cards leave those null.

Tools

| Tool | Purpose | | -------------------------- | -------------------------------------------------------------- | | tt_list_orgs | List the owner's orgs — call first, pass orgId onward | | tt_list_timetables / tt_get_timetable | List / get datasets | | tt_create_timetable / tt_update_timetable / tt_delete_timetable | Manage datasets (write) | | tt_list_periods / tt_create_period / tt_update_period / tt_delete_period | Bell schedule | | tt_list_subjects / tt_create_subject / tt_update_subject / tt_delete_subject | Subjects | | tt_list_classes / tt_create_class / tt_update_class / tt_delete_class | Classes | | tt_list_divisions / tt_create_division / tt_update_division / tt_delete_division | Class splits | | tt_create_group / tt_update_group / tt_delete_group | Subgroups within a division | | tt_list_teachers / tt_create_teacher / tt_update_teacher / tt_delete_teacher | Teachers + workload limits | | tt_list_classrooms / tt_create_classroom / tt_update_classroom / tt_delete_classroom | Rooms | | tt_list_lessons / tt_create_lesson / tt_update_lesson / tt_delete_lesson | Lessons | | tt_list_constraints / tt_create_constraint / tt_update_constraint / tt_delete_constraint | Rules | | tt_get_availability / tt_set_availability | Working-time grids | | tt_generate | Start async solve → returns jobId (Әкімші/ORG_ADMIN only, needs org) | | tt_job_status | Poll a job: RUNNING / DONE / FAILED (+ score) | | tt_last_generation | Cached summary of the last solve | | tt_grid / tt_matrix | Placed cards / dense all-classes matrix | | tt_move_card | Manually move &/or pin one card (write) |

Write tools need timetable.write; reads need timetable.read.

Constraint types (type)

hardness is HARD (must hold) or SOFT (weighted preference, weight 1–10). params carry type-specific settings (e.g. { "teacherId": "…", "day": 2 }).

• Time: TEACHER_AVAILABILITY, CLASS_AVAILABILITY, NO_GAPS, MAX_LESSONS_PER_DAY, LIMIT_EARLY_LATE
• Teacher: MIN_TEACHER_GAPS, TEACHER_MAX_HOURS_DAY, TEACHER_FREE_DAY, MAX_CONSECUTIVE
• Room: FIXED_ROOM, ROOM_CAPACITY, MIN_ROOM_CHANGES
• Pedagogical: HARD_SUBJECTS_MORNING, MERGE_DOUBLES, ONCE_PER_DAY, LUNCH_REQUIRED

Generation flow

// 0. tt_list_orgs → [{ "organizationId": "org-uuid", "name": "…мектеп", "roleCode": "…", "status": "ACTIVE" }, …]  — pick organizationId

// 1. tt_generate  → { "jobId": "…" }
{ "ttId": "…", "orgId": "org-uuid", "difficulty": "NORMAL" }

// 2. tt_job_status (poll until status != RUNNING)
{ "jobId": "…", "orgId": "org-uuid" }
// → { "status": "DONE", "result": { "feasible": true, "placedCards": 120, "unplacedCards": 0, … } }

// 3. tt_matrix (render) or tt_grid (raw cards)
{ "ttId": "…", "orgId": "org-uuid" }

Changelog

• 0.4.1 — README: UBT Battle in the overview, an Updating section, and @latest in the setup examples. No code changes.
• 0.4.0 — UBT Battle app tools: bank_list_ubt_subjects, bank_publish_group, bank_group_readiness. bank_list_groups now returns ubtCode and shortTitle.