# PC 客户端 (Qt 框架) 图形化编程 MCP 服务端方案与集成资源

> 本项目是一个专为基于 **Qt 框架 (Qt C++ / PyQt6 / PySide6)** 开发的 PC 桌面图形化编程客户端，设计的内嵌 **MCP Server (Model Context Protocol)** 完整工业级落地方案。
> 使得用户可以在 AI Agent (如 Cursor、Claude Desktop、Antigravity IDE、Trae 等) 中通过**自然语言描述图形化编程需求**，由 Agent 自动在 Qt 客户端的 `QGraphicsScene` 画布侧实时完成组件拖拽、接口引脚连线与拓扑渲染！

---

## 📁 目录结构与资源导航

```text
mcp-visual-programming-pc-client/
├── README.md                              # 本文档（极简快速开始）
├── docs/                                  # 细化的具体方案与技术规范文档
│   ├── 01_Architecture_Design.md         # 架构设计方案与 Qt 线程安全通信机制 (QThread + Signals)
│   ├── 02_MCP_Tools_Specification.md      # 7 大 MCP 工具接口定义与参数规范
│   ├── 03_CModel_Parsing_Guide.md         # cmodel 模型文件解析与画布拓扑映射指南
│   └── 04_Deployment_and_Integration.md   # 部署方式、PyInstaller 打包与 IDE 接入指南
├── src/                                   # 模块化核心源代码
│   ├── model_parser/                      # cmodel 模型文件解析模块 (CModelReader)
│   │   └── cmodel_reader.py
│   └── qt_client/                         # Qt 界面与内嵌 MCP 引擎通信模块
│       ├── main_window.py                 # Qt 主窗口与 QGraphicsScene 画布
│       └── mcp_thread.py                  # FastMCP 线程与 pyqtSignal 跨线程桥梁
├── resources/                             # 示例资源文件
│   ├── sample_model.cmodel.json           # 示例机器人 cmodel 模型文件
│   └── mcp_config_example.json            # IDE (Cursor/Claude/Trae) 接入配置文件
├── run_qt_client.py                       # 客户端程序一键启动入口
└── requirements.txt                       # 依赖清单 (PyQt6, FastMCP, uvicorn)
```

---

## 🌟 三大业务需求设计摘要

1. **根据已有模型文件 (cmodel) 编程**：由 `src/model_parser/cmodel_reader.py` 动态解析 `.cmodel` 模型描述包，自动提取设备器件（如主控 `G_MainController`、激光雷达 `LS-MR-LS`、舵轮 `Steerwheel_FL`、电池组等）及其 API 端口。
2. **依据接口节点编程**：提供引脚端口级连线 Tool `connect_interface_ports`，支持在设备器件节点的引脚端口（如 `getMinDistance.distanceMeters`）与控制器引脚端口间自动建立贝塞尔连线。
3. **器件对象节点 + 通用节点库**：划分为模型器件节点（`DEVICE_OBJECT_NODE`）与通用逻辑节点（`COMMON_FLOW_NODE`：`Flow_IfElse`, `Flow_Loop`, `Func_PIDController`, `Var_GlobalDouble`）。

---

## 🚀 极简快速开始

```bash
git clone https://github.com/doghelWang/mcp-visual-programming-pc-client.git
cd mcp-visual-programming-pc-client

# 1. 安装依赖
pip install -r requirements.txt

# 2. 运行 Qt 图形化客户端
python3 run_qt_client.py
```

### 配置 IDE (`mcp.json`)

在 **Cursor / Antigravity IDE / Claude Desktop / Trae** 的 `mcp.json` 中添加配置：

```json
{
  "mcpServers": {
    "qt-visual-programming-client": {
      "command": "python3",
      "args": [
        "/Users/wangfeifei/code/mcp-visual-programming-pc-client/run_qt_client.py"
      ],
      "env": {
        "AMR_MODEL_FILE": "/Users/wangfeifei/code/mcp-visual-programming-pc-client/resources/sample_model.cmodel.json"
      }
    }
  }
}
```

在 AI 聊天框直接输入：
> **“请帮我在 Qt 客户端画布上自动创建一个激光雷达实时获取距离并进行避障制动的图形化编程流程。”**

即可看到 Qt 窗口画布自动绘制节点与拓扑连线！

---

## 📖 详细方案文档链接

- 📘 [01. 软件架构设计与 Qt 线程通信方案](file:///Users/wangfeifei/code/mcp-visual-programming-pc-client/docs/01_Architecture_Design.md)
- 📙 [02. MCP 接口协议与 Tools 规范文档](file:///Users/wangfeifei/code/mcp-visual-programming-pc-client/docs/02_MCP_Tools_Specification.md)
- 📗 [03. cmodel 模型解析与拓扑映射规范](file:///Users/wangfeifei/code/mcp-visual-programming-pc-client/docs/03_CModel_Parsing_Guide.md)
- 📙 [04. 部署方式、打包编译与 IDE 接入指南](file:///Users/wangfeifei/code/mcp-visual-programming-pc-client/docs/04_Deployment_and_Integration.md)