agentleFS
awaikawaik/direct-mcp-ai-project/.claude/skills/lidfly-connection-doctor/SKILL.md

lidfly-connection-doctor

Skill20 starsChanged 4 days agoMITView on GitHub

Диагностировать подключение LidFly MCP v3 в Claude Code, Claude Desktop, Codex, ChatGPT, Cursor, OpenCode и VS Code: неверный config, timeout транспорта, незавершённый или слетающий MCP OAuth, конфликт статического Authorization с OAuth, вход клиента в другой аккаунт LidFly, отсутствие provider-подключения, устаревший снимок инструментов ChatGPT и устаревшие skills. Использовать при Failed, Authenticate/Login, Authentication failed, requires OAuth reauthentication, SSE 405 и недоступных инструментах.

  • Reads credentials

The file

Files
SKILL.md

LidFly Connection Doctor

Определи слой сбоя и дай минимальное действие для восстановления. Не смешивай настройку AI-клиента, MCP OAuth, provider OAuth и skills.

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

Используй доступный контекст, не угадывай:

  • Claude Code: команда claude, проектный .mcp.json, CLAUDE.md, .claude/.
  • Claude Desktop: интерфейс Connectors/Integrations и кнопки Authenticate/Login.
  • Codex CLI/app/extension: AGENTS.md, .codex/config.toml, .agents/skills/.
  • ChatGPT (и Codex через ChatGPT-приложение, клиент openai-mcp): MCP-приложение в разделе «Плагины» chatgpt.com.
  • Cursor: .cursor/mcp.json, AGENTS.md, .agents/skills/.
  • OpenCode: opencode.json/opencode.jsonc, команда opencode, AGENTS.md, сгенерированные этим репозиторием .agents/skills/; .opencode/skills/ проверяй только при явно подтверждённой ручной установке.
  • VS Code: только оболочка. Сначала определи, работает внутри Claude Code или Codex, и применяй инструкцию этого клиента.

Не предлагай .cursor/mcp.json пользователю Claude. Не создавай параллельный config другого клиента.

Диагностируй по порядку

  1. Проверь, настроен ли удалённый Streamable HTTP endpoint https://lidfly.ru/mcp/v3 в формате текущего клиента.
  2. Определи выбранный способ авторизации: OAuth по email или API-ключ аккаунта в заголовке Authorization: Bearer <account_key>. Проверь состояние именно этого способа.
  3. Только после успешной авторизации MCP проверь доступность верхнеуровневых LidFly tools.
  4. Только после успешного MCP соединения проверяй provider-подключения через get_provider_context. Если пользователь ждёт кабинеты, которые у него подключены в LidFly, сначала проверь аккаунт и способ входа (раздел «MCP работает, но кабинетов нет»).
  5. После рабочего MCP проверь наличие и свежесть skills.

Оба способа поддерживаются для агентов и новых интеграций на /mcp/v3. API-ключ не является устаревшим способом или вариантом только для клиентов без OAuth. Ключ доступен в личном кабинете: Настройки → API-ключ → «Скопировать ключ». Не запрашивай значение ключа в чате и не показывай его в диагностике. В одном подключении выбирай один способ: статический Authorization может перекрыть OAuth-токен. При рабочем API-ключе не требуй перехода на OAuth. Источник: решение владельца от 03.10.2026 и src/core/mcp-oauth.ts, resolveMcpBearerPrincipal, ветка api_key.

Не привязывай исправность к фиксированному числу tools или meta-tools.

Классифицируй состояние

Codex: частая повторная авторизация

Если Codex после уже завершённого входа пишет requires OAuth reauthentication или снова требует браузерный вход после истечения access token, сначала определи версии всех процессов, которые используют общее хранилище: CLI, приложение и расширение Codex в VS Code. Для этого сценария поддерживается Codex 0.149 или новее.

