---
name: qmd-mcp-skill
description: Use a local QMD knowledge base through UXC over MCP stdio, with daemon-backed session reuse and typed retrieval flows that avoid repeated model warmup and unnecessary query-expansion latency.
metadata:
  short-description: Query local QMD indexes via UXC MCP stdio
---

# QMD MCP Skill

Use this skill to query a local QMD index through `uxc` using a fixed MCP stdio link.

Reuse the `uxc` skill for generic protocol discovery, JSON envelope parsing, and daemon lifecycle basics.

## Prerequisites

- `uxc` is installed and available in `PATH`.
- `qmd` is installed and available in the runtime `PATH`, or can be launched through a shell wrapper.
- A QMD index already exists and is healthy:
  - `qmd status`
  - `qmd update`
  - `qmd embed`
- For GPU-backed setups, the shell used by `qmd mcp` already exports any required runtime environment such as `CUDA_PATH`, `CUDACXX`, `LD_LIBRARY_PATH`, or Node/nvm initialization.

## Core Workflow

1. Verify the local QMD index first:
   - `qmd status`
   - Confirm collections, vector count, and device look reasonable before linking MCP.
2. Use a fixed link command by default:
   - `command -v qmd-mcp-cli`
   - If missing and `qmd` already works in the current shell:
     - `uxc link --daemon-idle-ttl 0 qmd-mcp-cli "qmd mcp"`
   - If `qmd` depends on `nvm`, CUDA env, or other shell setup, wrap it explicitly:
     - `uxc link --daemon-idle-ttl 0 qmd-mcp-cli "/bin/bash -lc 'export NVM_DIR=$HOME/.nvm; . $NVM_DIR/nvm.sh; nvm use 23 >/dev/null; export CUDA_PATH=/usr/local/cuda-11.6; export CUDA_HOME=/usr/local/cuda-11.6; export CUDACXX=/usr/local/cuda-11.6/bin/nvcc; export LD_LIBRARY_PATH=/usr/local/cuda-11.6/lib64:${LD_LIBRARY_PATH:-}; export NODE_LLAMA_CPP_CMAKE_OPTION_CMAKE_CUDA_ARCHITECTURES=86; export NODE_LLAMA_CPP_GPU=cuda; qmd mcp'"`
   - `qmd-mcp-cli -h`
   - If command conflict is detected and cannot be safely reused, stop and ask skill maintainers to pick another fixed command name.
3. Confirm the daemon-backed stdio path is active:
   - `uxc daemon status`
   - `uxc daemon sessions`
4. Inspect operation schema before execution:
   - `qmd-mcp-cli query -h`
   - `qmd-mcp-cli get -h`
   - `qmd-mcp-cli multi_get -h`
   - `qmd-mcp-cli status -h`
5. Prefer typed retrieval over CLI-style auto expansion:
   - Start with `query` using explicit `lex` / `vec` / `hyde` searches
   - Use `get` or `multi_get` only after narrowing candidates

## Recommended Usage Pattern

1. Health check the index:
   - `qmd-mcp-cli status`
2. Start with a fast explicit search payload:
   - `qmd-mcp-cli query '{"searches":[{"type":"lex","query":"\"execution layer\" MCP CLI"},{"type":"vec","query":"What is the missing execution surface between MCP and CLI?"}],"collections":["workspace"],"limit":5,"intent":"Find the article explaining capability description, execution surface, and workflow orchestration"}'`
3. Retrieve the chosen file:
   - `qmd-mcp-cli get file=workspace/public/mcp-is-not-the-problem/readme.md`
4. Use `multi_get` for a short candidate set only:
   - `qmd-mcp-cli multi_get pattern='workspace/public/*.md,workspace/research/*.md' maxBytes=20480`

## Capability Map

- Search:
  - `query`
- Retrieval:
  - `get`
  - `multi_get`
- Health:
  - `status`

## Guardrails

- Keep automation on JSON output envelope; do not rely on `--text`.
- Parse stable fields first: `ok`, `kind`, `protocol`, `data`, `error`.
- Use `qmd-mcp-cli` as the default command path.
- `qmd-mcp-cli <operation> ...` is equivalent to `uxc "qmd mcp" <operation> ...` when `qmd` already runs correctly in the current shell.
- If `qmd` requires shell initialization or GPU env exports, use the same wrapped shell command in the link and any direct `uxc "<host>" ...` fallback.
- Prefer explicit typed `query` payloads over the standalone QMD CLI hybrid mode when latency matters.
- Treat `lex` as the default fast path:
  - exact names
  - quoted phrases
  - negation
- Add `vec` when the question is semantic but still bounded.
- Add `hyde` only for nuanced or sparse topics; it is the most expensive query type.
- Use `intent` to disambiguate ambiguous search terms instead of over-expanding the query text itself.
- Keep `limit` and `candidateLimit` modest for interactive use.
- `--daemon-idle-ttl 0` is recommended for QMD because the first heavy request may warm models and sessions; long-lived reuse makes repeated calls much faster.

## Notes

- The first MCP request can still be slow while the `uxc` daemon creates the stdio session and QMD warms model state.
- Repeated calls through the same `uxc` daemon session can drop sharply in latency once the session is warm.
- This skill is best for local knowledge bases, notes, and markdown corpora already indexed by QMD.
- If you need the highest-quality but slowest retrieval path, you can still express it through `query` with richer `searches` arrays instead of shelling out to the standalone QMD CLI hybrid mode.

## References

- Invocation patterns:
  - `references/usage-patterns.md`