Підключення
Підключення через MCP
Підключіть Claude Desktop, Claude Code, Cursor, Codex або інший клієнт MCP до локальних інструментів роботи з проєктами Oleafly.
Oleafly може працювати як сервер MCP (Model Context Protocol). Клієнти MCP, як-от Claude Desktop, Claude Code, Cursor, Codex і Grok CLI, можуть читати проєкт Oleafly, редагувати його, шукати в ньому й компілювати його. Ключ постачальника ШІ в Oleafly не потрібен: модель надає клієнт.
Цей варіант підійде, якщо у вас уже є підписка Claude (або подібна) і ви хочете керувати Oleafly із цього чат-застосунку, не вставляючи API-ключ у Налаштування.
Як увімкнути
Розділ «Як увімкнути»- Відкрийте Налаштування → Інтеграції → Сервер MCP Oleafly.
- Увімкніть перемикач Увімкнути сервер MCP.
Сервер працює, лише поки запущено процес Oleafly. Він приймає з’єднання лише на 127.0.0.1 і ніколи — у вашій локальній мережі. Закриття вікна проєкту не зупиняє сервер. Його зупиняють вимкнення MCP або вихід із Oleafly.
Oleafly надає перевагу порту 5323 (http://127.0.0.1:5323/mcp). Якщо він недоступний, сервер автоматично прив’язується до іншого вільного локального порту та зберігає його для наступного запуску. У Налаштуваннях показано чинну URL-адресу. Кнопка перезапуску в них повторно використовує поточний порт, якщо це можливо, або обирає інший вільний.
Підключіть свій клієнт
Розділ «Підключіть свій клієнт»У Налаштуваннях є готові до копіювання фрагменти для поширених клієнтів. Скопіюйте чинну URL-адресу, бо обраний порт може відрізнятися від 5323, і замініть <token> токеном доступу з Налаштувань (Показати / Копіювати).
Claude Code
Розділ «Claude Code»claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"Claude Desktop
Розділ «Claude Desktop»Додайте до claude_desktop_config.json (міст stdio через mcp-remote, оскільки Desktop віддає перевагу stdio):
{ "mcpServers": { "oleafly": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://127.0.0.1:5323/mcp", "--header", "Authorization: Bearer <token>", "--transport", "http-only" ] } }}Розширення для Claude Desktop
Розділ «Розширення для Claude Desktop»Кожен реліз містить oleafly.mcpb — розширення для Claude Desktop, тож файл конфігурації й токен вам не знадобляться. Завантажте його з останнього релізу (відкривається в новій вкладці) і відкрийте в Claude Desktop, щоб установити.
Розширення запускає команду oleafly, яка постачається з застосунком, і працює з проєктом, відкритим в Oleafly, тож тримайте Oleafly запущеним з увімкненим MCP-сервером. Якщо Claude Desktop не знаходить команду, виберіть її в налаштуваннях розширення: oleafly-cli усередині Oleafly.app/Contents/MacOS на macOS або oleafly-cli.exe у %LOCALAPPDATA%\Oleafly на Windows.
У MCP Registry це саме розширення значиться як io.github.Oleafly/oleafly.
Cursor / VS Code
Розділ «Cursor / VS Code»У .cursor/mcp.json (або в MCP-конфігурації вашого клієнта):
{ "mcpServers": { "oleafly": { "url": "http://127.0.0.1:5323/mcp", "headers": { "Authorization": "Bearer <token>" } } }}Grok CLI
Розділ «Grok CLI»У ~/.grok/config.toml:
[mcp_servers.oleafly]url = "http://127.0.0.1:5323/mcp"headers = { Authorization = "Bearer <token>" }Codex CLI
Розділ «Codex CLI»Скористайтеся фрагментом Codex CLI у налаштуваннях Oleafly: він надає міст stdio до запущеного сервера. Додайте запис до конфігурації Codex і використовуйте чинну URL-адресу й токен, які показує Oleafly:
[mcp_servers.oleafly]command = "npx"args = [ "-y", "mcp-remote@latest", "http://127.0.0.1:5323/mcp", "--header", "Authorization: Bearer <token>", "--transport", "http-only"]Мосту потрібні Node.js і npx. Після зміни конфігурації клієнта перезапустіть його або перепідключіться.
Файл mcp.json поруч із даними Oleafly (шлях показано в Налаштуваннях) містить ту саму URL-адресу й токен, якщо вам зручніше налаштувати все скриптом. Його записують, лише поки сервер працює (режим 0600 на Unix), і видаляють, коли сервер зупиняється. Ставтеся до нього як до будь-якого іншого локального секрету.
Що вміють інструменти
Розділ «Що вміють інструменти»Більшість інструментів MCP мають ті самі назви та схеми, що й вбудований асистент. Інструменти виявлення та маршрутизації проєктів надає серверна частина настільного застосунку.
Коли в застосунку відкрито проєкт, інструменти працюють саме з ним. Із підключеним вікном скористайтеся list_projects і open_project, щоб обрати інший проєкт.
Після закриття останнього вікна серверна частина надалі надає read_file, list_files і search_project. Записи, заміни, створення та перейменування файлів також лишаються доступними, якщо це дозволяє політика схвалення. Ці інструменти використовують лише останній проєкт, про який повідомив застосунок, і відхиляють виклик, якщо той проєкт уже недійсний. Вони ніколи не вгадують за іншими проєктами бібліотеки. Статус, вибір проєкту, видалення, компіляція, журнали, перевірка PDF, зміна теми та інструменти для рисунків потребують підключеного вікна.
Орієнтація
Розділ «Орієнтація»| Інструмент | Що робить |
|---|---|
get_status | Версія Oleafly, відкритий проєкт, його рушій документа, головний документ, стан останньої компіляції і причина, чому остання компіляція завершилася невдачею або не змогла запуститися |
list_projects | Проєкти з ідентифікаторами, назвами, рушіями, типами, головними документами, мітками часу, кольорами, станом перегляду та історією експорту |
open_project | Відкриває проєкт за ідентифікатором, щоб інші інструменти працювали з ним |
list_files | Дерево файлів проєкту |
project_map | Структура, мітки, цитування, макроси, граф входжень, невирішені посилання |
search_project | Пошук тексту в поточному проєкті |
Читання
Розділ «Читання»| Інструмент | Що робить |
|---|---|
read_file | Читає файл проєкту |
get_log | Журнал останньої компіляції |
get_pdf_text | Текст, витягнутий зі скомпільованого PDF |
verify_pdf_pages | Перевіряє відтворені сторінки PDF на проблеми компонування за зображеннями сторінок або текстом сторінок |
get_pdf_text і verify_pdf_pages читають останній PDF, який має Oleafly. Коли остання компіляція завершилася невдачею або не змогла запуститися, їхній результат каже, що PDF застарілий, і чому: він походить з ранішої компіляції або є частковим із невдалої компіляції. get_log каже те саме, коли остання компіляція не змогла запуститися, бо тоді його журнал походить з ранішої компіляції.
Редагування
Розділ «Редагування»| Інструмент | Що робить |
|---|---|
write_file | Записує або перезаписує файл |
replace_in_file | Шукає й замінює у файлі |
create_file | Створює файл або теку |
rename_file | Перейменовує або переміщує шлях |
delete_file | Видаляє файл або теку |
set_main_doc | Задає вхідний документ компіляції |
Компіляція та рисунки
Розділ «Компіляція та рисунки»| Інструмент | Що робить |
|---|---|
compile | Компілює проєкт у PDF |
preview_figure | Відображає рисунок окремо та повертає зображення PNG |
insert_figure | Вставляє останній переглянутий рисунок у документ |
load_image | Завантажує зображення з проєкту для роботи з рисунками |
compile каже, чи вдалася збірка, перелічує її помилки, каже, чи є PDF, і закінчується останньою частиною журналу. Збірка, що завершилася, також повідомляє про свої попередження. Коли збірка не могла запуститися, не завершилася або потребує чогось поза кодом, як-от установки TeX чи версії Typst, якої немає, результат дає причину й називає виправлення, яке Oleafly пропонує вам у застосунку. Інструмент просить клієнта повідомити вас і не чіпати ваш код. Компіляція, яку ви зупинили, позначається як зупинена, щоб клієнт не вважав її помилкою в коді. Власний асистент Oleafly отримує той самий результат.
Спочатку викличте get_status, щоб дізнатися, чи проєкт створено в LaTeX, Typst чи Markdown, і пишіть вихідний код у відповідному форматі. preview_figure і insert_figure працюють у проєктах LaTeX і Typst:
- У LaTeX рисунок — це код TikZ, скомпільований у невеликому окремому документі, а
insert_figureогортає його в середовищеfigure. - У Typst рисунок — це розмітка Typst, як-от полотно CeTZ або діаграма fletcher, відрендерена версією Typst проєкту.
insert_figureогортає його в#figure, ставить мітку після нього та переносить його рядки#importвище. - У проєкті Markdown обидва інструменти повертають помилку й нічого не змінюють.
load_image працює в будь-якому проєкті.
Застосунок
Розділ «Застосунок»| Інструмент | Що робить |
|---|---|
toggle_theme | Перемикає світлий / темний режим |
Навички
Розділ «Навички»| Інструмент | Що робить |
|---|---|
list_skills | Показує список установлених навичок: ідентифікатор, назву, опис і те, чи ввімкнено їх |
load_skill | Завантажує повні інструкції однієї навички та список її файлів |
read_skill_file | Читає довідковий файл або скрипт із теки навички |
Інструменти навичок працюють одразу після підключення, без відкритого проєкту й без вікна Oleafly. Клієнт бачить усі дійсні навички, зокрема вимкнені в Налаштуваннях: перемикачі визначають, які навички використовує власний асистент Oleafly, а не те, що клієнт може прочитати. Агенти, які натомість читають навички з теки, можуть скористатися Ділитися навичками з іншими агентами на цьому комп’ютері в Налаштування → Асистент ШІ → Навички. Див. Навички.
Нотатки
Розділ «Нотатки»Ці інструменти доступні, поки Нотатки ввімкнено в Налаштування → Експерименти, як описано в Увімкнення нотаток. Вони працюють із вашими нотатками, а не з відкритим проєктом, і потребують підключеного вікна.
| Інструмент | Що робить |
|---|---|
list_knowledge_notes | Показує список ваших нотаток, від найновіших, з ідентифікаторами, назвами, тегами, пов’язаними проєктами й короткими підсумками. Можна фільтрувати за тегом або проєктом |
search_notes | Шукає у ваших нотатках і повертає ідентифікатори, назви, теги, посилання та фрагменти, що збіглися |
read_note_by_id | Читає нотатку як Markdown разом із її front matter |
today_note | Читає щоденну нотатку на сьогодні або назву, яку вона мала б, якщо ще не існує |
list_note_tasks | Показує список завдань із прапорцями у ваших нотатках, спершу з найновішої нотатки. Можна фільтрувати за нотаткою та за станом: відкриті чи виконані |
note_backlinks | Показує нотатки, що посилаються на нотатку, з текстом навколо кожного посилання |
append_to_note | Додає Markdown в кінець нотатки або щоденної нотатки на сьогодні |
edit_note_section | Переписує частину нотатки під одним заголовком або додає в її кінець |
create_note | Створює нотатку з назвою, Markdown, тегами та пов’язаним проєктом |
append_to_note і edit_note_section не пишуть у нотатку напряму. Їхні зміни з’являються в ній як пропозиції, доки ви не приймете їх в Oleafly. create_note чекає вашого схвалення в Oleafly, і append_to_note теж, коли спершу має створити щоденну нотатку на сьогодні. За політики Довіряти цьому з’єднанню створення нотатки не запитує. Нотатку, спільну через сервер співпраці, цим способом можна читати, але не змінювати. Лише читання прибирає три інструменти, що змінюють нотатки.
Схвалення та безпека
Розділ «Схвалення та безпека»Багато клієнтів MCP запитують дозвіл перед викликом інструменту. Oleafly також застосовує політику, обрану в Налаштування → Інтеграції → Сервер MCP Oleafly:
- Підтверджувати кожну зміну — типова політика. Записи, перейменування та видалення показують картку схвалення, доки підключене вікно застосунку. Без вікна такі операції відхиляються, бо ніде показати картку.
- Автоматично схвалювати правки, підтверджувати видалення дозволяє записам і перейменуванням виконуватися в серверній частині. Видалення все одно потребують підключеного вікна для підтвердження.
- Довіряти цьому з’єднанню дозволяє записам і перейменуванням виконуватися в серверній частині без запиту Oleafly. Видалення все одно потребує підключеного вікна. Використовуйте цю політику, лише коли ви довіряєте клієнту та його власним механізмам схвалення.
Це підкріплюють ще два перемикачі:
- Лише читання (окремий перемикач) повністю прибирає інструменти змін із
tools/list, тож зовнішній застосунок може читати й компілювати, але ніколи не змінюватиме файли, якою б не була політика вище. - Токен доступу: випадкове 256-бітне значення, збережене в автентифікованому зашифрованому локальному сховищі в
~/.oleafly/. Згенеруйте його заново, щоб анулювати старі клієнти. Звичайне читання конфігурації ніколи не викриває токен. Показати його в Налаштуваннях може лише панель керування з’єднанням запущеного сервера.
І дві незмінні умови, які не налаштовуються:
- Лише localhost: адреса прив’язки —
127.0.0.1. Запити з браузерним заголовкомOriginвідхиляються, аHostмає бути loopback. - Обмеження проєктом: інструменти роботи з файлами в серверній частині приймають шляхи відносно проєкту й не виходять за канонічні шляхи проєкту, про який повідомив застосунок. Виклик інструменту не може передати ідентифікатор іншого проєкту або змусити серверну частину обрати інший проєкт бібліотеки.
Спостерігайте за роботою
Розділ «Спостерігайте за роботою»Доки підключене вікно, вкладка Активність MCP записує вхідні виклики. Виклики серверної частини можуть тривати й після закриття останнього вікна, але панелі активності та картки схвалення не буде, доки вікно не підключиться знову.
Чому claude.ai у браузері не може підключитися
Розділ «Чому claude.ai у браузері не може підключитися»Хмарний чат-сервіс не може дістати 127.0.0.1 на вашій машині. Натомість скористайтеся Claude Desktop (або Claude Code, Cursor тощо). Не виводьте порт MCP у публічний інтернет через тунель: це дозволило б будь-кому, хто знає URL-адресу, редагувати й видаляти ваші локальні файли проєкту.
Усунення несправностей
Розділ «Усунення несправностей»| Симптом | Що спробувати |
|---|---|
| Деякі інструменти недоступні | Перегляд рисунків та інші інструменти, що живуть лише в інтерфейсі, потребують вікна Oleafly. Відкрийте застосунок і проєкт, потім повторіть tools/list. |
Порт змінився з 5323 | Пріоритетний порт був недоступний, тож Oleafly обрав вільний. Скопіюйте чинну URL-адресу з Налаштувань. |
| HTTP 401 | Токен не збігається (наприклад, після «Згенерувати заново»). Скопіюйте новий токен у клієнт. |
| HTTP 403 | Клієнт надіслав заголовок Origin або Host, що не є loopback. Використовуйте нативний клієнт MCP, а не вкладку браузера. |
| Час виклику вичерпано | Кожен виклик інструменту чекає до 5 хвилин (300 с) на компіляцію або на те, щоб ви натиснули «Схвалити». Схваліть або відхильте картки, що очікують, або повторіть спробу. Компіляція може тривати довше, до години для зошита Quarto чи Calepin. Вона продовжує працювати в Oleafly після завершення часу виклику, а інструменти, яким потрібне вікно Oleafly, чекають на неї, тож дайте їй завершитися, перш ніж повторювати. |
compile повертає причину замість помилок | Збірка не могла запуститися, наприклад через те, що TeX не встановлено. Скористайтеся виправленням, яке Oleafly пропонує в застосунку, наприклад установкою TinyTeX, а потім скомпілюйте знову. |
| Не вдається підключитися | Oleafly має бути запущеним із увімкненим MCP. Цей сервер зупиняється, коли ви виходите із застосунку; щоб мати інструменти проєкту із закритим застосунком, підключіть клієнт до oleafly mcp. |
Додайте зовнішні інструменти до Oleafly
Розділ «Додайте зовнішні інструменти до Oleafly»
Щоб дати вбудованому асистентові більше інструментів, відкрийте Налаштування → Асистент ШІ → MCP.
- Переглянути реєстр, щоб знайти сервер і ознайомитися з його налаштуванням.
- Імпортувати з інших інструментів, щоб обрати наявні конфігурації серверів. Перевірте обрані записи перед імпортом.
- Додати сервер, щоб указати сервер самостійно, а потім перевірити з’єднання.
Підключені сервери надають свої інструменти асистентові. З цієї самої сторінки можна переглянути стан з’єднання та увімкнути чи вимкнути сервери. Облікові дані та команди — частина конфігурації кожного сервера; перевіряйте їх перед підключенням нового сервера.
alphaXiv також підключається як сервер MCP, але його налаштовують не тут, а в Налаштування → Інтеграції → alphaXiv за допомогою API-ключа. Після підключення він з’являється в цьому списку як alphaXiv. Кроки описано в розділі Підключення джерел досліджень.
Налаштуйте зовнішній сервер вручну
Розділ «Налаштуйте зовнішній сервер вручну»
У Налаштування → Асистент ШІ → MCP оберіть Додати сервер. Локальний сервер запускає команду через stdio; віддалений сервер підключається до URL-адреси. Форма JSON використовує формат серверів Oleafly:
{ "name": "Research tools", "enabled": true, "transport": "stdio", "command": "your-mcp-server", "args": ["--stdio"], "env": {}}Замініть команду та аргументи на описані в документації встановленого вами сервера. Значення змінних середовища належать об’єкту env.
{ "name": "Research service", "enabled": true, "transport": "remote", "url": "https://your-server.example/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" }}Замініть приклад URL-адреси й токена на дані підключення сервісу. Скористайтеся Перевірити, щоб перевірити з’єднання, а потім перегляньте інструменти, які надає сервер. Увімкнути чи вимкнути сервер можна в його рядку. Дією редагування змінюйте конфігурацію, дією вилучення — відключайте його.
Імпорт наявних конфігурацій MCP
Розділ «Імпорт наявних конфігурацій MCP»Оберіть Імпортувати з інших інструментів, перегляньте виявлені конфігурації та позначте потрібні сервери. Перед імпортом перевірте шляхи до виконуваних файлів, змінні середовища, URL-адреси та облікові дані. Імпортуються лише параметри з’єднання; виконуваний файл сервера сам не встановлюється.
Перевірте з’єднання
Розділ «Перевірте з’єднання»- Відкрийте в Oleafly невеликий тренувальний проєкт.
- Підключіть зовнішній клієнт фрагментом, скопійованим із застосунку.
- Попросіть клієнта викликати
get_statusі вивести список файлів проєкту. - Попросіть його прочитати головний документ і запропонувати зміну назви.
- Перегляньте дію в Oleafly, перш ніж схвалити запис.
- Скомпілюйте та огляньте PDF.
Для підключеного зовнішнього інструмента всередині Oleafly почніть із простого запиту лише для читання, який підтримує цей сервер, і огляньте картку інструменту, що з’явиться в чаті.