Если хотя бы один клиент старше, обнови его или полностью закрой все старые процессы Codex до изменения credentials. Не запускай новый login, пока старый CLI, приложение или расширение ещё работает: старый процесс может снова сохранить запись без issuer. Затем выполни одну миграцию в таком порядке:

codex --version
codex mcp logout lidfly
codex mcp login lidfly
codex mcp list

Классифицируй причину по границе клиента и сервера:

  • Если после истечения access token /token вообще не вызывался, ошибка возникла локально до обращения к LidFly. Это слой mcp_oauth: несовместимая legacy-схема credentials или отсутствующая issuer-привязка. Не обвиняй сервер, не меняй token TTL, soft_rotation, grants или rate limits и не предлагай повторять login без закрытия старых процессов.
  • Если /token вызывался и вернул invalid_grant, это отдельная серверная ветка refresh grant. Проверь безопасные события oauth_refresh_*, client binding и срок grant, не подменяя диагноз локальной issuer-ошибкой.
  • Если /token вернул успех, а следующий MCP-запрос не прошёл, проверяй доставку нового Bearer и MCP admission отдельно; новый браузерный вход сам по себе это не исправляет.

При локальной диагностике credentials проверяй только наличие поля issuer и безопасные сроки. Никогда не показывай access/refresh token, authorization code, PKCE verifier, state или значения из Keychain. После миграции проверь read-only MCP-вызов, автоматический refresh после истечения 15-минутного access token и два параллельных актуальных процесса Codex без нового /authorize.

В обычной клиентской диагностике обновляй навыки штатным установщиком текущего клиента; не предполагай наличие репозитория разработчика. Только при явной задаче на поддержку исходников в репозитории меняй канонический skills-source; generated-копии обновляются только через проверенный подписанный release, не вручную.

Codex: после перезапуска LidFly не запускается

Признаки: в новом сеансе Codex нет инструментов LidFly, при запуске есть предупреждение (warning) о сервере lidfly, codex mcp list показывает для него невыполненный вход, хотя раньше LidFly в этом Codex уже работал. Codex не отправляет сохранённый вход: LidFly не получает ни запросов с токеном, ни обновления через /token. Это слой mcp_oauth на компьютере пользователя, а не сбой сервера и не истечение авторизации LidFly. Не ищи имена инструментов LidFly в файлах проекта: настройка в .codex/config.toml не означает, что сервер запущен в этом сеансе.

На Windows это известная ошибка Codex: после перезапуска он не читает вход MCP из хранилища учётных данных Windows (openai/codex#28201, открыта; проверено 12.11.2026 на Codex 0.167.1). Дай одно действие по шагам:

  1. Полностью закрыть все процессы Codex: CLI, приложение и расширение VS Code.
  2. В глобальном ~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml) добавить первой строкой файла, до любых разделов [...]: mcp_oauth_credentials_store = "file". Проектный .codex/config.toml для этого не меняй.
  3. Выполнить codex mcp logout lidfly, codex mcp login lidfly, codex mcp list и начать новый чат.

После этого Codex хранит вход в файле ~/.codex/.credentials.json; не показывай и не пересылай его содержимое. Если пользователь не хочет хранить вход в файле, второй поддерживаемый способ — API-ключ LidFly в переменной окружения через bearer_token_env_var, без смешивания с OAuth в одном подключении.

На macOS и Linux при тех же признаках сделай один codex mcp logout lidfly и codex mcp login lidfly с закрытыми старыми процессами. Если вход снова пропадает после каждого перезапуска, это уже не настройка: готовь обращение через $lidfly-support-escalation с версией Codex, ОС и текстом предупреждения.

ChatGPT: устаревший снимок инструментов

ChatGPT хранит снимок списка инструментов и схем своего MCP-приложения и сам его не перечитывает; так же ведёт себя Codex, подключённый через ChatGPT-приложение. Если ChatGPT не видит новых инструментов LidFly или получает ошибку параметров (Required at …, INVALID_ARGUMENT, отклонённое поле), выдай одно действие:

