# 本地智能体安装

这个目录下现在只保留两个本地命令入口：

1. 记录/待办优先的 `qingflow-app-user-mcp`
2. 精简 builder 的 `qingflow-app-builder-mcp`

## npm 安装器适用场景

适合这类本地 agent / gateway：

- Claude Desktop
- Cline / Roo / Cursor 这类本地 MCP 客户端
- OpenClaw 风格的本地 agent 容器或本地 gateway
- 任何支持 `command + args + env` 的 stdio MCP 客户端

## 前置条件

- Node.js >= 16.16
- Python >= 3.11
- 安装过程中可以访问 PyPI

如果机器上没有默认 `python3` / `python`，可以先设置：

```bash
export QINGFLOW_MCP_PYTHON=/path/to/python3.11
```

## 安装方式

### 方式 1：在源码目录预热运行环境

```bash
cd qingflow-support/mcp-server
npm install
```

这个模式适合你已经有源码 checkout，只想让当前目录具备本地 agent 可调用的运行时。

### 方式 2：全局安装到当前机器

```bash
cd qingflow-support/mcp-server
npm install -g .
```

### 方式 3：安装到某个本地 agent workspace

```bash
npm install /absolute/path/to/qingflow-support/mcp-server
```

### 方式 4：离线分发 tgz 安装包

先在源码目录打包：

```bash
cd qingflow-support/mcp-server
npm run pack:npm
```

会生成：

```bash
dist/npm/josephyan-qingflow-mcp-<version>.tgz
```

然后在目标机器安装：

```bash
npm install /absolute/path/to/dist/npm/josephyan-qingflow-mcp-<version>.tgz
```

安装时会自动：

1. 创建 `.npm-python/`
2. 在其中建立 Python 虚拟环境
3. 执行 `pip install .`
4. 在安装位置暴露 `qingflow-app-user-mcp`、`qingflow-app-builder-mcp` 命令

## 本地验证

如果你在源码目录执行了 `npm install`，可直接这样启动：

```bash
cd qingflow-support/mcp-server
node ./npm/bin/qingflow-app-user-mcp.mjs
node ./npm/bin/qingflow-app-builder-mcp.mjs
```

如果你是全局安装：

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

如果你是把包安装到了某个本地 agent workspace，命令通常位于：

/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-user-mcp
/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-builder-mcp
```

如果你是从 tgz 安装到某个空目录，命令通常位于：

/absolute/path/to/install-dir/node_modules/.bin/qingflow-app-user-mcp
/absolute/path/to/install-dir/node_modules/.bin/qingflow-app-builder-mcp
```

这是 stdio MCP server，正常情况下不会输出欢迎信息，而是等待客户端连接。

## 客户端配置

### 通用 stdio MCP 客户端

如果你直接使用源码 checkout：

```json
{
  "mcpServers": {
    "qingflow": {
      "command": "node",
      "args": [
        "/absolute/path/to/qingflow-support/mcp-server/npm/bin/qingflow-app-user-mcp.mjs"
      ],
      "env": {
        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
      }
    }
  }
}
```

如果你已经全局安装：

```json
{
  "mcpServers": {
    "qingflow": {
      "command": "qingflow-app-user-mcp",
      "args": [],
      "env": {
        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
      }
    }
  }
}
```

如果你把包安装到了某个本地 agent workspace：

```json
{
  "mcpServers": {
    "qingflow": {
      "command": "/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-user-mcp",
      "args": [],
      "env": {
        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
      }
    }
  }
}
```

### 使用 npx

如果不做全局安装，也可以直接让客户端运行 npm 包里的命令：

```json
{
  "mcpServers": {
    "qingflow-user": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "@josephyan/qingflow-mcp",
        "qingflow-app-user-mcp"
      ],
      "env": {
        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api"
      }
    }
  }
}
```

说明：
- 由于包里不再暴露 `qingflow-mcp` 命令，`npx` 模式应使用 `-p <package> <bin>` 形式

- 源码目录 `npm install` 不会把命令加到全局 PATH；这种模式请用 `node ./npm/bin/qingflow-app-user-mcp.mjs` 或 `node ./npm/bin/qingflow-app-builder-mcp.mjs`
- `npx` 方式适合临时安装或容器化本地 agent
- 全局安装方式更适合长期固定使用的本机开发环境

## 排障

如果安装失败，优先检查：

1. `node -v`
2. `python3 --version`
3. `pip` 是否能访问 PyPI
4. 是否设置了错误的 `QINGFLOW_MCP_PYTHON`

如果需要重装 Python 侧运行环境，可以删掉：

```bash
rm -rf .npm-python
```

然后重新执行：

```bash
npm install
```