Context7 для Cursor и Claude Code: подключение и проверка работы

Когда агент предлагает незнакомый метод библиотеки, полезно спросить, откуда он его взял. Правдоподобный пример может относиться к другой версии пакета или вовсе не соответствовать его API. Для проверки нужна документация именно той библиотеки, которая используется в проекте.

Context7 находит документацию библиотек и передаёт подходящие фрагменты агенту. Сервис можно подключить к Cursor и Claude Code. Его назначение — дать источники для работы с API; полученный код всё равно нужно проверить в приложении. Описание Context7.

• Описание Context7

Ниже — настройка для локальных клиентов и контрольный запрос, который помогает отличить реальное обращение к документации от ответа по памяти. Инструкция сверена с официальными материалами; подключение к вашему аккаунту и практический тест здесь не проводились.

Когда Context7 полезен

Начните с задачи, где ответ зависит от конкретной библиотеки: настройка роутера, работа с формой, запрос к базе через ORM, загрузка файла через SDK. В таких случаях важно знать, какие методы существуют, что они принимают и какое поведение обещает документация.

Если же задача — поправить опечатку или разобраться в собственной бизнес-логике, внешний поиск по библиотекам может ничего не добавить. Сначала определите, какого знания не хватает.

Не начинайте с просьбы «подключи всю документацию». Сформулируйте вопрос, на который должен ответить найденный источник.

Как устроен поиск документации

В MCP-подключении используются два основных инструмента: `resolve-library-id` находит идентификатор библиотеки, а `query-docs` получает материалы под конкретный вопрос. Если идентификатор уже известен, первый поиск можно пропустить. Документация интеграции.

• Документация интеграции

Для проверки удобно представлять процесс в виде цепочки:

Задача и версия пакета
        ↓
Выбор нужной библиотеки
        ↓
Поиск ответа в документации
        ↓
Сопоставление с кодом проекта
        ↓
Изменение и проверка результата

Каждый переход можно проверить отдельно. Ошибка при выборе библиотеки не исправляется тем, что агент аккуратно перепишет найденный пример. А наличие подходящей документации ещё не подтверждает, что обработчик правильно встроен в ваше приложение.

Что подготовить перед установкой

Нужен установленный Cursor или Claude Code, доступ в интернет и рабочий Node.js с npm/npx для команды настройки. Установщик `ctx7` требует Node.js 18 или новее; для нового окружения разумно использовать поддерживаемую LTS-версию. Требования CLI.

• Требования CLI

В обычном терминале проверьте:

node --version
npx --version

Если команда не найдена, сначала настройте Node.js в том окружении, где запускаете установщик. Это может быть терминал macOS, Windows или WSL — проверяйте именно используемую среду.

Если Context7 уже подключён, изучите существующую конфигурацию перед повторной установкой. Две записи одного сервиса с разными способами входа затруднят проверку: станет непонятно, через какую из них агент делает запрос.

Подключение к Claude Code

Выполните в терминале:

npx ctx7 setup --claude

Установщик проводит вход через OAuth и предлагает способ подключения. Следуйте его подсказкам и завершите авторизацию в браузере. Это текущий стартовый путь из инструкции Context7 для Claude Code.

• инструкции Context7 для Claude Code

Доступны два режима: MCP и CLI + Skills. В MCP агент получает инструменты сервера; в CLI + Skills обращается к документации через команды `ctx7` по инструкции навыка. Для проверки ниже выберите MCP, чтобы видеть вызовы инструментов с указанными именами. По умолчанию настройка CLI выполняется глобально, а флаг `--project` ограничивает её текущим проектом. Режимы настройки.

• Режимы настройки

После завершения откройте Claude Code и проверьте подключение через `/mcp`. Эта команда показывает доступные серверы и их состояние. Управление MCP в Claude Code.

• Управление MCP в Claude Code

Если вы предпочли режим CLI + Skills, проверяйте фактические обращения к `ctx7`, а не наличие MCP-сервера. Это разные пути к документации.

Подключение к Cursor

Для Cursor используйте отдельную команду в терминале:

npx ctx7 setup --cursor

Пройдите предложенную авторизацию и выберите MCP, если хотите повторить контрольный сценарий статьи. Инструкция для Cursor.

• Инструкция для Cursor

