Ментор від Читай

Журнал змін

Поточна версія — 1.0.0-beta.13. Журнал змін ведемо англійською.

Правила

Versioning policy (FR-032): [semver](https://semver.org). Agents and their operators depend on tool names, input fields and result fields, so:

  • Major — a tool, an input field or a result field is removed, renamed, or changes meaning; a required input field is added.
  • Minor — a tool is added; an optional input field or a result field is added.
  • Patch — descriptions, documentation and fixes that do not change a shape.

A pre-release (-beta.N) may break any of this, and says so here.

Every release bumps version.ts and adds an entry below, newest first.

Unreleased — 2026-11-01

  • `quota_exceeded` now carries details.limit (weekly | daily) and details.resetsAt (ISO UTC); the message names the time in UTC. There is no lesson count any more: AI work is gated by a daily safety limit. rate_limited is unchanged.
  • Changed. Blocks per worksheet: 40 → 15 (tutor_get_block_schema → limits.blocksPerWorksheet). The rule holds for every way of adding a block, not only tutor_create_lesson. Worksheets that already hold more keep working; only adding is refused.
  • `tutor_add_block` answers limit_reached with a new optional limit field when the worksheet is full, and a problem at worksheetId. Put the block on another worksheet.
  • `tutor_create_lesson` reports every worksheet over 15 blocks at once, each with its path and count, and creates nothing.
  • Changed. Blocks per worksheet: 15 → 20 (tutor_get_block_schema → limits.blocksPerWorksheet). tutor_add_block answers limit_reached for the 21st block, and tutor_create_lesson reports sheets over 20. Worksheets that hold more keep working.
  • Authoring guide. The vocabulary note now says expression holds only the word or phrase (with its article); plural, government and usage notes go with the meaning.
  • Changed. The gap-no-base-word warning is now one per block (have = the number of gaps, text = their numbers), and is not given when the block's instruction says the answer is several words («lassen», «інфінітив», «два слова»).
  • Warnings gain three rules: matching-duplicate, passage-script and gap-no-base-word, and two optional fields, text and itemId. tutor_create_lesson and tutor_add_worksheet return them whether or not a template is named; tutor_add_block and tutor_update_block have a new optional warnings result (an update of only the key is checked against the saved content). A warning never stops a save.

1.0.0-beta.13 — 2026-10-28

Breaking (pre-release). Mentor no longer writes lesson content on a tool call: the agent writes it, and Mentor stores it. Read /mcp/authoring-guide.md or call tutor_get_authoring_guide first.

  • Removed (switched off, not deleted). tutor_generate_lesson and tutor_get_generation_status are no longer in tools/list; a call to either answers the new not_available error. The needsGeneration field is gone from the block-edit result.
  • Added tools. tutor_get_block, tutor_add_worksheet, tutor_read_source, tutor_get_authoring_guide, tutor_archive_course.
  • Added fields. template, course and warnings on tutor_create_lesson; template and warnings on tutor_add_worksheet; briefFor on tutor_get_course and its brief result; authoring on tutor_get_block_schema. Warnings never block a save.
  • New error. not_available: the tool exists but is switched off on this server; use the tool the message names, do not retry.
  • Changed. The block-edit rule: a block is edited by writing its content, with no regeneration.
  • Folded in (from Unreleased). - A refusal because of the teacher's plan (spec 114) is a limit_reached error whose result has a new optional field, details: { error: "teacher_plan_limit", kind: "lessons" | "students", limit, plan, message }. Nothing was created and nothing existing changed; the agent must not retry, and tells the teacher where the plans are. - The assistant (spec 106) calls the same tools in process, as a new principal kind, assistant: it is not a token, it has the teacher's own scopes and its calls are written to the call log with source = 'assistant'.

1.0.0-beta.12 — 2026-10-11

Wording only: the product calls the person who uses it «викладач», not «вчитель». The tutor_archive_lesson description and the Ukrainian docs text say so. No tool, input or result field changed.

1.0.0-beta.11 — 2026-10-08

Reshaping a lesson that already exists: an agent could add and remove blocks but not copy a lesson, change what a sheet is for, or remove a sheet, so a taught lesson could not be turned into a self-study one without the teacher doing it by hand.

  • New tools. tutor_copy_lesson (a whole copy under an optional title; returns the new lesson's sheets with id, title, purpose, blockCount), tutor_update_worksheet (title and/or purpose of a sheet) and tutor_delete_worksheet (archives a sheet; a lesson's last live sheet is refused).
  • A lesson holds one live sheet per purpose, so setting a purpose another live sheet already has fails with conflict; remove or retarget that sheet first.
  • HTTP 409 from the shared services now maps to conflict instead of validation_failed.

1.0.0-beta.10 — 2026-10-08

Tool hints corrected after the ChatGPT tool scan; no input or result changes.

  • tutor_generate_lesson: openWorldHint: true (it fetches article and YouTube links and calls an AI model).
  • tutor_update_lesson, tutor_update_course, tutor_update_image: destructiveHint: true (they overwrite or clear fields, and an image's alt text changes in every block that shows it).
  • tutor_publish: destructiveHint: true (it makes a course public, and unpublishing removes it).

1.0.0-beta.9 — 2026-10-08

  • tutor_upload_images: each entry of files now declares download_url and file_id as required, matching ChatGPT's documented file schema (the plugin tool scan rejected the schema without it).

1.0.0-beta.8 — 2026-10-09

Images in lessons.

  • New tools. tutor_upload_images (modes url, file, link, drop), tutor_get_upload, tutor_list_images, tutor_update_image (alt text) and tutor_delete_image (confirm: true required; without it the tool lists where the image is used and deletes nothing).
  • Block content takes images by reference. content.images (up to 5) on open_prompt, writing, gap_fill, theory and passage; image on mcq questions, matching left items and vocabulary items; content.imageSlot { want } for a picture the teacher adds later. An image is { "assetId": "…" }; the server fills the rest and refuses an unknown id with the path of the field.
  • ChatGPT files. tutor_upload_images carries _meta["openai/fileParams"] = ["files"].
  • tutor_get_block_schema describes the image fields; tutor_get_lesson returns previewUrl next to every image.
  • New error codes link_expired and fetch_refused.

1.0.0-beta.7 — 2026-10-04

  • tutor_update_lesson takes an optional worksheetTitle: the title of the lesson's first sheet, so a sheet title can be changed without recreating the lesson.

1.0.0-beta.6 — 2026-10-04

Sign-in with OAuth (ChatGPT and other MCP clients), and lessons generated for a course.

resource_metadata="…" on 401, /.well-known/oauth-protected-resource/api/mcp` (RFC 9728) and

  • OAuth 2.1. Besides a personal token, a client may now sign the teacher in: authorization code + PKCE (S256), public clients only. Discovery: WWW-Authenticate: Bearer /.well-known/oauth-authorization-server (RFC 8414). Clients register with a client ID metadata document (an https client_id) or dynamic registration (RFC 7591). Access tokens (chitay_oat_…`) last an hour; refresh tokens rotate. A connection appears in the teacher's token list and is revoked there like a token.
  • Every tool in tools/list now has annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and securitySchemes (the OAuth scope it needs). Destructive: tutor_delete_block, tutor_archive_lesson, tutor_remove_lesson_from_course, tutor_update_block.
  • scope_missing for an OAuth connection carries _meta["mcp/www_authenticate"], so the client can offer to sign in again with the missing scope.
  • tutor_generate_lesson: three optional fields. courseId writes the lesson for that course — the course's title, level, audience, outcomes, outline and what the previous lessons taught go into the brief — and adds it to the course at position (default last); subject and level default to the course's, so subject is no longer required. generateExercises: true continues past the material step: the model plans the lesson and the exercises are generated, with no extra quota. The result has course when courseId was given.
  • tutor_get_generation_status reports such a lesson as generating until it is done.

1.0.0-beta.5 — 2026-10-01

Descriptions and rules take formatted text.

  • The course description in tutor_create_course and tutor_update_course is formatted text: **bold**, *italic*, ~~strike~~, blank-line paragraphs, - and 1. lists, > quote. Up to 2,000 visible characters (markers not counted); maxLength is now 4,000, the stored ceiling.
  • The lesson description in tutor_create_lesson, tutor_generate_lesson and tutor_update_lesson keeps **bold**, *italic*, ~~strike~~ and paragraphs; list and quote lines are kept as typed. Up to 500 visible characters; maxLength is now 1,000.
  • forWhom and outcomes items also keep ~~strike~~.
  • tutor_get_block_schema for theory returns formatting: the rule's paragraphs may use the same formatting.
  • Over a visible limit, the tools answer validation_failed with the field's path (description; lesson.description in tutor_create_lesson).
  • tutor_get_course and tutor_get_lesson return the text as stored, markers included. The docs have a new section, «Форматований текст».

1.0.0-beta.4 — 2026-10-01

Courses say who they are for and what a learner gets.

  • tutor_create_course and tutor_update_course accept two optional lists, forWhom («Для кого цей курс») and outcomes («Що ви отримаєте після курсу»), shown on the course's storefront page and to its students. Up to 8 items of up to 200 visible characters each; only **bold** and *italic* are kept, other formatting is removed. A list is replaced whole; null or [] clears it.
  • Over a limit, both answer validation_failed with the path forWhom / outcomes (too many items) or forWhom[i] / outcomes[i] (an item too long).
  • tutor_get_course returns forWhom and outcomes, always arrays.

1.0.0-beta.3 — 2026-10-01

Lessons in use stay editable; courses carry a pacing.

  • Breaking (pre-release): the error code edit_locked is gone. Every lesson tool now changes a lesson whatever students have done on it; answers, scores and feedback already handed in are kept. tutor_get_lesson still returns editable, always true.
  • tutor_create_course and tutor_update_course accept pacing: teacher_paced (the default) or self_paced, where a student opens each next lesson themselves. Pacing cannot change once the course has been assigned; tutor_update_course then answers the new error code conflict. tutor_get_course returns pacing and pacingLocked.

1.0.0-beta.2 — 2026-09-30

Five tools, from what a nine-lesson course build missed. 20 tools now.

  • tutor_update_lesson — change a lesson's title, description, subject, level or instruction language (edit_locked once students work on it).
  • tutor_archive_lesson — take a lesson out of the library. It is archived, not destroyed; the teacher restores it in the web app.
  • tutor_get_course — a course with its lessons in order, each with the stepId the two tools below take.
  • tutor_remove_lesson_from_course and tutor_reorder_course_lessons — undo an add and set the order of a course's lessons.
  • Fix: tutor_list_lessons and tutor_get_lesson reported a lesson written by hand as planned; they now say completed, as tutor_get_generation_status already did.
  • A call whose arguments were sent inside a raw, input or arguments wrapper now gets an error that says so.

1.0.0-beta.1 — 2026-09-30

First release. Personal access tokens (read, write, publish scopes) and the tutor toolset, 15 tools. A beta may still change any of them; changes are listed here.

  • tutor_list_lessons, tutor_get_lesson, tutor_get_block_schema, tutor_list_courses, tutor_get_generation_status — read.
  • tutor_create_lesson, tutor_add_block, tutor_update_block, tutor_delete_block, tutor_reorder_blocks — write a lesson by hand; the first is all-or-nothing and every problem comes back with its path.
  • tutor_generate_lesson — start the platform's own generation from a topic, an article, a YouTube link or a transcript. It stops at the plan step, which the teacher confirms in the web app; the status tool reports pending there.
  • tutor_create_course, tutor_update_course, tutor_add_lesson_to_course — courses.
  • tutor_publish — publish or unpublish a course; needs the publish scope and a teacher account allowed to publish.
  • subject and level of tutor_create_lesson and tutor_generate_lesson are now enums (the same lists the web form and the courses tools use); the reference lists the allowed values with their names. /llms.txt and /mcp/docs.md?tool=<name> serve the docs one tool at a time.