Qmd Wrapper

QMD包装

  

英语 | 简体中文

基于Rust的命令行包装器 QMD（查询标记文档） MCP服务器，支持通过HTTP远程访问QMD搜索功能。

特性

• 🔌 远程MCP访问 -使用完整的CLI奇偶校验通过HTTP连接到QMD服务器
• 📦 静态链接 -零运行时依赖关系的单个二进制文件（musl）
• 💾 会话保持 -跨CLI调用的自动会话管理
• 🚀 快速轻便 -~3.6MB二进制文件，LTO优化
• 🔒 缺省巩固安全 -rustls TLS后端，无OpenSSL依赖
• 🎯 交互式设置 -通过健康检查指导配置

快速开始

1.下载

# From releases page
wget https://github.com/tidyinfo/qmd-wrapper/releases/latest/download/qmd

# Make executable
chmod +x qmd

2.配置

# Connect to remote QMD server
./qmd connect --hostname  --port 

# Example
./qmd connect --hostname 192.168.1.100 --port 8181

3.使用

# Search documents
./qmd search "your query" --json

# Get status
./qmd status

# Retrieve document
./qmd get path/to/file.md

安装

来自预构建二进制文件

1. 从下载最新版本 发布
2. 放置在您的路径中： sudo cp qmd /usr/local/bin/

来源

先决条件：

• 锈1.92或更高版本
• musl工具（用于静态链接）

# Clone repository
git clone https://github.com/tidyinfo/qmd-wrapper.git
cd qmd-wrapper

# Install Rust (if needed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable

# Add musl target
rustup target add x86_64-unknown-linux-musl

# Install musl tools (Debian/Ubuntu)
sudo apt-get install musl-tools musl-dev

# Build static binary
cargo build --release --target x86_64-unknown-linux-musl

# Binary location
ls -lh target/x86_64-unknown-linux-musl/release/qmd

配置

服务器连接

# Non-interactive mode
./qmd connect --hostname example.com --port 8181

# Interactive mode (with prompts)
./qmd connect

配置文件位置

包装器按以下顺序搜索配置：

1. ./qmd.toml （与二进制目录相同）
2. ./config.toml （与二进制目录相同）
3. /etc/qmd/config.toml
4. ~/.config/qmd/config.toml
5. ~/.qmd.toml

配置格式

[server]
host = "localhost"
port = 8181
session_id = "auto-generated-after-first-connect"

命令

搜索命令

# Keyword search (BM25)
./qmd search "query" [options]

# Query expansion + reranking (if supported)
./qmd query "query" [options]

# Vector similarity search (if supported)
./qmd vsearch "query" [options]

搜索选项：

文献检索

# Get single document
./qmd get [:line] [-l N] [--from N]

# Get multiple documents by glob pattern
./qmd multi-get 
 [-l N] [--max-bytes N]

# List collections or files
./qmd ls [collection[/path]]

索引管理

# Show index status
./qmd status

# Re-index all collections
./qmd update [--pull]

# Create vector embeddings
./qmd embed [-f]

# Cleanup cache and orphaned data
./qmd cleanup

收集管理

# List collections
./qmd collection list

# Add collection
./qmd collection add [path] --name  --mask 

# Remove collection
./qmd collection remove 

# Rename collection
./qmd collection rename 
 

上下文管理

# List contexts
./qmd context list

# Add context
./qmd context add [path] "text"

# Remove context
./qmd context rm 

例子

基本搜索工作流程

# 1. Connect to server
./qmd connect --hostname qmd.example.com --port 8181

# 2. Check index status
./qmd status

# 3. Search for documents
./qmd search "machine learning" --json -n 10

# 4. Get full document
./qmd get docs/ml-basics.md --full

# 5. Search with filters
./qmd search "neural networks" --min-score 0.7 --collection research

高级用法

# Export results as CSV
./qmd search "API design" --csv > results.csv

# Get document from specific line
./qmd get src/main.rs:100 -l 50

# Batch retrieve files
./qmd multi-get "docs/*.md" --max-bytes 50000

# Full-text search with line numbers
./qmd search "configuration" --full --line-numbers

建筑

┌─────────────────┐     HTTP POST      ┌─────────────────────┐
│   qmd wrapper   │ ─────────────────> │  QMD MCP Server     │
│   (Rust CLI)    │    JSON-RPC        │  (Node.js + Bun)    │
│                 │ <───────────────── │  http://host:port   │
│  - CLI parsing  │    MCP Response    │                     │
│  - Session mgmt │                    │  - Tool registry    │
│  - Config mgmt  │                    │  - Search engine    │
│                 │                    │  - Vector DB        │
└─────────────────┘                    └─────────────────────┘

会话管理

MCP HTTP传输需要会话初始化：

1. 第一个命令：自动呼叫 initialize 端点
2. 会话ID：摘自 Mcp-Session-Id 响应头
3. 坚持：保存到配置文件以供重用
4. 后续命令：重用缓存的会话ID
5. 服务器重新启动：会话不匹配时自动重新初始化

故障排除

连接问题

# Test server health
curl http://host:port/health

# Expected response
{"status":"ok","uptime":N}

会话问题

# Reset session (edit config file)
# Remove the session_id line from qmd.toml

常见错误

发展

项目结构

qmd-wrapper/
├── Cargo.toml           # Dependencies
├── src/
│   ├── main.rs          # Entry point
│   ├── cli.rs           # CLI definitions
│   ├── config.rs        # Configuration
│   └── mcp_client.rs    # MCP client
├── dist/                # Built binaries
└── README.md            # This file

构建命令

# Debug build
cargo build

# Release build (dynamic)
cargo build --release

# Static build (musl)
cargo build --release --target x86_64-unknown-linux-musl

# Run tests
cargo test

# Format code
cargo fmt

# Lint
cargo clippy

依赖项

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

致谢

• QMD -最初的QMD项目
• 模型上下文协议 -MCP规范
• 拍手 -优秀的CLI库

______________________________________________________________________

简体中文

QMD Wrapper 是一个基于 Rust 的命令行工具，用于远程访问 QMD（查询标记文档） MCP 服务器。

主要特性

• 🔌 远程 MCP 访问 - 通过 HTTP 连接 QMD 服务器，支持完整 CLI 功能
• 📦 静态链接 - 单一二进制文件，零运行时依赖
• 💾 会话持久化 - 自动管理会话状态
• 🚀 快速轻量 - 约 3.6MB，LTO 优化
• 🔒 安全默认 - rustls TLS，无需 OpenSSL
• 🎯 交互配置 - 引导式配置和健康检查

快速开始

# 1. 下载
wget https://github.com/tidyinfo/qmd-wrapper/releases/latest/download/qmd
chmod +x qmd

# 2. 配置
./qmd connect --hostname 192.168.1.100 --port 8181

# 3. 使用
./qmd search "查询内容" --json

完整文档

详细使用说明请参考上方的英文文档部分。

常见问题

Q: 如何重置会话？\ A: 编辑 qmd.toml 文件，删除 session_id 行。

Q: 支持哪些搜索选项？\ A: 支持 -n, --json, --csv, --full, --min-score 等，详见上方 Commands 部分。

Q: 如何构建静态二进制？\ A: 使用命令 cargo build --release --target x86_64-unknown-linux-musl。

技术支持

如有问题，请提交 。