qt4-doc-mcp-server

Qt Documentation MCP サーバー

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

ローカルにインストールした Qt 4.8、Qt 5、または Qt 6 のドキュメントを AI コーディングアシスタントで利用できます。一度に選択できるドキュメントセットは 1 つで、オフラインで動作します。

ツールリファレンス | 変更履歴 | コントリビューション | トラブルシューティング

✨ 特長

• 🔌 オフラインファースト - ローカルのドキュメントのみで動作します
• 🔍 全文検索 - すべての Qt ドキュメントから必要な情報を検索できます
• ⚡ スマートキャッシュ - 繰り返しのクエリにすばやく応答します
• 🎯 フラグメント対応 - 必要に応じて特定のセクションを抽出できます
• 🛠️ MCP 標準 - Claude、VS Code、その他の MCP クライアントと互換性があります

📦 前提条件

• Python 3.11 以降が必要です（Docker イメージを使用する場合は不要です）
• サポート対象のリリース（Qt 4.8、Qt 5、または Qt 6）のQt HTML ドキュメント
  • 同梱のヘルパーがダウンロードするのは 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

次に、QT_DOC_BASE がそのディレクトリを指すように .env を作成します（「設定」を参照）。

クイックスタートコマンド

# 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 コマンドもエイリアスとして引き続き利用できます。

エージェント向け FTS CLI

インデックスを作成した後、エージェントは検索を行い、実体化された Markdown の絶対パスを取得できます。

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

このコマンドは、サーバーと同じ .env 設定を読み込みます。検索の前に、不足または古くなった FTS インデックスを自動的に作成し、不完全な Markdown キャッシュをすべて準備します。その後、各検索結果のタイトル、絶対 .md パス、FTS スニペットを標準出力に出力します。準備メッセージ、エラー、警告は標準エラー出力に出力されます。ドキュメントをその場で変更した後は、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

このリポジトリをクローンせず、公開済みのイメージだけを使う場合は、prepare スクリプトを実行する代わりに 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 インストーラーまたはディストリビューションのドキュメントパッケージに含まれる既存の Qt 5 または Qt 6 の doc/html ツリーも、マウント元として使用できます。

初回起動時に、ドキュメントが変換されて /data ボリュームにインデックスが作成されます。2 回目以降の起動では、それらが再利用されます。ドキュメントセットのサイズによっては、ヘルスエンドポイントが応答するまで、初回起動に 1、2 分かかることがあります。

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 ファイルを作成してください。ヘルパースクリプトが適切なデフォルト値を設定します。必要に応じて調整してください。

ツールは、オンライン URL ではなく、ルートからの相対パスと完全に一致する Markdown パスでドキュメントを識別します。たとえば、Qt 4 のページには qcompleter.md、Qt 5/6 のグローバルページには qtdoc/accessible.md、Qt 5/6 の Core ページには qtcore/qobject.md を使用します。デフォルトでは、各ドキュメントセットは独自のインデックスと Markdown キャッシュを $QT_DOC_BASE/.index/ に保存するため、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 対応エージェントに登録してください。

Stdio トランスポート

HTTP の代わりに stdio でサーバーを実行するには、次のコマンドを使用します。

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"]
    }
  }
}

🛠️ 利用可能なツール

このサーバーは、有効なローカル Qt ドキュメントセットを操作するための 2 つの MCP ツールを提供します。

1. read_documentation - 有効な Qt ドキュメントセットのページを読み込み、Markdown に変換します

   • フラグメントの抽出（#details、#public-functions）
   • start_index と max_length によるページネーション
   • 対象を絞ったコンテンツのためのセクション限定モード
   • リンクを正規化し、GFDL の帰属表示を含む Markdown を返します

2. search_documentation - 有効な Qt ドキュメントセット全体を全文検索します

   • BM25 関連度ランキングを使用した SQLite FTS5
   • 一致箇所をハイライトしたコンテキストスニペット
   • 検索結果数の設定（デフォルト：10、最大：50）

パラメーター、戻り値、例、エラー処理を含む詳細な API ドキュメントについては、**ツールリファレンス**を参照してください。

📚 関連リソース

• Model Context Protocol の仕様
• Qt ドキュメント
• FastMCP フレームワーク
• ツールリファレンス
• 変更履歴
• コントリビューションガイド
• トラブルシューティングガイド

📄 ライセンス

• コード： MIT License（LICENSE を参照）。
• Qt ドキュメント： © The Qt Company Ltd. および貢献者。GFDL 1.3 に基づきライセンスされています。このサーバーはローカルで取得したドキュメントを変換し、出力に帰属表示を含めます。ローカルミラーを再配布する場合は、LICENSE.FDL を含め、通知を保持してください。
• 詳細については THIRD_PARTY_NOTICES.md を参照してください。