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

Сервер MCP для Ментор

Сервер MCP дозволяє ШІ-агентові, якому ви довіряєте, створювати й редагувати ваші уроки та курси в Ментор: від порожнього аркуша до готового уроку з вправами, ключами відповідей і посиланням для перегляду.

Що це і кому потрібне

MCP (Model Context Protocol) — відкритий протокол, яким ШІ-застосунки звертаються до зовнішніх інструментів. Сервер Ментор показує агентові набір інструментів із префіксом tutor_: створити урок, додати чи змінити блок, скласти курс, прочитати довідник з авторингу, опублікувати. Ментор нічого не пише за агента: зміст уроку складає сам агент за довідником (tutor_get_authoring_guide, також /mcp/authoring-guide.md), а Ментор перевіряє його й зберігає.

  • Вам потрібні готові матеріали в Ментор, а писати вправи вручну довго: опишіть агентові урок — він створить його одним викликом.
  • Ви вже користуєтеся Claude, Cursor чи іншим клієнтом MCP і хочете працювати з уроками звідти.
  • Ви автоматизуєте виробництво матеріалів власним скриптом: протокол відкритий, а кожен інструмент описано з прикладами.

Агент працює від вашого імені й лише в межах дозволів токена. Створене ним — чернетки, які бачите тільки ви.

Підключення

  1. Відкрийте в Ментор сторінку «Налаштування» і знайдіть розділ «ШІ-агенти (MCP)».
  2. Натисніть «Створити токен», дайте йому назву (наприклад, «Claude на ноутбуці»), оберіть дозволи й термін дії.
  3. Скопіюйте токен одразу: повністю він показується лише один раз. Далі в списку видно лише назву та останні символи.
  4. Вставте токен у налаштування вашого клієнта за одним із прикладів нижче.

Адреса сервера — https://mentor.chitay.org.ua/api/mcp. Сервер працює за протоколом MCP (Streamable HTTP) і приймає лише запити POST із заголовком Authorization: Bearer <токен>.

Виконайте команду в терміналі.

claude mcp add --transport http chitay https://mentor.chitay.org.ua/api/mcp --header "Authorization: Bearer chitay_pat_ВАШ_ТОКЕН"

Токен — це пароль до вашого облікового запису в межах обраних дозволів. Не передавайте його іншим і не публікуйте. Якщо токен потрапив не до тих рук, відкличте його в налаштуваннях: він перестане діяти одразу.

Дозволи, ліміти й чернетки

Кожен токен має один або кілька дозволів. Кожен інструмент вимагає одного з них; у довіднику він указаний біля назви.

ДозвілЩо дозволяє
readПереглядати уроки й курси, читати схеми блоків.
writeСтворювати й змінювати уроки, блоки та курси. Включає read.
publishПублікувати курс у каталозі та знімати з публікації. Включає read і write.

Усе, що агент створює, — приватні чернетки. Жоден інструмент не видає урок студентам і не надсилає повідомлень: викладач відкриває посилання reviewUrl, переглядає результат і вирішує сам.

Урок можна правити й тоді, коли студенти вже з ним працюють: зміни одразу бачать усі, кому його видано. Уже здані роботи й оцінки не змінюються.

Курс має спосіб проходження pacing: teacher_paced — уроки відкриває викладач (типово), self_paced — студент сам завершує урок і відкриває наступний. Щойно на курс когось записано, змінити спосіб уже не можна: tutor_update_course відповідає кодом conflict.

Ще два поля курсу — списки forWhom («Для кого цей курс») і outcomes («Що ви отримаєте після курсу»). Їх бачать студенти курсу, а після публікації — відвідувачі сторінки курсу на Читай. До 8 пунктів, кожен до 200 видимих символів; з форматування лишаються тільки **жирний**, *курсив* і ~~закреслений~~, решта прибирається. Список замінюється цілком; null або [] очищає його. tutor_get_course повертає обидва списки.

ЛімітЗначення
Запити на один токендо 60 на хвилину (типове значення)
Запити від одного викладачадо 600 на годину, усіма токенами разом (типове значення)
Активних токенівдо 10
Розмір запитудо 1 МБ

Щоб перевірити токен, достатньо викликати tools/list. Список інструментів повертається для будь-якого дозволу — агент бачить усе, що існує, навіть якщо викладач ще не дав права цим скористатися.

Форматований текст

Опис курсу, пункти forWhom / outcomes, опис уроку і правило в блоці theory — форматований текст: невелика частина markdown. Його зберігають і повертають (tutor_get_course, tutor_get_lesson) таким, як написано, а студентам показують відформатованим.

