SocratiCode — MCP-сервер для глубокого понимания кодовой базы

Каждый, кто работал с AI-агентами над большим чужим кодом, знает эту боль: агент честно грепает по файлам, выкачивает в контекст десятки случайных фрагментов, тратит токены и всё равно не понимает архитектуру. SocratiCode — open-source проект, который предлагает другой подход: заранее проиндексировать кодовую базу и отдать агенту готовый, структурированный слой знаний о ней.

По замыслу автора, «ваш AI читает код — SocratiCode его понимает». Проект распространяется под лицензией AGPL-3.0, опубликован в npm как пакет socraticode и работает как локальный MCP-сервер (stdio), а также как нативный плагин для Claude Code, OpenAI Codex, Cursor, расширение VS Code и Gemini CLI. Данные не покидают вашу машину: по умолчанию всё крутится в Docker (Qdrant для векторного поиска и Ollama для эмбеддингов), API-ключи не нужны. Судя по заявлению авторов, движок обкатан на корпоративных репозиториях объёмом более 40 миллионов строк кода.

Что умеет

Набор функций у SocratiCode вполне конкретный — это не «обёртка над grep», а полноценный слой кодовой аналитики:

• Гибридный поиск. Каждый фрагмент кода индексируется в Qdrant дважды: как плотный семантический вектор и как BM25-вектор для точного поиска по идентификаторам. Запрос выполняется одним round-trip, результаты сливаются через Reciprocal Rank Fusion (RRF). Семантика находит «аутентификацию» даже если этих слов в коде нет, BM25 — конкретную функцию по имени.
• AST-aware чанкинг. Файлы режутся не по строкам, а по границам функций и классов через ast-grep — качество поисковой выдачи заметно выше, чем при наивном разбиении.
• Полиглотный граф зависимостей. Статический анализ импортов для 19+ языков, поиск циклических зависимостей, Mermaid-диаграммы и интерактивный HTML-просмотрщик.
• Impact-анализ на уровне символов. Второй слой графа отслеживает, кто кого вызывает: blast radius при изменении функции, трассировка потока выполнения от точки входа, 360°-обзор символа.
• Контекстные артефакты. Помимо кода можно проиндексировать схемы БД, OpenAPI-спецификации, Kubernetes-манифесты и архитектурные документы — и искать по ним тем же гибридным поиском.

Зачем это нужно, если есть встроенный поиск

Авторы приводят сравнительную таблицу: встроенные индексы Cursor и Copilot привязаны к конкретному инструменту — сменил ассистента, начал с нуля. SocratiCode же хранит понимание кодовой базы отдельно от AI-хоста: проиндексировал один раз — и Claude Code, и Cursor, и Copilot, и ваша собственная локальная модель пользуются одним и тем же знанием.

Бенчмарк на кодовой базе VS Code (2,45 млн строк) заявляет внушительные цифры: на 61% меньше контекста, на 84% меньше вызовов инструментов и в 37 раз быстрее по сравнению с grep-агентом (тестировалось с Claude Opus 4.6). Отдельный аргумент: поскольку blast radius и call-flow уже вычислены заранее, даже небольшие модели справляются с архитектурно сложными задачами, которые иначе потребовали бы топового ризонинга.

Ключевой принцип, который авторы рекомендуют прописать агенту в инструкциях: search before reading. Индекс даёт карту кодовой базы за миллисекунды; чтение сырых файлов — дорого и прожорливо по контексту.

Быстрый старт

Требования минимальные: Node.js 18.17+ с npx на PATH и запущенный Docker (для локальных Qdrant и Ollama). Для любого MCP-хоста с JSON-конфигурацией достаточно:

{
  "mcpServers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"]
    }
  }
}

Для Claude Code удобнее нативный плагин — он включает MCP-сервер, workflow-скиллы и агентские инструкции:

