# QMD MCP

[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/X1pheR/qmd-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/X1pheR/qmd-mcp)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14153/badge)](https://www.bestpractices.dev/projects/14153)
[![M8ven Live Monitored](https://m8ven.ai/badge/mcp/x1pher-qmd-mcp-jfo7qm)](https://m8ven.ai/mcp/x1pher-qmd-mcp-jfo7qm)

QMD MCP packages [QMD](https://github.com/tobi/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`](CONTRIBUTING.md) for the development workflow, test requirements, and coding conventions. Security issues must follow the private process in [`SECURITY.md`](SECURITY.md).

Release changes are recorded in [`CHANGELOG.md`](CHANGELOG.md).

## Quick start

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

```text
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

```bash
mkdir -p qmd/config qmd/content
cd qmd
```

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

### 2. Create `config/index.yml`

```yaml
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`

```yaml
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

```bash
docker compose up -d
```

Check the service:

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

The Streamable HTTP MCP endpoint is:

```text
http://127.0.0.1:8181/mcp
```

### Docker CLI alternative

You can run the same release without Compose:

```bash
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`](docs/tools.md) for the complete nine-tool reference, including access level and side effects.

## Runtime paths

The container uses these stable paths:

| Path | Purpose |
|---|---|
| `/config/index.yml` | QMD collection configuration |
| `/data/index.sqlite` | QMD index database |
| `/data/home` | Runtime home directory |
| `/data/cache` | Model and runtime cache |

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.

| Variable | Default | Purpose |
|---|---:|---|
| `QMD_HTTP_HOST` | `0.0.0.0` | HTTP listen address inside the container |
| `QMD_HTTP_PORT` | `8181` | HTTP listen port |
| `QMD_CONFIG_PATH` | `/config/index.yml` | QMD collection configuration file |
| `INDEX_PATH` | `/data/index.sqlite` | QMD index database |
| `QMD_SOURCE_RELATIVE_ROOT` | unset | Optional common source root. When set, query results include exact, collision-safe `source_relative_path` values relative to this root. |
| `QMD_DEFAULT_COLLECTION` | unset | Default collection for `start_embed`; otherwise the first configured collection is used |
| `QMD_FORCE_CPU` | `0` | Set to `1` to disable acceleration probing and force CPU use |
| `QMD_EMBED_PARALLELISM` | unset | Optional QMD embedding parallelism override |
| `QMD_EMBED_MAX_DOCS_PER_BATCH` | `8` | Default maximum documents per manual or scheduled embedding batch; accepted range `1`-`32` |
| `QMD_EMBED_MAX_BATCH_MB` | `16` | Default maximum manual or scheduled embedding batch size in MiB; accepted range `1`-`128` |
| `QMD_EMBED_MAX_DURATION_MS` | `3600000` | Maximum embedding session length; accepted range `60000`-`7200000` ms |
| `QMD_EMBED_INTERVAL_MINUTES` | `0` | Automatic embedding check interval; `0` disables all embedding timers. Integer `0`-`1440` minutes |
| `QMD_EMBED_INITIAL_DELAY_SECONDS` | `120` | First automatic embedding check delay; integer `0`-`3600` seconds |
| `QMD_REFRESH_INTERVAL_MINUTES` | `15` | Scheduled index-refresh interval; refresh never starts embedding. `0` disables it, maximum `1440` |
| `QMD_REFRESH_INITIAL_DELAY_SECONDS` | `120` | Delay before the first scheduled refresh; accepted range `0`-`3600` |

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`](SECURITY.md) for vulnerability reporting and deployment guidance and [`docs/SECURE-DEVELOPMENT.md`](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`](UPSTREAM.md) for the current upstream version, patch inventory, and update process. [Automatic embedding acceptance](docs/automatic-embedding-acceptance.md) 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`](LICENSE) and [`UPSTREAM.md`](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.