QMD MCP Usage Patterns

This skill defaults to fixed link command qmd-mcp-cli.

Create it when missing:

command -v qmd-mcp-cli
uxc link --daemon-idle-ttl 0 qmd-mcp-cli "qmd mcp"

If qmd depends on shell setup, wrap the command 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'"

Inspect the linked tools first:

qmd-mcp-cli -h
qmd-mcp-cli query -h
qmd-mcp-cli get -h
qmd-mcp-cli multi_get -h
qmd-mcp-cli status -h

Fast Interactive Search

Prefer a typed lex query first:

qmd-mcp-cli query '{"searches":[{"type":"lex","query":"\"execution layer\" MCP CLI -migration"}],"collections":["workspace"],"limit":5,"intent":"Find the article about the missing execution surface for agents"}'

Add vec when the query is more semantic:

qmd-mcp-cli query '{"searches":[{"type":"lex","query":"\"Bitcoin L2\" DA rollup"},{"type":"vec","query":"How should Bitcoin layer 2 relate to DA and rollup architecture?"}],"collections":["workspace"],"limit":5,"intent":"Find articles discussing Bitcoin L2, DA, and rollup design"}'

Use hyde only when recall is still weak:

qmd-mcp-cli query '{"searches":[{"type":"lex","query":"\"connection pool\" timeout -redis"},{"type":"vec","query":"Why do database connections time out under load?"},{"type":"hyde","query":"Connection pool exhaustion occurs when all connections are busy and requests must wait. Under high concurrency, long-running queries can cause timeout cascades."}],"limit":5}'

Retrieve Documents After Search

Fetch one chosen document:

qmd-mcp-cli get file=workspace/public/how-to-define-bitcoin-l2/readme.md

Fetch multiple known candidates:

qmd-mcp-cli multi_get '{"pattern":"workspace/public/how-to-define-bitcoin-l2/readme.md,workspace/public/how-bitcoin-layer2-should-work/readme.md","maxBytes":32768}'

Session Reuse Checks

Check that uxc is reusing the stdio session:

uxc daemon status
uxc daemon sessions

Recommended signs:

• mcp_stdio_sessions is non-zero
• mcp_reuse_hits increases after repeated calls
• the qmd-mcp-cli session appears as ready

Fallback Equivalence

• qmd-mcp-cli <operation> ... is equivalent to uxc "qmd mcp" <operation> ... when qmd already runs correctly in the current shell.
• If shell initialization or GPU env exports are required, use the same wrapped shell command directly with uxc "<wrapped-host>" ... as fallback.

Limitations

• The first daemon-backed call can still be slow because QMD may warm model state on first real request.
• lex is usually the best default for low latency.
• vec and especially hyde raise latency and should be added intentionally.
• This skill assumes the QMD index already exists and is healthy; it does not replace qmd update or qmd embed.