Подключение облачной библиотеки для агентов

Эта страница предназначена прежде всего для ИИ-агентов.

Connect this Linkly AI library: <library URL>
Follow https://linkly.ai/docs/ru/library-setup.md

Инструкция для ИИ-агента

Задача

Подключи существующую облачную библиотеку к ИИ-клиенту пользователя, не загружая документы на его компьютер. Проведи через вход и Link, настрой OAuth или API Key, а затем докажи работу фактическим поиском.

Преобразование адреса

Веб-адрес вида:

https://linkly.ai/<username>/<library-slug>

соответствует идентификатору:

cloud://<username>/<library-slug>

Не изменяй имя пользователя и slug. Если адрес имеет другую форму, открой страницу и найди показанный идентификатор вместо догадки. В адресе с дополнительным путём (/settings) или query-параметрами оставь только <owner>/<slug>. При сомнении после подключения вызови list_libraries и возьми точный идентификатор оттуда. Веб-адрес нельзя передавать в library напрямую.

Ограничения

Не создавай аккаунт, имя пользователя, API Key или подписку вместо пользователя
Не публикуй и не меняй видимость библиотеки
Не сохраняй ключ в проекте, истории оболочки или сообщении
Не объявляй успех до реального поиска именно в указанной библиотеке
Не перезаписывай локальный сервер linkly-ai: облачный должен быть отдельной записью linkly-ai-cloud
Локальный linkly-ai никогда не принимает cloud://; это граница подключения, а не временная ошибка
В каждом поиске явно передавай library. Без него шлюз обращается к Desktop пользователя, а для бесплатного плана сразу возвращает ошибку
Один вызов работает с одной библиотекой; две библиотеки требуют двух поисков
После записи MCP-конфигурации не жди инструменты в текущем сеансе — они появятся после нового разговора или полного перезапуска

Определи тип клиента

Онлайн-приложение без оболочки: OAuth
Консольный или настольный клиент с пользовательскими заголовками: MCP + API Key
Агент с установленным Linkly AI CLI: удалённый CLI

Во встроенном чате Linkly AI Desktop связанную библиотеку можно упомянуть через @ без настройки MCP; достаточно выполнить Шаг 1.

Шаг 0. Проверка состояния

claude mcp list
codex mcp list
linkly auth status

Не запускай команды, не относящиеся к фактическому клиенту. Проверь, нет ли уже сервера linkly-ai-cloud, и не перезаписывай одноимённую конфигурацию без согласия. Также определи, доступны ли текущему сеансу retrieval-инструменты и от какого сервера: облачный представляется как linkly-ai-cloud, локальный — linkly-ai. Наличие аккаунта и нажатие Link нельзя проверить из оболочки — спроси пользователя.

Состояние	Действие
`linkly-ai-cloud` есть и перечисляет библиотеки	Сразу проверить поиск
Сервер есть, но целевой библиотеки нет	Выполнить только пункт Link в Шаге 1
Есть только локальный `linkly-ai`	Выполнить Шаг 1 и сохранить локальную запись
Linkly-серверов нет	Выполнить Шаг 1 полностью

Шаг 1. Аккаунт и Link

1. Вход

Попроси пользователя войти на linkly.ai через Google, GitHub или Notion. Бесплатного аккаунта достаточно. Не проси сообщать пароль.

2. Имя пользователя

При первом входе пользователь сам выбирает имя. Не подставляй случайное значение.

3. Подключение библиотеки

Открой точную предоставленную страницу и попроси нажать Link. Успех: кнопка стала Linked, статус — Connected. Даже собственную библиотеку нужно связать отдельно: доступ MCP определяется связью, а не владельцем. Для закрытой библиотеки необходимо приглашение владельца. Бесплатный аккаунт имеет одно место для Link. Если оно занято, пользователь должен отключить другую библиотеку или перейти на Pro с 99 местами.

4. Учётные данные

Выбери один способ: OAuth для веб-клиента или API Key из Dashboard → Integrations для клиента с заголовками. Ключ начинается с lkai_, равнозначен учётным данным и предназначен только для инструментов владельца. CLI может сохранить его в собственном защищённом хранилище. Критерий Шага 1: пользователь подтвердил Linked; для API key также подтвердил наличие полного значения lkai_... без публикации в чате.

Шаг 2. Облачный MCP

Адрес всегда:

https://mcp.linkly.ai/mcp

Имя сервера всегда linkly-ai-cloud, а не linkly-ai: иначе локальная конфигурация будет незаметно перезаписана, а Skills сочтут облачный сервер локальным.

Вариант A. API Key

Сначала покажи команду и объясни, что ключ будет записан в локальную конфигурацию. Получи согласие пользователя.

claude mcp add --transport http linkly-ai-cloud https://mcp.linkly.ai/mcp \
  --header "Authorization: Bearer <your API Key>"

Универсальная конфигурация:

{
  "mcpServers": {
    "linkly-ai-cloud": {
      "url": "https://mcp.linkly.ai/mcp",
      "headers": {
        "Authorization": "Bearer <your API Key>"
      }
    }
  }
}

Не записывай реальный ключ в отслеживаемый файл; предпочитай переменную окружения или защищённое хранилище клиента. У разных клиентов поле называется url, httpUrl или serverUrl; сверяйся с руководством интеграции. Если поддерживается ${env:LINKLY_API_KEY}, используй переменную окружения, чтобы не хранить секрет открытым текстом. Проверь ключ прямым рукопожатием:

curl -sf --max-time 10 -X POST https://mcp.linkly.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer lkai_YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}'