claude plugin marketplace add giancarloerra/socraticode
claude plugin install --scope user socraticode@socraticode

Из коробки поддерживаются Claude Code, OpenAI Codex, VS Code, Cursor, Gemini CLI, Continue, Cline, Roo Code, Zed и OpenCode (в README приведены готовые конфиги для каждого). При первом запуске сервер сам проверит Docker, скачает образы, поднимет Qdrant и Ollama и загрузит модель эмбеддингов — первичная установка занимает около пяти минут, последующие старты — секунды.

Первый запрос к агенту на новом проекте: «Index this codebase». Индексация идёт в фоне, прогресс проверяется вопросом «What is the codebase index status?». По данным авторов, 3+ млн строк на MacBook Pro M4 индексируются менее чем за 10 минут.

Инструменты MCP-сервера

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

Классический сценарий из примеров README: спросить «что сломается, если я переименую validateUser?» — и получить по хопам список файлов, начиная с прямых вызовов и заканчивая тестами.

Детали, которые радуют

Проект продуман для реальной, а не демонстрационной работы:

• Докачиваемая индексация. Файлы обрабатываются батчами по 50 с чекпоинтами в Qdrant; крах, пауза или рестарт не теряют прогресс — индексация продолжается с последней контрольной точки.
• Живой file watcher. Индекс обновляется автоматически при каждом изменении файлов и между сессиями.
• Мультиагентность. Несколько AI-агентов могут одновременно работать с одной кодовой базой через общий индекс: межпроцессные блокировки координируют индексацию и слежение, один watcher обслуживает всех.
• Branch-aware режим. С SOCRATICODE_BRANCH_AWARE=true каждая git-ветка получает свои коллекции — удобно для CI/CD и ревью PR.
• Кросс-проектный поиск. Связанные проекты линкуются через .socraticode.json, и один запрос ищет по всем сразу.
• Мультипровайдерные эмбеддинги. По умолчанию локальный Ollama, но одной переменной окружения переключается на OpenAI (text-embedding-3-small), Google Gemini, LM Studio или LiteLLM.
• Интерактивный граф офлайн. HTML-просмотрщик с Cytoscape.js и Dagre вендорится внутрь пакета: файлы цветные по языкам, циклы красным, правый клик подсвечивает обратное транзитивное замыкание («кто сломается, если это изменить»), есть экспорт в PNG — файл можно приложить к PR.

Честно описаны и ограничения: call-граф строится статическим анализом без вывода типов. Динамическая диспетчеризация (getattr, eval, reflection), нераскрытые макросы и «магия» фреймворков (Spring DI, Rails has_many, декораторная маршрутизация) невидимы — «ноль вызывающих» на DI-тяжёлой кодовой базе стоит перепроверить. Для контроля качества в codebase_graph_status отдаётся метрика unresolvedEdgePct.

Языки и файлы

Три уровня поддержки: полный (индексация + граф + AST-чанкинг) для JavaScript/TypeScript, Python, Java, Kotlin, Scala, C/C++/C#, Go, Rust, Ruby, PHP, Swift, Dart, Elixir, Bash, HTML, CSS/SCSS, Svelte, Vue; условный AST для GDScript; индексация без графа для конфигов и документации (JSON, YAML, TOML, Markdown, SQL, Dockerfile и др.). Всего 63 расширения файлов и 8 специальных имён из коробки, плюс настройка нестандартных расширений через EXTRA_EXTENSIONS.

Лицензия и облако

Ядро — AGPL-3.0 с отдельной коммерческой лицензией для enterprise-сценариев. Облачная версия SocratiCode Cloud (private beta) добавляет общий командный индекс, SSO, аудит-логи и варианты развёртывания в VPC/air-gapped; open-source ядро остаётся бесплатным. У проекта есть и сателлит — JanuScope, локальный policy-прокси для MCP: блокировка инструментов, гейт на SQL-мутации, редактирование PII и аудит.

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