🔍 code-search-mcp

Zero-daemon локальный MCP-сервер семантического поиска по коду на базе LanceDB и встроенных ONNX-эмбеддингов.
Хватит искать точные слова через grep. Дайте вашему ИИ-ассистенту для кода возможность искать по смыслу.

Работает из коробки с Claude Code, Gemini CLI, Antigravity (agy) и Cursor на macOS, Windows и Linux.

☕️ Представьте приложение для кофейни

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

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

// Apply a 15% promotional deduction if the customer visits before 9 AM
export function calculateEarlyBirdReward(bill: OrderSummary): number {
  if (bill.orderHour < 9) {
    return bill.subtotal * 0.85;
  }
  return bill.subtotal;
}

Теперь представьте, что вы открываете своего ИИ-ассистента для кода (например, Claude Code, Cursor или Gemini CLI) и спрашиваете:

«Где рассчитывается утренняя скидка на напиток?»

Если ваш инструмент опирается только на традиционный текстовый поиск (например, grep), он ищет точное слово "discount".

• Нашёл ли он calculateEarlyBirdReward? Нет.

• Почему? Потому что в коде использовались слова promotional deduction и EarlyBirdReward, но не использовалось точное слово "discount".

Именно здесь семантический поиск меняет всё.

Related MCP server: smart-coding-mcp

🧠 Что такое семантический поиск (человеческим языком)?

Традиционный поиск ищет точные буквы и слова.

Семантический поиск ищет смысл за вашими словами.

Как это работает: карта смыслов

1. Числа вместо букв: ИИ-модель берёт фрагмент текста (или кода) и превращает его в список чисел, который называется эмбеддинг (или вектор).

2. Координаты на карте: Представьте эти числа как GPS-координаты на огромной карте человеческих понятий.

   • "discount" и "promotional deduction" оказываются рядом друг с другом на карте.

   • "espresso shot" и "latte" находятся вместе.

   • "database migration" находится далеко, на другой стороне карты.

3. Поиск ближайших соседей: Когда вы задаёте вопрос на естественном языке, поисковый движок превращает ваш вопрос в координаты и просто находит фрагменты кода, расположенные на карте ближе всего к нему.

                  [ Map of Meaning ]

   ☕️ "morning drink discount"   📍 (Your Question)
              │ (Close match!)
              ▼
   🏷 "calculateEarlyBirdReward" 📍 (Your Code)
   
   ─────────────────────────────────────────────
   
   🗄 "sql database migration"   📍 (Far Away - Ignored)

🚀 Почему семантический поиск — прорыв для написания кода с ИИ

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

Вместо этого ИИ должен мгновенно находить нужные 2–3 файла.

В реальных проектах наши кодовые базы полны этого контекста:

• Markdown-документация (.md): ADR-документы, руководства по API, онбординг-документация.

