# Qingflow App Builder MCP

这个包提供 Qingflow App Builder MCP 的 stdio MCP 服务入口，用于把轻流能力接入支持 MCP 的 AI 客户端或本地 agent 运行时。

## 安装

```bash
npm install @qingflow-tech/qingflow-app-builder-mcp@1.1.41
```

推荐从官网复制这一条一键安装 Qingflow CLI：

```bash
npx qingflow-cli@latest install
```

如果你只想直接安装当前 npm 包，也可以使用上面的 `npm install` 命令。

## 运行

```bash
npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.1.41 qingflow-app-builder-mcp
```

全局安装后可以直接运行：

```bash
qingflow-app-builder-mcp
```

## 常用环境变量

- `QINGFLOW_MCP_DEFAULT_BASE_URL`
- `QINGFLOW_MCP_DEFAULT_QF_VERSION`
- `QINGFLOW_MCP_HOME`

首次安装时会自动初始化本地 Python 运行环境，随后提供 `qingflow-app-builder-mcp` stdio MCP 服务入口。

## 内置 Skills

- `skills/qingflow-app-builder`
- `skills/qingflow-app-builder-code-integrations`
- `skills/qingflow-workflow-builder`
- `skills/qingflow-mcp-setup`

## Skills 安装

包内已包含上面列出的 skill 文件，但安装 npm 包不会自动覆盖本机 agent skills。需要挂载到本地 agent 时，请显式执行：

```bash
qingflow-app-builder-mcp-skills list
qingflow-app-builder-mcp-skills install --agent codex --scope user
```

如果你通过一次性 `npx -p` 执行 skills 安装，建议加 `--copy`，避免 symlink 指向 npm 临时执行缓存：

```bash
npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.1.41 qingflow-app-builder-mcp-skills install --agent codex --scope user --copy
```

`qingflow-app-builder-mcp-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。

## 排障

- 如果 npm 全局目录没有权限，推荐使用 `npx qingflow-cli@latest install`，安装器会自动 fallback 到用户目录。
- 如果本地 MCP 客户端报 `Transport closed`，优先删除安装目录里的 `.npm-python` 后重新安装，并确认 CLI/user/builder 包版本一致。
- stdio MCP 入口不会在启动瞬间重建 Python 运行时，避免安装日志写入 stdout 破坏 MCP 握手。