Course QK — Test Bank & Timetable MCP

An MCP server for Course QK. Two modules:

• Test bank (/bank) — subjects, topics, questions (create, read, update, delete).
• 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

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

{
  "mcpServers": {
    "qk-mcp": {
      "command": "npx",
      "args": ["-y", "@innlabkz/qk-mcp"],
      "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

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_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 |

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" }