• Комментарии в коде: объясняющие, почему существует бизнес-правило (например: // Списываем зерно из бункера кофемашины).

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

Семантический поиск напрямую связывает ваши мысли на естественном языке с этими Markdown-документами, комментариями и фрагментами кода — даже когда вы не помните точных имён функций.

🛠 Что мы создали: code-search-mcp

Многие существующие инструменты семантического поиска для разработчиков требуют сложной настройки:

• Установка Python 3, виртуальных окружений и pip.

• Запуск внешнего фонового сервера базы данных (например, ChromaDB), слушающего сетевой порт.

• Настройка демонов автозапуска (LaunchAgents на Mac, Task Scheduler в Windows), которые разряжают батарею при включении.

• Добавление сложных Git-хуков (pre-commit), которые могут заблокировать работу, если сервер БД офлайн.

Мы хотели совершенно другое: Ноль настройки. Ноль внешних демонов. Мгновенная работа в любом проекте.

Поэтому мы создали code-search-mcp — автономный кросс-платформенный Model Context Protocol (MCP) сервер для Node.js.

┌─────────────────────────────────────────────────────────────┐
│                       AI Client                             │
│       (Claude Code / Gemini CLI / Antigravity / Cursor)     │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP Protocol (JSON-RPC over stdio)
┌──────────────────────────────▼──────────────────────────────┐
│                      code-search-mcp                        │
│                                                             │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────┐  │
│  │   Scanner &      │  │  EmbeddingEngine │  │  Watcher  │  │
│  │ Layered Ignores  │  │  (all-MiniLM-L6) │  │(chokidar) │  │
│  └────────┬─────────┘  └────────┬─────────┘  └─────┬─────┘  │
│           │                     │                  │        │
│           └───────────┬─────────┴──────────────────┘        │
│                       ▼                                     │
│              VectorStore (LanceDB)                          │
│        node_modules/.cache/code-search/                     │
└─────────────────────────────────────────────────────────────┘

⚙️ Технологии внутри

🔍 Как это работает под капотом

1. Как he know when to start индексирование?

Когда ваш ИИ-ассистент запускается (например, вы запускаете Claude Code, Antigravity или Gemini CLI), he подключается к code-search-mcp через стандартный ввод/вывод (stdio).

• MCP-сервер подключается мгновенно, меньше чем за 15 мс.

• Фоновый рабочий процесс начинает сканирование файлов проекта, не блокируя вашу чат-сессию.

2. Можно ли искать до завершения индексации? (суперспособность в процессе индексации)

Да! Если вы зададите вопрос через 2 секунды после открытия проекта, code-search-mcp никогда не блокирует и не зависает.

Он ет по всем уже проиндексированным файлам и показывает вающий заголовок прогресса в реальном времени:

⚠️ [Index status: INDEXING (35% complete - 2,100/6,000 files indexed)]
Results from currently indexed files:

### Match 1: src/drinks/espresso.ts (Lines 12-30) [Score: 54.2%]

3. Будьте терпеливы при первом запуске — он работает только один раз! ⏳

В огромных репозиториях с более чем 5000 файлов самое первое индексирование занимает несколько минут, потому что локальная ИИ-модель впервые генерирует векторные эмбеддинги для каждого чанка кода на вашей машине.

Хорошие новости:

• Вы платите время только один раз: итоговая векторная база данных постоянно хранится в node_modules/.cache/code-search/lancedb/.

• Мгновенный запуск при следующем открытии: В каждой последующей сессии или перезапуске редактора сервер подключается менее чем за 15 мс без переиндексации.

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

• Ждать не нужно: Вы можете сразу начинать задавать вопросы и искать — ассистент ищет по тому, что уже проиндексировано в фоне.

4. Где хранится индекс?

По умолчанию база данных хранится здесь: 📁 node_modules/.cache/code-search/lancedb/

Почему node_modules/.cache?

• node_modules уже игнорируется Git в 100% проектов.

• Ноль шума в Git системы: неотслеживаемые папки номехи в Git никогда не появляются в вашем репозитории.

• (Если в проекте нет node_modules, сервер корректно использует .code-search/).

5. Что происходит при переключении Git-веток? 🔀

Когда вы выполняете git checkout, git switch или git pull:

1. Детекция живым наблюдателем: Git обновляет файлы на диске. Он обнаруживает добавленные, изменённые или удалённые файлы в реальном времени.

2. Быстрое дифференциальное повторное сканирование: переиндексируются только те файлы, которые изменились между ветками (1–2 секунды вместо минут).

3. Автоматическая очистка: удалённые файлы и старые фрагменты кода из предыдущей ветки автоматически удаляются из LanceDB.

4. Ручная синхронизация: если вы хотите принудительно выполнить полную переиндексацию после большого merge'а, просто скажите ассистенту: "Выполни code_search_reindex с параметром force: true".

⚙️ Как управлять настройками и игнорировать лишние файлы

По умолчанию code-search-mcp автоматически игнорирует бинарные файлы (.png, .mp4, .zip), результаты сборки (dist/, build/), локбоксы и любые файлы объемом более 500 КБ, а также учитывает ваш существующий .gitignore.

Если вы хотите настроить параметры или игнорировать дополнительные файлы для вашего проекта, у вас есть два простых варианта:

Вариант 1: Создайте файл .codesearchignore (быстро и просто)

Создайте в корне проекта файл .codesearchignore и используйте стандартный синтаксис gitignore:

# Ignore mock data and test fixtures
tests/fixtures/**
src/mocks/**

# Ignore auto-generated files
src/models/*.generated.ts
locales/**

Вариант 2: Создайте файл .codesearchrc.json (расширенные настройки)

Создайте файл .codesearchrc.json в корне проекта, чтобы управлять поведением индексации, пакетной обработкой и лимитом размера файлов:

{
  "maxFileSizeKb": 300,
  "batchSize": 50,
  "customExcludes": [
    "legacy_vendor/**",
    "docs/archive/**"
  ],
  "supportedExtensions": [
    ".ts", ".tsx", ".js", ".vue", ".py", ".md", ".json"
  ]
}

📦 Как установить инструмент

Вы можете установить и запустить инструмент любым из следующих способов:

1 шаг: / choice among installation method

Способ A: Прямо из GitHub через npx (без установки — не нужна публикация в npm!)

Любой ИИ-клиент может запустить его напрямую из вашего GitHub-репозитория в момент необходимости:

npx -y github:your-username/code-search-mcp

(Node автоматически скачивает репозиторий, собирает бандл и запускает MCP-сервер).

Способ B: Из npm-реестра (после публикации)

Если вы опубликовали пакет в npm:

npx -y code-search-mcp
# or global install:
npm install -g code-search-mcp

Способ C: Локальная разработка / через npm link (самый быстрый локальный старт)

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

cd /path/to/code-search-mcp
npm install
npm run build
npm link

Теперь code-search-mcp зарегистрирован как глобальная команда в вашей системе!

2 шаг: подключите его к ИИ-клиенту

1. Claude Code

# If running via GitHub:
claude mcp add code-search -s user -- npx -y github:your-username/code-search-mcp

# If running locally (linked):
claude mcp add code-search -s user -- code-search-mcp

2. Antigravity CLI (agy)

Выполните эту команду в терминале:

mkdir -p ~/.gemini/config/plugins/code-search && cat << 'EOF' > ~/.gemini/config/plugins/code-search/plugin.json
{ "name": "code-search" }
EOF
cat << 'EOF' > ~/.gemini/config/plugins/code-search/mcp_config.json
{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "github:your-username/code-search-mcp"]
    }
  }
}
EOF

3. Gemini CLI

Добавьте в ~/.gemini/settings.json:

{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "github:your-username/code-search-mcp"],
      "trust": true
    }
  }
}

4. Cursor / Claude Desktop

Добавьте в .cursor/mcp.json:

{
  "mcpServers": {
    "code-search": {
      "command": "npx",
      "args": ["-y", "github:your-username/code-search-mcp", "--path", "${workspaceFolder}"]
    }
  }
}

🤖 Руководство для ИИ-агента и справочник инструментов

Если вы ИИ-ассистент (Claude Code, Gemini CLI, Cursor, Antigravity или Windsurf), читающий этот репозиторий, вот ваше краткое руководство по использованию инструментов MCP, предоставляемых code-search-mcp:

🛠️ Доступные MCP-инструменты

🧭 Матрица выбора инструмента: когда какой инструмент использовать

                       ┌───────────────────────────────────────────────┐
                       │ What are you looking for in the codebase?     │
                       └───────────────────────┬───────────────────────┘
                                               │
           ┌───────────────────────────────────┼───────────────────────────────────┐
           ▼                                   ▼                                   ▼
┌─────────────────────────┐         ┌─────────────────────────┐         ┌─────────────────────────┐
│ Concept / Feature /     │         │ Known Symbol / Callers  │         │ Exact Literal String /  │
│ Business Logic Intent   │         │ & Blast Radius Analysis │         │ Error Code / CSS Class  │
│ (Natural Language)      │         │ (Exact identifier)      │         │ (Exact text match)      │
└──────────┬──────────────┘         └──────────┬──────────────┘         └──────────┬──────────────┘
           ▼                                   ▼                                   ▼
┌─────────────────────────┐         ┌─────────────────────────┐         ┌─────────────────────────┐
│ 🔍 USE: code_search     │         │ 🌳 USE: codegraph       │         │ 🔎 USE: grep_search     │
│ • "where is payment..." │         │ • codegraph_explore     │         │ • "ERR_INVALID_AUTH"    │
│ • "tax calculation..."  │         │ • callers / callees     │         │ • ".btn-primary-blue"   │
└─────────────────────────┘         └─────────────────────────┘         └─────────────────────────┘

💡 Полезные советы для ИИ-агентов

1. Используйте codeOnly: true для чистой логики реализации: Если вы хотите найти вычисления и формулы на чистом TypeScript/JavaScript и исключить документацию в Markdown или руководства по навыкам, всегда передавайте codeOnly: true.

2. Используйте pathFilter для сужения до подсистем: Если пользователь спрашивает «как работает оформление заказа в биллинговом модуле?», передайте pathFilter: "src/billing".

3. Используйте номера строк для прямого редактирования кода: Фрагменты кода возвращаются с номерами строк, начиная с 1 (14: export function calculateTotal()). Эти диапазоны можно передать напрямую в replace_file_content или view_file — без угадывания.

4. Устойчивость к опечаткам: Свободно передавайте обычные слова — движок автоматически обрабатывает множественные формы (стемминг) и опечатки (исправление Левенштейна) за <1мс.

🤝 Идеальная пара для ИИ: почему стоит установить оба инструмента: code-search и codegraph

Современные ИИ-ассистенты для работы с кодом показывают наилучший результат, когда у них есть два взаимосторонних инструмента: семантический поиск (code-search-mcp) и AST-граф кода (codegraph).

                   ┌─────────────────────────────────────────────────────────┐
                   │  User: "Where is subscription discount handled?"        │
                   └────────────────────────────┬────────────────────────────┘
                                                │
                                                ▼
                   ┌─────────────────────────────────────────────────────────┐
                   │ 1. SEMANTIC SEARCH (code_search)                        │
                   │ • Understands intent, concepts, and natural language     │
                   │ • Finds: subscription-billing.engine.ts (via JSDoc)     │
                   └────────────────────────────┬────────────────────────────┘
                                                │
                                                ▼
                   ┌─────────────────────────────────────────────────────────┐
                   │ 2. AST CODE GRAPH (codegraph_explore)                   │
                   │ • Understands syntax trees, callers, and blast radius   │
                   │ • Traces: callers into legacy LegacyOrderProcessor.js   │
                   │ • Discovers: unit tests (subscription-billing.spec.ts)  │
                   └─────────────────────────────────────────────────────────┘

Почему одного инструмента недостаточно:

Пример из реальной практики: современный движок против легаси-монолита

В реальной корпоративной кодовой базе:

1. Современный движок (subscription-billing.engine.ts) имеет осознанные имена (calculateSubscriptionDiscount) и подробные JSDoc-объяснения. code_search находит её с более 55% совпадением за миллисекунды.

2. Легаси-ядро (LegacyOrderProcessor.js) — это файл на 2 000 строк, исползующий старые термины (getDiscountedTotal, applyOldDeduction) или опечатки. Только семантический поиск может его занизить.

3. Синергия: когда code_search попадает на subscription-billing.engine.ts, codegraph_explore проментно прослеживает все вызовы в LegacyOrderProcessor.js и карпографирует радиус поражения по unit-тестам, покрывающим их — без догадок!

Рекомендуемая парная конфигурация

Добавьте оба инструмента в вашу MCP-конфигурацию:

{
  "mcpServers": {
    "code-search": {
      "command": "node",
      "args": ["/path/to/code-search-mcp/dist/bin/cli.js"]
    },
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    }
  }
}

📋 Рекомендации по настройке ассистента

Чтобы ваш ИИ-ассистент автоматически выбирал code_search и codegraph, добавьте следующее правило в файл инструкций проекта (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md or .cursorrules):

## Code Navigation & Search

1. **CodeGraph (`codegraph_explore`)**: Call FIRST when exploring known symbols, tracking call paths, finding usages, or analyzing blast radius (callers + covering tests).
2. **Semantic Search (`code_search`)**: Call FIRST when looking for features, domain behaviors, or business logic described in natural language (e.g. "where is discount calculated", "checkout suggestions formatted").

🧪 Как проверить, что всё работает

После установки вы можете проверить работу code-search-mcp тремя проверки:

Проверка 1. Спросите своего ИИ-ассистента о статусе

В любом чате с Claude Code, Cursor или Gemini CLI спросите:

«Проверь code_search_status»

Ожидаемый результат:

Index Status: READY (or INDEXING)
Progress: 100%
Files: 6,070 / 6,070 indexed
Chunks: 8,204 code chunks in LanceDB

Проверка 2. Попробуйте семантический поиск по естественному языку

Спросите ИИ-ассистента:

«Используй code_search, чтобы найти, как обрабатываются правила скидок и бонусов для клиентов»

Ожидаемый результат:

### Match 1: src/rewards/early-bird.ts (Lines 1-18) [Score: 56.4%]

Ассистент мгновенно возвращает релевантные фрагменты кода с точными номерами строк и оценками схожести.

Проверка 3. Проверьте отслеживание файлов в живом режиме

1. Создайте в проекте новый тестовый файл (например, src/drinks/secret-recipe.ts) с уникальным комментарием:

   // Caramel macchiato secret syrup blend formula
   export const caramelBlend = 42;

2. Сохраните файл.

3. Сразу спросите вашего ИИ-ассистента:

   «Найди формулу секретной смеси сиропов через code_search»

4. Новый файл будет найден и показан менее чем за 1 секунду — никакого ручного пересборки или перезапуском не требуется!

Проверка 4. Запуск автоматических тестов (необязательно)

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

npm test

Все 31 модульный и интеграционный тест будут выполены и пройдены, проверяя рукопожатие MCP-протокола, генерацию векторов ONNX, хранение LanceDB, жизненный цикл watcher, стемминг слов и коррекцию опечаток.

🛠️ Реальные проблемы, с которые мы столкнулись, и как починили (простыми понятиями)

Создание поискового движка, одинаково хорошо работающего для людей и ИИ-агентов, выздоявило несколько практических сложностей. Вот что было найдено, и как решена каждая проблема:

1. 🔤 Ловушка множественного числа и окончаний ("marks" против "Marker")

• Проблема: когда человек общается на естественном языке и пишет: "как chart iqа uses marks на графике", он использует множественное число "marks". При этом в коде класс может называться CIQ.Marker or markersSample. Обычный запрос (LIKE '%marks%') полностью упускает Marker из-за лишней «s».

• Устранение: мы создали лёгкий стеммер. Он автоматически удаляет типичные суффиксы (-s, -ing, -ed, -ers, tion). При поиске "marks" ищется корень "mark" и мгновенно находятся CIQ.Marker, markAxis, markersSample — с нулевой производительностью.

2. ✍️ Ловушка опечаток ("calcualte mrgin shortfall")

• Проблема: люди живо наберётся в чат и допускают опечатки (например, mrgin вместо margin или calcualte вместо calculate). Если в слове опечатка, классический keyword search не сработает в 100% случаев.

• Устранение: создан встроенный словарь в памяти + корректор Левенштейна. Во время индексации движок собирает словарь всех реальных имён переменных, классов и терминов в вашем репозитории. Когда вы приходите с описанкой, движок проверяет словарь и исправляет опечатку за <1 мс перед поиском.

3. 🤖 Дружелюбные для ИИ-агентов блоки кода (с номерами строк)

• Проблема: при выводеомы в ходе водики строка (Lines 10-50), но код внутри блока не имел номеров строк. Когда ИИ-агент (Claude Code, Gemini CLI, Antigravity) хотел отредактировать или процитировать строку, ему приходилось вручную пересчитать или угадывать смещение.

• Устрашение: теперь каждая строка в фрагменте кода автоматически получает префикс с исходным номером (10: export class ...). ИИ-агенты могут сразу передавать точные номера строк в инструменты редактирования, без дополнительных чтений.

4. 📚 Шум документации в чистом поиске по коду

• Проблема: при поиске общих понятий, например «как форматива валюту», большие markdown-файлы и инженерные гайды часто ранжировались выше реальных .ts утилитов, потому что док содержат много разговорного английского.

• Что мы сделали:

  1. Добавлены параметры поиска: codeOnly: true (игнорирует markdown/doc), pathFilter: "src/...", language.

  2. Снижен вес встроенных JSON-словарей, чтобы ключевая логика TypeScript/JavaScript всегда была выше приоритет.

5. 🔁 Переполнение результата (множество чанков из одного большого файла)

• Проблема: при поиске общей темы один файл на 3000 строк с нескольким совпадениями занимал все 10 слотов и скрывал совпадения из мелких خوب вспомогательных файлов.

• Устранение: введено разнообразие в рамках одного файла: engine возвращает не более 2 чанков с высокими очками срезов для каждого файла, что позволяет получить хорошее разнообразие результатов по всей базе.

6. ⚡ Конфликты блокировки БД при быстрых сохранениях

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

• Устранено: добавлена асинхронная очередь записей с попеременно-экспоненциальной задержкой (backoff). Если возникают конфликты добавления, очередь несколько миллисекунд и безопасно повторяет, не роняя сервер.

💡 Итог

Совмещая эмбеддинги ONNX внутри процесса с встроенной LanceDB, интеллектуальной генерацией токенов и протоколом контекста моделей (MCP), мы устраняли трение локального семантического поиска:

• ✅ Без бэкграунд-демонов на вашем ноутбуке.

• ✅ Без зависимостей OpenAI/Python и ChromaDB.

• ✅ Без засорение git (только node_modules/.cache).

• ✅ Автоматическая обработка опечаток и словоформ в <1 мс.

• ✅ Мгновенный смысловой поиск, связавание природных вопросов на ваш язык с точным кодом и markdown-документами.

Приятной разработки! ☕️🚀