qmd MCP服务器详解：HTTP接口与后台守护进程配置教程

qmd MCP服务器详解：HTTP接口与后台守护进程配置教程

【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd

QMD是一个强大的本地文档搜索引擎，而其MCP（Model Context Protocol）服务器功能让AI助手能够直接访问您的知识库！🚀 通过本文，您将学会如何配置和使用qmd的MCP服务器HTTP接口和后台守护进程，实现AI助手的无缝知识检索。

什么是qmd MCP服务器？

qmd MCP服务器是基于Model Context Protocol标准实现的接口服务，允许AI助手（如Claude、Cursor等）通过标准协议访问您的本地文档库。它提供了两种运行模式：标准输入输出（stdio）模式和HTTP服务器模式，后者支持后台守护进程运行。

核心功能与架构概览

qmd MCP服务器位于src/mcp/server.ts，提供以下核心功能：

• 智能文档搜索：支持lex（关键词）、vec（语义向量）、hyde（假设文档）三种搜索模式
• 文档检索：通过qmd://协议URI访问文档内容
• 批量获取：支持glob模式批量获取文档
• 索引状态查询：查看文档统计和集合信息
• HTTP REST API：提供标准的HTTP接口供外部调用

上图展示了qmd的智能搜索架构，通过查询扩展、并行搜索和结果重排序，实现高效的知识检索。

HTTP服务器配置教程

启动HTTP服务器

qmd提供两种HTTP服务器启动方式：

前台模式（调试用）：

qmd mcp --http --port 8181

后台守护进程模式（生产用）：

qmd mcp --http --daemon --port 8181

端口配置与管理

默认端口为8181，您可以通过--port参数自定义端口：

# 使用自定义端口9000 qmd mcp --http --daemon --port 9000

服务器管理命令

停止守护进程：

qmd mcp stop

查看运行状态：

# 检查PID文件是否存在 ls ~/.cache/qmd/mcp.pid

查看运行日志：

# 日志文件位于缓存目录 cat ~/.cache/qmd/mcp.log

HTTP接口详解

健康检查端点

GET /health

返回服务器状态和运行时间信息。

REST搜索接口

POST /search 或 POST /query

支持JSON格式的搜索请求，参数格式与MCP工具调用一致。

MCP协议端点

POST /mcp

标准的MCP协议端点，支持完整的工具调用和资源访问。

MCP工具功能详解

1. 智能搜索工具（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 in use and new requests must wait..." } ], "limit": 10, "intent": "database performance optimization" }

搜索类型说明：

• lex：BM25关键词搜索，支持短语和排除语法
• vec：语义向量搜索，理解自然语言含义
• hyde：假设文档搜索，生成答案片段进行匹配

2. 文档获取工具（get）

通过文件路径或文档ID获取完整文档内容：

{ "file": "docs/api.md:100", "fromLine": 100, "maxLines": 50, "lineNumbers": true }

3. 批量获取工具（multi_get）

使用glob模式批量获取文档：

{ "pattern": "journals/2025-05*.md", "maxLines": 100, "maxBytes": 10240 }

4. 索引状态工具（status）

查看当前索引状态：

{}

实际应用场景

场景一：AI助手集成

将qmd MCP服务器与AI助手集成，让助手能够搜索您的技术文档、会议记录和个人知识库。配置AI助手连接到http://localhost:8181/mcp即可。

场景二：自动化文档检索

通过HTTP API构建自动化工作流，例如：

• 自动检索相关文档进行代码审查
• 构建智能知识问答系统
• 文档相关性分析和推荐

场景三：团队知识共享

部署qmd MCP服务器到团队服务器，让团队成员通过统一的接口访问共享知识库。

配置最佳实践

1. 性能优化配置

对于大型文档库，建议调整以下参数：

# 增加候选文档数量提高召回率 qmd query --candidate-limit 100 "your query" # 关闭重排序提升CPU性能 qmd query --no-rerank "fast search"

2. 安全配置

HTTP服务器默认只绑定到localhost，确保不会暴露到公网。如需外部访问，请配置适当的防火墙规则。

3. 监控与维护

定期检查：

• 日志文件大小和内容
• 内存使用情况
• 索引更新状态

故障排除指南

常见问题1：端口被占用

# 检查端口占用 lsof -i :8181 # 停止占用进程或更换端口 qmd mcp --http --port 9191

常见问题2：守护进程无法启动

# 检查PID文件 rm ~/.cache/qmd/mcp.pid # 重新启动 qmd mcp --http --daemon

常见问题3：搜索性能问题

• 确保已运行qmd embed生成向量嵌入
• 调整--candidate-limit参数
• 考虑使用--no-rerank选项

进阶配置技巧

自定义集合过滤

在搜索时指定特定集合：

{ "searches": [{"type": "lex", "query": "error handling"}], "collections": ["docs", "meetings"] }

意图上下文传递

通过intent参数提供搜索上下文：

{ "searches": [{"type": "lex", "query": "performance"}], "intent": "web page load times and Core Web Vitals" }

总结

qmd MCP服务器为您的本地知识库提供了强大的AI接口能力。通过HTTP服务器和后台守护进程配置，您可以实现7x24小时的知识检索服务。无论是个人使用还是团队协作，qmd MCP都能显著提升信息查找效率。

记住关键命令：

• qmd mcp --http- 启动HTTP服务器
• qmd mcp --http --daemon- 后台运行
• qmd mcp stop- 停止服务

现在就开始配置您的qmd MCP服务器，让AI助手成为您知识库的智能导航员吧！💡

【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd