# Как настроить QMD для кодинг-агентов и сократить расход токенов на поиск файлов

> AI Release · @ai_release1 · https://ai-release.org/guides/kak-nastroit-qmd-dlya-koding-agentov-i-sokratit-rashod.html

## TL;DR
- Время выполнения: 30–45 минут
- Уровень сложности: Intermediate
- Понадобится: macOS, Linux или WSL2; Node.js LTS (или bun); git; кодинг-агент с поддержкой MCP (Claude Code, Cursor или аналог); репозиторий с markdown-документацией и кодом; свободное место под локальный файл индекса — оцените по размеру репозитория, индекс лежит на диске рядом с ним

QMD — локальный поисковый движок по markdown-файлам и коду, который отдаёт агенту не файлы целиком, а top-k релевантных фрагментов. MCP (Model Context Protocol) — стандарт, по которому агент вызывает внешние инструменты; через него агент и обращается к QMD.

## Требования и подготовка
![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/kak-nastroit-qmd-dlya-koding-agentov-i-sokratit-rashod-ru-1.jpg?v=1794840571)


- ОС: macOS 13+, Ubuntu 22.04+ или Windows 10/11 с WSL2.
- Node.js LTS и npm — проверить: `node -v && npm -v`. Точную минимальную версию сверьте с документацией QMD.
- git — QMD индексирует рабочую копию, а не историю коммитов.
- Кодинг-агент с MCP: Claude Code (`claude --version`), Cursor или аналог.
- Ключ доступа, если ваша конфигурация использует облачные эмбеддинги или реранкер — какие провайдеры и переменные окружения поддерживаются, сверьтесь с документацией.
- Права на запись в каталог индекса (по умолчанию он создаётся рядом с репозиторием или в домашнем каталоге — уточните в `qmd --help`).

**Как работает схема (поток данных):**

1. QMD один раз обходит каталоги и строит локальный индекс: разбивает файлы на фрагменты и сохраняет их в файл на диске.
2. Агент вместо `grep -r` и чтения файлов целиком делает один MCP-вызов поиска.
3. QMD возвращает 3–10 фрагментов с путём и номером строки.
4. Агент открывает только тот файл, который ему действительно нужен.

Экономия возникает на шаге 3–4: агенту в контекст попадают сотни строк вместо десятков тысяч.

**Пример:** монорепозиторий, где документация лежит в `docs/`, а сервисы — в `services/api/` и `services/worker/`. Создаём две коллекции — `docs` и `services`, — чтобы поиск по документации не разбавлялся кодом.

