qt4-doc-mcp-server

Qt Documentation MCP Server

mcp-name: io.github.jztan/qt4-doc-mcp-server

将本地安装的 Qt 4.8、Qt 5 或 Qt 6 文档接入你的 AI 编码助手。支持离线使用，每次只能选择一套文档。

工具参考 | 更新日志 | 贡献指南 | 故障排除

✨ 功能

• 🔌 离线优先 - 完全使用本地文档
• 🔍 全文搜索 - 在所有 Qt 文档中查找所需内容
• ⚡ 智能缓存 - 加快重复查询的响应速度
• 🎯 片段支持 - 按需提取特定章节
• 🛠️ MCP 标准 - 兼容 Claude、VS Code 和其他 MCP 客户端

📦 前置条件

• 需要 Python 3.11+（使用 Docker 镜像时无需安装）
• 一个受支持版本的 Qt HTML 文档（Qt 4.8、Qt 5 或 Qt 6）
  • 随附的辅助工具仅下载 Qt 4.8.4。
  • 对于 Qt 5/6 离线文档，请将 QT_DOC_BASE 直接指向现有文档根目录。
• 约 500MB 磁盘空间，用于文档、缓存和搜索索引
• 支持 FTS5 的 SQLite（Python 3.11+ 默认包含）

🚀 安装

从 PyPI 安装（推荐）

pip install qt4-doc-mcp-server

从源代码安装

git clone https://github.com/jztan/qt4-doc-mcp-server.git
cd qt4-doc-mcp-server
uv sync --locked

设置 Qt 文档

# Automated setup (recommended, requires the cloned repo)
python scripts/prepare_qt48_docs.py --segments 4

# This will:
# - Download Qt 4.8.4 source archive
# - Extract HTML documentation
# - Create .env with sensible defaults
# - Copy GFDL license file

辅助脚本随代码仓库提供，不包含在 PyPI 软件包中。只从 PyPI 安装？请改为手动下载文档：

curl -LO https://download.qt.io/archive/qt/4.8/4.8.4/qt-everywhere-opensource-src-4.8.4.tar.gz
tar -xzf qt-everywhere-opensource-src-4.8.4.tar.gz qt-everywhere-opensource-src-4.8.4/doc/html
mv qt-everywhere-opensource-src-4.8.4/doc/html ./qt4-docs-html

然后创建一个 .env 文件，将 QT_DOC_BASE 指向该目录（参见下文的配置）。

快速入门命令

# 1. Install
pip install qt4-doc-mcp-server

# 2. Setup Qt docs
python scripts/prepare_qt48_docs.py --segments 4

# 3. Build search index (optional; the server builds it on first start)
qt-doc-build-index

# 4. Start server
qt-doc-mcp

# 5. Verify health
curl -s http://127.0.0.1:8000/health

旧版 qt4-doc-mcp-server 命令仍可用作别名，以兼容现有客户端配置。

便于 Agent 使用的 FTS CLI

构建索引后，Agent 可以搜索并获取物化后的绝对 Markdown 路径：

qt-doc-cli "accessible applications" --limit 5

该命令读取与服务相同的 .env 设置。搜索前，它会自动构建缺失或过期的 FTS 索引，并完整预热不完整的 Markdown 缓存。随后，它会将每条结果的标题、绝对 .md 路径和 FTS 摘要输出到 stdout；准备消息、错误和警告则输出到 stderr。就地修改文档后，请使用 qt-doc-warm-md --force。

🐳 Docker

每次发布时，都会将预构建的多架构镜像（amd64/arm64）发布到 GitHub Container Registry。该容器仅支持离线使用：将准备好的 Qt doc/html 目录以只读方式挂载到 /docs，所有派生数据（Markdown 缓存和搜索索引）都存放在 /data 卷中。

# Prepare Qt docs on the host first (one-time, writes to ./qt4-docs-html)
python scripts/prepare_qt48_docs.py --segments 4

# Run from GHCR
docker run -d --name qt4-doc-mcp-server -p 8000:8000 \
  -v "$PWD/qt4-docs-html:/docs:ro" \
  -v qt4-doc-data:/data \
  ghcr.io/jztan/qt4-doc-mcp-server:latest

# Verify
curl -s http://127.0.0.1:8000/health

只使用已发布的镜像，不克隆此代码仓库？请直接下载 Qt 4.8.4 文档，而不要运行准备脚本：

curl -LO https://download.qt.io/archive/qt/4.8/4.8.4/qt-everywhere-opensource-src-4.8.4.tar.gz
tar -xzf qt-everywhere-opensource-src-4.8.4.tar.gz qt-everywhere-opensource-src-4.8.4/doc/html
mv qt-everywhere-opensource-src-4.8.4/doc/html ./qt4-docs-html

任何现有的 Qt 5 或 Qt 6 doc/html 目录树（来自 Qt 安装程序或发行版文档软件包）也可用作挂载源。

首次启动时会将文档转换并索引到 /data 卷中；之后启动时会复用这些数据。根据文档集的大小，首次启动可能需要一两分钟，健康检查端点才会响应。

