QMD MCP

QMD MCP 将 QMD 封装为长期运行的 Streamable HTTP MCP 服务器。它提供 QMD 搜索和文档检索能力，并附带受限的索引维护操作，而不会暴露任意的 shell 执行。

这是一个社区维护的集成。它与上游 QMD 项目没有关联，未获得其认可，也并非由上游 QMD 项目官方维护。

反馈与贡献

请使用 GitHub Issues 提交错误报告和功能请求，并通过 pull requests 提出建议的更改。有关开发工作流程、测试要求和编码规范，请参阅 CONTRIBUTING.md。安全问题必须遵循 SECURITY.md 中描述的私下流程。

版本变更记录在 CHANGELOG.md 中。

Related MCP server: Web Search MCP Remote Server

快速开始

公共 Docker 镜像发布在 GitHub Container Registry (GHCR) 上：

ghcr.io/x1pher/qmd-mcp:v0.1.3

该软件包是公开的，因此 Docker 无需 GitHub 登录即可拉取。

对于生产环境部署，请使用对应 GitHub Release 中发布的不可变摘要（digest），而不是仅依赖版本标签。

该镜像目前支持 linux/amd64。为了保持镜像体积可控，它有意仅保留 QMD 的 linux-x64 原生 llama 运行时。

1. 创建目录

mkdir -p qmd/config qmd/content
cd qmd

将你要让 QMD 索引的 Markdown 文件放入 content/ 目录中。

2. 创建 config/index.yml

global_context: >-
  This is a local Markdown knowledge base. Search results are discovery evidence;
  read the source document before relying on a material claim.

collections:
  notes:
    path: /vault
    pattern: "**/*.md"
    ignore:
      - "archive/**"

  archive:
    path: /vault/archive
    pattern: "**/*.md"
    includeByDefault: false

  append-only-log:
    path: /vault/logs
    pattern: "history.md"
    includeByDefault: false
    embedding: false

path 值指的是容器内的路径。下面的 Compose 示例将 ./content 挂载到 /vault。

embedding: false 是 QMD MCP 包装器的一个扩展，用于那些应仅进行词法索引的集合。这些文件仍会被索引，并可用于显式的词法（lex）搜索，但它们会被排除在嵌入健康检查、计划嵌入和手动 start_embed 任务之外。对于大体积的 append-only 日志或其他只需精确查找的内容，反复重建向量只会增加成本，却无法提供有用的语义召回效果，因此适合使用此选项。

3. 创建 compose.yml

services:
  qmd-mcp:
    image: ghcr.io/x1pher/qmd-mcp:v0.1.3
    container_name: qmd-mcp
    environment:
      QMD_FORCE_CPU: "1"
      QMD_REFRESH_INTERVAL_MINUTES: "15"
      QMD_REFRESH_INITIAL_DELAY_SECONDS: "120"
    ports:
      - "127.0.0.1:8181:8181"
    volumes:
      - ./content:/vault:ro
      - ./config:/config:ro
      - qmd-data:/data
    healthcheck:
      test:
        - CMD
        - node
        - -e
        - >-
          fetch('http://127.0.0.1:8181/health')
          .then(r=>process.exit(r.ok?0:1))
          .catch(()=>process.exit(1))
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s
    restart: unless-stopped

volumes:
  qmd-data:

该示例仅将 HTTP 端口绑定到 loopback 回环地址。如果其他容器需要直接调用 QMD MCP，请将两个容器附加到同一个 Docker 网络，并使用 QMD 服务名称，而不要在宿主机上广泛暴露该端口。

QMD_FORCE_CPU=1 提供一个符合预期的 CPU-only 部署方式。如果你确实想让 QMD 探测受支持的加速能力，请将该变量移除或将其设置为 0。

4. 启动容器

docker compose up -d

检查服务状态：

curl --fail http://127.0.0.1:8181/health

Streamable HTTP MCP 端点为：

http://127.0.0.1:8181/mcp

Docker CLI 替代方式

你也可以在不使用 Compose 的情况下运行同一个发布版本：

docker volume create qmd-data

docker run -d \
  --name qmd-mcp \
  --restart unless-stopped \
  -p 127.0.0.1:8181:8181 \
  -e QMD_FORCE_CPU=1 \
  -e QMD_REFRESH_INTERVAL_MINUTES=15 \
  -e QMD_REFRESH_INITIAL_DELAY_SECONDS=120 \
  -v "$PWD/content:/vault:ro" \
  -v "$PWD/config:/config:ro" \
  -v qmd-data:/data \
  ghcr.io/x1pher/qmd-mcp:v0.1.3

