Перейти к содержимому
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-серверамиMCP-клиентClaude 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 пользуется серверамиMCP-клиентClaude Desktop, CursorOleafly MCPТолько 127.0.0.1ПроектЧтение, правка, компиляцияТокен доступаОдобренияАссистентВстроен в OleaflyЛокальный серверЗапускает командуУдалённый серверПодключается к URL
MCP-клиент на вашем компьютере обращается к инструментам проекта Oleafly через 127.0.0.1 и токен. В обратную сторону ассистент Oleafly может пользоваться инструментами добавленных вами MCP-серверов.
  1. Откройте Настройки → Интеграции → Oleafly MCP.
  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"
]
}
}
}

В каждый релиз входит 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 также применяет политику, выбранную в разделе Настройки → Интеграции → Oleafly MCP:

  • Подтверждать каждое изменение — политика по умолчанию. Записи, переименования и удаления показывают карточку подтверждения, пока окно приложения подключено. Без окна такие операции отклоняются: карточку негде показать.
  • Автоматически разрешать правки, подтверждать удаления позволяет записям и переименованиям выполняться в бэкенде. Удаления по-прежнему требуют подключённого окна для подтверждения.
  • Доверять этому подключению позволяет записям и переименованиям в бэкенде выполняться без запроса Oleafly. Удаление всё равно требует подключённого окна. Используйте эту политику, только если доверяете клиенту и его собственным средствам подтверждения.

Всё это дополняют ещё два переключателя:

  • Только для чтения (отдельный переключатель) полностью убирает изменяющие инструменты из tools/list, поэтому внешнее приложение может читать и компилировать, но никогда не изменит файлы, независимо от политики выше.
  • Токен доступа: случайное 256-битное значение, хранящееся в аутентифицированном зашифрованном локальном хранилище в ~/.oleafly/. Создайте его заново, чтобы отключить старые клиенты. Обычное чтение конфигурации никогда не раскрывает токен. Его можно увидеть только в элементах управления подключением работающего сервера в настройках.

И ещё два инварианта, которые вы не настраиваете:

  • Только localhost: адрес привязки — 127.0.0.1. Запросы с браузерным заголовком Origin отклоняются, а Host должен быть петлевым.
  • Ограничение проектом: файловые инструменты бэкенда принимают пути относительно проекта и не дают каноническим путям выйти за пределы проекта, о котором сообщило приложение. Вызов инструмента не может передать идентификатор другого проекта и не заставит бэкенд выбрать другой проект библиотеки.

Пока окно подключено, вкладка Активность 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. Используйте обычный клиент MCP, а не вкладку браузера.
Время вызова истеклоКаждый вызов инструмента ждёт до 5 минут (300 с) компиляции или нажатия «Разрешить». Разрешите или отклоните ожидающие карточки либо повторите вызов. Компиляция может занять больше времени, до часа для блокнота Quarto или Calepin. Она продолжает идти в Oleafly после истечения времени вызова, а инструменты, которым нужно окно Oleafly, ждут её, поэтому дайте ей закончиться, прежде чем повторять.
compile возвращает причину вместо ошибокСборка не смогла запуститься, например потому, что TeX не установлен. Воспользуйтесь исправлением, которое предлагает Oleafly в приложении, например установкой TinyTeX, затем скомпилируйте снова.
Не удаётся подключитьсяOleafly должен быть запущен с включённым MCP. Этот сервер останавливается при выходе из приложения; чтобы получить инструменты проекта при закрытом приложении, подключите клиент к oleafly mcp.
Настройки → ИИ-ассистент → 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 и токена на данные для подключения сервиса. Нажмите Проверить, чтобы проверить соединение, затем посмотрите инструменты, которые предоставляет сервер. Включать и выключать сервер можно в его строке. Действие правки меняет конфигурацию, а действие удаления отключает сервер.

Выберите Импортировать из других инструментов, просмотрите найденные конфигурации и отметьте нужные серверы. Перед импортом проверьте пути к исполняемым файлам, переменные окружения, URL и учётные данные. Импортируются настройки подключения; исполняемый файл сервера при этом не устанавливается.

  1. Откройте в Oleafly небольшой учебный проект.
  2. Подключите внешний клиент с помощью фрагмента, скопированного из приложения.
  3. Попросите клиента вызвать get_status и перечислить файлы проекта.
  4. Попросите его прочитать главный документ и предложить новое название.
  5. Просмотрите действие в Oleafly, прежде чем разрешать запись.
  6. Скомпилируйте проект и посмотрите PDF.

Для подключённого внутри Oleafly внешнего инструмента начните с простого запроса только на чтение, который поддерживает этот сервер, и посмотрите получившуюся карточку инструмента в чате.

Просмотр изображения

Не удалось загрузить ответы ИИ

Попробуйте снова или воспользуйтесь поиском по документации.