QMD MCP

QMD MCP

QMD MCP packages QMD as a long-running Streamable HTTP MCP server. It provides QMD search and document retrieval together with bounded index-maintenance operations, without exposing arbitrary shell execution.

This is a community-maintained integration. It is not affiliated with, endorsed by, or officially maintained by the upstream QMD project.

Feedback and contributions

Use GitHub Issues for bug reports and feature requests and pull requests for proposed changes. See CONTRIBUTING.md for the development workflow, test requirements, and coding conventions. Security issues must follow the private process in SECURITY.md.

Release changes are recorded in CHANGELOG.md.

Quick start

Release images are published on GitHub Container Registry (GHCR):

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

Published packages are public, so Docker does not need a GitHub login to pull an accepted release.

For production deployments, select the stable version tag from an accepted GitHub Release. Retain its resolved digest as immutable provenance and rollback evidence.

The image supports linux/amd64 and linux/arm64. Each platform image retains only its matching QMD native llama runtime to keep the image bounded.

1. Create the directories

mkdir -p qmd/config qmd/content
cd qmd

Put the Markdown files you want QMD to index in content/.

2. Create 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:
  docs:
    path: /vault
    pattern: "**/*.md"
    ignore:
      - "notes/**"

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

  history:
    path: /vault/logs
    pattern: "history.md"
    includeByDefault: false
    embedding: false

path values refer to paths inside the container. The Compose example below mounts ./content at /vault.

embedding: false is a QMD MCP wrapper extension for collections that should remain lexical-only. The files are still indexed and available to explicit lexical (lex) searches, but they are excluded from embedding health and manual start_embed jobs. Use it for large append-only logs or other exact-lookup material where repeatedly rebuilding vectors adds cost without useful semantic recall.

3. Create compose.yml

services:
  qmd-mcp:
    image: ghcr.io/x1pher/qmd-mcp:v0.2.2
    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:

The example binds the HTTP port to loopback only. If another container must call QMD MCP directly, attach both containers to a shared Docker network and use the QMD service name instead of exposing it broadly on the host.

QMD_FORCE_CPU=1 gives a predictable CPU-only deployment. Remove it or set it to 0 if you deliberately want QMD to probe for supported acceleration.

4. Start the container

docker compose up -d

Check the service:

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

The Streamable HTTP MCP endpoint is:

http://127.0.0.1:8181/mcp

Docker CLI alternative

You can run the same release without 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.2.2

What QMD MCP provides

QMD MCP keeps QMD's read-oriented MCP tools and adds bounded administration operations:

• health reports index and runtime state;
• start_update starts a bounded asynchronous filesystem reindex job;
• start_embed starts a bounded asynchronous embedding job;
• job_status reports recent administration jobs;
• scheduled refresh updates the lexical/index state only; embeddings run explicitly through start_embed, while embedding: false collections remain lexical-only;
• routine query runs with reranking disabled;
• query_reranked provides a separate CPU-heavy reranked path;
• query results can include an exact source_relative_path for authoritative filesystem handoff when QMD_SOURCE_RELATIVE_ROOT is configured and the source path resolves unambiguously;
• document retrieval returns internal text by default; user-visible MCP resource exposure requires both exposeToUser=true and confirmUserApprovedExposure=true, and preview/show/open/render/inspect intent is not approval.

Only one administration job runs at a time. Completed jobs are retained in memory with a bounded history. See docs/tools.md for the complete nine-tool reference, including access level and side effects.

Runtime paths

The container uses these stable paths:

Source collections should normally be mounted read-only. /data must remain writable because it contains the rebuildable index and model/runtime cache.

Configuration

The Dockerfile provides working defaults for the normal runtime paths and HTTP listener. Override only the settings your deployment needs.

Invalid bounded numeric values fail at startup instead of being silently accepted. QMD_SOURCE_RELATIVE_ROOT never exposes its absolute path; only a relative source path is returned, and ambiguous normalized-path collisions return null rather than guessing.

Automatic embedding

Automatic embedding is disabled by default. Set a positive QMD_EMBED_INTERVAL_MINUTES to enable periodic checks after QMD_EMBED_INITIAL_DELAY_SECONDS.

Each check selects pending work using the effective collection embedding policy. Missing embedding means enabled; default search selection and QMD_DEFAULT_COLLECTION do not limit the scheduler. One scheduled_embed job processes eligible collections sequentially under the same maintenance claim as manual jobs and refresh. Across admitted checks, the first eligible collection rotates in process memory so one collection cannot consume every shared deadline indefinitely. Busy or active-query checks skip without queuing work. Policy and pending work are rechecked before each collection.

Scheduled embedding is resumable across cooperative deadlines. Successfully embedded chunks of an unfinished document are retained as internal checkpoints for the exact model/fingerprint, remain pending until the full document is complete, and are skipped on the next scheduled attempt. Incomplete checkpoint groups are excluded from vector-search results. Manual embedding keeps the previous atomic cleanup behavior for an interrupted incomplete document. Results preserve per-collection outcomes and current aggregate pending work. Cooperative deadline cancellation is reported as deadline debt rather than a model failure; genuine embedding failures keep their existing error handling. Successful/no-op/skipped checks are quiet; incomplete runs log a compact summary without document content.

