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

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

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

• Описание Context7

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

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

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

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

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

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

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

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

Весь процесс удобно держать в голове как цепочку:

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

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

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

Понадобятся установленный Cursor или Claude Code, доступ в интернет и рабочий Node.js с npm/npx для команды настройки. Установщик `ctx7` требует Node.js 18 или новее. В новом окружении берите LTS-версию, которая ещё поддерживается.

• Требования 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. В первом агент получает инструменты сервера, во втором обращается к документации через команды `ctx7` по инструкции навыка. Для проверки ниже выберите MCP, тогда в истории будут видны вызовы инструментов с их именами. По умолчанию настройка CLI выполняется глобально, а флаг `--project` ограничивает её текущим проектом.

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

Затем откройте Claude Code и выполните `/mcp`. Команда покажет доступные серверы и их состояние.

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

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

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

У Cursor своя команда:

npx ctx7 setup --cursor

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

• Инструкция для 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` и не трогайте остальные подключения.

• Context7: конфигурация 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 не работает

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

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

• Context7: устранение неполадок

Отдельная история — Cursor Cloud Agents. У них собственная конфигурация MCP, поэтому Context7, работающий в локальном редакторе, в облачном запуске может оказаться недоступен. Настраивайте его по инструкции для Cloud Agents.

• Context7: настройка Cursor Cloud Agents