Если вместо лёгкого индекса нужен полноценный локальный семантический поиск с эмбеддингами, посмотрите разбор [Как настроить локальный семантический поиск по файлам с Rummage и EmbeddingGemma 2](https://ai-release.org/guides/kak-nastroit-lokalnyy-semanticheskiy-poisk-po-faylam-s.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide) — там тот же принцип «сначала индекс, потом ответ».

## Шаг 1. Установите QMD и проверьте CLI

**Что сделать:** поставить QMD глобально и убедиться, что бинарник доступен в `PATH`.

**Зачем:** агенту нужно запускать сервер по имени команды; если бинарник не в `PATH`, MCP-подключение упадёт ещё до поиска.

```bash
npm install -g qmd
qmd --version
qmd --help
```

**Пример:** `qmd --help` печатает список подкоманд. Если в вашей версии установка описана иначе (bun, Homebrew, готовый бинарник) — сверьтесь с разделом Install в документации проекта; имя пакета и флаги между версиями меняются.

**Как проверить:** команда `qmd --version` выводит строку с номером версии без ошибок, а `qmd --help` — список подкоманд. Запишите путь к бинарнику — он понадобится в Шаге 3:

```bash
which qmd
# например: /usr/local/bin/qmd
```

**Почему это работает:** MCP-клиент запускает процесс по имени или абсолютному пути; глобальная установка кладёт исполняемый файл в `PATH`, поэтому агент находит его без дополнительных настроек.

## Шаг 2. Соберите индекс и ограничьте область поиска
![Иллюстрация к разделу «Шаг 2. Соберите индекс и ограничьте область поиска»](https://ai-release.org/guides/img/kak-nastroit-qmd-dlya-koding-agentov-i-sokratit-rashod-ru-2.jpg?v=1794840575)


**Что сделать:** добавить каталоги как коллекции, собрать индекс и исключить мусор — `node_modules`, сборки, `.env`, логи.

**Зачем:** индекс по `node_modules` и `dist` раздувает файл на диске и подмешивает в выдачу нерелевантные фрагменты, из-за чего агент снова начинает читать лишнее.

```bash
cd <путь-к-репозиторию>

# регистрируем коллекции
qmd collection add ./docs      --name docs
qmd collection add ./services  --name services

# строим индекс
qmd index

# смотрим, что получилось
qmd status
qmd collections
```

**Пример:** после `qmd index` команда `qmd status` показывает число проиндексированных документов и фрагментов по каждой коллекции. Если по коллекции `docs` ноль документов — путь указан неверно.

Что включать и что исключать:

| Каталог | Включать | Причина |
|---|---|---|
| `docs/`, `*.md` | да | основные знания для агента |
| `services/**/*.ts` | да | исходники, по которым идёт поиск |
| `node_modules/`, `dist/`, `build/` | нет | шум и лишний объём индекса |
| `.env`, `*.pem`, ключи | нет | секреты не должны попадать ни в индекс, ни в контекст агента |

Правила исключения задаются в конфиге QMD или через фильтры коллекции — синтаксис сверьте с документацией (`qmd collection add --help`). Каталоги с секретами проще не регистрировать вовсе.

**Как проверить:** выполните тестовый поиск и убедитесь, что в выдаче есть пути из нужных каталогов:

```bash
qmd search "rate limit" --limit 5
```

Ожидаемый результат — 5 строк вида `docs/api/limits.md:12  ...фрагмент...`. Если выдача пустая или в ней только пути из `node_modules` — вернитесь к регистрации коллекций.

Пересобирайте индекс после крупных правок: `qmd index`. Если расходы на агента выходят за бюджет, ограничьте их отдельно — см. [Как настроить лимиты расходов и бюджеты для ИИ-агентов: контроль затрат на API](https://ai-release.org/guides/kak-nastroit-limity-rashodov-i-byudzhety-dlya-ii-agento.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

## Шаг 3. Подключите MCP-сервер к агенту и замерьте экономию
![Иллюстрация к разделу «Шаг 3. Подключите MCP-сервер к агенту и замерьте экономию»](https://ai-release.org/guides/img/kak-nastroit-qmd-dlya-koding-agentov-i-sokratit-rashod-ru-3.jpg?v=1794840579)


**Что сделать:** прописать QMD как MCP-сервер в конфиге агента и сравнить объём данных, который агент читает при обычном поиске и через QMD.

**Зачем:** без MCP-подключения агент про QMD не знает и продолжает жечь токены на `grep` и чтение файлов целиком.

Для Claude Code конфиг проекта — файл `.mcp.json` в корне репозитория:

```json
{
  "mcpServers": {
    "qmd": {
      "command": "/usr/local/bin/qmd",
      "args": ["mcp"],
      "env": {}
    }
  }
}
```

Для Cursor тот же блок кладётся в `~/.cursor/mcp.json`. Точное имя подкоманды запуска сервера (`mcp` или иное) сверьте с `qmd --help` — это единственное место, где конфиг зависит от версии.

**Пример:** в Claude Code команда `/mcp` показывает список серверов; рядом с `qmd` должен быть статус `connected`. Если статус `failed` — смотрите раздел «Возможные проблемы».

Теперь замер. Сравниваем, сколько байт текста уходит в контекст при обычном поиске и при поиске через QMD:

```bash
# 1) «слепой» поиск: сколько байт в файлах, которые агент прочитал бы целиком
grep -rIl "rate limit" . --exclude-dir=node_modules | xargs wc -c | tail -1

# 2) выдача QMD
qmd search "rate limit" --limit 5 > /tmp/qmd.out
wc -c /tmp/qmd.out
```

**Пример вывода:** первая команда — `412033 total`, вторая — `3800 /tmp/qmd.out`. Подставьте свои значения: соотношение и есть ваша экономия в байтах. Байты переведите в токены тем же токенизатором, что использует ваша модель, — коэффициент зависит от языка и кода.

Чек-лист приёмки:

- [ ] `qmd --version` отрабатывает без ошибок
- [ ] `qmd status` показывает ненулевое число документов в каждой коллекции
- [ ] `qmd search "<запрос>"` возвращает релевантные пути
- [ ] `/mcp` в агенте показывает `qmd` со статусом `connected`
- [ ] агент на вопрос «где описаны лимиты API» отвечает со ссылкой на файл, не запуская `grep -r`

**Почему это работает:** инструмент поиска попадает в список доступных агенту функций, и модель выбирает его вместо обхода файловой системы — контекст наполняется только найденными фрагментами.

## Возможные проблемы и решения

**Проблема. Агент не видит инструмент QMD**
- Ошибка: `MCP error -32000: Connection closed`
- Причина: MCP-клиент запускает процесс в окружении без вашего `PATH` (типично для GUI-приложений), поэтому `"command": "qmd"` не находится.
- Решение: укажите абсолютный путь из `which qmd` в поле `command` и перезапустите агент. Проверка — `/mcp` показывает `connected`.

**Проблема. Поиск возвращает пустую выдачу**
- Ошибка: `qmd status` печатает `documents: 0` для коллекции, агент отвечает «No results found».
- Причина: коллекция зарегистрирована по неверному пути (запуск не из корня репозитория) либо индекс не пересобран после добавления файлов.
- Решение: `qmd collection list`, затем удалить и добавить коллекцию с корректным путём, после чего `qmd index`. Проверка — `qmd search "..." --limit 5` отдаёт непустой результат.

**Проблема. Ошибка авторизации при построении индекса**
- Ошибка: `Error: 401 Unauthorized`
- Причина: в конфигурации выбран провайдер эмбеддингов, а переменная окружения с ключом не задана в оболочке, из которой запускается `qmd index`.
- Решение: экспортируйте ключ (`export <ПЕРЕМЕННАЯ>=...` — имя переменной сверьте с документацией), пересоберите индекс `qmd index`. Проверка — команда завершается без ошибок и `qmd status` показывает ненулевое число документов.

## Резюме и следующие шаги

Вы развернули локальный индекс QMD, подключили его к агенту через MCP и получили воспроизводимый замер расхода контекста до и после. Дальше имеет смысл автоматизировать пересборку индекса и отдельно ограничить бюджеты API-вызовов агента.

## FAQ

**Что такое QMD простыми словами?**
Локальный поисковый движок по markdown и коду, который по запросу возвращает несколько релевантных фрагментов с путями и номерами строк вместо целых файлов.

**Экономит ли QMD токены, если агент всё равно открывает файл?**
Да, потому что агент открывает один файл по точному пути, а не перебирает `grep -r` и не читает десятки кандидатов целиком; разницу покажет замер из Шага 3.

**Нужен ли API-ключ для работы QMD?**
Зависит от конфигурации: локальные модели эмбеддингов ключа не требуют, облачные — требуют. Поддерживаемые провайдеры и имена переменных сверьте с документацией.

**Безопасно ли индексировать рабочий репозиторий?**
Индекс хранится локально, но всё, что в него попало, может уйти в контекст агента. Не регистрируйте каталоги с `.env`, ключами и приватными данными — общие правила в [Безопасность ИИ-агентов: как защитить данные и избежать утечек](https://ai-release.org/guides/bezopasnost-ii-agentov-kak-zaschitit-dannye-i-izbezhat.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).
