QMD Wrapper

English | 简体中文

A Rust-based command-line wrapper for the QMD (Query Markup Documents) MCP server, enabling remote access to QMD search functionality via HTTP.

Features

• 🔌 Remote MCP Access - Connect to QMD servers over HTTP with full CLI parity
• 📦 Statically Linked - Single binary with zero runtime dependencies (musl)
• 💾 Session Persistence - Automatic session management across CLI invocations
• 🚀 Fast & Lightweight - ~3.6MB binary with LTO optimization
• 🔒 Secure by Default - rustls TLS backend, no OpenSSL dependencies
• 🎯 Interactive Setup - Guided configuration with health checks

Quick Start

1. Download

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

# Make executable
chmod +x qmd

2. Configure

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

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

3. Use

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

# Get status
./qmd status

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

Installation

From Pre-built Binary

1. Download the latest release from Releases
2. Place in your PATH: sudo cp qmd /usr/local/bin/

From Source

Prerequisites:

• Rust 1.92 or later
• musl-tools (for static linking)

# 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

Configuration

Server Connection

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

# Interactive mode (with prompts)
./qmd connect

Config File Locations

The wrapper searches for configuration in the following order:

1. ./qmd.toml (same directory as binary)
2. ./config.toml (same directory as binary)
3. /etc/qmd/config.toml
4. ~/.config/qmd/config.toml
5. ~/.qmd.toml

Configuration Format

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

Commands

Search Commands

# 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]

Search Options:

Option	Description	Default
-n, --num <NUM>	Number of results	5
--all	Return all matches	false
--min-score <SCORE>	Minimum similarity score	0
--full	Output full document	false
--line-numbers	Add line numbers	false
--files	Output docid,score,filepath,context	false
--json	JSON output	false
--csv	CSV output	false
--md	Markdown output	false
--xml	XML output	false
-c, --collection <NAME>	Filter by collection	-
--index <NAME>	Custom index name	index

Document Retrieval

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

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

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

Index Management

# 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

Collection Management

# List collections
./qmd collection list

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

# Remove collection
./qmd collection remove <name>

# Rename collection
./qmd collection rename <old> <new>

Context Management

# List contexts
./qmd context list

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

# Remove context
./qmd context rm <path>

Examples

Basic Search Workflow

# 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

Advanced Usage

# 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

Architecture

┌─────────────────┐     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        │
└─────────────────┘                    └─────────────────────┘

Session Management

The MCP HTTP transport requires session initialization:

1. First Command: Automatically calls initialize endpoint
2. Session ID: Extracted from Mcp-Session-Id response header
3. Persistence: Saved to config file for reuse
4. Subsequent Commands: Reuse cached session ID
5. Server Restart: Automatically re-initializes on session mismatch

Troubleshooting

Connection Issues

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

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

Session Problems

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

Common Errors

Error	Cause	Solution
Failed to connect	Server offline	Check server status
Server already initialized	Session mismatch	Delete session_id from config
Tool not found	Unsupported tool	Check server capabilities

Development

Project Structure

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

Build Commands

# 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

Dependencies

Crate	Version	Purpose
clap	4.5	CLI parsing
reqwest	0.12	HTTP client
tokio	1	Async runtime
serde	1.0	Serialization
toml	0.8	Config parsing
dialoguer	0.11	Interactive prompts

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Acknowledgments

• QMD - The original QMD project
• Model Context Protocol - MCP specification
• clap - Excellent CLI library

---

简体中文

QMD Wrapper 是一个基于 Rust 的命令行工具，用于远程访问 QMD (Query Markup Documents) 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。

技术支持

如有问题，请提交 GitHub Issue。