qmd-mcp

# 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