Для ручного подключения откройте настройки MCP в Cursor. Глобальная конфигурация хранится в `~/.cursor/mcp.json`, проектная — в `.cursor/mcp.json`. В официальной инструкции Context7 приведён такой вариант HTTP-подключения:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

`YOUR_API_KEY` — место для ключа из вашего аккаунта. Этот пример соответствует официальной конфигурации MCP-клиентов. В существующем файле добавьте запись `context7` в объект `mcpServers`, сохранив остальные подключения.

• официальной конфигурации MCP-клиентов

Не сохраняйте личный ключ в общем репозитории. Для первой ручной настройки удобнее личный конфигурационный файл. Если используете OAuth, у Context7 отдельный адрес `https://mcp.context7.com/mcp/oauth`; не смешивайте два способа входа в одной инструкции. Варианты авторизации.

• Варианты авторизации

Обычно достаточно автоматической настройки. К ручной переходите, когда требуется разобраться в существующей конфигурации или задать её самостоятельно.

Как проверить, что агент действительно использовал Context7

Для первого запроса лучше выбрать знакомую библиотеку. Тогда проще заметить неверный источник. Если у вас есть проект с Zod, откройте его и отправьте агенту:

Найди установленную версию Zod в проекте. Используй Context7, чтобы выяснить, как в этой версии проверять email и получать результат проверки без исключения. Сначала выбери библиотеку, затем найди документацию. Покажи идентификатор, ссылки на источники и короткий пример. Если документация не позволяет подтвердить нужную версию, скажи об этом. Файлы не меняй.

Это учебный запрос, а не зафиксированный результат работы сервиса. Если Zod в проекте нет, замените его на знакомый установленный пакет и задайте небольшой вопрос по его API.

При чтении ответа проверяйте три уровня:

Если идентификатор передан заранее, отсутствие `resolve-library-id` нормально: важен запрос документации по правильному идентификатору. Если инструмент вернул ошибку, гладкий ответ агента после неё не превращает неудачное обращение в успешную проверку.

Почему версия библиотеки важнее убедительного примера

Указание версии в запросе помогает сузить задачу, но её всё равно нужно сопоставить с найденными материалами. В CLI Context7 версионные идентификаторы доступны, когда они есть в результатах поиска; выбирать их следует из фактически возвращённого списка. Поиск библиотек и версий.

• Поиск библиотек и версий

Допустим, в проекте стоит старая основная версия пакета, а агент показывает пример для новой. Не просите сразу «исправить весь проект под этот код». Сначала выясните, есть ли нужная операция в установленной версии. Обновление зависимости — отдельное решение, которое может затронуть другие части приложения.

Для задач с библиотеками можно использовать такой порядок:

1. Определить версию по файлам проекта.
2. Найти документированный способ выполнить операцию.
3. Проверить применимость примера к установленной версии.
4. Внести ограниченное изменение и запустить соответствующую проверку.

Если версию подтвердить не удалось, откройте официальную документацию нужного выпуска или руководство по миграции напрямую. Отсутствие результата в одном инструменте не означает, что у библиотеки нет решения.

Нужно ли каждый раз писать use context7

Прямое указание `use context7` удобно для проверки подключения. Автоматическая настройка также может установить навык поиска документации. Варианты вызова описаны в руководстве Context7 для Claude Code.

• руководстве Context7 для Claude Code

Для рабочего проекта полезнее сформулировать условие применения. Например:

Если решение зависит от API внешней библиотеки, сначала определи
её версию в проекте и найди подходящую документацию через Context7.
Если нужный источник недоступен или версия не подтверждена,
сообщи об этом и проверь официальную документацию напрямую.

Это предложенная формулировка правила. В Claude Code её можно включить в CLAUDE.md, а в Cursor — в правила проекта. Она задаёт повод для обращения к документации и порядок работы при неудаче, не требуя внешнего поиска для каждой правки текста.

• CLAUDE.md

Что делать, если Context7 не работает

Проверяйте тот этап, на котором остановился запрос. Повторная установка всего клиента редко помогает понять, где причина.

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

• разделом Troubleshooting

Есть отдельная особенность Cursor Cloud Agents: они используют собственную конфигурацию MCP. Работа Context7 в локальном редакторе не подтверждает его доступность в облачном запуске. Для него следуйте инструкции настройки Cloud Agents.

• инструкции настройки Cloud Agents