Back to search
QtDocMcp
MCP serverGitHub
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
Markdown
[](/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
- # qt-docs-mcp
- A local [Model Context Protocol](https://modelcontextprotocol.io) server that serves the Qt
- documentation already installed in this image. It speaks JSON-RPC over stdio, reads the compiled
- `.qch` documentation (Qt Help), and exposes three tools:
- | Tool | Input | Returns |
- | --- | --- | --- |
- | `qt_lookup` | `identifier` (required), `limit` (1–50, default 10) | Documentation pages for a class, method, property, enum, or signal — `QObject::deleteLater` |
- | `qt_search` | `query` (required, ≤512 chars), `limit` (1–50, default 10) | Ranked full-text hits with snippets |
- | `qt_read` | `url` (required, `qthelp://`), `section` (optional anchor or heading), `max_chars` (optional) | The page as Markdown, starting with `Source: <url>` |
- The point is to replace "glob and grep a directory of HTML files" with an indexed lookup: the
- agent asks for `QObject::deleteLater` and gets the page, not a file path to guess at.
- ## Build
- ```sh
- /Qt/6.12.0/gcc_64/bin/qt-cmake -G Ninja -S . -B build
- cmake --build build
- ```
- Qt 6.12 (Core, Gui, Help) and CMake ≥3.22 are the only requirements; there are no third-party
- dependencies. `qt_standard_project_setup()` supplies AUTOMOC, and only the tests need Qt6::Test.
- `cmake --install build --prefix /opt/qt-docs-mcp` puts the binary in
- `/opt/qt-docs-mcp/bin/qt-docs-mcp`, which is the path the deployment notes and the OpenCode
- example use. The Qt runtime libraries are not installed with it: the installed binary carries a
- RUNPATH of the Qt library directory it was linked against followed by `$ORIGIN/../lib`, so it runs
- in place. If you copy it somewhere else — or into an image without that SDK — either put the Qt
- libraries in `../lib` beside it, or set `LD_LIBRARY_PATH` to the Qt lib directory of the SDK you
- built against. The SDK entry comes first in the RUNPATH, so while that directory exists on the
- machine it wins over `../lib`: use `LD_LIBRARY_PATH` to try a bundled copy in place.
- ## Test
- ```sh
- QT_QPA_PLATFORM=offscreen ctest --test-dir build --output-on-failure
- ```
- - `tst_config` — environment parsing, bounds, cache-directory selection.
- - `tst_html` — the qdoc HTML → Markdown converter against captured fixtures.
- - `tst_docs` — the real mounted documentation: registration, lookup, search, reads, and the
- address validation that keeps `qt_read` inside the collection. Skipped when no docs are mounted.
- - `tst_mcp_protocol` — spawns the built binary and drives `initialize` → `tools/list` →
- `tools/call` over a pipe, asserting that stdout carries protocol traffic only.
- `tests/CMakeLists.txt` sets `QT_DOCS_ROOT` for the tests from the `QT_DOCS_ROOT` CMake cache
- variable (default `/qt-docs`), and every test uses its own `QTemporaryDir` as the cache so a test
- run never contends the production collection.
- ## Run
- ```sh
- QT_DOCS_ROOT=/qt-docs QT_HELP_CACHE_DIR=/var/cache/qt-docs-mcp /opt/qt-docs-mcp/bin/qt-docs-mcp
- ```
- The binary reads JSON-RPC from stdin, so running it by hand waits for input: feed it a line or
- two and press Ctrl-D, for example
- ```sh
- printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
- | QT_DOCS_ROOT=/qt-docs QT_HELP_CACHE_DIR=/var/cache/qt-docs-mcp /opt/qt-docs-mcp/bin/qt-docs-mcp
- ```
- The server reads newline-delimited JSON-RPC on stdin and writes one compact JSON line per response
- on stdout, flushed immediately. **stdout carries protocol traffic only**; every diagnostic goes to
- stderr, so a client that pipes stdout into a JSON parser cannot be corrupted by a warning.
- ### Environment
- | Variable | Default | Meaning |
- | --- | --- | --- |
- | `QT_DOCS_ROOT` | `/qt-docs` | Directory holding the `.qch` files, searched recursively |
- | `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 |
- | `QT_DOCS_MAX_RESULTS` | `10` | Default `limit` for the tools (clamped to 1–50) |
- | `QT_DOCS_MAX_CHARS` | `20000` | Default output budget for `qt_read` (clamped to 1000–500000) |
- | `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 |
- | `QT_DOCS_SEARCH_TIMEOUT_MS` | `10000` | How long one search waits before it gives up |
- | `QT_DOCS_LOG_LEVEL` | `warning` | Qt logging level: `debug`, `info`, `warning`, `critical`, `fatal` |
- ### Tool results
- Every tool answers with one text block *and* a `structuredContent` object holding the same
- payload, so a client can read whichever channel it prefers: the text block is that JSON
- serialised, except for `qt_read`, whose payload carries the page as Markdown in its `text`
- field and sends that as the text block too — the body is in both, never only in one. A genuine
- failure sets `isError: true` and a machine-readable `status`; an empty but valid answer never
- does. Statuses: `ok`, `no_results`, `not_found`, `index_not_ready`, `docs_missing`,
- `docs_unreadable`, `invalid_argument`, `timeout`, `search_failed`, `internal_error`.
- ### Protocol, in one line
- One JSON object per line in, one JSON object per line out. The server speaks the MCP revisions
- `2025-11-25` and `2025-06-18`; an `initialize` asking for anything older or unknown is answered
- with `2025-06-18`. Batch (array) framing belongs to revisions this server does not claim, so an
- array on a line is refused rather than executed.
- Protocol-level problems come back as JSON-RPC errors and the server stays alive: `-32700` when the
- line is not a JSON document this parser can read at all (the text is malformed, or it is a bare
- scalar — Qt's parser only accepts an object or an array at the top level), `-32600` when it parses
- but is not a request this server can route (an array, a missing or non-string `method`, a `jsonrpc`
- other than `"2.0"`, an `id` that is not a string or an integer, `params` that is not an object) —
- answered with a null
- `id` whenever the caller's `id` could not be trusted, `-32601` for an unknown method or tool, and
- `-32602` when a valid envelope carries arguments the method itself rejects. A notification (a valid
- envelope with no `id`) is never answered; an `id`-bearing call to a `notifications/...` method is
- refused, not swallowed. Bad tool *arguments* are a different thing: they come back inside the tool
- result as `invalid_argument`, with `isError: true`.
- A search index that has not finished building is a temporary state, not a failure of the
- documentation: `qt_search` answers `index_not_ready` with a "try again" message while indexing keeps
- running in the background, and a later search on the same server succeeds.
- ## Deployment
- - Mount the documentation read-only at `/qt-docs` and a writable directory at
- `/var/cache/qt-docs-mcp`. The server only ever writes to the cache: the collection
- (`qt-docs.qhc`) and its search index live there, so the documentation mount stays untouched.
- - Ship the Qt runtime libraries the binary needs (Core, Gui, Widgets, Sql, Help) and the plugins it
- loads: `sqldrivers/libqsqlite.so` for the collection and its search index, and the offscreen
- platform plugin `platforms/libqoffscreen.so`. Qt looks for plugins under `QT_PLUGIN_PATH` and
- then under the plugin directory baked into the Qt build (`<Qt prefix>/plugins`, where the SDK
- keeps them), so an in-place install needs nothing extra. A deployment that carries its own Qt
- libraries needs the whole `plugins/` tree at `<install prefix>/plugins`, plus a `qt.conf` next to
- the executable (`[Paths]` / `Prefix=..`) or `QT_PLUGIN_PATH` pointing at it. Without the SQLite
- driver the collection cannot be opened at all: every tool answers `docs_unreadable` (or
- `index_not_ready` when only the index is missing) and stderr names the driver.
- - No network access is required, and no X11 or Wayland platform: the server runs as a
- `QGuiApplication` with the offscreen platform plugin, which it selects when `QT_QPA_PLATFORM` is
- unset (Qt Help's indexer loads the font database).
- - The first run builds the search index in the cache directory (minutes for a full Qt docs mount,
- then sub-second warm starts). `qt_search` waits for it up to `QT_DOCS_INDEX_WAIT_MS` and answers
- `index_not_ready` when that runs out; `qt_lookup` and `qt_read` work without the index. The
- indexing that is already running does not stop with that answer, so a later `qt_search` on the
- same server succeeds - the timeout is not sticky, and a `0` budget only means nobody waits.
- - Every `.qch` in the mount has to be readable. Qt Help registers archives into one shared index,
- and one unreadable archive poisons the entries of the readable ones next to it, so the server
- refuses the whole mount (`docs_unreadable`) instead of serving half a corpus: fix or remove the
- bad file rather than working around it in the client.
- - **One server process per cache directory.** Qt Help does not support two processes sharing one
- collection file, and the collection is writable (registering modules rewrites it), so two servers
- pointed at the same `QT_HELP_CACHE_DIR` can corrupt it. Give each instance its own cache
- directory when more than one client is in play, for example
- `QT_HELP_CACHE_DIR=/var/cache/qt-docs-mcp-<client>`; the default is safe only for a single
- server.
- ## OpenCode
- Copy [`docs/opencode.example.jsonc`](docs/opencode.example.jsonc) into your `opencode.jsonc` (or
- `.opencode/opencode.jsonc`) and adjust the binary path:
- ```jsonc
- {
- "$schema": "https://opencode.ai/config.json",
- "mcp": {
- "servers": {
- "qt-docs": {
- "type": "local",
- "command": ["/opt/qt-docs-mcp/bin/qt-docs-mcp"],
- "environment": {
- "QT_DOCS_ROOT": "/qt-docs",
- "QT_HELP_CACHE_DIR": "/var/cache/qt-docs-mcp"
- }
- }
- }
- }
- }
- ```
- OpenCode exposes the tools as `<server>_<tool>`, so this server's tools are
- `qt_docs_qt_lookup`, `qt_docs_qt_search`, and `qt_docs_qt_read` (the server name's `-` becomes
- `_`). `.opencode/agents/librarian.md` grants exactly those three and nothing else; if you rename
- the server, update those three `action:` entries there.
- ## Layout
- ```
- src/Config.{h,cpp} environment parsing, bounds, cache directory
- src/main.cpp application, logging to stderr
- src/mcp/StdioTransport.{h,cpp} stdin/stdout framing for JSON-RPC lines
- src/mcp/McpServer.{h,cpp} initialize/ping/tools/list/tools/call dispatch
- src/mcp/ToolHandler.{h,cpp} shared tool plumbing (argument helpers, result envelopes)
- src/mcp/JsonRpc.{h,cpp} JSON-RPC constants and error codes
- src/tools/ToolRegistry.{h,cpp} the three tool schemas and their routing
- src/tools/{Lookup,Search,Read}Tool.{h,cpp}
- src/help/DocEngine.{h,cpp} lazy Qt Help engine: registration, lookup, search, reads
- src/help/DocumentRegistry.{h,cpp} collection reconciliation and qthelp:// address resolution
- src/help/ResultStatus.h the status enum and its names
- src/html/HtmlTokenizer.{h,cpp} hand-written HTML scanner (qdoc HTML is not XML)
- src/html/HtmlToMarkdown.{h,cpp} scanner → Markdown, section extraction, truncation
- docs/m0-findings.md spike measurements behind the design
- ```
- ## Limitations
- - Qt Help indexes one entry per identifier, so `qt_lookup` on an overloaded name returns the first
- overload's anchor; `qt_read` the page to see the rest.
- - No numeric relevance score exists in the search API; `rank` is the 1-based result order.
- - The server follows the documentation version it is given: swapping the mount for another Qt
- version needs no rebuild, because registration is reconciled against the mounted files.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.