Введение в контекст Claude: заставьте ИИ по-настоящему понимать весь ваш код-репозиторий

Контекст Claude — это открытый плагин MCP (Model Context Protocol), разработанный векторным вендором Zilliz. Его ключевая задача сформулирована предельно ясно: встроить в кодового помощника ИИ семантическое понимание всего код-репозитория.

В традиционном рабочем процессе, когда вы хотите, чтобы ИИ помог разобраться с незнакомым репозиторием, вам приходится вручную копировать пути к файлам, описывать структуру проекта, объяснять взаимосвязи модулей — хотя это как раз те вещи, которые ИИ должен делать сам. Контекст Claude с помощью технологий семантического поиска позволяет ИИ напрямую запрашивать функции, классы и структуры данных прямо в код-репозитории, больше не полагаясь на ваше ручное «вкладывание контекста».

Проект размещён на GitHub: zilliztech/claude-context. Используется лицензия MIT, весь код полностью открыт.

---

Сложность / время / польза

Для начинающих | около 20 минут | Вы научитесь с помощью всего 2 команд наделять любой инструмент для разработки семантическим пониманием кода на миллион строк — и при этом сократить расход токенов примерно на 40%.

---

Целевая аудитория

• Разработчики, которые ежедневно используют AI-инструменты для программирования, например Claude Code, Cursor, Windsurf, Cline и т. п.
• Тех, кто уже имеет базовое представление о RAG (Retrieval-Augmented Generation) и векторном поиске и хочет перейти к практическому применению
• Команды, которым нужно снизить стоимость токенов и повысить точность ответов ИИ

---

Ключевые зависимости и среда

Системные требования

• Node.js >= 20.0.0 и < 24.0.0
• Операционная система: macOS, Windows или Linux — любая

Зависимости сервиса

• Zilliz Cloud (бесплатного лимита достаточно для личного использования): предоставляет бэкенд векторной базы данных
• OpenAI API Key: используется для генерации векторов (embeddings) модели (при желании можно заменить на другого провайдера, поддерживающего embeddings)

---

Полное дерево структуры проекта

Контекст Claude — это чистый npm-пакет, поэтому вам не нужно клонировать или собирать какой-либо локальный код. После установки он сам управляет своей структурой хранения:

~/.claude/
└── plugins/
    └── claude-context/          # директория плагина MCP
        └── [файлы индексных данных]        # инкрементальные снапшоты Merkle-дерева

Если вы используете Core-пакет и подключаете его напрямую в приложение, структура будет такой:

your-project/
├── node_modules/
│   └── @zilliz/claude-context-core/
├── .env                        # хранение API Key
└── your-codebase/              # код, который нужно проиндексировать

---

Пошагово

Шаг 1: зарегистрируйте Zilliz Cloud и получите учётные данные для векторной базы

Для хранения векторов Контекст Claude опирается на Zilliz Cloud (или на Milvus, развернутый у вас самостоятельно). На этом шаге вам нужно создать бесплатный аккаунт.

Откройте zilliz.com/cloud, зарегистрируйтесь, используя e-mail или аккаунт GitHub. После входа в консоли создайте новый Serverless Cluster:

1. Нажмите Create Cluster
2. Выберите тип Serverless (бесплатного лимита полностью хватает)
3. Выберите ближайший регион (часто используют AWS us-west-2 или Сингапур)
4. Назовите кластер, например claude-context

После завершения создания кластера перейдите на страницу его деталей, найдите Connection Info и скопируйте два значения для дальнейшего использования:

• Public Endpoint: выглядит примерно как https://xxx.api.gcp-us-west1.zillizcloud.com
• API Key: выглядит примерно как xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Шаг 2: получите OpenAI API Key

Контекст Claude использует embedding-модель, чтобы превращать фрагменты кода в векторы. Вам нужно подготовить OpenAI API Key для запуска модели text-embedding-3-small по умолчанию.

Откройте platform.openai.com/api-keys, нажмите Create new secret key и скопируйте сгенерированное значение (формат sk-xxxxxxxx...).

Шаг 3: установите MCP-плагин Claude Context в Claude Code

Теперь мы регистрируем этот MCP-сервер в Claude Code. Откройте терминал, перейдите в любую папку проекта и выполните команды:

claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-your-openai-api-key \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

Замените плейсхолдеры на свои реальные значения:

• sk-your-openai-api-key → ваш OpenAI API Key
• your-zilliz-cloud-api-key → ваш Zilliz Cloud API Key
• your-zilliz-cloud-public-endpoint → ваш Zilliz Public Endpoint

При успешном выполнении команды вы увидите, что MCP-сервер зарегистрирован. Проверка установки:

claude mcp list

В списке должно быть claude-context, а статус — running.

Если вы используете другой AI-инструмент для программирования, способ настройки будет немного отличаться. Пара типичных сценариев:

Cursor (рекомендуется через конфигурационный файл):

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

Windsurf (тоже использует JSON-конфигурацию):

// ~/.windsurf/mcp_settings.json
{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

Шаг 4: проиндексируйте ваш первый код-репозиторий

После установки перейдите в папку вашего проекта и запустите Claude Code:

cd your-project-directory
claude

В диалоге введите следующую команду, чтобы запустить индексацию:

Index this codebase

Контекст Claude сразу начнёт анализировать репозиторий. Процесс состоит из двух этапов:

1. Сканирование файлов: обход директорий и фильтрация нужных код-файлов по расширениям
2. Векторное встраивание: для каждого файла кода выполняется разбиение на чанки через AST (абстрактное синтаксическое дерево), затем вызывается embedding-модель для генерации векторов и их запись в векторную базу данных

Во время индексации вы можете в любой момент спросить о прогрессе:

Check the indexing status

В ответе будет указан текущий процент прогресса индексации и количество уже обработанных файлов.

Шаг 5: проверьте эффект семантического поиска и разберитесь с результатами

После завершения индексации можно начинать семантический поиск. Ниже несколько типичных сценариев запросов:

Поиск реализации конкретной функции:

Find functions that handle user authentication

Результаты будут содержать релевантные имена функций, пути к файлам, фрагменты кода и оценку релевантности (в диапазоне 0–1: чем выше, тем точнее).

Понимание взаимосвязей между модулями:

How does the payment module connect to the order module?

Быстрое обнаружение кода, связанного с настройками:

Where is the database connection pool configured?

Формат ответа выглядит так:

File: src/database/connection.ts:45-78
Score: 0.94
Content:
  const pool = new Pool({
    max: 20,
    idleTimeoutMillis: 30000,
    connectionTimeoutMillis: 2000,
  });

Если вы хотите очистить индекс и начать заново, выполните:

Clear the index for this codebase

---

Частые проблемы и устранение

В1: Несовместимая версия Node.js, ошибка при выполнении команды

Симптомы: команда claude mcp add падает с ошибкой или MCP-сервер сразу же завершается после запуска.

Причина: Контекст Claude сейчас не поддерживает Node.js 24.x.

Решение:

# проверить текущую версию Node
node -v

# если это 24.x — понизить до 20.x (LTS)
nvm install 20
nvm use 20

В2: Ошибка в настройке переменных окружения, индексация не удаётся

Симптомы: Index this codebase не отвечает или возвращает ошибку Milvus connection failed.

Шаги проверки:

1. Убедитесь, что MILVUS_ADDRESS не содержит префикс https://, используйте только часть с хостом
2. Убедитесь, что MILVUS_TOKEN полностью совпадает с API Key, отображаемым в консоли Zilliz Cloud
3. Убедитесь, что OPENAI_API_KEY начинается с sk-

Пример корректного формата:

-e MILVUS_ADDRESS=in-xx-xxxxxxxx.api.gcp-us-west1.zillizcloud.com
-e MILVUS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-e OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

В3: Индексация зависла, прогресса нет

Симптомы: после запуска команды индексации нет ответа.

Решение:

1. Сначала выполните Check the indexing status, чтобы понять текущий статус
2. Проверьте сетевое соединение (нужно иметь доступ к OpenAI API и Zilliz Cloud)
3. Если кластер создан недавно, endpoint может ещё инициализироваться — подождите 1–2 минуты и попробуйте снова

В4: Результаты поиска пустые или полностью нерелевантные

Симптомы: запрос должен совпадать с нужным содержимым, но возвращается пусто.

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

Решение:

1. Сначала проверьте статус индексации: Check the indexing status
2. Попробуйте более конкретный запрос (используйте фактические имена переменных или функции из кода)
3. Если вы уверены, что код есть, но поиск не находит — очистите индекс и выполните индексацию заново:

Clear the index for this codebase
Index this codebase

В5: Инкрементальная индексация не сработала — изменённый код не находится

Симптомы: вы изменили какой-то файл, но результаты семантического поиска всё равно указывают на старую версию.

Причина: Контекст Claude использует снимки Merkle-дерева для обнаружения изменений файлов. Если вы вручную удалили файл со снапшотом, инкрементальная проверка может не сработать.

Решение: достаточно очистить индекс и начать заново:

Clear the index for this codebase
Index this codebase

В6: Не удаётся подключиться по MCP, инструмент недоступен

Симптомы: в списке инструментов нет search_code, index_codebase и т. п.

Решение:

1. Перезапустите Claude Code (иногда MCP-сервер нужно загрузить заново)
2. Проверьте, что в конфигурации MCP нет синтаксических ошибок (в JSON важны запятые и кавычки)
3. Проверьте, является ли статус плагина running в выводе claude mcp list

claude mcp list

Если статус stopped, перезапустите вручную:

claude mcp remove claude-context
# затем снова выполните команду установки из шага 3

---

Дополнительное чтение / направления развития

Использование пользовательской embedding-модели

text-embedding-3-small от OpenAI — вариант по умолчанию, но Контекст Claude поддерживает множество embedding-провайдеров, что позволяет сделать полностью локальную развёртку:

Использование Ollama (локальная модель):

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=ollama \
  -e OLLAMA_BASE_URL=http://localhost:11434 \
  -e OLLAMA_MODEL=nomic-embed-text \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

Использование VoyageAI:

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=voyageai \
  -e VOYAGEAI_API_KEY=your-voyageai-key \
  -e VOYAGEAI_MODEL=voyage-code-3 \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

Интеграция LangChain/LangGraph для продвинутого RAG

Если вы хотите напрямую встроить возможности Контекста Claude в своё приложение, используйте пакет Core:

import { Context, MilvusVectorDatabase, OpenAIEmbedding } from '@zilliz/claude-context-core';

// инициализация embedding и векторной базы данных
const embedding = new OpenAIEmbedding({
    apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
    model: 'text-embedding-3-small'
});

const vectorDatabase = new MilvusVectorDatabase({
    address: process.env.MILVUS_ADDRESS || 'your-zilliz-cloud-public-endpoint',
    token: process.env.MILVUS_TOKEN || 'your-zilliz-cloud-api-key'
});

const context = new Context({ embedding, vectorDatabase });

// индексирование репозитория и отслеживание прогресса
const stats = await context.indexCodebase('./your-project', (progress) => {
    console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);

// выполнение семантического поиска
const results = await context.semanticSearch('./your-project', 'vector database operations', 5);
results.forEach(result => {
    console.log(`File: ${result.relativePath}:${result.startLine}-${result.endLine}`);
    console.log(`Score: ${(result.score * 100).toFixed(2)}%`);
    console.log(`Content: ${result.content.substring(0, 100)}...`);
});

Подробные примеры можно посмотреть в evaluation/retrieval/custom.py।

Визуальный семантический поиск в VSCode

Если вам удобнее работать прямо в IDE, установите плагин Semantic Code Search: он позволяет выполнять семантический поиск непосредственно в VS Code без запуска Claude Code.

Стратегия управления несколькими репозиториями

Контекст Claude поддерживает одновременное управление несколькими код-репозиториями. Достаточно вызывать Index this codebase в разных директориях — для каждой директории будет поддерживаться отдельный индекс. Для различия можно задавать имя директории:

# рабочая директория A
cd ~/projects/frontend && claude
# в диалоге выполните Index this codebase

# рабочая директория B
cd ~/projects/backend && claude
# в диалоге выполните Index this codebase

Принцип разбиения на чанки по AST и инкрементальная индексация через Merkle-дерево

Способность Контекста Claude понимать код базируется на двух ключевых технологиях:

• Разбиение на чанки по AST: анализируется структура кода с помощью абстрактного синтаксического дерева; чанки формируются по границам функций, классов и модулей, а не просто по количеству строк. Это гарантирует, что каждый chunk — семантически целостная единица кода.
• Инкрементальная индексация на основе Merkle-дерева: после изменения каждого файла выполняется сравнение по Merkle-дереву — переиндексируются только изменённые файлы, а не проводится полная перестройка. Это существенно снижает стоимость поддержки больших код-репозиториев.

Если вас интересуют детали реализации этих двух технологий, вы можете посмотреть исходный код packages/core в репозитории zilliztech/claude-context.