Откройте chatgpt.com → Настройки → Плагины → LidFly → «Обновить инструменты» (Refresh) и начните новый чат.

Адрес приложения должен быть https://lidfly.ru/mcp/v3. Адрес существующего приложения не редактируется: для перехода со старого /mcp/lite создай новое приложение через Плагины → Добавить → «Создать MCP-приложение» (нужен режим разработчика: Настройки → Безопасность и вход), войди и удали старое.

Ожидается MCP OAuth

Если UI показывает Failed и доступна кнопка Authenticate или Login, выдай ровно одно действие:

Нажмите Authenticate/Login, завершите вход в открывшемся браузере и затем повторите проверку подключения.

На этом остановись. Не называй это timeout, не предлагай менять config и не обсуждай Яндекс, VK, Авито или другие provider tools до завершения MCP OAuth.

Config отсутствует или неверен

Исправляй только config обнаруженного клиента:

  • Claude Code: проектный .mcp.json или claude mcp add для remote HTTP OAuth.
  • Codex: .codex/config.toml и codex mcp login lidfly.
  • Cursor: .cursor/mcp.json с HTTP endpoint.
  • OpenCode: opencode.json/opencode.jsonc, "type": "remote", URL https://lidfly.ru/mcp/v3 и opencode mcp auth lidfly.
  • Claude Desktop: native Connector/Integration, без .cursor/mcp.json.
  • VS Code: config Claude Code или Codex, который реально работает внутри VS Code.

Транспорт должен быть HTTP/Streamable HTTP, не SSE.

Машиночитаемая ошибка аутентификации

Если ответ LidFly содержит credential_type, используй его до разбора текста ошибки:

  • legacy_or_unknown_bearer: сервер не получил OAuth access token и не признал Bearer действующим API-ключом. Если для подключения ожидался OAuth, это слой config: безопасно проверь конфигурацию текущего клиента на статический Authorization, но не утверждай, что заголовок есть, пока не увидел его или серверная диагностика не доказала повторную отправку прежнего ключа.
  • oauth_access_token: до сервера дошёл OAuth-токен, но он истёк, отозван или больше не принимается. Это слой mcp_oauth: обнови токен или повтори вход. Не удаляй статический заголовок без отдельного доказательства.

Не смешивай эти ветки: одинаковый HTTP 401 не означает одинаковую причину.

OpenCode: статический Authorization перекрывает OAuth

Если OpenCode после завершённого входа пишет Authentication failed, затем SSE error: Non-200 status code (405), не делай вывод, что LidFly требует SSE. OpenCode сначала пробует Streamable HTTP, а SSE запускает как fallback после ошибки первого транспорта; 405 в этой последовательности вторичен.

Для выбранного OAuth-режима классифицируй сбой как config, когда подтверждено хотя бы одно из следующего:

  • в блоке LidFly в opencode.json/opencode.jsonc есть headers.Authorization или другой статический Bearer API key;
  • в блоке LidFly стоит "oauth": false: этот флаг отключает OAuth, поэтому logout/auth не восстановят OAuth-доступ, пока флаг не удалён или не изменён;
  • серверная диагностика показывает один и тот же невалидный API key до и после успешной выдачи OAuth-токенов.

Одно действие восстановления для подтверждённого OAuth-режима: удали только статический headers.Authorization и, если задан, "oauth": false из блока LidFly, не показывая значение заголовка, затем выполни opencode mcp logout lidfly и opencode mcp auth lidfly. Статический заголовок перекрывает OAuth-токен, поэтому новый API-ключ не создавай и LidFly на SSE не переключай. Если пользователь попросил исправить доступный локальный config, можешь удалить эти поля сам, сохранив остальные настройки.

После входа сначала выполни opencode mcp debug lidfly: команда проверяет HTTP-соединение и OAuth discovery flow. Затем проверь opencode mcp list и доступность верхнеуровневых LidFly tools. Только после этого переходи к provider connections и skills.

Connection timeout