Docker Compose

如果文档位于默认的 ./qt4-docs-html 位置，则无需配置：

docker compose up -d

如果文档位于其他位置（包括服务器也支持的 Qt 5 或 Qt 6 doc/html 目录树），请将 QT_DOC_HTML_PATH 指向文档所在位置。如果主机上的 8000 端口已被占用，请在同一个文件中设置 HOST_PORT（使用普通的 docker run 时，请修改 -p 左侧的端口）：

cp .env.docker.example .env.docker   # set QT_DOC_HTML_PATH
docker compose --env-file .env.docker up -d

或者使用便捷脚本。该脚本会检查 Docker 是否正在运行，在首次运行时创建 .env.docker，构建并启动服务，然后等待健康检查端点就绪：

./deploy.sh

将 MCP 客户端指向 http://127.0.0.1:8000/mcp（可流式传输的 HTTP）。Qt 文档采用 GFDL 1.3 许可；容器只提供你的本地副本，不会重新分发文档。

⚙️ 配置

这些设置适用于原生运行方式（pip 或源码）。在 Docker 中，它们已在容器内设置（QT_DOC_BASE=/docs、QT_DOC_STATE_DIR=/data、SERVER_HOST=0.0.0.0）；.env.docker 中的 QT_DOC_HTML_PATH 变量不是服务器设置，只是挂载到 /docs 的主机路径。

在仓库根目录下创建 .env 文件。辅助脚本会写入合理的默认值；请根据需要调整：

工具使用相对于根目录的精确 Markdown 路径标识文档，而非在线 URL。例如，Qt 4 页面使用 qcompleter.md，Qt 5/6 全局页面使用 qtdoc/accessible.md，Qt 5/6 Core 页面使用 qtcore/qobject.md。默认情况下，每个文档集都会在 $QT_DOC_BASE/.index/ 下存储各自的索引和 Markdown 缓存，因此切换 QT_DOC_BASE 后会复用已有的派生数据。将 QT_DOC_STATE_DIR 设置为其他可写目录，即可迁移两者。Markdown 缓存会映射文档目录树：例如，使用默认状态目录时，qtcore/qobject.md 会缓存为 .index/md/qtcore/qobject.md，并附带 qobject.meta.json。

🔌 MCP 客户端设置

默认情况下，服务会在 http://127.0.0.1:8000/mcp 暴露 HTTP 端点。请按照以下说明，将其注册到你首选的兼容 MCP 的 Agent。

Stdio 传输

使用 stdio 而非 HTTP 运行服务：

qt-doc-mcp --transport stdio

对于仅支持 stdio 的 MCP 客户端，请使用 args: ["--transport", "stdio"] 配置该命令。启动索引和 Markdown 缓存进度会写入 stderr，stdout 则专用于 MCP 协议消息。

code --add-mcp '{"name":"qt-docs","type":"http","url":"http://127.0.0.1:8000/mcp"}'

{
  "servers": {
    "qt-docs": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

claude mcp add --transport http qt-docs http://127.0.0.1:8000/mcp

{
  "mcpServers": {
    "qt-docs": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

codex mcp add qt-docs -- npx -y mcp-client-http http://127.0.0.1:8000/mcp

[mcp_servers.qt-docs]
command = "npx"
args = ["-y", "mcp-client-http", "http://127.0.0.1:8000/mcp"]

{
  "mcpServers": {
    "qt-docs": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

{
  "mcpServers": {
    "qt-docs": {
      "command": "npx",
      "args": ["-y", "mcp-client-http", "http://127.0.0.1:8000/mcp"]
    }
  }
}

🛠️ 可用工具

此服务提供 2 个 MCP 工具，用于处理当前本地 Qt 文档集：

1. read_documentation - 将当前 Qt 文档集中的页面读取并转换为 Markdown

   • 提取片段（#details、#public-functions）
   • 使用 start_index 和 max_length 分页
   • 仅章节模式，用于获取指定内容
   • 返回包含规范化链接和 GFDL 署名信息的 Markdown

2. search_documentation - 在当前 Qt 文档集中进行全文搜索

   • 使用 SQLite FTS5 和 BM25 相关性排序
   • 提供带有高亮匹配项的上下文摘要
   • 可配置结果数量限制（默认值：10，最大值：50）

有关参数、返回值、示例和错误处理的详细 API 文档，请参阅 工具参考。

📚 相关资源

• Model Context Protocol 规范
• Qt 文档
• FastMCP 框架
• 工具参考
• 更新日志
• 贡献指南
• 故障排除指南

📄 许可证

• **代码：**MIT 许可证（参见 LICENSE）。
• Qt 文档：© The Qt Company Ltd. 及贡献者，采用 GFDL 1.3 许可。此服务会转换本地获取的文档，并在输出中注明出处。如果重新分发本地镜像，请附上 LICENSE.FDL 并保留声明。
• 更多详情请参阅 THIRD_PARTY_NOTICES.md。