Семантический поиск

Семантический поиск по файлам Markdown. Находите связанные заметки по смыслу, а не просто по ключевым словам. Обнаруживайте дубликаты перед созданием новых заметок.

Поддерживает два транспортных протокола сервера:

• stdio MCP — для интеграции с Claude Code (один процесс на сессию)

• HTTP — комбинированный MCP-over-HTTP + REST на одном порту; один «разогретый» процесс, общий для всех клиентов

Возможности

• Семантический поиск с использованием sentence-transformers

• Обнаружение дубликатов/похожих заметок

• Автоматическое обновление индекса с помощью отслеживания изменений файлов

• Поддержка нескольких директорий

• Извлечение встроенных тегов (#tag-name)

Related MCP server: mcp-recall-md

Установка

Установка только для CPU — рекомендуется для macOS (любой Mac, Apple Silicon или Intel) и Linux/Windows без видеокарты NVIDIA. Экономит около 5 ГБ бинарных файлов CUDA. На macOS графический процессор Apple (MPS) по-прежнему автоматически обнаруживается и используется через встроенный бэкенд MPS в PyTorch — метка «CPU» относится только к отсутствию CUDA, а не к вычислительному устройству во время выполнения.

uv tool install --index https://download.pytorch.org/whl/cpu \
  git+https://github.com/bborbe/semantic-search

Установка CUDA — только для Linux/Windows с выделенной видеокартой NVIDIA. Не применимо к macOS (NVIDIA CUDA не поддерживается на Mac).

uv tool install git+https://github.com/bborbe/semantic-search

Обновление

uv tool upgrade semantic-search

Режимы сервера

stdio MCP (для каждой сессии Claude Code)

Запускает один процесс на каждую сессию Claude Code. Просто, но каждая сессия загружает свою копию модели объемом ~400 МБ–1 ГБ.

claude mcp add -s project semantic-search \
  --env CONTENT_PATH=/path/to/vault \
  -- \
  uvx --from git+https://github.com/bborbe/semantic-search semantic-search-mcp

Доступные инструменты:

• search_related(query, top_k=5) — поиск семантически связанных заметок

• check_duplicates(file_path) — обнаружение дубликатов/похожих заметок

HTTP (общий для всех клиентов)

Один долгоживущий процесс обслуживает MCP-over-HTTP по адресу /mcp плюс REST по адресам /search, /duplicates, /health, /reindex. Все сессии Claude Code и REST-клиенты используют один общий «разогретый» индексатор.

CONTENT_PATH=/path/to/vault semantic-search-http --host 127.0.0.1 --port 8321

Укажите его в конфигурации MCP для Claude Code:

{
  "mcpServers": {
    "semantic-search": {
      "type": "http",
      "url": "http://127.0.0.1:8321/mcp"
    }
  }
}

REST-эндпоинты:

Примеры запросов:

# Search
curl 'http://127.0.0.1:8321/search?q=kubernetes+deployment'

# Find duplicates
curl 'http://127.0.0.1:8321/duplicates?file=notes/my-note.md'

# Health check
curl 'http://127.0.0.1:8321/health'

Плагин Claude Code

Этот репозиторий также поставляется как плагин для маркетплейса Claude Code с командами для настройки, поиска и исследований.

Установка

claude plugin marketplace add bborbe/semantic-search
claude plugin install semantic-search

Обновление

claude plugin marketplace update semantic-search
claude plugin update semantic-search@semantic-search

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

# One-shot interactive setup: installs the binary, writes the launchd/systemd
# unit, registers the MCP server in your Claude config.
/semantic-search:configure

# Search indexed markdown
/semantic-search:search kubernetes deployment

# Multi-step research across results
/semantic-search:research kafka backup strategy

Команды

Запуск в фоновом режиме

Для использования в производственных целях запускайте semantic-search-http как фоновую службу, чтобы каждая сессия Claude Code (и любой REST-клиент) использовали один «разогретый» процесс.

Краткий пример (macOS):

launchctl load ~/Library/LaunchAgents/com.github.bborbe.semantic-search-http.plist

Краткий пример (Linux):

systemctl --user enable --now semantic-search-http.service

CLI-команды

Разовые команды без запуска сервера:

# Search
CONTENT_PATH=/path/to/vault semantic-search search "kubernetes deployment"

# Find duplicates
CONTENT_PATH=/path/to/vault semantic-search duplicates path/to/note.md

Бинарные файлы

Конфигурация

Переменные окружения

Несколько директорий

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

CONTENT_PATH=/path/to/vault1,/path/to/vault2,/path/to/docs

Все директории индексируются вместе и ищутся как единый индекс.

Как это работает

При первом запуске загружается небольшая модель эмбеддингов (~90 МБ) и индексируются ваши файлы Markdown (<1 с для типичных хранилищ). Индекс автоматически обновляется при изменении файлов через отслеживание файловой системы.

Индексируемый контент

Каждый файл Markdown индексируется с учетом взвешенных компонентов:

Разработка

# Clone
git clone https://github.com/bborbe/semantic-search
cd semantic-search

# Install dev dependencies
make install

# Run checks
make check

# Run tests
make test

Лицензия

Лицензия BSD 2-Clause — см. LICENSE.