Ставь этот диагноз только после того, как config корректен и MCP OAuth не ожидает действия пользователя. Проверь доступность endpoint и повтори один безопасный connect/read. Не советуй повторять provider write.

В OpenCode сначала выполни opencode mcp debug lidfly. Если HTTP/OAuth исправны, а получение списка tools завершается по timeout, проверь timeout в блоке LidFly: для remote MCP OpenCode по умолчанию ждёт 5000 мс. Увеличь только этот timeout до обоснованного значения, например 30000, затем один раз повтори read-only проверку. Не маскируй увеличением timeout ошибки аутентификации или неверный endpoint.

Если timeout повторяется, кратко зафиксируй клиент, endpoint и безопасный текст ошибки. Предложи $lidfly-support-escalation; не передавай токены, raw config с секретами или provider payload.

MCP работает, но кабинетов нет

Сначала проверь аккаунт, а не провайдера. Если пользователь ждёт кабинеты, которые подключены у него в LidFly, вызови subscription_status и сверь способ входа, маскированный email и ID LF-… с ожидаемым аккаунтом (ID в личном кабинете: Настройки → «Ваш аккаунт»). Это диагностика по жалобе, а не обязательный вызов перед каждой задачей.

  • ID другой при OAuth — слой mcp_oauth: клиент вошёл в другой аккаунт LidFly под другим email. Сервер не перепривязывает выданную авторизацию. Дай одно действие для обнаруженного клиента и вход с email нужного кабинета:
    • Claude Code: claude mcp logout <имя сервера>, затем claude mcp login <имя сервера> (имя видно в claude mcp list); в версиях без этих команд — /mcp → сервер LidFly → Clear authentication → Authenticate.
    • Codex: codex mcp logout <имя сервера>, затем codex mcp login <имя сервера>.
    • Claude Desktop, claude.ai и ChatGPT: отключить авторизацию LidFly в настройках подключения клиента и подключить заново. Названия пунктов меню не выдумывай.
    • Клиент не определён: сброс сохранённой авторизации LidFly штатным способом этого клиента. Перезапуск или Reconnect без сброса авторизации оставляют прежний аккаунт. Удаление и повторное добавление сервера не заменяют выход.
  • ID другой при статическом API-ключе — слой config: замени ключ в Authorization на ключ нужного аккаунта или удали статический заголовок и войди по OAuth. Значение ключа не запрашивай и не показывай.
  • ID владельца при командном доступе («Вход выполнен под email участника команды») — норма, а не вход под чужим email.
  • После смены входа снова вызови subscription_status. Если пользователь пишет «не помогло», сначала выясни, был ли новый вход (открывалась ли страница входа LidFly, изменился ли ID), и не повторяй тот же совет.

Только когда аккаунт и способ входа верны, вызови get_provider_context({ provider: ... }). Если нужного подключения нет, объясни, какое подключение добавить в LidFly. Пустой результат сам по себе не доказывает, что пользователь его не добавлял: проверь выбранный проект. На этом шаге не меняй MCP config: транспорт и MCP OAuth уже исправны.

Skills отсутствуют или устарели

Сначала докажи, что MCP tools доступны. Затем сравни project skills с текущим клиентским набором:

  • Claude Code: .claude/skills;
  • Codex: .agents/skills (legacy .codex/skills не считать основным);
  • Cursor: .agents/skills.
  • OpenCode: используй сгенерированные репозиторием .agents/skills; .opencode/skills проверяй только при явно подтверждённой ручной установке — sync этого репозитория туда не пишет.

Предлагай обновить только skills текущего клиента. Отсутствие skills не выдавай за ошибку OAuth или транспорта.

Формат ответа

Сообщи:

  1. обнаруженный клиент;
  2. слой сбоя: config, mcp_oauth, transport, provider_connection или skills;
  3. одно следующее действие;
  4. что проверять после него.

Для Failed + Authenticate/Login оставь только одно действие из раздела MCP OAuth.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.