ЕлементЯк писати
Жирний**текст**
Курсив*текст*
Закреслений~~текст~~
Абзацпорожній рядок між абзацами; один перенос — новий рядок
Списокрядки - пункт
Нумерований списокрядки 1. пункт
Цитатарядки > текст
НаголосU+0301 одразу після голосної: за́мок
Сам символ\*, \~, \\; на початку рядка ще \-, \>, \1.
ПолеЩо дієВидимих символів
Опис курсу descriptionуседо 2000
Пункт forWhom[i], outcomes[i]жирний, курсив, закресленийдо 200
Опис уроку descriptionжирний, курсив, закреслений, абзацидо 500
Правило theory.content.rule[]усе; кожен абзац — окремий елемент масивубез окремого ліміту
  • Видимі символи — те, що бачить читач: маркери, - / 1. / > на початку рядка, зворотні скісні й наголос не рахуються, перенос рядка — один символ.
  • Більше за ліміт — validation_failed зі шляхом до поля (description, lesson.description, forWhom[2]).
  • Розмітка, якої поле не має, не помилка: її зберігають, як написано, і показують звичайним текстом. Порожні пари маркерів прибираються.

Зображення в уроках

Зображення потрапляють у блок за assetId. Спершу завантажте файл інструментом tutor_upload_images (або знайдіть уже завантажений через tutor_list_images), потім передайте { "assetId": "…" } у вмісті блока: images (до 5) у відкритих питаннях, письмі, пропущених словах, теорії й тексті; image у питанні тесту, лівому елементі відповідності та слові словника. Решту полів сервер заповнює сам.

КлієнтЯкий режим `tutor_upload_images`
ChatGPT (застосунок Ментор)file: вкладені файли й картинки, створені ChatGPT. Якщо файл прийшов без download_url — drop.
Claude Code, Codex та інші агенти з оболонкоюlink і curl, або url
Claude.ai та чати без передавання файлівdrop: агент дає сторінку, викладач відкриває її й додає файли
Будь-який клієнт, публічна картинкаurl: адреса https
  • PNG, JPEG або WebP до 20 МБ кожен; до 5 файлів за раз. Сервер зменшує зображення до 2000 пікселів, перекодовує у WebP і прибирає метадані, зокрема геолокацію.
  • Сховище викладача — 500 МБ. Після переповнення файл повертається з кодом quota.
  • link працює 15 хвилин і один раз; drop — 30 хвилин, і сторінку може відкрити лише власник токена.
  • url приймає тільки публічні адреси https: приватні мережі, перенаправлення на них і відповіді, що не є зображенням, відхиляються з кодом fetch_refused.
  • tutor_update_image змінює опис (alt) у бібліотеці й в усіх блоках; tutor_delete_image без confirm: true лише показує, де зображення використовується.

Зображення бачитиме кожен, хто має посилання на урок. Не додавайте фото студентів і персональних документів.

Формат помилок

Якщо інструмент не виконався, відповідь має ознаку isError: true і один текстовий елемент із JSON такого вигляду:

{
  "error": {
    "code": "validation_failed",
    "message": "Вхідні дані не прийнято: 2 проблеми.",
    "problems": [
      {
        "path": "lesson.worksheets[0].blocks[3].content.questions[1].options",
        "code": "schema",
        "message": "Має бути щонайменше 2 варіанти відповіді."
      },
      {
        "path": "lesson.worksheets[0].blocks[3].content[q2]",
        "code": "invariant",
        "message": "Ключ посилається на варіант, якого немає."
      }
    ]
  }
}
  • code стабільний: за ним агент вирішує, що робити. Перелік кодів — у довіднику.
  • message написано для людини, його формулювання може змінитися. Повідомлення перевірки блоків українською, як і для викладачів у веб-інтерфейсі.
  • problems є лише в validation_failed і містить усі знайдені проблеми одразу, тож виправити можна за одну спробу.
  • path — шлях до місця помилки від кореня аргументів виклику: a.b[0].c. Елемент списку блока, у якого є id, позначено ним у квадратних дужках.
  • Поле, якого інструмент не знає, теж validation_failed зі шляхом до цього поля — його ніколи не відкидають мовчки.

Помилки автентифікації — це HTTP-відповіді до початку роботи з MCP: 401 (токен відсутній, невідомий, відкликаний або прострочений; заголовок WWW-Authenticate: Bearer realm="chitay-mcp", resource_metadata="…" — за ним OAuth-клієнт знаходить, де увійти) і 403, якщо обліковий запис уже не має доступу.

Що зберігається

Токен зберігається лише у вигляді одностороннього відбитка: відновити його з бази неможливо. Для кожного виклику записується журнал — хто (токен), який інструмент, з яким результатом, коли й скільки тривало. Вмісту уроків, студентів і IP-адрес у журналі немає; записи видаляються через 90 днів.

Версії

Сервер повідомляє версію в serverInfo.version і дотримується семантичного версіювання. Мажорна версія змінюється, якщо інструмент або поле зникає, перейменовується чи змінює значення; додавання інструмента або необов’язкового поля — мінорна; виправлення опису чи документації — патч. Кожна зміна записується в журналі змін. Попередні випуски (-beta.N) можуть змінювати що завгодно, і це буде сказано в журналі.

Увімкнути генерацію назад (для супровідників). Інструменти tutor_generate_lesson і tutor_get_generation_status вимикає константа GENERATION_TOOLS_ENABLED у lib/mcp/tools/generationSwitch.ts. Щоб повернути їх, змініть значення на true і розгорніть сервіс: обидва інструменти з’являться в tools/list, а помічник у Менторі знову генеруватиме уроки. Код генерації не видаляється, форма на сайті від цього перемикача не залежить.