holon-run/qmd-mcp-skill

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