SavePearlHarbor

SocratiCode: разбираю MCP-сервер, который даёт ИИ-агенту понимание кодовой базы

—

от автора

admin

Что внутри: Qdrant, Ollama, AST-чанкинг и гибридный поиск без лишних танцев с бубном

Если вы работаете с Claude Code, Cursor или другими ИИ-ассистентами на больших кодовых базах, то наверняка знаете эту боль. Просишь агента найти, где у нас обрабатывается авторизация. Он начинает делать grep -r "auth" по всему проекту, читать десятки файлов подряд, заполнять контекстное окно мусором. На монорепе с миллионом строк это превращается в медленный и дорогой процесс. И часто бесполезный — нужный класс называется IdentityVerifier, а не Auth, и grep его просто не найдёт.

Эту проблему пытаются решить разными способами: от индексации в IDE до встроенных систем семантического поиска в платных версиях ИИ-ассистентов. Я недавно наткнулся на open source проект SocratiCode, который подходит к задаче с другой стороны — через MCP (Model Context Protocol). Решил разобраться, как он устроен, и потестировать на реальных проектах.

Что такое SocratiCode

Если коротко — это MCP-сервер, который индексирует вашу кодовую базу и предоставляет ИИ-агенту набор инструментов для умного поиска по ней. Вместо grep и чтения файлов агент получает API: семантический поиск, анализ графа зависимостей, поиск по контекстным артефактам (схемы БД, API-спецификации, инфраструктурные конфиги).

Стек под капотом такой:

  • Qdrant — векторная БД с HNSW-индексированием, хранит и dense-векторы, и sparse-векторы BM25;

  • Ollama — локальные эмбеддинги по умолчанию (опционально OpenAI или Gemini);

  • ast-grep — AST-aware чанкинг кода по границам функций и классов, плюс анализ зависимостей для 18+ языков;

  • Docker — единственное обязательное требование, всё остальное поднимается автоматически. Лицензия AGPL-3.0, есть коммерческая лицензия для тех, кому AGPL не подходит. Что важно: всё работает локально по умолчанию, ваш код не уходит ни в какие облака.

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

Установка

Тут реально без танцев. Если у вас Claude Code, команда такая:

claude mcp add socraticode -- npx -y socraticode

Для VS Code, Cursor, Windsurf, Cline, Roo Code в конфиг MCP добавляется блок:

"socraticode": {  "command": "npx",  "args": ["-y", "socraticode"]}

Для OpenAI Codex CLI правится ~/.codex/config.toml:

[mcp_servers.socraticode]command = "npx"args = ["-y", "socraticode"]

После рестарта хоста SocratiCode при первом запуске сам подтягивает Docker-образы для Qdrant и Ollama, скачивает модель эмбеддингов и поднимает контейнеры. Один раз потратил минут пять на загрузку всего этого добра, дальше старт занимает секунды.

Дальше говорите агенту: «Проиндексируй эту кодовую базу». Индексация идёт в фоне, можно следить за прогрессом запросом «What is the codebase index status?». На моём проекте около 200 тысяч строк (Python + TypeScript) первичная индексация заняла около минуты на M2 Pro.

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

Самая интересная часть с инженерной точки зрения — гибридный поиск. SocratiCode кладёт в Qdrant не один вектор на каждый чанк кода, а два: dense (семантический) и sparse BM25 (лексический). Когда агент делает запрос, оба прогона идут параллельно в одном round-trip к Qdrant, а результаты объединяются через RRF — Reciprocal Rank Fusion.

Зачем такая схема. Семантический поиск хорош для концептуальных запросов: ищешь «middleware для авторизации» — находит код, который про авторизацию, даже если в нём нет слова «auth». BM25 наоборот — точно находит идентификаторы, имена функций, специфичные строки. По отдельности каждый из методов проседает в своих слепых зонах: семантика не умеет ловить редкие имена переменных, лексика не понимает синонимов и контекста.

RRF берёт результаты обоих и выдаёт объединённый ранжированный список без необходимости настраивать веса. Формула там простая: для каждого документа считается сумма 1/(k+rank) по всем поисковикам, где он встретился. Эмпирически это даёт результат не хуже, чем тонко тюнингованные взвешенные комбинации.

Чанкинг тоже не банальный. Вместо разбивки по N строкам или по байтам файлы режутся по границам функций и классов через ast-grep. Для языков без поддержки AST-парсинга система фолбэчится на построчное разбиение. Это критично для качества: семантическая близость работает гораздо лучше, когда чанк — это законченный логический блок, а не случайный кусок с обрезанной серединой функции.

Граф зависимостей

Помимо поиска SocratiCode строит граф зависимостей кода через статический анализ импортов. Поддерживаются import, require, use, include для 18+ языков. Граф автоматически строится после индексации и обновляется при изменениях файлов.

Что это даёт на практике. У агента появляется отдельный инструмент: «покажи, что зависит от этого модуля» или «найди циклические зависимости». Для рефакторинга очень полезно — раньше я задавал такие вопросы через серию grep-ов, теперь агент получает структурный ответ за один вызов.

Циклические зависимости визуализируются через Mermaid-диаграммы. Это, конечно, не замена полноценному инструменту вроде Madge или dependency-cruiser, но для базовых задач достаточно. И главное — оно встроено в общий пайплайн, не нужно отдельно настраивать ещё один инструмент.

Контекстные артефакты

Это отдельная фича, которая мне понравилась больше всего. SocratiCode умеет индексировать не только код, но и так называемые контекстные артефакты: схемы БД, OpenAPI-спецификации, Terraform-конфиги, архитектурные документы. Они складываются в отдельный поисковый индекс.