QMD MCP 提供的功能

QMD MCP 保留 QMD 面向读取的 MCP 工具，并添加了受限的管理操作：

• health 报告索引和运行时状态；

• start_update 启动受限的异步文件系统重建索引任务；

• start_embed 启动受限的异步嵌入任务；

• job_status 报告近期的管理任务；

• 计划刷新和嵌入可以自动运行，而 embedding: false 的集合仍保持纯词法索引；

• 常规 query 在禁用重排序的情况下运行；

• query_reranked 单独提供 CPU 密集的重排序路径；

• 在配置了 QMD_SOURCE_RELATIVE_ROOT 且源路径可以被明确解析时，查询结果可能包含精确的 source_relative_path，用于权威的文件系统交接；

• 文档检索默认返回内部索引文本，并明确支持 MCP 资源的主动启用。

同一时间仅允许运行一个管理任务。已完成的任务会保留在内存中，并且历史记录数量是有限的。完整的九个工具参考资料（包括访问级别和副作用）请参阅 docs/tools.md。

运行时路径

容器使用以下稳定的路径：

源集合通常应以只读方式挂载。/data 必须保持可写，因为它包含可重建的索引以及模型/运行时缓存。

配置

Dockerfile 为正常运行的路径和 HTTP 监听功能提供了默认设置。你只需要更改你的部署实际需要改动的配置即可。

无效的受限数值会在启动时直接失败，而不会被静默接受。QMD_SOURCE_RELATIVE_ROOT 永远不会暴露其绝对路径；它只会返回一个相对的源路径；并且如果规范化路径出现歧义或冲突，则返回 null，而进行猜不会猜测。

安全模型

• 容器以上游 Node 镜像中的非特权 node 用户身份运行。

• 源集合通常应以只读方式挂载。

• 索引和缓存状态与源内容保持独立。

• 管理操作仅限于指定的任务操作上。该包装器直接调用 QMD store API；它不会调用 QMD CLI 更新钩子，也不会暴露任意 shell 执行。

• MCP 请求体在 JSON 解析前将被限制为 1 MiB。

• 错误消息会隐藏已配置的索引和配置路径。

• MCP 传输本身并不可用于身份验证。请将其放在可被信任的网络边界内，或者放在经过认证的 MCP 网关之后。

• 生产部署时应使用发布的版本摘要（digest），而不是分支、latest 或其他会变变更的标签。

有关漏洞报告和部署指导，请参阅 SECURITY.md；有关安全的设计原则、常见弱点类别以及本项目采用的代码审查期望，请参阅 docs/SECURE-DEVELOPMENT.md。

上游关系

这个仓库不是完整 QMD 源代码树的 fork。它在镜像构建期间引用了一个精确的 @tobilu/qmd 包版本，并应用了一组很小范围的 fail-closed 兼容补丁。假如预期版本的补丁目标不再精确匹配，则构建失败。

当前上游版本、补丁清单和更新流程请参见 UPSTREAM.md。

验证

容器构建是主要的验证边界。它会安装锁定的依赖集，应用每个上游补丁，运行完整的单元/属性测试套件，执行 JavaScript 语法检查，并在运行时阶段之前清掉仅开发时依赖。CI 还会启动该镜像、初始化 MCP 协议，验证九个工具列表是否完整，针对临时 Markdown 集合执行真实的索引更新，并验证相应的文档编号。

依赖和基础镜像更新由 Dependabot 提出。只有当镜像构建和功能发布验收在指定的 QMD 版本上通过验证后，该版本才会接受。

发布

版本使用 SemVer 标签，例如 v0.1.3。一个 release 必须指向一个确切的 CI 通过提交。该标签触发的 Release 工作流会：

1. 验证标签与 package.json 匹配；

2. 构建 linux/amd64 镜像；

3. 将镜像发布到 GHCR；

4. 记录不可变的镜像摘要（digest）；

5. 发布 SBOM/证明文件和 GitHub 的 attestation；

6. 创建对应的 GitHub Release。

常规 CI 不会发布镜像或发布版本。Release 标签是固定不变的，不能复用给另一个不同的提交。

许可证

QMD MCP 的原始包装代码采用 MIT 许可证。QMD 及捆绑的相关依赖保留其自身的许可证。请参见 LICENSE 和 UPSTREAM.md 了解更多。