Сервер MCP для Ментор
Сервер MCP дозволяє ШІ-агентові, якому ви довіряєте, створювати й редагувати ваші уроки та курси в Ментор: від порожнього аркуша до готового уроку з вправами, ключами відповідей і посиланням для перегляду.
Що це і кому потрібне
MCP (Model Context Protocol) — відкритий протокол, яким ШІ-застосунки звертаються до зовнішніх інструментів. Сервер Ментор показує агентові набір інструментів із префіксом tutor_: створити урок, додати чи змінити блок, скласти курс, прочитати довідник з авторингу, опублікувати. Ментор нічого не пише за агента: зміст уроку складає сам агент за довідником (tutor_get_authoring_guide, також /mcp/authoring-guide.md), а Ментор перевіряє його й зберігає.
- Вам потрібні готові матеріали в Ментор, а писати вправи вручну довго: опишіть агентові урок — він створить його одним викликом.
- Ви вже користуєтеся Claude, Cursor чи іншим клієнтом MCP і хочете працювати з уроками звідти.
- Ви автоматизуєте виробництво матеріалів власним скриптом: протокол відкритий, а кожен інструмент описано з прикладами.
Агент працює від вашого імені й лише в межах дозволів токена. Створене ним — чернетки, які бачите тільки ви.
Підключення
- Відкрийте в Ментор сторінку «Налаштування» і знайдіть розділ «ШІ-агенти (MCP)».
- Натисніть «Створити токен», дайте йому назву (наприклад, «Claude на ноутбуці»), оберіть дозволи й термін дії.
- Скопіюйте токен одразу: повністю він показується лише один раз. Далі в списку видно лише назву та останні символи.
- Вставте токен у налаштування вашого клієнта за одним із прикладів нижче.
Адреса сервера — 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, а помічник у Менторі знову генеруватиме уроки. Код генерації не видаляється, форма на сайті від цього перемикача не залежить.