Конфигурируется через файл .socraticodecontextartifacts.json в корне проекта. Указываете пути и типы артефактов, SocratiCode их парсит и делает доступными для семантического поиска.

Пример из документации:

{  "artifacts": [    {      "type": "database_schema",      "path": "db/schema.sql",      "description": "Main PostgreSQL schema"    },    {      "type": "api_spec",      "path": "docs/openapi.yaml",      "description": "Public API specification"    }  ]}

После этого агент может отвечать на вопросы типа «какие таблицы участвуют в авторизации» или «какие эндпоинты возвращают данные пользователя» — без ручного указания файлов. Это закрывает кейс, где код и его инфраструктурное окружение нужно рассматривать вместе.

Бенчмарк, на который стоит смотреть с оговорками

Авторы провели тест на VS Code — это 2.45 миллиона строк кода. Использовали Claude Opus 4.6. Сравнивали SocratiCode с обычным grep-based подходом, когда агент сам ищет по тексту.

Результаты, которые они приводят:

  • на 61% меньше контекста уходит в LLM;

  • на 84% меньше вызовов инструментов;

  • в 37 раз быстрее по wall-clock времени. Звучит внушительно. Но к таким цифрам всегда стоит подходить с холодной головой.

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

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

Что я заметил при использовании

Тестировал на нашем рабочем монорепе (около 800 тысяч строк, Python + TypeScript + немного Go). Прогнал несколько типовых задач и сравнил поведение Claude Code с SocratiCode и без.

Что стало заметно лучше.

Запросы вида «где в коде обрабатывается X» — где X концептуальная вещь, а не конкретная функция. Раньше агент тратил несколько ходов на grep с разными вариациями ключевых слов, теперь сразу получает релевантные куски. Пример: «где у нас валидация входных данных API» — без SocratiCode агент сначала ищет «validation», потом «validate», потом «schema», потом начинает читать middleware. С SocratiCode — один вызов, и сразу несколько релевантных мест с разной формулировкой.

Архитектурные вопросы. «Какие сервисы используют наш Redis-кеш?» — раньше требовало серии запросов. Теперь агент через граф зависимостей получает список модулей, которые импортируют клиент кеша.

Вопросы по схеме БД — после настройки контекстных артефактов это просто ускорилось в разы. Агент не лезет читать миграции, а получает структурированный ответ из проиндексированной схемы.

Что осталось так же или хуже.

Точечные задачи. «Покажи определение функции parseConfig» — никакой выгоды от SocratiCode, обычный grep справляется быстрее и точнее. Семантический поиск тут просто лишняя ступенька.

Свежие изменения. Watcher обновляет индекс с задержкой в 2 секунды (debounced), что нормально, но если вы только что добавили функцию и сразу спрашиваете про неё — может ещё не попасть в индекс. На практике это редко мешает, но бывает.

Память. Docker-контейнеры с Qdrant и Ollama едят прилично — на моём ноуте Activity Monitor показывал около 3.5 ГБ суммарно при активной индексации. Для рабочего проекта нормально, для слабых машин — момент, который стоит учитывать.

Когда это имеет смысл ставить

После недели использования сформулировал для себя простой критерий. Если ваш проект меньше 50 тысяч строк — экономии особо не будет, grep отрабатывает за миллисекунды, контекстное окно переваривает любой запрос. Накладные расходы на индексацию и поддержание Docker-контейнеров не оправдываются.

Если проект 100–500 тысяч строк — уже становится полезно. Особенно если вы регулярно решаете архитектурные задачи или работаете с незнакомыми частями кодовой базы.

От 500 тысяч строк и выше — это уже почти необходимость, если вы серьёзно используете ИИ-агентов. Без векторного поиска агент либо тратит много токенов на grep и чтение, либо вообще не может ответить на вопросы про общую структуру.

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

Альтернативы

SocratiCode не одинок в этой нише. Есть несколько других open source проектов с похожей идеей:

  • Cody от Sourcegraph — умеет индексировать кодовую базу, но в основном через свой клиент, а не через MCP;

  • Aider имеет свою систему карты репозитория, но без полноценного векторного индекса;

  • Continue поддерживает локальную индексацию через свой формат. SocratiCode выигрывает в том, что это чистый MCP-сервер, который работает с любым MCP-совместимым хостом одинаково. Поставил один раз — пользуешься в Claude Code, Cursor, Windsurf и так далее. Не нужно учить разные интерфейсы.

Минус: фичи доступны только через MCP-вызовы, отдельного UI или CLI для прямой работы с индексом нет. Если хочется самому делать запросы к индексу без посредничества ИИ — придётся писать что-то поверх.

Вывод

SocratiCode — рабочий инструмент, который решает конкретную инженерную задачу: дать ИИ-агенту понимание структуры кодовой базы вместо построчного чтения. Архитектурные решения — Qdrant с гибридным поиском, AST-чанкинг, MCP как точка интеграции — выбраны грамотно.

Пафосные формулировки в духе «читкод для вайбкодеров» и «в 30 раз умнее» — это маркетинговая упаковка, в которой проект встретили в некоторых телеграм-каналах. Реальные цифры скромнее: для архитектурных задач на больших кодовых базах ускорение в разы есть, для точечных — не будет.

Если вы регулярно работаете с большим кодом через ИИ-агента — однозначно стоит попробовать. Установка простая, риски минимальные, всё локально. Если ваш проект помещается в один файл — пройдите мимо, не ваш случай.

Ссылки:

ссылка на оригинал статьи https://habr.com/ru/articles/1031878/