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

Verify the local QMD index first:
- ```
qmd status
```
- Confirm collections, vector count, and device look reasonable before linking MCP.

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"

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.

Confirm the daemon-backed stdio path is active:
- ```
uxc daemon status
```
- ```
uxc daemon sessions
```

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

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

Health check the index:
- ```
qmd-mcp-cli status
```

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"}'

Retrieve the chosen file:

qmd-mcp-cli get file=workspace/public/mcp-is-not-the-problem/readme.md

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

qmd-mcp-skill

NPX Install

Tags

SKILL.md Content