QMD MCP

QMD MCP empaqueta QMD como un servidor MCP HTTP Streamable de larga duración. Proporciona búsqueda y recuperación de documentos de QMD junto con operaciones acotadas de mantenimiento del índice, sin exponer ejecución arbitraria de shell.

Esta es una integración mantenida por la comunidad. No está afiliada, respaldada ni mantenida oficialmente por el proyecto QMD original.

Comentarios y contribuciones

Utilice GitHub Issues para informar de errores y solicitar funciones, y pull requests para los cambios propuestos. Consulte CONTRIBUTING.md para conocer el flujo de trabajo de desarrollo, los requisitos de pruebas y las convenciones de codificación. Los problemas de seguridad deben seguir el proceso privado descrito en SECURITY.md.

Los cambios de cada versión se registran en CHANGELOG.md.

Related MCP server: Web Search MCP Remote Server

Inicio rápido

La imagen pública de Docker se publica en GitHub Container Registry (GHCR):

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

El paquete es público, por lo que Docker no necesita iniciar sesión en GitHub para descargarlo.

Para despliegues en producción, utilice el digest inmutable publicado en la correspondiente GitHub Release en lugar de confiar únicamente en la etiqueta de versión.

La imagen admite actualmente linux/amd64. Conserva intencionadamente solo el runtime nativo llama linux-x64 de QMD para mantener acotado el tamaño de la imagen.

1. Cree los directorios

mkdir -p qmd/config qmd/content
cd qmd

Coloque los archivos Markdown que desea que QMD indexe en content/.

2. Cree 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

Los valores de path hacen referencia a rutas dentro del contenedor. El ejemplo de Compose que aparece a continuación monta ./content en /vault.

embedding: false es una extensión del envoltorio de QMD MCP para colecciones que deben permanecer solo léxicas. Los archivos se siguen indexando y están disponibles para búsquedas léxicas explícitas (lex), pero quedan excluidos del estado de salud de embeddings, del embedding programado y de los trabajos manuales de start_embed. Úselo para registros de solo añadidura de gran tamaño u otro material de consulta exacta donde reconstruir vectores repetidamente añade coste sin proporcionar recuperación semántica útil.

3. Cree 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:

El ejemplo vincula el puerto HTTP solo al loopback. Si otro contenedor debe llamar a QMD MCP directamente, conecte ambos contenedores a una red Docker compartida y use el nombre del servicio QMD en lugar de exponerlo ampliamente en el host.

QMD_FORCE_CPU=1 proporciona un despliegue predecible solo con CPU. Elimínelo o establézcalo en 0 si desea deliberadamente que QMD detecte aceleración compatible.

4. Inicie el contenedor

docker compose up -d

Compruebe el servicio:

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

El endpoint MCP HTTP Streamable es:

http://127.0.0.1:8181/mcp

Alternativa con Docker CLI

Puede ejecutar la misma versión sin 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

Qué proporciona QMD MCP

QMD MCP conserva las herramientas MCP orientadas a lectura de QMD y añade operaciones de administración acotadas:

• health informa del estado del índice y del runtime;

• start_update inicia un trabajo asíncrono acotado de reindexación del sistema de archivos;

• start_embed inicia un trabajo asíncrono acotado de embedding;

• job_status informa de los trabajos de administración recientes;

• la actualización y el embedding programados pueden ejecutarse automáticamente mientras las colecciones con embedding: false permanecen solo léxicas;

• la query rutinaria se ejecuta con el reranking deshabilitado;

• query_reranked proporciona una ruta separada de reranking con uso intensivo de CPU;

• los resultados de las consultas pueden incluir un source_relative_path exacto para la entrega autoritativa al sistema de archivos cuando QMD_SOURCE_RELATIVE_ROOT está configurado y la ruta de origen se resuelve sin ambigüedad;

• la recuperación de documentos devuelve el texto interno por defecto, con exposición explícita de recursos MCP mediante opt-in.

Solo se ejecuta un trabajo de administración a la vez. Los trabajos completados se conservan en memoria con un historial acotado. Consulte docs/tools.md para la referencia completa de las nueve herramientas, incluidos los niveles de acceso y los efectos secundarios.

