Чат-клієнти (MCP)
Obscura можна підключити до чат-клієнта, яким ви вже користуєтеся: Claude Desktop, Claude Code або Codex. Чат читає план, картки, пам’ять і тексти сцени, пише чернетку своєю моделлю й зберігає її в Obscura. Ваш API-ключ для цього не потрібен: модель працює в межах облікового запису чат-клієнта, а Obscura сама модель не викликає.
Зв’язок іде через storygen-mcp. Це невелика програма, яку чат-клієнт запускає сам. Вона звертається до запущеної Obscura на вашому комп’ютері й більше нікуди.
Що вміє чат
Чат отримує двадцять шість інструментів:
- список творів і огляд твору: сцени, їхній порядок і стан тими самими словами, що в списку сцен, а також рейтинг, цільова довжина й персонажі твору;
- новий твір: назва, мова, цільова довжина, режим твору й, за бажанням, віковий рейтинг;
- шаблони плану й персонажів: ті самі файли, що дає сторінка твору;
- властивості твору: назва, мова й віковий рейтинг;
- нова сцена на потрібному місці твору, з планом або за зразком попередньої сцени;
- план і властивості сцени: план (лише поверх прочитаного), назва, довжина, учасники й мова прози;
- контекст сцени: план, завдання, картки учасників, пам’ять попередніх сцен, віковий рейтинг, мова й цільова довжина;
- текст сцени: поточний план, завдання, чернетка, проза або пам’ять сцени разом з ідентифікатором поточної версії; довгий текст чат читає частинами;
- імпорт плану й персонажів: так само, як форма імпорту;
- збереження чернетки: нова версія чернетки сцени, лише поверх чернетки, яку чат прочитав;
- посилання на переписування по пам’яті: посилання, що відкриває Ghost Mode поточної чернетки сцени;
- наступні кроки: посилання на сцену в Obscura;
- картка публікації: читання й зміна окремих полів картки поверх прочитаної, з каталогом жанрів FB2;
- новий підпис у спільному довіднику авторів і псевдонімів;
- обкладинка з файла на вашому комп’ютері;
- текстова обкладинка з картки публікації в одній із чотирьох палітр — коли чат не має доступу до файлів, як-от Claude Desktop зі збірки Microsoft Store;
- експорт книги у FB2, EPUB, PDF, MD чи TXT: чат дає посилання на готовий файл;
- налаштування твору: читання профілю письма, моделей ролей, стану ключів і пресетів, за бажанням — промптів і списку моделей провайдера;
- зміна налаштувань: окремих полів профілю письма чи однієї ролі поверх прочитаного;
- пресет ролей: перегляд і, з вашої згоди в чаті, застосування збереженого пресета;
- завдання етапу: інструкції й матеріал для завдання сцени, редактури чи пам’яті — такі самі, як отримала б модель Obscura;
- результат етапу: відповідь чату на завдання етапу, яку Obscura перевіряє так само, як відповідь своєї моделі;
- запуск: у творі «Пише Obscura» — перегляд і, з вашої згоди в чаті, запуск моделлю Obscura одного етапу сцени чи пропозиції картки публікації;
- стан запуску: що з запуском зараз, його результат і скасування запуску, який почав чат.
Видаляти твори й сцени, переносити їх у кошик, переставляти сцени, запускати генерацію, пропозицію анотації чи оцінювач, змінювати промпти, оцінювача, бюджет і ключі чат не може.
Встановлення
storygen-mcp входить у звичайне встановлення. Якщо Obscura встановлено раніше, повторіть дві команди встановлення в теці застосунку, щоб додати нові залежності:
./.venv/Scripts/python.exe -m pip install -r requirements-lock.txt
./.venv/Scripts/python.exe -m pip install --no-deps -e ".[web,publication]"
Після цього в теці .venv/Scripts/ з’явиться storygen-mcp.exe. Далі в прикладах тека застосунку — C:\Obscura; підставте свою.
Підключення
Кнопка в бібліотеці
Найпростіше підключитися з бібліотеки Obscura: розгорніть блок «Підключити до Claude».
- Підключити Claude Desktop дописує в налаштування Claude Desktop лише запис
obscura. Решта налаштувань лишається, а поруч з’являється копія файла до зміни (claude_desktop_config.json.obscura-backup). Obscura показує, у який файл записала, і пропонує перезапустити Claude: він читає налаштування лише під час запуску. - Перезапустити Claude зараз закриває Claude Desktop разом із відкритою розмовою, зокрема ненадісланим текстом, і відкриває знову. Перезапущу сам пояснює, як зробити це вручну: закрите вікно лишає Claude працювати, тож вийдіть через значок Claude біля годинника («Quit») і відкрийте його знову.
- Інший спосіб — запасний шлях, коли файла налаштувань ще немає (Claude Desktop жодного разу не запускали) або він має невідомий формат. Obscura готує файл розширення
obscura.mcpbу теці творів і відкриває теку. У Claude Desktop відкрийте Settings → Desktop app → Extensions, перетягніть файл у вікно й натисніть Install. Claude покаже стандартне попередження про розширення поза каталогом. - Підключити Claude Code виконує
claude mcp add --scope user obscuraі перевіряє запис. Якщо Claude Code не знайдено, Obscura показує команду з кнопкою «Копіювати».
Чат не може сам підключити чи перезапустити Claude: ці дії виконуєте лише ви в Obscura.
Вручну
Перед роботою запустіть Obscura, як звичайно. Чат-клієнт підключається до http://127.0.0.1:8765. Якщо Obscura запущено на іншому порту, додайте аргументи --url http://127.0.0.1:<порт>.
Якщо ви запускаєте Obscura без консолі через storygen-desktop (встановлення), замість --url додайте аргументи --data-dir <тека творів> (типово %USERPROFILE%\Obscura). Тоді запускати Obscura заздалегідь не треба: на першому запиті чату міст сам знайде її на будь-якому порту, а якщо вона не запущена — тихо запустить її у треї без браузера. Obscura лишиться у треї й після закриття чату; вийти з неї можна через значок.
Claude Code. У терміналі:
claude mcp add --scope user obscura -- C:\Obscura\.venv\Scripts\storygen-mcp.exe
--scope user робить сервер доступним у будь-якій теці. Без нього Claude Code бачить сервер лише в теці, де виконано команду.
Claude Desktop. Додайте сервер у файл налаштувань claude_desktop_config.json. Де лежить файл, залежить від способу встановлення:
- версія з Microsoft Store —
%LOCALAPPDATA%\Claude-Data\claude_<ідентифікатор>\claude_desktop_config.json(текаclaude_з літерами й цифрами одна); - версія зі звичайного інсталятора —
%APPDATA%\Claude\claude_desktop_config.json.
Файл може вже містити налаштування застосунку: не видаляйте їх, а додайте поруч розділ mcpServers. Поки Claude Desktop працює, він сам перезаписує цей файл, тому спершу повністю закрийте застосунок, зокрема іконку в області сповіщень. Потім збережіть файл і запустіть Claude Desktop знову. Файл лише з цим сервером виглядає так:
{
"mcpServers": {
"obscura": {
"command": "C:\\Obscura\\.venv\\Scripts\\storygen-mcp.exe"
}
}
}
Для іншого порту додайте "args": ["--url", "http://127.0.0.1:8770"]. У командах claude mcp add і codex mcp add аргументи йдуть після шляху до програми: … storygen-mcp.exe --url http://127.0.0.1:8770.
Codex. У терміналі:
codex mcp add obscura -- C:\Obscura\.venv\Scripts\storygen-mcp.exe
Або додайте в ~/.codex/config.toml розділ [mcp_servers.obscura] з рядком command = 'C:\Obscura\.venv\Scripts\storygen-mcp.exe'.
Чат-клієнти в браузері (claude.ai, chatgpt.com) локальних серверів не підтримують.
Як писати з чатом
- Обговоріть із чатом ідею, план і персонажів.
- Попросіть імпортувати план і персонажів у потрібний твір. Твір чат може створити сам (див. нижче) або ви створюєте його в Obscura заздалегідь. Імпорт додає матеріали так само, як форма, і сам не повторюється.
- Попросіть прочитати контекст першої сцени й написати чернетку. Чат зберігає її як поточну чернетку сцени.
- Щоб доповнити чи переписати наявну чернетку, попросіть чат спершу прочитати її. Чат пише поверх прочитаного тексту, тож ваші правки, зроблені в Obscura, не губляться.
- Відкрийте сцену в Obscura за посиланням з чату. Попередня чернетка, якщо вона була, лишається в історії версій.
- Перепишіть чернетку власними словами в режимі переписування по пам’яті, затвердіть прозу й оновіть пам’ять сцени. Попросіть чат дати посилання на переписування: воно відкриє режим одразу, без пошуку сцени й кнопки.
- Переходьте до наступної сцени.
Почати твір із чату
Попросіть чат створити твір: назву, мову (українська чи англійська) і, якщо хочете, віковий рейтинг. Потім чат бере шаблони плану й персонажів, заповнює їх разом із вами й імпортує. Далі він може додати сцени, переписати план сцени, змінити назву, мову чи рейтинг твору.
- Створення твору мову не фіксує. Мову можна змінити, доки в творі немає тексту від моделі чи чату. План, назви й персонажі, записані з чату, мову теж не фіксують.
- У виданні з Microsoft Store рейтинг понад межу видання відхиляється, і твір тоді не створюється.
- План сцени чат переписує лише поверх прочитаного. Якщо ви змінили план після того, як чат його прочитав, запис відхиляється з поясненням «План сцени змінено після того, як його прочитали» і нічого не зберігає.
- Попередній план лишається в історії версій сцени. План із чату там не позначено окремо: це ваш авторський матеріал.
- Кілька властивостей твору чат змінює по черзі. Якщо одну з них відхилено (наприклад, мову вже зафіксовано), решта не змінюється, а чат повідомить, що встиг застосувати.
- Зайві твори видаляєте ви в Obscura: чат цього не вміє.
Чернетка з чату має позначку «Зовнішній клієнт: <назва>» в історії версій і в рядку стану над редактором. Якщо чат назвав модель, вона теж показується. Це заява клієнта: Obscura не може перевірити, яка модель насправді писала текст. Щойно ви збережете власну правку, позначка зникає з рядка стану, а в історії лишається біля версії з чату.
Obscura можна тримати відкритою поруч із чатом. Коли ви повертаєтеся у вікно Obscura, сторінка сама перевіряє, чи чат щось записав. Якщо в редакторі немає незбережених правок, ви одразу побачите нову чернетку. Якщо правки є, текст лишається вашим, а над редактором з’являється «Сцену змінено ззовні» з кнопкою «Відкрити новішу версію»; перед заміною тексту вона спитає підтвердження.
Публікація з чату
Чат може заповнити картку публікації, додати підпис автора, поставити обкладинку й експортувати книгу.
- Чат змінює лише ті поля картки, які ви назвали; решта лишається. Якщо картку змінили після того, як чат її прочитав, запис відхиляється з кодом 409, і чат має прочитати картку знову.
- Жанри FB2 чат бере з того самого каталогу, що й сторінка картки.
- Обкладинку чат читає з файла на локальному диску: дайте повний шлях, наприклад
C:\Users\…\cover.png. Підходять PNG і JPEG до 10 MiB. Файл із мережевого диска чи спільної теки спершу скопіюйте на свій диск. Завантажена обкладинка стає частиною картки лише тоді, коли чат її туди запише. - Чат може попросити Obscura намалювати текстову обкладинку зі збереженої картки. Вона так само стає частиною картки, лише коли чат запише її в картку.
- Експорт повертає посилання на файл в Obscura. Незавершений твір чат експортує лише з вашого явного дозволу, а для FB2 у картці потрібні автор і жанр.
- Якщо сторінка картки відкрита, повернувшись до неї, ви побачите зміни з чату. Незбережені правки у формі лишаються, а сторінка повідомить, що картку змінено ззовні.
Налаштування з чату
Чат може змінити жанр, тон, оповідача, правила стилю й обсяг твору, вибрати провайдера й модель для ролі, змінити контекст, температуру чи режим редактора, а також застосувати збережений пресет ролей.
- Чат змінює лише названі поля одного розділу: профілю письма або однієї ролі. Якщо ви змінили цей розділ після того, як чат його прочитав, запис відхиляється з кодом 409, і чат має прочитати налаштування знову. Нові сцени чи зміна назви твору запису не заважають.
- Ключів чат не бачить: лише чи ключ є і де він (змінна середовища чи сховище ключів). Назву змінної ключа змінюєте тільки ви. Коли чат перемикає провайдера, роль бере стандартний ключ і адресу нового провайдера.
- Пресет чат спершу показує й застосовує лише після підтвердження. Пресет із назвою ключа, якої немає серед ролей твору, застосовуєте ви на сторінці налаштувань.
- Ці інструменти моделей не викликають, але від вибраної моделі залежить вартість наступних запусків в Obscura. Бюджет твору чат не змінює.
- Налаштування ролей не мають історії версій. Що саме змінилося, чат бачить у відповіді інструмента: попросіть його показати. Перед великою зміною можна зберегти пресет.
- Якщо сторінка налаштувань відкрита, повернувшись до неї, ви побачите зміни з чату. Незбережені правки лишаються, а сторінка повідомить, що налаштування змінено ззовні.
Хто пише тексти
Кожен твір має режим: Пише чат або Пише Obscura. Твір, створений чатом, типово має режим Пише чат; у формі нового твору в Obscura типово вибрано Пише Obscura. Режим показують список творів і відомості про твір у чаті.
- Пише чат: чат пише чернетки й проходить етапи сцени сам, як описано нижче.
- Пише Obscura: тексти пишуть моделі Obscura. Чат і далі читає твір, імпортує план і персонажів, змінює налаштування й публікацію, але чернетку чи результат етапу Obscura відхилить із поясненням «Твір у режимі «пише Obscura»: запустіть етап через start_run». Натомість чат може запустити етап моделлю Obscura (див. нижче).
- У режимі Пише чат навпаки: запускати моделі Obscura чат не може, він пише сам.
- Режим змінюєте лише ви: в налаштуваннях твору, розділ Письмо, поле Хто пише тексти. Чат змінити режим не може. Зміна режиму не чіпає написаних текстів і запущених етапів.
Запуски Obscura з чату
У творі з режимом Пише Obscura чат може попросити Obscura виконати один етап сцени — завдання сцени, чернетку, редактуру чи пам’ять — або запропонувати картку публікації. Це звичайний запуск Obscura: моделі ваших ролей, бюджет твору й та сама перевірка готовності, що й для кнопок.
- Спершу чат показує перегляд: які моделі працюватимуть, скільки буде викликів, попередження й залишок бюджету твору. Запускає він лише після вашої згоди в чаті.
- Запуск коштує грошей за тарифами моделей ролей. Для хмарних провайдерів потрібен ліміт бюджету твору, як і для кнопок. Чат може передати ліміт для одного запуску. Наперед суму Obscura не оцінює: перегляд показує моделі й бюджет.
- Запуск іде у фоні. Чат перевіряє його стан окремим запитом; готовий текст він читає так само, як інші тексти сцени, а пропозиції картки приходять разом зі станом запуску.
- Чат може скасувати лише запуск, який почав сам. Паузу, продовження, ваші запуски, сцену цілком, решту твору, підготовку, оцінювання, перевірку впливу й перевірку книги лишено вам: такі запити від чату Obscura відхиляє.
- Якщо попередня пам’ять потребує вашого підтвердження, етап пам’яті не запуститься: чат порадить підтвердити її в Obscura.
- Зміни, що чекають вашого рішення, ви приймаєте в Obscura, як і після запуску кнопкою.
Етапи сцени з чату
Чат може пройти всі етапи сцени сам: скласти завдання сцени, написати чернетку, відредагувати її й оновити пам’ять. Для кожного етапу він отримує ті самі інструкції, що й модель Obscura: стандартні промпти або ваші власні, налаштування ролі, мову твору, рейтинг і пам’ять попередніх сцен. Для чернетки інструкції письменника приходять разом із контекстом сцени.
- Відповідь чату Obscura перевіряє тим самим кодом, що й відповідь своєї моделі. Неправильну відповідь вона не зберігає навіть частково, а повертає чату всі порушення разом. Після трьох відмов поспіль чат має зупинитися й показати порушення вам.
- Якщо між завданням і відповіддю сцену, налаштування ролі чи промпт змінили, відповідь відхиляється, і чат бере завдання знову.
- Результат від чату поводиться як результат моделі: завдання із суттєвими змінами чекає вашого рішення, редактура в режимі вибору правок потрапляє в «Правки редактора», а пам’ять стає поточною. Ядро пам’яті підтверджуєте ви, як і для моделі.
- Якщо попередню прозу змінено після її пам’яті, чат не отримає завдання пам’яті: використання попередньої пам’яті підтверджуєте ви в Obscura.
- В історії версій такі версії мають позначку «Зовнішній клієнт: <назва>». Відредагована чатом проза — версія редактури з цією позначкою.
- Ці інструменти грошей не коштують і в бюджеті не рахуються. Якщо роль не налаштовано, Obscura бере типові для чату межі контексту; вікна самого чату вона не знає.
Почати історію одним запитом
Чат-клієнт бачить запит «Почати історію» (start_story). Він веде чат від задуму до твору: створити твір у режимі «пише чат», заповнити план і персонажів, написати сцени й наприкінці дати посилання, щоб читати й правити твір у вікні Obscura.
Версія з Microsoft Store
Версія з Microsoft Store містить міст MCP: окремо встановлювати нічого не треба, а кнопка «Підключити до Claude» в бібліотеці розгорнута одразу. Новий твір у ній за замовчуванням у режимі «пише чат». Якщо Obscura не запущена, Claude сам тихо запускає її у треї, коли вона знадобиться; вийти з неї можна через значок.
Безкоштовна версія не пише довгу прозу (книги, частини, арки), серії й сцени понад межу рейтингу. Коли чат натрапляє на таку межу, він пояснює, що це можливість платної версії, і дає посилання на запис.
Обмеження
- Obscura має бути запущена. Інакше чат отримає помилку «Obscura не запущено за адресою …».
- Контекст наступної сцени можна прочитати лише після того, як оновлено пам’ять попередньої. Так само працює й генерація в Obscura.
- Якщо після читання контексту сцену змінили, збереження відхиляється з поясненням «Сцену вже змінено». Якщо змінилися картки, рейтинг, мова твору чи пам’ять попередніх сцен — «Контекст сцени змінився — прочитайте його знову». В обох випадках попросіть чат прочитати контекст ще раз.
- Якщо чернетку змінили після того, як чат її прочитав (ви в Obscura чи інша розмова), збереження відхиляється з поясненням «Чернетку змінено після того, як її прочитали». Попросіть чат прочитати чернетку знову й повторити зміну поверх неї.
- Чат бачить лише збережені тексти. Незбережених правок у відкритому редакторі він не бачить: збережіть їх, перш ніж просити чат щось змінити.
- Помилки Obscura чат бачить із префіксом «Error executing tool …». Далі йде код і пояснення Obscura.
- Чернетка з чату вважається матеріалом, створеним моделлю: після неї мову твору змінити не можна.
- Obscura не оцінює чернетку з чату автоматично й не рахує її в бюджеті. Витрати йдуть з облікового запису чат-клієнта.
- Звичайні чат-клієнти можуть відмовитися писати відверті сцени. Obscura цього не обходить.