MCP health and HTTP /health expose scheduledEmbedding enablement, interval, initial delay, last outcome, next planned check and reused embedding bounds. State is process-local and resets on restart. The next check is a plan, not a promised job start. scheduledRefresh.embeddingAutomatic: false describes refresh only: refresh remains update-only.

The scheduler uses one shared cooperative time budget. Its optional AbortSignal is forwarded through the pinned SDK, embedding session and native loops. After observing abort, no new document preparation, retry or native evaluation starts. Already-started native calls are awaited, including parallel workers. Completed scheduled chunks are checkpointed for later resume instead of being recomputed; an incomplete checkpoint group is not search-visible until all expected chunks exist. Shutdown clears scheduler timers and waits for actual maintenance completion before closing the store. A cooperative deadline cannot hard-limit an in-flight native call's wall-clock duration. Manual embedding retains its per-collection session duration and atomic incomplete-document cleanup; the absent duration default is 3600000 ms.

Use one server writer per index; other replicas or direct CLI writers are outside the process-local claim. Batch bytes are a packing target, not a RAM ceiling. Deployments must supply appropriate CPU/RAM/swap limits and embedding parallelism. Query deferral applies at admission and between collections; queries arriving during a collection keep the existing behavior.

Security model

• The container runs as the upstream Node image's unprivileged node user.
• Source collections should normally be mounted read-only.
• Index and cache state remain separate from source content.
• Administration is limited to the exposed job operations. The wrapper calls the QMD store API directly; it does not invoke QMD CLI update hooks or expose arbitrary shell execution.
• MCP request bodies are capped at 1 MiB before JSON parsing.
• Error messages redact configured index and config paths.
• MCP transport is not an authentication layer. Keep it on a trusted network boundary or place it behind an authenticated MCP gateway.
• Production deployments should select a stable version tag instead of a branch, latest, or another moving tag; retain the resolved digest as artifact evidence.

See SECURITY.md for vulnerability reporting and deployment guidance and docs/SECURE-DEVELOPMENT.md for the secure-design principles, common weakness classes, and review expectations applied to the project.

Upstream relationship

This repository is not a fork of the full QMD source tree. It consumes an exact @tobilu/qmd package version and applies a small fail-closed compatibility patch set during image build. The build fails if an expected upstream patch target no longer matches exactly.

See UPSTREAM.md for the current upstream version, patch inventory, and update process. Automatic embedding acceptance maps the behavioral and image checks.

Validation

The container build is the primary validation boundary. It installs the locked dependency set, applies every upstream patch, runs the complete unit/property test suite, performs JavaScript syntax checks, and prunes development-only dependencies before the runtime stage. CI also starts the image, initializes the MCP protocol, verifies the exact nine-tool surface, runs a real index update against a temporary Markdown collection, and verifies the resulting document count.

Dependency and base-image updates are proposed by Dependabot. A QMD update is accepted only after the image build and functional release acceptance pass against the proposed version.

Releases

Versions use SemVer tags such as v0.2.0. A release must point to an exact CI-green commit. The tag-triggered Release workflow:

1. verifies that the tag matches package.json;
2. builds the linux/amd64 and linux/arm64 images and publishes one multi-architecture tag;
3. publishes it to GHCR;
4. records the immutable image digest;
5. publishes SBOM/provenance and a GitHub attestation;
6. creates the corresponding GitHub Release.

Normal CI does not publish images or releases. Release tags are immutable and are never reused for a different commit.

License

QMD MCP's original wrapper code is MIT licensed. QMD and bundled dependencies retain their own licenses. See LICENSE and UPSTREAM.md.

Storage-aware maintenance admission

All maintenance shares the existing single-job owner and now checks local full I/O and memory PSI avg10 before starting. Defaults defer at 5% and wait five minutes after pressure; this is workload admission, not an alert-threshold change. Read/query service remains available. Scheduled embedding checks again between collections and preserves committed progress. Refresh yields to active queries. A one-minute quiet period separates jobs; partial/failed work backs off per kind for 30, 60 then at most120 minutes, so embedding debt does not starve ordinary refresh forever. Restart uses the existing initial startup delays.

health.storageAdmission exposes the last decision and cooldowns. QMD_IO_PSI_FULL_AVG10_MAX and QMD_MEMORY_PSI_FULL_AVG10_MAX configure bounded integer thresholds. Missing/malformed PSI defers rather than silently accepting work. An optional QMD_STORAGE_THROTTLE_FILE is a deployment-owned read-only atomic JSON cache: schemaVersion:1, ISO8601 observedAt, nonnegative numeric throttledIOs. Any positive throttling defers; a configured missing/stale/malformed cache also defers. Default maximum age is10 minutes (QMD_STORAGE_THROTTLE_MAX_AGE_MS). No cloud credentials, API client, network request or producer is added to QMD; operators own sampling/delivery and must not configure the cache before its producer is accepted. Unconfigured cloud coverage is explicit in health. Normal15-minute refresh and30-minute embedding cadence remains deployment-owned.

QMD_PRESSURE_ROOT may select an operator-owned absolute read-only directory containing io and memory PSI files; default /proc/pressure. Integration tests mount deterministic healthy/degraded fixtures outside /proc, preserving Docker proc-safety confinement. Production uses the real kernel pressure interface.