Перейти до вмісту
Oleaflyv0.4.12

Підключення

Підключіть 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 в обох напрямкахВ одному напрямку клієнт MCP на вашому комп’ютері, як-от Claude Desktop, Cursor чи Codex, підключається до сервера MCP Oleafly на 127.0.0.1 з токеном носія. Він може читати, редагувати й компілювати проєкт, а ваша політика підтверджень визначає, які зміни чекають на вас. В іншому напрямку вбудований асистент Oleafly використовує інструменти з доданих вами серверів MCP: локального сервера, який запускає команду, або віддаленого сервера за URL.Ваш клієнт MCP використовує інструменти OleaflyАсистент Oleafly використовує інші сервери MCPКлієнт MCPClaude Desktop,Cursor, CodexOleafly MCPЛише 127.0.0.1ПроєктЧитання, редагування, компіляціяТокен носіяПідтвердженняАсистентВбудований в OleaflyЛокальний серверЗапускає командуВіддалений серверПідключається до URLMCP в обох напрямкахВ одному напрямку клієнт MCP на вашому комп’ютері, як-от Claude Desktop, Cursor чи Codex, підключається до сервера MCP Oleafly на 127.0.0.1 з токеном носія. Він може читати, редагувати й компілювати проєкт, а ваша політика підтверджень визначає, які зміни чекають на вас. В іншому напрямку вбудований асистент Oleafly використовує інструменти з доданих вами серверів MCP: локального сервера, який запускає команду, або віддаленого сервера за URL.Ваш клієнт MCP використовує OleaflyАсистент Oleafly використовує сервериКлієнт MCPClaude Desktop, CursorOleafly MCPЛише 127.0.0.1ПроєктЧитання, редагування, компіляціяТокен носіяПідтвердженняАсистентВбудований в OleaflyЛокальний серверЗапускає командуВіддалений серверПідключається до URL
Клієнт MCP на вашому комп’ютері дістається до інструментів проєкту Oleafly через 127.0.0.1 і токен. В іншому напрямку асистент Oleafly може використовувати інструменти з доданих вами серверів MCP.
  1. Відкрийте Налаштування → Інтеграції → Сервер MCP Oleafly.
  2. Увімкніть перемикач Увімкнути сервер MCP.

Сервер працює, лише поки запущено процес Oleafly. Він приймає з’єднання лише на 127.0.0.1 і ніколи — у вашій локальній мережі. Закриття вікна проєкту не зупиняє сервер. Його зупиняють вимкнення MCP або вихід із Oleafly.

Oleafly надає перевагу порту 5323 (http://127.0.0.1:5323/mcp). Якщо він недоступний, сервер автоматично прив’язується до іншого вільного локального порту та зберігає його для наступного запуску. У Налаштуваннях показано чинну URL-адресу. Кнопка перезапуску в них повторно використовує поточний порт, якщо це можливо, або обирає інший вільний.

Підключіть свій клієнт

Розділ «Підключіть свій клієнт»

У Налаштуваннях є готові до копіювання фрагменти для поширених клієнтів. Скопіюйте чинну URL-адресу, бо обраний порт може відрізнятися від 5323, і замініть <token> токеном доступу з Налаштувань (Показати / Копіювати).

Вікно термінала
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"

Додайте до 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/mcp.json (або в MCP-конфігурації вашого клієнта):

{
"mcpServers": {
"oleafly": {
"url": "http://127.0.0.1:5323/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}

У ~/.grok/config.toml:

[mcp_servers.oleafly]
url = "http://127.0.0.1:5323/mcp"
headers = { Authorization = "Bearer <token>" }

Скористайтеся фрагментом Codex CLI у налаштуваннях Oleafly: він надає міст stdio до запущеного сервера. Додайте запис до конфігурації Codex і використовуйте чинну URL-адресу й токен, які показує Oleafly:

~/.codex/config.toml
[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. Додайте сервер, перегляньте реєстр або імпортуйте конфігурації з іншого інструмента.
Налаштування → Асистент ШІ → MCP. Додайте сервер, перегляньте реєстр або імпортуйте конфігурації з іншого інструмента. Відкрити повний знімок екрана

Щоб дати вбудованому асистентові більше інструментів, відкрийте Налаштування → Асистент ШІ → MCP.

  • Переглянути реєстр, щоб знайти сервер і ознайомитися з його налаштуванням.
  • Імпортувати з інших інструментів, щоб обрати наявні конфігурації серверів. Перевірте обрані записи перед імпортом.
  • Додати сервер, щоб указати сервер самостійно, а потім перевірити з’єднання.

Підключені сервери надають свої інструменти асистентові. З цієї самої сторінки можна переглянути стан з’єднання та увімкнути чи вимкнути сервери. Облікові дані та команди — частина конфігурації кожного сервера; перевіряйте їх перед підключенням нового сервера.

alphaXiv також підключається як сервер MCP, але його налаштовують не тут, а в Налаштування → Інтеграції → alphaXiv за допомогою API-ключа. Після підключення він з’являється в цьому списку як alphaXiv. Кроки описано в розділі Підключення джерел досліджень.

Налаштуйте зовнішній сервер вручну

Розділ «Налаштуйте зовнішній сервер вручну»
Додати сервер → Форма. Оберіть «Локальна команда» або «Віддалена URL», заповніть поля з’єднання, потім натисніть «Додати» і перевірте результат.
Додати сервер → Форма. Оберіть «Локальна команда» або «Віддалена URL», заповніть поля з’єднання, потім натисніть «Додати» і перевірте результат. Відкрити повний знімок екрана

У Налаштування → Асистент ШІ → 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-адреси та облікові дані. Імпортуються лише параметри з’єднання; виконуваний файл сервера сам не встановлюється.

Перевірте з’єднання

Розділ «Перевірте з’єднання»
  1. Відкрийте в Oleafly невеликий тренувальний проєкт.
  2. Підключіть зовнішній клієнт фрагментом, скопійованим із застосунку.
  3. Попросіть клієнта викликати get_status і вивести список файлів проєкту.
  4. Попросіть його прочитати головний документ і запропонувати зміну назви.
  5. Перегляньте дію в Oleafly, перш ніж схвалити запис.
  6. Скомпілюйте та огляньте PDF.

Для підключеного зовнішнього інструмента всередині Oleafly почніть із простого запиту лише для читання, який підтримує цей сервер, і огляньте картку інструменту, що з’явиться в чаті.

Перегляд зображення

Не вдалося завантажити відповіді ШІ

Спробуйте ще раз або скористайтеся пошуком у документації.