QMD MCP

QMD MCP упаковывает QMD в виде долго работающего Streamable HTTP MCP-сервера. Он предоставляет поиск QMD и получение документов, а также ограниченные операции обслуживания индекса, не открывая доступа к произвольному выполнению команд оболочки.

Это поддерживаемая сообществом интеграция. Она не связана с вышестоящим проектом QMD, не одобрена им и не поддерживается им официально.

Обратная связь и вклад

Используйте GitHub Issues для сообщений об ошибках и запросов новых функций, а pull requests — для предлагаемых изменений. Описание рабочего процесса разработки, требований к тестам и соглашений о кодировании см. в CONTRIBUTING.md. Проблемы безопасности должны обрабатываться через приватный процесс, описанный в SECURITY.md.

Изменения в релизах фиксируются в CHANGELOG.md.

Related MCP server: Keenable MCP

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

Публичный Docker-образ публикуется в GitHub Container Registry (GHCR):

ghcr.io/x1pher/qmd-mcp:v0.1.3

Пакет является публичным, поэтому Docker не требует входа в GitHub для его загрузки.

Для производственных развертываний используйте неизменяемый digest, опубликованный в соответствующем GitHub Release, а не полагайтесь только на тег версии.

Образ в настоящее время поддерживает linux/amd64. Он намеренно содержит только нативный рантайм llama QMD linux-x64, чтобы размер образа оставался ограниченным.

1. Создайте каталоги

mkdir -p qmd/config qmd/content
cd qmd

Поместите файлы Markdown, которые вы хотите индексировать с помощью QMD, в content/.

2. Создайте config/index.yml

global_context: >-
  This is a local Markdown knowledge base. Search results are discovery evidence;
  read the source document before relying on a material claim.

collections:
  notes:
    path: /vault
    pattern: "**/*.md"
    ignore:
      - "archive/**"

  archive:
    path: /vault/archive
    pattern: "**/*.md"
    includeByDefault: false

  append-only-log:
    path: /vault/logs
    pattern: "history.md"
    includeByDefault: false
    embedding: false

Значения path указывают на пути внутри контейнера. Пример Compose ниже монтирует ./content в /vault.

embedding: false — это расширение обёртки QMD MCP для коллекций, которые должны оставаться только лексическими. Файлы по-прежнему индексируются и доступны для явного лексического поиска (lex), но исключаются из проверки состояния эмбеддингов, запланированного создания эмбеддингов и ручных заданий start_embed. Используйте это для больших журналов с добавлением только в конец или других материалов, требующих точного поиска, где повторное построение векторов добавляет затраты, не давая полезного семантического поиска.

3. Создайте compose.yml

services:
  qmd-mcp:
    image: ghcr.io/x1pher/qmd-mcp:v0.1.3
    container_name: qmd-mcp
    environment:
      QMD_FORCE_CPU: "1"
      QMD_REFRESH_INTERVAL_MINUTES: "15"
      QMD_REFRESH_INITIAL_DELAY_SECONDS: "120"
    ports:
      - "127.0.0.1:8181:8181"
    volumes:
      - ./content:/vault:ro
      - ./config:/config:ro
      - qmd-data:/data
    healthcheck:
      test:
        - CMD
        - node
        - -e
        - >-
          fetch('http://127.0.0.1:8181/health')
          .then(r=>process.exit(r.ok?0:1))
          .catch(()=>process.exit(1))
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s
    restart: unless-stopped

volumes:
  qmd-data:

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

QMD_FORCE_CPU=1 обеспечивает предсказуемое развертывание только на CPU. Удалите его или установите в 0, если вы намеренно хотите, чтобы QMD проверял наличие поддерживаемого ускорения.

4. Запустите контейнер

docker compose up -d

Проверьте службу:

curl --fail http://127.0.0.1:8181/health

Конечная точка Streamable HTTP MCP:

http://127.0.0.1:8181/mcp

Альтернатива с Docker CLI

Вы можете запустить тот же релиз без Compose:

docker volume create qmd-data

docker run -d \
  --name qmd-mcp \
  --restart unless-stopped \
  -p 127.0.0.1:8181:8181 \
  -e QMD_FORCE_CPU=1 \
  -e QMD_REFRESH_INTERVAL_MINUTES=15 \
  -e QMD_REFRESH_INITIAL_DELAY_SECONDS=120 \
  -v "$PWD/content:/vault:ro" \
  -v "$PWD/config:/config:ro" \
  -v qmd-data:/data \
  ghcr.io/x1pher/qmd-mcp:v0.1.3

Что предоставляет QMD MCP

QMD MCP сохраняет ориентированные на чтение MCP-инструменты QMD и добавляет ограниченные административные операции:

• health сообщает состояние индекса и рантайма;

• start_update запускает ограниченное асинхронное задание переиндексации файловой системы;

• start_embed запускает ограниченное асинхронное задание создания эмбеддингов;

• job_status сообщает о недавних административных заданиях;

• запланированное обновление и создание эмбеддингов могут выполняться автоматически, пока коллекции с embedding: false остаются только лексическими;

• обычный query выполняется с отключённым реранжированием;

• query_reranked предоставляет отдельный ресурсоёмкий по CPU путь с реранжированием;

• результаты запросов могут включать точный source_relative_path для точной передачи в файловую систему, когда настроен QMD_SOURCE_RELATIVE_ROOT и путь к источнику разрешается однозначно;

• получение документов по умолчанию возвращает внутренний текст с явным opt-in предоставлением ресурсов MCP.

Одновременно выполняется только одно административное задание. Завершённые задания сохраняются в памяти с ограниченной историей. Полное описание девяти инструментов, включая уровень доступа и побочные эффекты, см. в docs/tools.md.

Пути рантайма

Контейнер использует следующие стабильные пути:

Исходные коллекции обычно следует монтировать в режиме только для чтения. /data должен оставаться доступным для записи, поскольку он содержит перестраиваемый индекс и кэш моделей/рантайма.

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

Dockerfile предоставляет рабочие значения по умолчанию для обычных путей рантайма и HTTP-слушателя. Переопределяйте только те настройки, которые нужны вашему развертыванию.

Недопустимые значения для ограниченных числовых параметров приводят к ошибке при запуске, а не принимаются молча. QMD_SOURCE_RELATIVE_ROOT никогда не раскрывает свой абсолютный путь; возвращается только относительный путь источника, а неоднозначные коллизии нормализованных путей возвращают null вместо предположений.

Модель безопасности

• Контейнер работает от имени непривилеги