Metadata-Version: 2.4
Name: qt4-doc-mcp-server
Version: 0.5.0
Summary: Offline MCP Server for Qt 4.8.4 documentation
Project-URL: Homepage, https://github.com/jztan/qt4-doc-mcp-server
Project-URL: Repository, https://github.com/jztan/qt4-doc-mcp-server.git
Project-URL: Issues, https://github.com/jztan/qt4-doc-mcp-server/issues
Project-URL: Changelog, https://github.com/jztan/qt4-doc-mcp-server/blob/master/CHANGELOG.md
Author-email: Kevin Tan <jingzheng.tan@gmail.com>
Maintainer-email: Kevin Tan <jingzheng.tan@gmail.com>
License: MIT License
        
        Copyright (c) 2025
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
License-File: LICENSE
Keywords: c++,documentation,mcp,model-context-protocol,qt4
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Groupware
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.14.0
Requires-Dist: lxml>=6.0.0
Requires-Dist: markdownify>=1.2.0
Requires-Dist: mcp[cli]>=1.19.0
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: uvicorn>=0.38.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# Qt 4.8.4 Documentation MCP Server

[![PyPI Version](https://img.shields.io/pypi/v/qt4-doc-mcp-server.svg)](https://pypi.org/project/qt4-doc-mcp-server/)
[![License](https://img.shields.io/github/license/jztan/qt4-doc-mcp-server.svg)](LICENSE)
[![Python Version](https://img.shields.io/pypi/pyversions/qt4-doc-mcp-server.svg)](https://pypi.org/project/qt4-doc-mcp-server/)
[![GitHub Issues](https://img.shields.io/github/issues/jztan/qt4-doc-mcp-server.svg)](https://github.com/jztan/qt4-doc-mcp-server/issues)
[![CI](https://github.com/jztan/qt4-doc-mcp-server/actions/workflows/pr-tests.yml/badge.svg)](https://github.com/jztan/qt4-doc-mcp-server/actions/workflows/pr-tests.yml)

Offline‑only MCP Server that serves Qt 4.8.4 documentation to Agents/LLMs and IDEs.
It loads local HTML docs, converts pages to Markdown, and provides fast full‑text
search via SQLite FTS5.

## Quickstart
1. Install the package: `pip install qt4-doc-mcp-server`.
2. Fetch and stage the Qt docs (one-time): `python scripts/prepare_qt48_docs.py --segments 4`.
3. Copy `.env` from the script output or create one manually (see table below).
4. Build the search index: `qt4-doc-build-index` (required for search functionality).
5. Run the server: `qt4-doc-mcp-server` (or `uv run python -m qt4_doc_mcp_server.main`).
6. Verify health: `curl -s http://127.0.0.1:8000/health` → `{ "status": "ok" }`.
7. Optional: warm the Markdown cache for faster responses: `qt4-doc-warm-md`.

## Project Structure

```
.
├─ README.md                    # Quick start, config, licensing
├─ LICENSE                      # MIT license for this codebase
├─ CHANGELOG.md                 # Keep a Changelog (Unreleased + releases)
├─ THIRD_PARTY_NOTICES.md       # Qt docs and deps licensing notes
├─ pyproject.toml               # Packaging, deps, console entry points
├─ scripts/
│  ├─ prepare_qt48_docs.py      # Download, extract, and stage Qt 4.8.4 docs; writes .env
├─ src/
│  └─ qt4_doc_mcp_server/
│     ├─ __init__.py            # Package version
│     ├─ main.py                # FastMCP app (+ /health) and CLI run()
│     ├─ config.py              # Env loader (dotenv) + startup checks
│     ├─ tools.py               # MCP tools (read_documentation, search_documentation)
│     ├─ fetcher.py             # Canonical URL + local path mapping
│     ├─ convert.py             # HTML extraction, link normalization, HTML→Markdown
│     ├─ cache.py               # LRU + Markdown store (disk) helpers
│     ├─ doc_service.py         # Read path orchestration (store + convert)
│     ├─ search.py              # FTS5 index build/query with BM25 ranking
│     └─ cli.py                 # CLI utilities (qt4-doc-warm-md, qt4-doc-build-index)
└─ tests/                       # pytest suite (e.g., test_doc_service.py)
```

## Requirements
- Python 3.11+
- Local Qt 4.8.4 HTML documentation (see below)

## Get the Qt 4.8.4 Docs

### Prepare Docs with Python helper (recommended)

```
python scripts/prepare_qt48_docs.py # copy docs by default into ./qt4-docs-html
```
OR
```
python scripts/prepare_qt48_docs.py --segments 4 # faster download with 4 segments
```

This will:
- Download and extract the Qt 4.8.4 source archive (or reuse if present)
- Stage the HTML docs at `qt4-docs-html` (symlink by default)
- Copy `LICENSE.FDL` next to the docs
- Create/update `.env` with `QT_DOC_BASE` and sensible defaults



## Configure (dotenv)
Create a `.env` file in the repo root. The helper script writes sensible defaults; adjust as needed:

| Variable | Default | Purpose |
| --- | --- | --- |
| `QT_DOC_BASE` | _required_ | Absolute path to the Qt 4.8.4 HTML docs (`.../doc/html`). |
| `INDEX_DB_PATH` | `.index/fts.sqlite` | Location of the SQLite FTS5 search index. |
| `MD_CACHE_DIR` | `.cache/md` | Directory for cached Markdown blobs + metadata. |
| `PREINDEX_DOCS` | `true` | Build search index automatically at startup if not present. |
| `PRECONVERT_MD` | `true` | Warm the Markdown cache automatically at startup. |
| `SERVER_HOST` | `127.0.0.1` | Bind address for the FastMCP server (`0.0.0.0` for containers). |
| `SERVER_PORT` | `8000` | TCP port for streamable HTTP transport. |
| `MCP_LOG_LEVEL` | `WARNING` | Logging verbosity (DEBUG/INFO/WARNING/ERROR). |
| `MD_CACHE_SIZE` | `512` | In-memory CachedDoc LRU capacity (counts pages). |
| `DEFAULT_MAX_MARKDOWN_LENGTH` | `20000` | Default maximum characters returned per request (prevents token limit issues). |

## Dev Setup and Run
```
uv venv .venv && source .venv/bin/activate

# Option 1: run without installing the package (dev-only)
# Using uv to run the module directly
uv run python -m qt4_doc_mcp_server.main

# Option 2: install and use the CLI
uv pip install -e .[dev]
qt4-doc-mcp-server
# Health check
curl -s http://127.0.0.1:8000/health

# Build the search index (required for search_documentation tool)
uv run qt4-doc-build-index

# Optional: preconvert all HTML→Markdown into the store for faster reads
uv run qt4-doc-warm-md

# Run tests (ensure TMPDIR points to a writable location when sandboxed)
uv run python -m pytest -q
```

## How It Works (high‑level)
- Offline‑only: no external HTTP fetches; everything reads from `QT_DOC_BASE`.
- HTML→Markdown: focused extraction of main content; normalized internal links;
  attribution appended.
- Markdown store: preconverted pages saved under `.cache/md` (sharded by URL hash)
  for fast reads; in‑memory LRU caches hot pages.
- Search: SQLite FTS5 index (title/headings/body) with BM25 ranking and context snippets.

## MCP Tools

The server provides two MCP tools:

1. **`read_documentation`** - Read and convert a specific Qt documentation page
2. **`search_documentation`** - Search across all Qt 4.8.4 documentation

### Example: read_documentation

Example MCP request/response (trimmed for brevity):

```json
// request
{
  "method": "tools/run",
  "params": {
    "name": "read_documentation",
    "arguments": {
      "url": "https://doc.qt.io/archives/qt-4.8/qstring.html",
      "fragment": "#details",
      "section_only": true,
      "max_length": 2000
    }
  }
}

// response
{
  "result": {
    "title": "QString Class",
    "canonical_url": "https://doc.qt.io/archives/qt-4.8/qstring.html",
    "markdown": "# QString Class\n...",
    "links": [
      {"text": "QStringList", "url": "https://doc.qt.io/archives/qt-4.8/qstringlist.html"}
    ],
    "attribution": "Content © The Qt Company Ltd./Digia — GNU Free Documentation License 1.3",
    "content_info": {
      "total_length": 15234,
      "returned_length": 2000,
      "start_index": 0,
      "truncated": true
    }
  }
}
```

**Note**: The `content_info` field appears when content is paginated or truncated. Use `start_index` and `max_length` parameters to retrieve additional pages. By default, responses are limited to 20,000 characters to avoid exceeding LLM token limits.

### Example: search_documentation

Example MCP request/response for searching:

```json
// request
{
  "method": "tools/run",
  "params": {
    "name": "search_documentation",
    "arguments": {
      "query": "signals slots",
      "limit": 5
    }
  }
}

// response
{
  "result": {
    "query": "signals slots",
    "count": 5,
    "results": [
      {
        "title": "Signals and Slots",
        "url": "https://doc.qt.io/archives/qt-4.8/signalsandslots.html",
        "score": 12.34,
        "context": "…used for communication between objects. <b>Signals</b> and <b>slots</b> mechanism is a central…"
      },
      {
        "title": "QObject Class Reference",
        "url": "https://doc.qt.io/archives/qt-4.8/qobject.html",
        "score": 8.76,
        "context": "…The QObject class supports <b>signals</b> and <b>slots</b> for inter-object communication…"
      }
    ]
  }
}
```

**Notes**:
- Search uses SQLite FTS5 with BM25 ranking for relevance
- Context snippets highlight matching terms with `<b>` tags
- The `limit` parameter controls maximum results (default: 10, max: 50)
- Build the index first with `qt4-doc-build-index` or set `PREINDEX_DOCS=true`

## MCP Client Configuration

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.

<details>
<summary><strong>Visual Studio Code (Native MCP Support)</strong></summary>

VS Code has built-in MCP support via GitHub Copilot (requires VS Code 1.102+).

**Using CLI (Quickest):**
```bash
code --add-mcp '{"name":"qt4-docs","type":"http","url":"http://127.0.0.1:8000/mcp"}'
```

**Using Command Palette:**
1. Open Command Palette (`Cmd/Ctrl+Shift+P`)
2. Run `MCP: Open User Configuration` (for global) or `MCP: Open Workspace Folder Configuration` (for project-specific)
3. Add the configuration:
   ```json
   {
     "servers": {
       "qt4-docs": {
         "type": "http",
         "url": "http://127.0.0.1:8000/mcp"
       }
     }
   }
   ```
4. Save the file. VS Code will automatically load the MCP server.

**Manual Configuration:**
Create `.vscode/mcp.json` in your workspace (or `mcp.json` in your user profile directory):
```json
{
  "servers": {
    "qt4-docs": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

</details>

<details>
<summary><strong>Claude Code</strong></summary>

Add to Claude Code using the CLI command:

```bash
claude mcp add --transport http qt4-docs http://127.0.0.1:8000/mcp
```

Or configure manually in your Claude Code settings file (`~/.claude.json`):

```json
{
  "mcpServers": {
    "qt4-docs": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

</details>

<details>
<summary><strong>Codex CLI</strong></summary>

Add to Codex CLI using the command:

```bash
codex mcp add qt4-docs -- npx -y mcp-client-http http://127.0.0.1:8000/mcp
```

Or configure manually in `~/.codex/config.toml`:

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

**Note:** Codex CLI primarily supports stdio-based MCP servers. The above uses `mcp-client-http` as a bridge for HTTP transport.

</details>

<details>
<summary><strong>Kiro</strong></summary>

Kiro primarily supports stdio-based MCP servers. For HTTP servers, use an HTTP-to-stdio bridge:

1. Create or edit `.kiro/settings/mcp.json` in your workspace:
   ```json
   {
     "mcpServers": {
       "qt4-docs": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-client-http",
           "http://127.0.0.1:8000/mcp"
         ],
         "disabled": false
       }
     }
   }
   ```
2. Save the file and restart Kiro. The Qt 4.8.4 documentation tools will appear in the MCP panel.

**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.

</details>

<details>
<summary><strong>Generic MCP Clients</strong></summary>

Most MCP clients use a standard configuration format. For HTTP servers:

```json
{
  "mcpServers": {
    "qt4-docs": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

For clients that require a command-based approach with HTTP bridge:

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

</details>

## Deployment
- **Direct (systemd, bare metal, CI runners):**
  - Install with `pip install qt4-doc-mcp-server`.
  - Ensure `.env` points to your Qt docs and writable cache/index directories.
  - Start with `qt4-doc-mcp-server`; add `PRECONVERT_MD=true` for faster first reads.
- **Containerization (roadmap):**
  - Docker support is planned; follow the repository for updates or open an issue if you need it sooner.

## Licensing
- Code: MIT License (see `LICENSE`).
- Qt docs: © The Qt Company Ltd./Digia, licensed under GFDL 1.3. This server
  converts locally obtained docs and includes attribution in outputs. If you
  redistribute a local mirror, include `LICENSE.FDL` and preserve notices.
- See `THIRD_PARTY_NOTICES.md` for more.
