{
"markdown": "# Qt Documentation MCP Server\n\nmcp-name: io.github.jztan/qt4-doc-mcp-server\n\n[](https://pypi.org/project/qt4-doc-mcp-server/)\n[](LICENSE)\n[](https://pypi.org/project/qt4-doc-mcp-server/)\n[](https://github.com/jztan/qt4-doc-mcp-server/issues)\n[](https://github.com/jztan/qt4-doc-mcp-server/actions/workflows/pr-tests.yml)\n[](https://pepy.tech/project/qt4-doc-mcp-server)\n\nBring locally installed Qt 4.8, Qt 5, or Qt 6 documentation to your AI coding assistant. Works offline with one selected documentation set at a time.\n\n## [Tool Reference](./docs/TOOL_REFERENCE.md) | [Changelog](./CHANGELOG.md) | [Contributing](./docs/CONTRIBUTING.md) | [Troubleshooting](./docs/TROUBLESHOOTING.md)\n\n## ✨ Features\n- 🔌 **Offline-First** - Works entirely with local documentation\n- 🔍 **Full-Text Search** - Find what you need across all Qt docs\n- ⚡ **Smart Caching** - Fast responses for repeated queries\n- 🎯 **Fragment Support** - Extract specific sections when needed\n- 🛠️ **MCP Standard** - Compatible with Claude, VS Code, and other MCP clients\n\n## 📦 Prerequisites\n- **Python 3.11+** required (not needed when using the Docker image)\n- **Qt HTML Documentation** for one supported release (Qt 4.8, Qt 5, or Qt 6)\n - The included helper downloads Qt 4.8.4 only.\n - Point `QT_DOC_BASE` directly at an existing Qt 5/6 offline documentation root.\n- **~500MB disk space** for docs + cache + search index\n- **SQLite with FTS5 support** (included in Python 3.11+ by default)\n\n## 🚀 Installation\n\n### From PyPI (Recommended)\n```bash\npip install qt4-doc-mcp-server\n```\n\n### From Source\n```bash\ngit clone https://github.com/jztan/qt4-doc-mcp-server.git\ncd qt4-doc-mcp-server\nuv sync --locked\n```\n\n### Setup Qt Documentation\n```bash\n# Automated setup (recommended, requires the cloned repo)\npython scripts/prepare_qt48_docs.py --segments 4\n\n# This will:\n# - Download Qt 4.8.4 source archive\n# - Extract HTML documentation\n# - Create .env with sensible defaults\n# - Copy GFDL license file\n```\n\nThe helper script ships with the repo, not the PyPI package. Installed from PyPI only? Download the docs manually instead:\n\n```bash\ncurl -LO https://download.qt.io/archive/qt/4.8/4.8.4/qt-everywhere-opensource-src-4.8.4.tar.gz\ntar -xzf qt-everywhere-opensource-src-4.8.4.tar.gz qt-everywhere-opensource-src-4.8.4/doc/html\nmv qt-everywhere-opensource-src-4.8.4/doc/html ./qt4-docs-html\n```\n\nThen create a `.env` with `QT_DOC_BASE` pointing at that directory (see Configuration below).\n\n### Quick Start Commands\n```bash\n# 1. Install\npip install qt4-doc-mcp-server\n\n# 2. Setup Qt docs\npython scripts/prepare_qt48_docs.py --segments 4\n\n# 3. Build search index (optional; the server builds it on first start)\nqt-doc-build-index\n\n# 4. Start server\nqt-doc-mcp\n\n# 5. Verify health\ncurl -s http://127.0.0.1:8000/health\n```\n\nThe legacy `qt4-doc-mcp-server` command remains available as an alias for existing client configurations.\n\n### Agent-friendly FTS CLI\n\nAfter building the index, agents can search and receive materialized absolute Markdown paths:\n\n```bash\nqt-doc-cli \"accessible applications\" --limit 5\n```\n\nThe command reads the same `.env` settings as the server. Before searching, it automatically builds a missing/outdated FTS index and fully warms an incomplete Markdown cache. It then prints each result's title, absolute `.md` path, and FTS snippet to stdout; preparation messages, errors, and warnings go to stderr. Use `qt-doc-warm-md --force` after changing documentation in place.\n\n## 🐳 Docker\n\nPrebuilt multi-arch images (amd64/arm64) are published to GitHub Container Registry on every release. The container is offline-only: you mount your prepared Qt `doc/html` directory read-only at `/docs`, and all derived state (Markdown cache and search index) lives in a volume at `/data`.\n\n```bash\n# Prepare Qt docs on the host first (one-time, writes to ./qt4-docs-html)\npython scripts/prepare_qt48_docs.py --segments 4\n\n# Run from GHCR\ndocker run -d --name qt4-doc-mcp-server -p 8000:8000 \\\n -v \"$PWD/qt4-docs-html:/docs:ro\" \\\n -v qt4-doc-data:/data \\\n ghcr.io/jztan/qt4-doc-mcp-server:latest\n\n# Verify\ncurl -s http://127.0.0.1:8000/health\n```\n\nUsing only the published image, without cloning this repo? Download the Qt 4.8.4 docs directly instead of running the prepare script:\n\n```bash\ncurl -LO https://download.qt.io/archive/qt/4.8/4.8.4/qt-everywhere-opensource-src-4.8.4.tar.gz\ntar -xzf qt-everywhere-opensource-src-4.8.4.tar.gz qt-everywhere-opensource-src-4.8.4/doc/html\nmv qt-everywhere-opensource-src-4.8.4/doc/html ./qt4-docs-html\n```\n\nAny existing Qt 5 or Qt 6 `doc/html` tree (from the Qt installer or distro documentation packages) works as the mount source too.\n\nFirst start converts and indexes the documentation into the `/data` volume; subsequent starts reuse it. Depending on the docset size, the first start can take a minute or two before the health endpoint responds.\n\n### Docker Compose\n\nWith docs in the default `./qt4-docs-html` location, no configuration is needed:\n\n```bash\ndocker compose up -d\n```\n\nFor docs elsewhere (including Qt 5 or Qt 6 `doc/html` trees, which the server also supports), point `QT_DOC_HTML_PATH` at them. If port 8000 is taken on the host, set `HOST_PORT` in the same file (with plain `docker run`, change the left side of `-p` instead):\n\n```bash\ncp .env.docker.example .env.docker # set QT_DOC_HTML_PATH\ndocker compose --env-file .env.docker up -d\n```\n\nOr use the convenience script, which checks Docker is running, creates `.env.docker` on first run, builds and starts the service, and waits for the health endpoint:\n\n```bash\n./deploy.sh\n```\n\nPoint your MCP client at `http://127.0.0.1:8000/mcp` (streamable HTTP). Qt documentation is licensed under GFDL 1.3; the container serves your local copy and never redistributes it.\n\n## ⚙️ Configuration\n\nThese settings apply to native (pip or source) runs. In Docker they are already set inside the container (`QT_DOC_BASE=/docs`, `QT_DOC_STATE_DIR=/data`, `SERVER_HOST=0.0.0.0`); the `QT_DOC_HTML_PATH` variable in `.env.docker` is not a server setting, just the host path mounted at `/docs`.\n\nCreate a `.env` file in the repo root. The helper script writes sensible defaults; adjust as needed:\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `QT_DOC_BASE` | _required_ | Absolute path to one Qt 4.8, Qt 5, or Qt 6 HTML documentation root. The server detects the active docset. |\n| `QT_DOC_STATE_DIR` | `$QT_DOC_BASE/.index` | Optional writable directory for the FTS index and Markdown cache. Use this when the documentation root is read-only. |\n| `PREINDEX_DOCS` | `true` | Build search index automatically at startup if not present. |\n| `PRECONVERT_MD` | `false` | Warm the Markdown cache automatically at MCP startup. |\n| `SERVER_HOST` | `127.0.0.1` | Bind address for the FastMCP server (`0.0.0.0` for containers). |\n| `SERVER_PORT` | `8000` | TCP port for streamable HTTP transport. |\n| `MCP_LOG_LEVEL` | `WARNING` | Logging verbosity (DEBUG/INFO/WARNING/ERROR). |\n| `MD_CACHE_SIZE` | `512` | In-memory CachedDoc LRU capacity (counts pages). |\n| `DEFAULT_MAX_MARKDOWN_LENGTH` | `20000` | Default maximum characters returned per request (prevents token limit issues). |\n\nThe tools identify documents by their exact root-relative Markdown path, not an online URL. For example, use `qcompleter.md` for a Qt 4 page, `qtdoc/accessible.md` for a Qt 5/6 global page, or `qtcore/qobject.md` for a Qt 5/6 Core page. By default, each docset stores its own index and Markdown cache under `$QT_DOC_BASE/.index/`, so switching `QT_DOC_BASE` reuses its existing derived state. Set `QT_DOC_STATE_DIR` to relocate both to a writable directory. The Markdown cache mirrors the documentation tree: for example, `qtcore/qobject.md` is cached as `.index/md/qtcore/qobject.md` plus `qobject.meta.json` with the default state directory.\n\n## 🔌 MCP Client Setup\n\nBy default, the server exposes an HTTP endpoint at `http://127.0.0.1:8000/mcp`. Register it with your preferred MCP-compatible agent using the instructions below.\n\n### Stdio transport\n\nRun the server over stdio instead of HTTP with:\n\n```bash\nqt-doc-mcp --transport stdio\n```\n\nFor stdio-only MCP clients, configure that command with `args: [\"--transport\", \"stdio\"]`. Startup indexing and Markdown-cache progress are written to stderr, leaving stdout exclusively for MCP protocol messages.\n\n\nVisual Studio Code (Native MCP Support)
\n\nVS Code has built-in MCP support via GitHub Copilot (requires VS Code 1.102+).\n\n**Using CLI (Quickest):**\n```bash\ncode --add-mcp '{\"name\":\"qt-docs\",\"type\":\"http\",\"url\":\"http://127.0.0.1:8000/mcp\"}'\n```\n\n**Using Command Palette:**\n1. Open Command Palette (`Cmd/Ctrl+Shift+P`)\n2. Run `MCP: Open User Configuration` (for global) or `MCP: Open Workspace Folder Configuration` (for project-specific)\n3. Add the configuration:\n ```json\n {\n \"servers\": {\n \"qt-docs\": {\n \"type\": \"http\",\n \"url\": \"http://127.0.0.1:8000/mcp\"\n }\n }\n }\n ```\n4. Save the file. VS Code will automatically load the MCP server.\n\n**Manual Configuration:**\nCreate `.vscode/mcp.json` in your workspace (or `mcp.json` in your user profile directory):\n```json\n{\n \"servers\": {\n \"qt-docs\": {\n \"type\": \"http\",\n \"url\": \"http://127.0.0.1:8000/mcp\"\n }\n }\n}\n```\n\n \n\n\nClaude Code
\n\nAdd to Claude Code using the CLI command:\n\n```bash\nclaude mcp add --transport http qt-docs http://127.0.0.1:8000/mcp\n```\n\nOr configure manually in your Claude Code settings file (`~/.claude.json`):\n\n```json\n{\n \"mcpServers\": {\n \"qt-docs\": {\n \"type\": \"http\",\n \"url\": \"http://127.0.0.1:8000/mcp\"\n }\n }\n}\n```\n\n \n\n\nCodex CLI
\n\nAdd to Codex CLI using the command:\n\n```bash\ncodex mcp add qt-docs -- npx -y mcp-client-http http://127.0.0.1:8000/mcp\n```\n\nOr configure manually in `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.qt-docs]\ncommand = \"npx\"\nargs = [\"-y\", \"mcp-client-http\", \"http://127.0.0.1:8000/mcp\"]\n```\n\n**Note:** Codex CLI primarily supports stdio-based MCP servers. The above uses `mcp-client-http` as a bridge for HTTP transport.\n\n \n\n\nKiro
\n\nKiro primarily supports stdio-based MCP servers. For HTTP servers, use an HTTP-to-stdio bridge:\n\n1. Create or edit `.kiro/settings/mcp.json` in your workspace:\n ```json\n {\n \"mcpServers\": {\n \"qt-docs\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"mcp-client-http\",\n \"http://127.0.0.1:8000/mcp\"\n ],\n \"disabled\": false\n }\n }\n }\n ```\n2. Save the file and restart Kiro. The active Qt documentation tools will appear in the MCP panel.\n\n**Note:** Direct HTTP transport support in Kiro is limited. The above configuration uses `mcp-client-http` as a bridge to connect to HTTP MCP servers.\n\n \n\n\nGeneric MCP Clients
\n\nMost MCP clients use a standard configuration format. For HTTP servers:\n\n```json\n{\n \"mcpServers\": {\n \"qt-docs\": {\n \"type\": \"http\",\n \"url\": \"http://127.0.0.1:8000/mcp\"\n }\n }\n}\n```\n\nFor clients that require a command-based approach with HTTP bridge:\n\n```json\n{\n \"mcpServers\": {\n \"qt-docs\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-client-http\", \"http://127.0.0.1:8000/mcp\"]\n }\n }\n}\n```\n\n \n\n## 🛠️ Available Tools\n\nThe server provides **2 MCP tools** for working with the active local Qt documentation set:\n\n1. **`read_documentation`** - Read and convert pages from the active Qt documentation set to Markdown\n - Fragment extraction (`#details`, `#public-functions`)\n - Pagination with `start_index` and `max_length`\n - Section-only mode for targeted content\n - Returns Markdown with normalized links and GFDL attribution\n\n2. **`search_documentation`** - Full-text search across the active Qt documentation set\n - SQLite FTS5 with BM25 relevance ranking\n - Context snippets with highlighted matches\n - Configurable result limits (default: 10, max: 50)\n\nFor detailed API documentation including parameters, return values, examples, and error handling, see the **[Tool Reference](docs/TOOL_REFERENCE.md)**.\n\n## 📚 Related Resources\n\n- [Model Context Protocol Specification](https://modelcontextprotocol.io/)\n- [Qt Documentation](https://doc.qt.io/)\n- [FastMCP Framework](https://github.com/jlowin/fastmcp)\n- [Tool Reference](docs/TOOL_REFERENCE.md)\n- [Changelog](CHANGELOG.md)\n- [Contributing Guide](docs/CONTRIBUTING.md)\n- [Troubleshooting Guide](docs/TROUBLESHOOTING.md)\n\n## 📄 License\n- **Code:** MIT License (see `LICENSE`).\n- **Qt Documentation:** © The Qt Company Ltd. and contributors, licensed under GFDL 1.3. This server\n converts locally obtained docs and includes attribution in outputs. If you\n redistribute a local mirror, include `LICENSE.FDL` and preserve notices.\n- See `THIRD_PARTY_NOTICES.md` for more details.\n",
"bytes": 13425,
"sha": "da13a7cb65357d571a68ff638359b0c0d78cf892ca48268b5f6ac76319b13cee",
"repo_slug": "jztan/qt4-doc-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_jztan_qt4_doc_mcp_server_afbca161/readme"
}