# qt-mcp

> 一个本地 stdio MCP 服务器，把 Qt 5.14.2 + MinGW 工具链封装成 **148 个 Python 工具**，让 Claude 或任何 MCP 兼容客户端可以直接搭建、构建、运行、测试、格式化、部署、检查 Qt C++ 项目，不用离开对话。

**概述**：本项目把 Qt 5.14.2 工具链（qmake / mingw32-make / windeployqt / moc / lupdate / qmllint / clang-format / cppcheck / signtool / cc / git 等）封装成 148 个 MCP 工具，覆盖 Qt 项目的完整生命周期。MIT 协议，当前版本 `v0.4.4`。

[![Python](https://img.shields.io/badge/python-≥3.10-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.4.4-orange)](CHANGELOG.md)
[![MCP](https://img.shields.io/badge/MCP-1.28%2B-purple)](https://modelcontextprotocol.io)
[![Tools](https://img.shields.io/badge/tools-148-blueviolet)](https://github.com/fan1959/qt-mcp)

---

## 项目特点

- **148 个工具**覆盖 Qt C++ 项目完整生命周期（脚手架 → 构建 → 运行 → 测试 → 静态分析 → 主题样式 → 部署签名 → 数据库 → 网络 → 多媒体 → 部署分发 → 游戏状态 → 信号槽 → Q_PROPERTY → Git → 文档 i18n → 运行时 IDE → 构建系统）
- **本地 FTS5 全文检索**：把 Qt 5.14.2 自带的 6613 页文档建成索引，100 ms 内搜到答案
- **AI 友好的诊断信息**：`qt_build` 把编译器 / moc / uic / 链接器输出解析成结构化 JSON，并给出可执行的修复建议
- **完整的 e2e 测试**：577+ pytest 测试，每个工具配套 happy path + error path + edge case 验证
- **零样例代码污染**：所有 Qt 二进制（`*.exe` / `*.dll`）走 subprocess 调真实 Qt SDK，不引入 C++ 源码

---

## V0.4.4 新增 1 个工具

| 工具 | 作用 |
|---|---|
| `qt_palette_gen` | 生成 QPalette C++ 代码（light/dark 主题），设置 11+ 个 QPalette 角色（Window/Base/Text/Highlight/Disabled 等）。配对 `qt_theme_gen` (QSS) 实现系统级 + per-widget 完整 theming。 |

详见 [CHANGELOG.md](CHANGELOG.md)。

---

## 5 分钟上手

### 前置条件

- Windows 10 / Windows 11
- Qt 5.14.2 已装（默认路径 `E:\Download_tools\QT\5.14.2\mingw73_64`）
- Python ≥ 3.10
- MinGW 730_64 已装

### 安装

```bash
git clone https://github.com/fan1959/qt-mcp.git
cd qt-mcp
pip install -e .
```

### 配到 Claude Code

在 `~/.claude.json` 或 MCP 客户端配置里加：

```json
{
  "mcpServers": {
    "qt-mcp": {
      "command": "python",
      "args": ["-m", "server"]
    }
  }
}
```

### 第一次使用

重启 Claude Code，在对话里说：

> 帮我用 Qt 写一个 hello world 项目

Claude 会调 `qt_scaffold` 生成项目骨架，再调 `qt_build` + `qt_run` 编译运行。整个过程你看着终端输出 + Claude 的解释，不用手动跑命令。

### Qt 路径自定义

如果 Qt 不在默认路径，设环境变量：

```bash
set QT_MCP_QT_ROOT=D:\Qt\5.14.2\mingw73_64    # Windows
export QT_MCP_QT_ROOT=/opt/Qt/5.14.2/gcc_64   # Linux
```

---

## 148 个工具完整清单

> **快速查找**：不确定用什么工具？调 `qt_cheatsheet` 即可拿到按类别分组的完整 quick reference（每次 sprint 加新工具时自动同步）。下面是这个清单的离线版本。

按 17 个类别组织。每条带一句话说明 + 与其他工具的关系。

### 1. 脚手架 / 生成器（14）—— 从零创建 Qt 项目

| 工具 | 用途 |
|---|---|
| `qt_scaffold` | 13 个模板（widget / mainwindow / dialog / qml_app / console_app / tictactoe_game / breakout_game / tasklist / music_player / cards_game / chess_game / generic_game / game_framework）。**首选**创建项目骨架。 |
| `qt_template_scaffold` | 自然语言描述 → 自动选模板（中文/英文关键词匹配）。**更适合 LLM 调用**：直接说"做个井字棋"即可。 |
| `qt_class_wizard` | 生成单个 QObject 子类的 .h/.cpp/.ui 三件套。**用于向现有项目加类**。 |
| `qt_viewmodel_gen` | MVVM ViewModel（Q_PROPERTY + Q_INVOKABLE + signals），配 QML 用。 |
| `qt_model_gen` | QAbstractListModel / QAbstractTableModel 子类，棋牌数据层。 |
| `qt_qml_component_gen` | 6 种 QML 组件（card / board / player / hand / deck / tile），含 qmldir。 |
| `qt_qtquick_3d_setup` | Qt 3D 项目骨架（4 模板：cube / sphere / scene / model_loader）。 |
| `qt_graphics_view_scaffold` | QGraphicsScene + QGraphicsView 教学项目（含拖拽）。 |
| `qt_cpp_tutorial_scaffold` | SCU C++ 强化 9 章 12 个 topic 的 .cpp 教学片段。**纯 C++ 无 Qt**。 |
| `qt_module_split_init` | 把平面 .pro 拆成 lib/ + app/（TEMPLATE=subdirs）。`plan_only=True` 默认。 |
| `qt_module_split_cmake` | CMake 版本的 lib/app 拆分。 |
| `qt_pro_lint` | .pro 文件 12 条 lint 规则（重复 SOURCES、Qt 模块 typo、TEMPLATE 缺失等）。 |
| `qt_pro_edit` | 读写 .pro 变量（list/get/set/append/remove）。**用于批量改 .pro**。 |
| `qt_pro_project_graph` | 扫描 .pro 引用 + #include，emit Graphviz DOT 依赖图。 |

### 2. 构建（6）

| 工具 | 用途 |
|---|---|
| `qt_build` | qmake + mingw32-make + 结构化 JSON 诊断。**最常用**。 |
| `qt_build_diagnostics` | 读 .qt_mcp_last_build.log 解析成 JSON（不重编译）。 |
| `qt_clean` | 移除 build artifacts（debug/ release/ moc_*.cpp/ ui_*.h 等）。 |
| `qt_shadow_build_setup` | build-debug/ + build-release/ + .pro.user + build_shadow.bat。 |
| `qt_build_cache` | ccache / sccache 检测 + 注入 QMAKE_CXX = ccache g++（5-10× 加速）。 |
| `qt_watch` | auto-rebuild on file change（watchdog）。 |

### 3. 运行 / 性能（4）

| 工具 | 用途 |
|---|---|
| `qt_run` | 启动 .exe（foreground 或 detached GUI）。**配 qt_kill_exe**。 |
| `qt_run_trace` | QT_LOGGING_RULES=*=true 捕获 trace 日志。 |
| `qt_perf_budget` | 启动延迟预算（first_cpu + first_window）。**CI gate**：是否在 budget_ms 内启动。 |
| `qt_perf_compare` | 与 baseline JSON 对比。**CI gate**：是否比上次慢 >regression_ms。 |

### 4. 测试（6）

| 工具 | 用途 |
|---|---|
| `qt_test` | QTestLIB C++ test exe + 解析 PASS/FAIL。 |
| `qt_qml_test` | qmltestrunner + 解析 TestCase 输出。 |
| `qt_test_fuzz` | libFuzzer skeleton（MinGW 需 clang++）。 |
| `qt_sanitizer_run` | ASan / UBSan / TSan 集成。 |
| `qt_coverage` | gcov + lcov → HTML 报告。 |
| `qt_test_coverage_diff` | 两个 lcov .info 对比覆盖率回归。 |

### 5. 静态分析 / Lint（15）

| 工具 | 用途 |
|---|---|
| `qt_lint` | cpplint + qmllint + clang-tidy 一站式。 |
| `qt_analyze` | clang-tidy 自定义检查（bugprone-*/performance-*）。 |
| `qt_clazy_check` | Qt 反模式 regex 检查（无 clazy 二进制依赖）。 |
| `qt_cppcheck` | cppcheck --json + Qt library。 |
| `qt_complexity_lint` | McCabe 圈复杂度 per function（threshold 默认 12）。 |
| `qt_format` / `qt_format_check` | clang-format 修 / 审计。 |
| `qt_documentation_lint` | doxygen 注释覆盖率（@brief/@param/@return）。 |
| `qt_async_await_lint` | QtConcurrent / QFuture / QThreadPool 7 条反模式。 |
| `qt_concurrency_lint` | QObject 跨线程并发 8 条规则。 |
| `qt_thread_affinity_check` | QObject 跨线程信号连接 4 条规则。 |
| `qt_qml_lint` | qmllint 包装。 |
| `qt_qml_perf_lint` | QML 运行时性能 6 条规则。 |
| `qt_qml_property_linter` | QML property 静态分析（unused/shadowed/mismatch）。 |
| `qt_layout_check` | .ui XML 布局反模式（5 条规则）。 |
| `qt_accessibility_check` | C++ 源码 a11y 扫描（缺 setAccessibleName / setObjectName 等）。 |

### 6. 信号与槽 / QObject（6）

| 工具 | 用途 |
|---|---|
| `qt_signal_slot_trace` | connect()/signals/slots 静态分析（text/json/dot）。 |
| `qt_signal_disconnect_check` | 找无配对 disconnect 的 connect site（生命周期泄漏）。 |
| `qt_signal_lint_fix` | 自动修 4 类反模式（unique_connection/queued_connection/functor_to_pointer/orphan_slot_stub）。 |
| `qt_qobject_invoke_metadata` | 静态 QObject 反射（signals/slots/Q_INVOKABLE/Q_PROPERTY）。 |
| `qt_qobject_invoke_property_diff` | 对比两 header set 的 QObject metadata 漂移。 |
| `qt_qobject_invocation_count` / `_history` / `_connect_monitor` | invokeMethod 调用计数 / 运行时 history / connect 拓扑热图。 |

### 7. Q_PROPERTY / Runtime 反射（5）

| 工具 | 用途 |
|---|---|
| `qt_property_browser` | 提取 Q_PROPERTY 渲染为 markdown/html/json 表。 |
| `qt_hotreload_check` | Q_PROPERTY 完整性（missing_notify / signal_not_found 等 7 条）。 |
| `qt_invoke_helper_gen` | 生成 Qt helper .exe（QApplication + QObject + JSON 协议）。 |
| `qt_qproperty_set` | 运行时通过 helper set Q_PROPERTY。 |
| `qt_meta_invoke` | 运行时通过 helper invoke Q_INVOKABLE。 |

### 8. 主题 / 样式（3）

| 工具 | 用途 |
|---|---|
| `qt_theme_gen` | QSS 完整 stylesheet（light/dark）。 |
| `qt_qstyle_sheet_gen` | QSS 14 个 widget selector 子集。 |
| `qt_qss_inspect` | 解析 .qss 报告 selector / property / 重复。 |
| `qt_palette_gen` | **QPalette C++ 代码生成（light/dark）**。配 qt_theme_gen 做完整 theming。 |

### 9. 多媒体 / 资源（5）

| 工具 | 用途 |
|---|---|
| `qt_audio` | 音频 list/probe/play snippet（QSoundEffect / QMediaPlayer）。 |
| `qt_audio_convert` | ffmpeg 批量转 mp3/opus/wav/ogg/flac。 |
| `qt_ico_create` | 多分辨率 .ico from PNG（16/32/48/64/128/256）。 |
| `qt_multimedia_setup` | QtMultimedia 启动项目（QMediaPlayer + QSoundEffect + QVideoWidget + .qrc）。 |
| `qt_svg_to_png` | SVG → PNG 多宽度（cairosvg + ImageMagick）。 |

### 10. 数据库（7）

| 工具 | 用途 |
|---|---|
| `qt_db_seed` | 创建 SQLite schema + seed data + CRUD 示例。 |
| `qt_db_validate` | FK integrity + orphan-row scan + integrity_check。 |
| `qt_db_dump` | SQLite → CSV/JSON/SQL dump。 |
| `qt_db_perf_index` | 索引建议器（EXPLAIN QUERY PLAN + CREATE INDEX SQL）。 |
| `qt_db_schema_diff` | 两个 .db schema 对比 + migration SQL。 |
| `qt_db_open_in_gui` | SQLiteStudio 集成（QT_MCP_DBGUI_EXE 覆盖）。 |
| `qt_mysql_setup` | Qt + MySQL/MariaDB starter + SETUP.md（关键：Qt 5.14 MinGW 不带 QMYSQL）。 |

### 11. 网络（3）

| 工具 | 用途 |
|---|---|
| `qt_network` | QTcpSocket / QTcpServer / QUdpSocket / QWebSocket 类骨架。 |
| `qt_http_client_gen` | QNetworkAccessManager HTTP 客户端（GET/POST + async/sync）。 |
| `qt_ftp_client_gen` | QNetworkAccessManager FTP 客户端（替代被移除的 QFtp）。 |

### 12. 文档 / i18n（7）

| 工具 | 用途 |
|---|---|
| `qt_docs_search` | FTS5 全文搜本地 Qt 5.14.2 文档（100ms 内）。 |
| `qt_docs_gen` | 生成 Doxyfile + doxygen 运行。 |
| `qt_documentation_auto_fill` | LLM 补 doxygen @brief/@param/@return（dry_run 默认）。 |
| `qt_translate` | lupdate + lrelease 完整流程。 |
| `qt_translation_validate` | .ts 翻译覆盖率（每语言 finished/total）。 |
| `qt_translation_sync` | 源 tr() vs .ts 同步（找 missing/orphan）。 |
| `qt_translation_auto_fill` | LLM 填 .ts unfinished 条目（dry_run 默认）。 |

### 13. 部署 / 分发（9）

| 工具 | 用途 |
|---|---|
| `qt_deploy` | windeployqt 打包 DLL。 |
| `qt_deploy_bundle` | **一站式**：windeployqt + signtool + NSIS installer 串联。 |
| `qt_signature` / `qt_signature_batch` | signtool.exe 单文件 / 批量签名。 |
| `qt_installer_gen` | NSIS / Inno Setup 脚本 + build_installer.bat。 |
| `qt_cmake_install` | CMake install() + CPack NSIS + windeployqt 集成。 |
| `qt_appx` | Microsoft Store (MSIX/AppX) 打包。 |
| `qt_steamworks_init` | Steamworks SDK 集成骨架（SteamAPI_Init + Achievements）。 |
| `qt_itch_butler` | itch.io .itch.toml + butler push 脚本。 |

### 14. 环境 / SDK（6）

| 工具 | 用途 |
|---|---|
| `qt_env` | 展示 Qt / MinGW 路径 + 版本。 |
| `qt_diagnose_env` | 健康检查（16+ 二进制 + 32/64-bit + PATH）。 |
| `qt_pkg` | 列已装 Qt 5 模块（headers/libs/plugins）。 |
| `qt_pkg_install` | aqtinstall 装 / 卸 Qt SDK。 |
| `qt_env_diff` | 两个 Qt SDK 安装对比（qmake 版本 + 模块差异）。 |
| `qt_dll_search_path` | 分析 .exe DLL 搜索路径（找缺失 Qt5*.dll）。 |

### 15. 文件 / 资源（6）

| 工具 | 用途 |
|---|---|
| `qt_validate` | .pro SOURCES/HEADERS/FORMS/RESOURCES 引用完整性。 |
| `qt_diff` | 两个 .pro 项目对比（变量 + SHA1）。 |
| `qt_gen_qrc` | 扫描图片目录 → emit .qrc。 |
| `qt_assets` | 高级 .qrc + 可选 Q_INIT_RESOURCE cpp。 |
| `qt_resources` | .qrc 增删改查（list/add/remove/validate）。 |
| `qt_resource_validate` | 深挖 .qrc（naming / case-collision / depth / size / prefix）。 |

### 16. Git / 合规（4）

| 工具 | 用途 |
|---|---|
| `qt_git_init` | 初始化 git repo（Qt 专用 .gitignore）。 |
| `qt_git_audit` | git 历史洞察（hot files / bus factor / churn / stale branches）。 |
| `qt_release_notes` | 自动生成 CHANGELOG.md 段（conventional-commits 分类）。 |
| `qt_copyright` | license 头批量加（SPDX 检测）。 |

### 17. 游戏 / 状态 / UI 工具（12）

| 工具 | 用途 |
|---|---|
| `qt_state` | QSettings 包装（APPDATA 持久化）。 |
| `qt_save` | JSON save files（便携 + 易检查）。 |
| `qt_score` | 玩家排行榜（leaderboard）。 |
| `qt_timer` | 命名计时器（turn time / total game）。 |
| `qt_replay` | 步骤回放系统。 |
| `qt_undo` | undo / redo 状态栈。 |
| `qt_achievement` | 游戏成就系统。 |
| `qt_leaderboard_ui` | leaderboard widget（table 或 cards）。 |
| `qt_anim` | QPropertyAnimation 代码生成（fade/move/scale/rotate/color/sequence）。 |
| `qt_input` | 键盘 / 鼠标 / 手柄 / focus chain / JSON 映射代码生成。 |
| `qt_input_recorder` | 鼠标键盘事件录制/回放（pyautogui）。 |
| `qt_anim` (paintEvent 子类型) | double_buffer / painter_path / doodle_board（v0.3.8 教学性增强）。 |

### 18. 运行时 / IDE（7）

| 工具 | 用途 |
|---|---|
| `qt_ui_action` | pywinauto 驱动运行中 Qt app（点击 / 输入 / 截图）。 |
| `qt_widget_introspect` | snapshot/find/details 三合一 widget 树探查（0xCarbon 借鉴）。 |
| `qt_runtime_props` | 运行时 widget accessible properties 快照（借 0xCarbon qt_props）。 |
| `qt_console_messages` | 抓运行中 Qt app 的 QPlainTextEdit / QStatusBar 文本。 |
| `qt_creator_open` | Qt Creator 直接打开 .pro（跳过欢迎页）。 |
| `qt_creator_run` | Qt Creator 内 Ctrl+B + 启动 .exe。 |
| `qt_designer` | designer.exe 打开 .ui 文件。 |
| `qt_ide_metadata` | 生成 .vscode/* + .idea/* 元数据（VSCode/CLion debug）。 |

### 19. 构建系统 / 包管理（5）

| 工具 | 用途 |
|---|---|
| `qt_cmake` | 生成 CMakeLists.txt（Qt5/Qt6 切换）。 |
| `qt_conanfile_gen` | Conan recipes（conanfile.py + conanfile.txt + profiles）。 |
| `qt_conda_env_gen` | conda-forge Qt 包（environment.yml + install 脚本）。 |
| `qt_module_split_init` (CMake 版) | qt_module_split_cmake 同主题。 |
| `qt_cmake_install` | 见上文 部署/分发 段。 |

### 20. 杂项（5）

| 工具 | 用途 |
|---|---|
| `qt_cheatsheet` | **发现入口**：打印 148 工具 quick reference（按 20 类别分组）。 |
| `qt_moc_check` | 单文件 moc 验证（不重编译）。 |
| `qt_deps` | objdump 列 .exe DLL 依赖。 |
| `qt_kill_exe` | 终止 Qt 进程（taskkill /IM）。 |
| `qt_smoke_test` | clean → build → run 三步健康检查。 |
| `qt_log` | Qt log 按 level/category 过滤分析。 |
| `qt_code_metrics` | 项目健康报告（LOC / 注释率 / 函数复杂度等）。 |
| `qt_heap_snapshot` | 解析 Valgrind massif / heaptrack 输出。 |
| `qt_asan_runtime_report` | 把 ASan/UBSan/TSan 报告翻译成中文 + 修复建议。 |
| `qt_modernize_qt5_to_qt6` | Qt 5 → Qt 6 自动迁移（6 条规则，dry_run 默认）。 |
| `qt_modernize_qt6_string_literal` | `tr("中文")` → `tr(u"中文")` + u"" 前缀。 |
| `qt_screenshot_diff` / `qt_screenshot_baseline_capture` / `qt_high_dpi_test` | 视觉回归（pixel diff + baseline 捕获 + 多 DPI）。 |

**总计：148 个工具**（v0.4.4 + 1；v0.4.3 + 4；v0.4.2 + 4；v0.4.1 + 3；v0.3.8 + 7；v0.3.7 + 12；v0.3.6 + 5；v0.3.5 + 6；v0.3.4 + 5；v0.3.3 + 5；v0.3.2 + 5；v0.3.1 + 3；v0.3.0 + 4；v0.2.9 + 8；v0.2.8 + 6；v0.2.7 + 8；v0.2.6 + 5；v0.2.5 + 4；v0.2.4 + 5；v0.2.3 + 8；v0.2.0–v0.2.2 + 13）

---

## 决策指南：哪个工具做什么

| 你想做什么？ | 用这些工具 |
|---|---|
| **从零做 Qt 项目** | `qt_scaffold --template=mainwindow` → `qt_build` → `qt_run` |
| **自然语言描述 → 自动选模板** | `qt_template_scaffold --description="..."` |
| **加新类** | `qt_class_wizard` |
| **加 QML 组件** | `qt_qml_component_gen --components=card` |
| **完整暗色主题** | `qt_palette_gen --mode=dark` → `qt_theme_gen --mode=dark` → 在 main.cpp 里 `applyPalette(*qApp); qApp->setStyleSheet(...)` |
| **写测试** | `qt_test`（C++）/ `qt_qml_test`（QML）/ `qt_test_fuzz`（fuzzing） |
| **静态分析** | `qt_lint` 一站式 / `qt_clazy_check` Qt 专属 / `qt_complexity_lint` 圈复杂度 |
| **CI 质量门** | `qt_build` + `qt_test` + `qt_perf_budget` + `qt_format_check` + `qt_test_coverage_diff` |
| **打包部署** | `qt_deploy_bundle`（一站式）或 `qt_deploy` + `qt_signature` + `qt_installer_gen` |
| **上 Steam** | `qt_steamworks_init` |
| **上 Microsoft Store** | `qt_appx` |
| **上 itch.io** | `qt_itch_butler` |
| **数据库持久化** | `qt_db_seed` → `qt_db_validate` → `qt_db_dump` |
| **MySQL 后端** | `qt_mysql_setup`（重要：Qt 5.14 不带 QMYSQL 驱动） |
| **HTTP API** | `qt_http_client_gen --method=POST` |
| **TCP 多人游戏** | `qt_network --skeleton_type=tcp_server` |
| **国际化** | `qt_translate` → `qt_translation_validate` → `qt_translation_sync` → `qt_translation_auto_fill`（LLM 填） |
| **修 signal/slot 反模式** | `qt_signal_slot_trace` 诊断 → `qt_signal_lint_fix --apply` 修 |
| **doxygen 注释补全** | `qt_documentation_lint` 找缺失 → `qt_documentation_auto_fill --apply` 补 |
| **Qt 5 → Qt 6 升级** | `qt_modernize_qt5_to_qt6 --apply` + `qt_modernize_qt6_string_literal --apply` |
| **跨平台依赖管理** | `qt_conanfile_gen`（Conan）或 `qt_conda_env_gen`（conda-forge） |
| **性能分析** | `qt_perf_budget` + `qt_perf_compare` + `qt_heap_snapshot` + `qt_asan_runtime_report` |
| **大项目拆分 lib/app** | `qt_module_split_init`（qmake）或 `qt_module_split_cmake`（CMake） |
| **打开 Qt Creator** | `qt_creator_open` |
| **在 VSCode/CLion 调试** | `qt_ide_metadata` |
| **找工具/查文档** | `qt_cheatsheet` / `qt_docs_search` |

---

## 完整工作流示例

### 示例 1：棋牌游戏全链路

```
1. qt_scaffold --template=chess_game --name=mygame
2. qt_theme_gen --mode=dark --output_file=mygame/dark.qss
3. qt_palette_gen --mode=dark --output_header=mygame/dark_palette.h
4. qt_qml_component_gen --components=card,board,tile
5. qt_assets --assets_dir=mygame/images/
6. qt_model_gen --class_name=CardModel
7. qt_viewmodel_gen --class_name=GameViewModel --properties=[...]
8. qt_state --action=save --key=score --data={...}    # 存档
9. qt_score --action=add --player=Alice --score=100    # 排行榜
10. qt_timer --action=start --timer_id=turn1
11. qt_input --action=keyboard --key_sequence=Esc --slot_name=onPause
12. qt_audio_convert --input_files=sfx/*.wav --output_format=mp3
13. qt_anim --animation_type=fade
14. qt_network --skeleton_type=tcp_server
15. qt_achievement --action=define --achievement_id=first_win
16. qt_undo --action=push --state_data={...}
17. qt_build
18. qt_test
19. qt_high_dpi_test --scale_factors=1.0,2.0
20. qt_screenshot_diff --image_a=baseline.png --image_b=current.png
21. qt_clazy_check --project_dir=mygame/
22. qt_translation_validate --ts_files=mygame/i18n/*.ts
23. qt_deploy_bundle --executable=mygame/release/mygame.exe
24. qt_signature_batch --action=sign --directory=mygame/deploy/
```

### 示例 2：Qt 5 → Qt 6 升级

```
1. qt_modernize_qt5_to_qt6 --project_dir=. --rule_ids=qregexp_to_qregularexpression
2. qt_modernize_qt6_string_literal --project_dir=. --apply
3. qt_build   # 验证编译通过
4. qt_test    # 验证测试通过
```

### 示例 3：CI 质量门（GitHub Actions）

```yaml
- run: qt_smoke_test --project_dir=. --run_seconds=10
- run: qt_format_check --target=. --init_clang_format=true
- run: qt_perf_budget --executable=release/myapp.exe --budget_ms=2000
- run: qt_test_coverage_diff --baseline_info=coverage_old.info --current_info=coverage.info
```

---

## 环境变量

| 变量 | 默认值 | 作用 |
|---|---|---|
| `QT_MCP_QT_ROOT` | `E:\Download_tools\QT\5.14.2\mingw73_64` | Qt 5.14.2 安装根目录 |
| `QT_MCP_QT_32_ROOT` | `E:\Download_tools\QT\5.14.2\mingw73_32` | Qt 32-bit 安装目录 |
| `QT_MCP_MINGW_BIN` | `E:\Download_tools\QT\Tools\mingw730_64\bin` | 64-bit MinGW bin/ |
| `QT_MCP_SANDBOX` | `E:\Download_tools\QT` | sandbox 根目录，所有 MCP 输入输出必须在此目录下 |
| `QT_MCP_JSON` | （未设）| 设为 `1` 时每个工具输出末尾追加 JSON footer（调试 / LLM 解析） |
| `QT_MCP_FFMPEG` | `E:\Download_tools\ffmpeg-8.1.1-essentials_build\bin\ffmpeg.exe` | ffmpeg 路径（`qt_audio_convert` 用） |
| `QT_MCP_DBGUI_EXE` | `C:/Program Files/SQLiteStudio/SQLiteStudio.exe` | SQLite GUI（`qt_db_open_in_gui` 用） |
| `QT_MCP_CPPCHECK_EXE` | `cppcheck`（PATH） | cppcheck 路径 |
| `QT_MCP_QT_VERSION` | `5.14.2` | Qt 版本（写入元数据） |

---

## 架构

```
Claude / MCP 客户端
       │ stdio JSON (一行 JSON 一个命令)
       ▼
  server.py (FastMCP)
       │
       ├─ 148 个 @mcp.tool 装饰的 async def qt_xxx(params) → str
       │
       ├─ 共享 helpers
       │   ├─ _json_footer()    # 每个工具结尾加 {ok, data}（QT_MCP_JSON 门控）
       │   ├─ _require_sandbox()  # 拦截 sandbox 外路径
       │   └─ _strip_comments()    # 静态分析前剥离注释
       │
       └─ subprocess 调 Qt SDK + 外部工具
              ├─ qmake / mingw32-make / windeployqt
              ├─ moc / uic / rcc / lupdate / lrelease
              ├─ qmllint / clang-format / cppcheck / ffmpeg
              ├─ objdump / signtool / git
              └─ pywinauto + UI Automation (运行时 widget 探查)
```

详细架构图见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

---

## 跑测试

```bash
cd qt-mcp
unset QT_MCP_SANDBOX        # 让所有工具用默认 sandbox
python -m pytest -q         # 577+ passed in ~3min
```

或跑单个套件：

```bash
python -m pytest tests/full/e2e_new_tools_v32.py -v   # V0.4.4 新工具（10 tests）
python -m pytest tests/light/ -v                      # 快速 smoke（不需要 Qt SDK）
```

**CI** 在每次 push / PR 时自动跑（`.github/workflows/ci.yml`）：Windows runner + Python 3.12 + 全套测试。

---

## 项目结构

```
qt-mcp/
├── server.py              ⭐ 148 个工具全在这一个文件（约 30K 行）
├── pyproject.toml         pip install 配置
├── README.md              本文件
├── CHANGELOG.md           版本历史
├── PROJECT_FILES.md       文件结构详解
├── LICENSE                MIT 协议
│
├── docs/                  架构图 + 演示截图
├── examples/minimal/      5 分钟跑通的 hello Qt 示例
├── tests/                 577+ pytest（tests/full + tests/light）
├── .github/               issue / PR 模板 + GitHub Actions CI
└── docs_data/             Qt 文档 FTS5 索引（51 MB，由 build_docs_index.py 生成）
```

详见 [PROJECT_FILES.md](PROJECT_FILES.md)。

---

## 添加新工具

参考 `qt_palette_gen`（V0.4.4 新加）的流程：

1. 在 `server.py` 合适位置插入 Pydantic Input + `@mcp.tool` 函数（约 200 行）
2. 在 `qt_cheatsheet` catalog 加一行：`"qt_xxx": ("category", "description")`
3. 加 e2e 测试到 `tests/full/e2e_new_tools_v<N+1>.py`（至少 5 个测试：happy / edge / error）
4. 更新 [README.md](README.md) 工具表 + 决策指南 + [CHANGELOG.md](CHANGELOG.md) 加 V0.X.Y 段
5. 跑 `pytest -q` 验证 + 新套件 10/10 PASS
6. **提醒用户重启 Claude Code**（stdio MCP server 缓存工具列表，加完要重启才生效）

---

## 协议

MIT 协议。可随便用、商用、改源码、闭源分发。详见 [LICENSE](LICENSE)。

## 贡献

欢迎 PR。提交前请确认：
- 新功能有 Pydantic Input + 完整 docstring (Args/Returns/Raises/Note) + 至少 5 个 e2e 测试
- 现有测试全 PASS（577+）
- 更新 [README.md](README.md) + [CHANGELOG.md](CHANGELOG.md)
- `.github/PULL_REQUEST_TEMPLATE.md` 检查清单全勾

## 仓库

- **GitHub**: https://github.com/fan1959/qt-mcp
- **Issues**: https://github.com/fan1959/qt-mcp/issues
- **当前版本**: V0.4.4 (2026-09)