Подключения
Подключение через 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 в настройки.
Включение
Заголовок раздела «Включение»- Откройте Настройки → Интеграции → Oleafly MCP.
- Включите переключатель Включить сервер 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 также применяет политику, выбранную в разделе Настройки → Интеграции → 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. |
Добавление внешних инструментов в 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 внешнего инструмента начните с простого запроса только на чтение, который поддерживает этот сервер, и посмотрите получившуюся карточку инструмента в чате.