Skip to content
Back to search

QtDocMcp

A local MCP server that gives AI coding assistants offline access to Qt documentation, with API lookup, full-text search, and Markdown output from Qt Help (.qch) files.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mikkomehtonen--qtdocmcp/badge.svg)](/listings/mikkomehtonen--qtdocmcp)

HTML

<a href="/listings/mikkomehtonen--qtdocmcp"><img src="/api/listings/mikkomehtonen--qtdocmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 201 lines
  1. # qt-docs-mcp
  2. A local [Model Context Protocol](https://modelcontextprotocol.io) server that serves the Qt
  3. documentation already installed in this image. It speaks JSON-RPC over stdio, reads the compiled
  4. `.qch` documentation (Qt Help), and exposes three tools:
  5. | Tool | Input | Returns |
  6. | --- | --- | --- |
  7. | `qt_lookup` | `identifier` (required), `limit` (1–50, default 10) | Documentation pages for a class, method, property, enum, or signal — `QObject::deleteLater` |
  8. | `qt_search` | `query` (required, ≤512 chars), `limit` (1–50, default 10) | Ranked full-text hits with snippets |
  9. | `qt_read` | `url` (required, `qthelp://`), `section` (optional anchor or heading), `max_chars` (optional) | The page as Markdown, starting with `Source: <url>` |
  10. The point is to replace "glob and grep a directory of HTML files" with an indexed lookup: the
  11. agent asks for `QObject::deleteLater` and gets the page, not a file path to guess at.
  12. ## Build
  13. ```sh
  14. /Qt/6.12.0/gcc_64/bin/qt-cmake -G Ninja -S . -B build
  15. cmake --build build
  16. ```
  17. Qt 6.12 (Core, Gui, Help) and CMake ≥3.22 are the only requirements; there are no third-party
  18. dependencies. `qt_standard_project_setup()` supplies AUTOMOC, and only the tests need Qt6::Test.
  19. `cmake --install build --prefix /opt/qt-docs-mcp` puts the binary in
  20. `/opt/qt-docs-mcp/bin/qt-docs-mcp`, which is the path the deployment notes and the OpenCode
  21. example use. The Qt runtime libraries are not installed with it: the installed binary carries a
  22. RUNPATH of the Qt library directory it was linked against followed by `$ORIGIN/../lib`, so it runs
  23. in place. If you copy it somewhere else — or into an image without that SDK — either put the Qt
  24. libraries in `../lib` beside it, or set `LD_LIBRARY_PATH` to the Qt lib directory of the SDK you
  25. built against. The SDK entry comes first in the RUNPATH, so while that directory exists on the
  26. machine it wins over `../lib`: use `LD_LIBRARY_PATH` to try a bundled copy in place.
  27. ## Test
  28. ```sh
  29. QT_QPA_PLATFORM=offscreen ctest --test-dir build --output-on-failure
  30. ```
  31. - `tst_config` — environment parsing, bounds, cache-directory selection.
  32. - `tst_html` — the qdoc HTML → Markdown converter against captured fixtures.
  33. - `tst_docs` — the real mounted documentation: registration, lookup, search, reads, and the
  34. address validation that keeps `qt_read` inside the collection. Skipped when no docs are mounted.
  35. - `tst_mcp_protocol` — spawns the built binary and drives `initialize` → `tools/list` →
  36. `tools/call` over a pipe, asserting that stdout carries protocol traffic only.
  37. `tests/CMakeLists.txt` sets `QT_DOCS_ROOT` for the tests from the `QT_DOCS_ROOT` CMake cache
  38. variable (default `/qt-docs`), and every test uses its own `QTemporaryDir` as the cache so a test
  39. run never contends the production collection.
  40. ## Run
  41. ```sh
  42. QT_DOCS_ROOT=/qt-docs QT_HELP_CACHE_DIR=/var/cache/qt-docs-mcp /opt/qt-docs-mcp/bin/qt-docs-mcp
  43. ```
  44. The binary reads JSON-RPC from stdin, so running it by hand waits for input: feed it a line or
  45. two and press Ctrl-D, for example
  46. ```sh
  47. printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  48. | QT_DOCS_ROOT=/qt-docs QT_HELP_CACHE_DIR=/var/cache/qt-docs-mcp /opt/qt-docs-mcp/bin/qt-docs-mcp
  49. ```
  50. The server reads newline-delimited JSON-RPC on stdin and writes one compact JSON line per response
  51. on stdout, flushed immediately. **stdout carries protocol traffic only**; every diagnostic goes to
  52. stderr, so a client that pipes stdout into a JSON parser cannot be corrupted by a warning.
  53. ### Environment
  54. | Variable | Default | Meaning |
  55. | --- | --- | --- |
  56. | `QT_DOCS_ROOT` | `/qt-docs` | Directory holding the `.qch` files, searched recursively |
  57. | `QT_HELP_CACHE_DIR` | `/var/cache/qt-docs-mcp` | Writable directory for the collection and its index. Unset and unwritable `/var/cache` falls back to a per-process directory under the system temp directory (`$TMPDIR/qt-docs-mcp-XXXXXX`), removed when the server exits; set but unwritable is a start-up error |
  58. | `QT_DOCS_MAX_RESULTS` | `10` | Default `limit` for the tools (clamped to 1–50) |
  59. | `QT_DOCS_MAX_CHARS` | `20000` | Default output budget for `qt_read` (clamped to 1000–500000) |
  60. | `QT_DOCS_INDEX_WAIT_MS` | `60000` | How long `qt_search` waits for the index to settle; `0` means do not wait at all — lookups and reads are unaffected and the search reports `index_not_ready` until background indexing finishes |
  61. | `QT_DOCS_SEARCH_TIMEOUT_MS` | `10000` | How long one search waits before it gives up |
  62. | `QT_DOCS_LOG_LEVEL` | `warning` | Qt logging level: `debug`, `info`, `warning`, `critical`, `fatal` |
  63. ### Tool results
  64. Every tool answers with one text block *and* a `structuredContent` object holding the same
  65. payload, so a client can read whichever channel it prefers: the text block is that JSON
  66. serialised, except for `qt_read`, whose payload carries the page as Markdown in its `text`
  67. field and sends that as the text block too — the body is in both, never only in one. A genuine
  68. failure sets `isError: true` and a machine-readable `status`; an empty but valid answer never
  69. does. Statuses: `ok`, `no_results`, `not_found`, `index_not_ready`, `docs_missing`,
  70. `docs_unreadable`, `invalid_argument`, `timeout`, `search_failed`, `internal_error`.
  71. ### Protocol, in one line
  72. One JSON object per line in, one JSON object per line out. The server speaks the MCP revisions
  73. `2025-11-25` and `2025-06-18`; an `initialize` asking for anything older or unknown is answered
  74. with `2025-06-18`. Batch (array) framing belongs to revisions this server does not claim, so an
  75. array on a line is refused rather than executed.
  76. Protocol-level problems come back as JSON-RPC errors and the server stays alive: `-32700` when the
  77. line is not a JSON document this parser can read at all (the text is malformed, or it is a bare
  78. scalar — Qt's parser only accepts an object or an array at the top level), `-32600` when it parses
  79. but is not a request this server can route (an array, a missing or non-string `method`, a `jsonrpc`
  80. other than `"2.0"`, an `id` that is not a string or an integer, `params` that is not an object) —
  81. answered with a null
  82. `id` whenever the caller's `id` could not be trusted, `-32601` for an unknown method or tool, and
  83. `-32602` when a valid envelope carries arguments the method itself rejects. A notification (a valid
  84. envelope with no `id`) is never answered; an `id`-bearing call to a `notifications/...` method is
  85. refused, not swallowed. Bad tool *arguments* are a different thing: they come back inside the tool
  86. result as `invalid_argument`, with `isError: true`.
  87. A search index that has not finished building is a temporary state, not a failure of the
  88. documentation: `qt_search` answers `index_not_ready` with a "try again" message while indexing keeps
  89. running in the background, and a later search on the same server succeeds.
  90. ## Deployment
  91. - Mount the documentation read-only at `/qt-docs` and a writable directory at
  92. `/var/cache/qt-docs-mcp`. The server only ever writes to the cache: the collection
  93. (`qt-docs.qhc`) and its search index live there, so the documentation mount stays untouched.
  94. - Ship the Qt runtime libraries the binary needs (Core, Gui, Widgets, Sql, Help) and the plugins it
  95. loads: `sqldrivers/libqsqlite.so` for the collection and its search index, and the offscreen
  96. platform plugin `platforms/libqoffscreen.so`. Qt looks for plugins under `QT_PLUGIN_PATH` and
  97. then under the plugin directory baked into the Qt build (`<Qt prefix>/plugins`, where the SDK
  98. keeps them), so an in-place install needs nothing extra. A deployment that carries its own Qt
  99. libraries needs the whole `plugins/` tree at `<install prefix>/plugins`, plus a `qt.conf` next to
  100. the executable (`[Paths]` / `Prefix=..`) or `QT_PLUGIN_PATH` pointing at it. Without the SQLite
  101. driver the collection cannot be opened at all: every tool answers `docs_unreadable` (or
  102. `index_not_ready` when only the index is missing) and stderr names the driver.
  103. - No network access is required, and no X11 or Wayland platform: the server runs as a
  104. `QGuiApplication` with the offscreen platform plugin, which it selects when `QT_QPA_PLATFORM` is
  105. unset (Qt Help's indexer loads the font database).
  106. - The first run builds the search index in the cache directory (minutes for a full Qt docs mount,
  107. then sub-second warm starts). `qt_search` waits for it up to `QT_DOCS_INDEX_WAIT_MS` and answers
  108. `index_not_ready` when that runs out; `qt_lookup` and `qt_read` work without the index. The
  109. indexing that is already running does not stop with that answer, so a later `qt_search` on the
  110. same server succeeds - the timeout is not sticky, and a `0` budget only means nobody waits.
  111. - Every `.qch` in the mount has to be readable. Qt Help registers archives into one shared index,
  112. and one unreadable archive poisons the entries of the readable ones next to it, so the server
  113. refuses the whole mount (`docs_unreadable`) instead of serving half a corpus: fix or remove the
  114. bad file rather than working around it in the client.
  115. - **One server process per cache directory.** Qt Help does not support two processes sharing one
  116. collection file, and the collection is writable (registering modules rewrites it), so two servers
  117. pointed at the same `QT_HELP_CACHE_DIR` can corrupt it. Give each instance its own cache
  118. directory when more than one client is in play, for example
  119. `QT_HELP_CACHE_DIR=/var/cache/qt-docs-mcp-<client>`; the default is safe only for a single
  120. server.
  121. ## OpenCode
  122. Copy [`docs/opencode.example.jsonc`](docs/opencode.example.jsonc) into your `opencode.jsonc` (or
  123. `.opencode/opencode.jsonc`) and adjust the binary path:
  124. ```jsonc
  125. {
  126. "$schema": "https://opencode.ai/config.json",
  127. "mcp": {
  128. "servers": {
  129. "qt-docs": {
  130. "type": "local",
  131. "command": ["/opt/qt-docs-mcp/bin/qt-docs-mcp"],
  132. "environment": {
  133. "QT_DOCS_ROOT": "/qt-docs",
  134. "QT_HELP_CACHE_DIR": "/var/cache/qt-docs-mcp"
  135. }
  136. }
  137. }
  138. }
  139. }
  140. ```
  141. OpenCode exposes the tools as `<server>_<tool>`, so this server's tools are
  142. `qt_docs_qt_lookup`, `qt_docs_qt_search`, and `qt_docs_qt_read` (the server name's `-` becomes
  143. `_`). `.opencode/agents/librarian.md` grants exactly those three and nothing else; if you rename
  144. the server, update those three `action:` entries there.
  145. ## Layout
  146. ```
  147. src/Config.{h,cpp} environment parsing, bounds, cache directory
  148. src/main.cpp application, logging to stderr
  149. src/mcp/StdioTransport.{h,cpp} stdin/stdout framing for JSON-RPC lines
  150. src/mcp/McpServer.{h,cpp} initialize/ping/tools/list/tools/call dispatch
  151. src/mcp/ToolHandler.{h,cpp} shared tool plumbing (argument helpers, result envelopes)
  152. src/mcp/JsonRpc.{h,cpp} JSON-RPC constants and error codes
  153. src/tools/ToolRegistry.{h,cpp} the three tool schemas and their routing
  154. src/tools/{Lookup,Search,Read}Tool.{h,cpp}
  155. src/help/DocEngine.{h,cpp} lazy Qt Help engine: registration, lookup, search, reads
  156. src/help/DocumentRegistry.{h,cpp} collection reconciliation and qthelp:// address resolution
  157. src/help/ResultStatus.h the status enum and its names
  158. src/html/HtmlTokenizer.{h,cpp} hand-written HTML scanner (qdoc HTML is not XML)
  159. src/html/HtmlToMarkdown.{h,cpp} scanner → Markdown, section extraction, truncation
  160. docs/m0-findings.md spike measurements behind the design
  161. ```
  162. ## Limitations
  163. - Qt Help indexes one entry per identifier, so `qt_lookup` on an overloaded name returns the first
  164. overload's anchor; `qt_read` the page to see the rest.
  165. - No numeric relevance score exists in the search API; `rank` is the 1-based result order.
  166. - The server follows the documentation version it is given: swapping the mount for another Qt
  167. version needs no rebuild, because registration is reconciled against the mounted files.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.