Ответ с "serverInfo":{"name":"linkly-ai-cloud" подтверждает цепочку. HTTP 401 означает неверный или отозванный ключ — пользователь должен создать новый.

Вариант B. OAuth

В ChatGPT, Claude.ai или другом приложении добавь Connector/MCP-сервер с именем linkly-ai-cloud и URL https://mcp.linkly.ai/mcp. После сохранения приложение откроет авторизацию linkly.ai; пользователь входит и подтверждает доступ. Полученный токен приложение затем отправляет автоматически, повторная авторизация не нужна.

Вариант C. CLI

linkly auth set-key lkai_YOUR_KEY
linkly search "your query" --remote --library "cloud://blueeon/linkly-init-example"

Подставляй предоставленный идентификатор дословно. --remote — единственный режим CLI, который видит облачные библиотеки; без него поиск остаётся локальным. После новой MCP-конфигурации сначала начни новый разговор. Если инструменты не появились, полностью заверши клиент и открой его снова; закрыть окно на macOS/Windows недостаточно. Не продолжай опрашивать текущий сеанс.

Шаг 3. Сквозная проверка

Если инструменты ещё не появились, честно остановись на «конфигурация записана, рукопожатие успешно, проверка ожидает перезагрузки». Повтори оба способа перезагрузки и передай фразу с полным ID библиотеки и конкретной темой для нового сеанса. Когда инструменты доступны, сначала вызови list_libraries: целевой cloud://<owner>/<slug> должен присутствовать вместе с числом документов. Затем попроси пользователя назвать безопасную тему или используй нейтральный запрос из описания:

Найди в cloud://username/library-slug сведения о начале работы и укажи источники.

Успех требует реального вызова search(query="…", library="cloud://username/library-slug") и результата с документами. Затем прочитай один документ через outline или read.

Полный двухсегментный library обязателен при каждом вызове. cloud://library-slug отклоняется. Без параметра шлюз обращается к Desktop пользователя и бесплатный аккаунт получает ошибку.

Если поиск пуст, проверь широту запроса, число документов в list_libraries, затем вызови explore и сформулируй новый запрос по реальному содержимому.

Устранение неполадок

Handshake 401 или 403

401 — ключ неверен или отозван; 403 — ему не хватает разрешения mcp. В обоих случаях создай новый ключ и скопируй полностью. Не печатай его в журнал.

Library not found

Проверь точный cloud:// ID, правильный аккаунт и Link. Собственные библиотеки тоже требуют Link.

Лимит Link исчерпан

Бесплатный аккаунт имеет одно место: отключи другую библиотеку либо перейди на Pro (99 мест).

Ошибка Desktop или требование Pro

Параметр library пропущен, поэтому запрос ушёл к компьютеру пользователя. Добавь полный ID.

cloud:// не поддерживается

Используется локальный linkly-ai. Создай отдельный linkly-ai-cloud; локальный путь облако не видит.

Требуется owner/slug

Вероятно, передан веб-URL или один сегмент. Преобразуй в cloud://<owner>/<slug> либо скопируй ID из list_libraries.

Инструменты не появились

Начни новый разговор; затем полностью заверши и снова открой клиент. Это механизм загрузки.

Локальный поиск внезапно пуст

Облачная запись перезаписала имя linkly-ai. Переименуй её в linkly-ai-cloud и восстанови локальный endpoint.

Библиотека содержит 0 документов

Владелец ещё не отправил контент; агент исправить это не может.

Итоговый отчёт

Укажи точный ID библиотеки, способ авторизации, имя сервера, нужен ли новый разговор/полный перезапуск, число и тематику документов, запрос проверки и подтверждение найденного документа. Напомни: пользователь называет библиотеку, а агент автоматически передаёт library. Не включай секреты; незавершённые шаги назови прямо.

Четыре примера вопросов

Сначала вызови explore и несколько тематических search, затем сформулируй четыре вопроса, явно относящиеся к реальному содержимому библиотеки. Не используй универсальные заготовки вроде «резюмируй базу знаний».

Начало работы

Основные функции

Подключение ИИ-инструментов

Для ИИ-агентов

Подключение облачной библиотеки для агентов

Инструкция для ИИ-агента

Задача

Преобразование адреса

Ограничения

Определи тип клиента

Шаг 0. Проверка состояния

Шаг 1. Аккаунт и Link

1. Вход

2. Имя пользователя

3. Подключение библиотеки

4. Учётные данные

Шаг 2. Облачный MCP

Вариант A. API Key

Вариант B. OAuth

Вариант C. CLI

Шаг 3. Сквозная проверка

Устранение неполадок

Итоговый отчёт

Четыре примера вопросов

Дополнительные материалы

​Инструкция для ИИ-агента

​Задача

​Преобразование адреса

​Ограничения

​Определи тип клиента

​Шаг 0. Проверка состояния

​Шаг 1. Аккаунт и Link

​1. Вход

​2. Имя пользователя

​3. Подключение библиотеки

​4. Учётные данные

​Шаг 2. Облачный MCP

​Вариант A. API Key

​Вариант B. OAuth

​Вариант C. CLI

​Шаг 3. Сквозная проверка

​Устранение неполадок

​Итоговый отчёт

​Четыре примера вопросов

​Дополнительные материалы

Инструкция для ИИ-агента

Задача

Преобразование адреса

Ограничения

Определи тип клиента

Шаг 0. Проверка состояния

Шаг 1. Аккаунт и Link

1. Вход

2. Имя пользователя

3. Подключение библиотеки

4. Учётные данные

Шаг 2. Облачный MCP

Вариант A. API Key

Вариант B. OAuth

Вариант C. CLI

Шаг 3. Сквозная проверка

Устранение неполадок

Итоговый отчёт

Четыре примера вопросов

Дополнительные материалы