qmd-mcp-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

使用此技能，通过固定的MCP标准IO链接，借助

uxc

查询本地QMD索引。

复用

uxc

技能实现通用协议发现、JSON信封解析和守护进程生命周期基础功能。

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.

```
uxc
```
已安装且可在
```
PATH
```
中访问。
```
qmd
```
已安装且可在运行时
```
PATH
```
中访问，或可通过shell包装器启动。
QMD索引已存在且状态正常：
- ```
qmd status
```
- ```
qmd update
```
- ```
qmd embed
```
对于GPU支持的配置，
```
qmd mcp
```
使用的shell已导出所有必要的运行时环境，如
```
CUDA_PATH
```
、
```
CUDACXX
```
、
```
LD_LIBRARY_PATH
```
，或Node/nvm初始化环境。

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

首先验证本地QMD索引：
- ```
qmd status
```
- 在链接MCP之前，确认集合、向量数量和设备状态合理。

默认使用固定链接命令：

```
command -v qmd-mcp-cli
```
如果该命令不存在且
```
qmd
```
在当前shell中可正常运行：
- ```
uxc link --daemon-idle-ttl 0 qmd-mcp-cli "qmd mcp"
```

如果

qmd

依赖

nvm

、CUDA环境或其他shell配置，请显式包装命令：

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
```
如果检测到命令冲突且无法安全复用，请停止操作并联系技能维护人员选择其他固定命令名称。

确认基于守护进程的标准IO路径处于活跃状态：
- ```
uxc daemon status
```
- ```
uxc daemon sessions
```

执行前检查操作模式：

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

优先选择类型化检索而非CLI风格的自动扩展：
- 从使用显式
```
lex
```
  /
```
vec
```
  /
```
hyde
```
  搜索的
```
query
```
  开始
- 仅在缩小候选范围后使用
```
get
```
  或
```
multi_get
```

Recommended Usage Pattern

Capability Map

能力映射

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

搜索：
- ```
query
```
检索：
- ```
get
```
- ```
multi_get
```
健康检查：
- ```
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.

自动化操作基于JSON输出信封；不要依赖
```
--text
```
参数。
优先解析稳定字段：
```
ok
```
、
```
kind
```
、
```
protocol
```
、
```
data
```
、
```
error
```
。
使用
```
qmd-mcp-cli
```
作为默认命令路径。

当

qmd

在当前shell中可正常运行时，

qmd-mcp-cli <operation> ...

等效于

uxc "qmd mcp" <operation> ...

。

如果
```
qmd
```
需要shell初始化或GPU环境变量导出，请在链接命令和任何直接
```
uxc "<host>" ...
```
回退命令中使用相同的包装shell命令。
当延迟很重要时，优先使用显式类型化
```
query
```
负载，而非独立QMD CLI混合模式。
将
```
lex
```
作为默认快速路径：
- 精确名称
- 带引号的短语
- 否定词
当问题具有语义但仍有边界时，添加
```
vec
```
搜索。
仅针对细微或稀疏主题添加
```
hyde
```
搜索；这是成本最高的查询类型。
使用
```
intent
```
消除模糊搜索词的歧义，而非过度扩展查询文本本身。
交互式使用时，保持
```
limit
```
和
```
candidateLimit
```
适中。
对于QMD，推荐使用
```
--daemon-idle-ttl 0
```
，因为第一个重型请求可能会预热模型和会话；长期复用可大幅降低重复调用的延迟。

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.

第一个MCP请求可能仍然较慢，因为
```
uxc
```
守护进程正在创建标准IO会话，且QMD正在预热模型状态。
一旦会话预热完成，通过同一
```
uxc
```
守护进程会话的重复调用延迟会显著降低。
此技能最适用于已由QMD索引的本地知识库、笔记和Markdown语料库。
如果需要最高质量但最慢的检索路径，仍可通过包含更丰富
```
searches
```
数组的
```
query
```
来实现，而非调用独立QMD CLI混合模式。

References

参考资料

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

调用模式：
- ```
references/usage-patterns.md
```

qmd-mcp-skill

Original

Translation

QMD MCP Skill

QMD MCP Skill

Prerequisites

前提条件

Core Workflow

核心工作流程

Recommended Usage Pattern

推荐使用模式

Capability Map

能力映射

Guardrails

防护规则

Notes

注意事项

References

参考资料