Rutas de runtime

El contenedor utiliza estas rutas estables:

Las colecciones de origen normalmente deben montarse en modo de solo lectura. /data debe permanecer escribible porque contiene el índice reconstruible y la caché de modelos/runtime.

Configuración

El Dockerfile proporciona valores por defecto funcionales para las rutas de runtime normales y el listener HTTP. Sobrescriba únicamente los ajustes que necesite su despliegue.

Los valores numéricos acotados no válidos provocan un fallo al iniciar en lugar de aceptarse silenciosamente. QMD_SOURCE_RELATIVE_ROOT nunca expone su ruta absoluta; solo se devuelve una ruta de origen relativa, y las colisiones de rutas normalizadas ambiguas devuelven null en lugar de hacer suposiciones.

Modelo de seguridad

• El contenedor se ejecuta como el usuario no privilegiado node de la imagen Node oficial.

• Las colecciones de origen normalmente deben montarse en modo de solo lectura.

• El estado del índice y de la caché permanece separado del contenido de origen.

• La administración se limita a las operaciones de trabajo expuestas. El envoltorio llama directamente a la API de almacenamiento de QMD; no invoca los hooks de actualización de la CLI de QMD ni expone ejecución arbitraria de shell.

• Los cuerpos de las solicitudes MCP están limitados a 1 MiB antes del análisis JSON.

• Los mensajes de error redactan las rutas configuradas de índice y configuración.

• El transporte MCP no es una capa de autenticación. Manténgalo en un límite de red de confianza o colóquelo detrás de una pasarela MCP autenticada.

• Los despliegues en producción deben usar un digest de imagen de versión inmutable en lugar de una rama, latest u otra etiqueta móvil.

Consulte SECURITY.md para la notificación de vulnerabilidades y las directrices de despliegue, y docs/SECURE-DEVELOPMENT.md para los principios de diseño seguro, las clases de debilidades comunes y las expectativas de revisión aplicadas al proyecto.

Relación con el proyecto original

Este repositorio no es un fork del árbol de fuentes completo de QMD. Consume una versión exacta del paquete @tobilu/qmd y aplica un pequeño conjunto de parches de compatibilidad de cierre seguro ante fallos durante la construcción de la imagen. La construcción falla si un objetivo de parche esperado del proyecto original ya no coincide exactamente.

Consulte UPSTREAM.md para conocer la versión actual del proyecto original, el inventario de parches y el proceso de actualización.

Validación

La construcción del contenedor es el límite principal de validación. Instala el conjunto de dependencias bloqueado, aplica todos los parches del proyecto original, ejecuta la suite completa de pruebas unitarias/de propiedades, realiza comprobaciones de sintaxis de JavaScript y elimina las dependencias solo de desarrollo antes de la etapa de runtime. CI también inicia la imagen, inicializa el protocolo MCP, verifica la superficie exacta de nueve herramientas, ejecuta una actualización real del índice contra una colección Markdown temporal y verifica el recuento de documentos resultante.

Las actualizaciones de dependencias y de la imagen base las propone Dependabot. Una actualización de QMD solo se acepta después de que la construcción de la imagen y la aceptación funcional de la versión pasen contra la versión propuesta.

Versiones

Las versiones usan etiquetas SemVer como v0.1.3. Una versión debe apuntar a un commit exacto que haya pasado CI. El flujo de trabajo de Release activado por etiqueta:

1. verifica que la etiqueta coincide con package.json;

2. construye la imagen linux/amd64;

3. la publica en GHCR;

4. registra el digest inmutable de la imagen;

5. publica SBOM/provenance y una atestación de GitHub;

6. crea la correspondiente GitHub Release.

El CI normal no publica imágenes ni versiones. Las etiquetas de versión son inmutables y nunca se reutilizan para un commit diferente.

Licencia

El código original del envoltorio de QMD MCP tiene licencia MIT. QMD y las dependencias incluidas conservan sus propias licencias. Consulte LICENSE y UPSTREAM.md.