@qingflow-tech/qingflow-app-user-mcp 1.0.0

package/README.md

@@ -0,0 +1,37 @@
+# Qingflow App User MCP
+
+Install:
+
+```bash
+npm install @qingflow-tech/qingflow-app-user-mcp@1.0.0
+```
+
+Run:
+
+```bash
+npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.0 qingflow-app-user-mcp
+```
+
+Environment:
+
+- `QINGFLOW_MCP_DEFAULT_BASE_URL`
+- `QINGFLOW_MCP_DEFAULT_QF_VERSION`
+- `QINGFLOW_MCP_HOME`
+
+This package bootstraps a local Python runtime on first install and then starts the `qingflow-app-user-mcp` stdio MCP server.
+
+Bundled skills:
+
+- `skills/qingflow-app-user`
+- `skills/qingflow-record-insert`
+- `skills/qingflow-record-update`
+- `skills/qingflow-record-delete`
+- `skills/qingflow-record-import`
+- `skills/qingflow-task-ops`
+- `skills/qingflow-record-analysis`
+
+Note:
+
+- The skill files are included in the npm package.
+- On install, the package copies them to `$CODEX_HOME/skills` (or `~/.codex/skills` if `CODEX_HOME` is unset).
+- If a stdio MCP client reports `Transport closed`, delete `.npm-python`, reinstall the package, and make sure CLI/user/builder packages are on the same version. The stdio entrypoints refuse runtime bootstrap so install logs never corrupt MCP stdout.

package/docs/local-agent-install.md

@@ -0,0 +1,332 @@
+# 本地智能体安装
+
+这个目录下现在有三个本地命令入口：
+
+1. 统一 CLI：`qingflow`
+2. 记录/待办优先的 `qingflow-app-user-mcp`
+3. 精简 builder 的 `qingflow-app-builder-mcp`
+
+## 本地鉴权推荐方案
+
+本地模式现在推荐优先使用 `credential` 建立会话，而不是直接注入 `token`。
+
+推荐链路：
+
+1. createClaw 或其它本地宿主为当前实例保存 `credential`
+2. 本地 MCP 调用 `auth_use_credential`
+3. MCP 用该 `credential` 请求 apaas `/mcp/auth/context`
+4. 解析并保存 `token / wsId / qfVersion / uid`
+5. 业务工具直接使用这份上下文
+
+`auth_use_credential` 是本地唯一鉴权主路径。
+
+## 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/qingflow-tech-qingflow-cli-<version>.tgz
+dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
+dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
+```
+
+然后在目标机器安装：
+
+```bash
+npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
+npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
+npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
+```
+
+安装时会自动：
+
+1. 创建 `.npm-python/`
+2. 在其中建立 Python 虚拟环境
+3. 执行 `pip install .`
+4. 在安装位置暴露 `qingflow`、`qingflow-app-user-mcp`、`qingflow-app-builder-mcp` 命令
+
+## 本地验证
+
+如果你在源码目录执行了 `npm install`，可直接这样启动：
+
+```bash
+cd qingflow-support/mcp-server
+node ./npm/bin/qingflow.mjs --help
+node ./npm/bin/qingflow-app-user-mcp.mjs
+node ./npm/bin/qingflow-app-builder-mcp.mjs
+```
+
+如果你是全局安装：
+
+```bash
+qingflow --help
+qingflow-app-user-mcp
+qingflow-app-builder-mcp
+```
+
+如果你是把包安装到了某个本地 agent workspace，命令通常位于：
+
+```bash
+/absolute/path/to/agent-workspace/node_modules/.bin/qingflow
+/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 安装到某个空目录，命令通常位于：
+
+```bash
+/absolute/path/to/install-dir/node_modules/.bin/qingflow
+/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",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_WINGS_BASE_URL": "https://ultron.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_WINGS_TOKEN_KEY": "wingsTokenKey",
+        "QINGFLOW_MCP_CREDIT_WINGS_TOKEN_VALUE": "replace-prod-balance-token",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_TOKEN_KEY": "serviceToken",
+        "QINGFLOW_MCP_CREDIT_APAAS_TOKEN_VALUE": "729ed3cc-8eea-11ec-b585-52540009137b",
+        "QINGFLOW_MCP_CREDIT_WS_ID_HEADER_KEY": "wsId",
+        "QINGFLOW_MCP_CREDIT_APAAS_AMOUNT": "1"
+      }
+    }
+  }
+}
+```
+
+如果你已经全局安装：
+
+```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",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_WINGS_BASE_URL": "https://ultron.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_WINGS_TOKEN_KEY": "wingsTokenKey",
+        "QINGFLOW_MCP_CREDIT_WINGS_TOKEN_VALUE": "replace-prod-balance-token",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_TOKEN_KEY": "serviceToken",
+        "QINGFLOW_MCP_CREDIT_APAAS_TOKEN_VALUE": "729ed3cc-8eea-11ec-b585-52540009137b",
+        "QINGFLOW_MCP_CREDIT_WS_ID_HEADER_KEY": "wsId",
+        "QINGFLOW_MCP_CREDIT_APAAS_AMOUNT": "1"
+      }
+    }
+  }
+}
+```
+
+如果你把包安装到了某个本地 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",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_WINGS_BASE_URL": "https://ultron.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_WINGS_TOKEN_KEY": "wingsTokenKey",
+        "QINGFLOW_MCP_CREDIT_WINGS_TOKEN_VALUE": "replace-prod-balance-token",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_TOKEN_KEY": "serviceToken",
+        "QINGFLOW_MCP_CREDIT_APAAS_TOKEN_VALUE": "729ed3cc-8eea-11ec-b585-52540009137b",
+        "QINGFLOW_MCP_CREDIT_WS_ID_HEADER_KEY": "wsId",
+        "QINGFLOW_MCP_CREDIT_APAAS_AMOUNT": "1"
+      }
+    }
+  }
+}
+```
+
+### 使用 npx
+
+如果不做全局安装，也可以直接运行独立包：
+
+```json
+{
+  "mcpServers": {
+    "qingflow-user": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@qingflow-tech/qingflow-app-user-mcp"
+      ],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_WINGS_BASE_URL": "https://ultron.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_WINGS_TOKEN_KEY": "wingsTokenKey",
+        "QINGFLOW_MCP_CREDIT_WINGS_TOKEN_VALUE": "replace-prod-balance-token",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_TOKEN_KEY": "serviceToken",
+        "QINGFLOW_MCP_CREDIT_APAAS_TOKEN_VALUE": "729ed3cc-8eea-11ec-b585-52540009137b",
+        "QINGFLOW_MCP_CREDIT_WS_ID_HEADER_KEY": "wsId",
+        "QINGFLOW_MCP_CREDIT_APAAS_AMOUNT": "1"
+      }
+    },
+    "qingflow-builder": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@qingflow-tech/qingflow-app-builder-mcp"
+      ],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_WINGS_BASE_URL": "https://ultron.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_WINGS_TOKEN_KEY": "wingsTokenKey",
+        "QINGFLOW_MCP_CREDIT_WINGS_TOKEN_VALUE": "replace-prod-balance-token",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_TOKEN_KEY": "serviceToken",
+        "QINGFLOW_MCP_CREDIT_APAAS_TOKEN_VALUE": "729ed3cc-8eea-11ec-b585-52540009137b",
+        "QINGFLOW_MCP_CREDIT_WS_ID_HEADER_KEY": "wsId",
+        "QINGFLOW_MCP_CREDIT_APAAS_AMOUNT": "1"
+      }
+    }
+  }
+}
+```
+
+说明：
+- 源码目录 `npm install` 不会把命令加到全局 PATH；这种模式请用 `node ./npm/bin/qingflow.mjs`、`node ./npm/bin/qingflow-app-user-mcp.mjs` 或 `node ./npm/bin/qingflow-app-builder-mcp.mjs`
+- `npx` 方式适合临时安装或容器化本地 agent
+- 全局安装方式更适合长期固定使用的本机开发环境
+- 计费接口鉴权参数需要分系统配置：`QINGFLOW_MCP_CREDIT_WINGS_TOKEN_KEY/VALUE`（wings）与 `QINGFLOW_MCP_CREDIT_APAAS_TOKEN_KEY/VALUE`（apaas）互不复用
+
+## 排障
+
+如果安装失败，优先检查：
+
+1. `node -v`
+2. `python3 --version`
+3. `pip` 是否能访问 PyPI
+4. 是否设置了错误的 `QINGFLOW_MCP_PYTHON`
+
+如果需要重装 Python 侧运行环境，可以删掉：
+
+```bash
+rm -rf .npm-python
+```
+
+然后重新执行：
+
+```bash
+npm install
+```
+
+如果 MCP 客户端一调用工具就报 `Transport closed`，优先检查这几件事：
+
+1. 不要混用不同版本的 `@qingflow-tech/qingflow-cli`、`@qingflow-tech/qingflow-app-user-mcp`、`@qingflow-tech/qingflow-app-builder-mcp`
+2. 删除安装目录下的 `.npm-python`
+3. 重新执行 `npm install` 或重新安装对应 tgz/npm 包
+4. 再启动 MCP 客户端
+
+现在 stdio MCP 入口会拒绝在启动瞬间“边启动边重建 Python 运行时”，因为安装日志一旦写进 stdout，就会破坏 MCP 握手并表现成 `Transport closed`。如果运行时缺失或版本不一致，入口会直接报错并提示重装，而不是静默自修复。
+
+## createClaw 本地接入示例
+
+如果 createClaw 已经为当前本地实例保存了 `credential`，推荐在首次建链时调用：
+
+```bash
+qingflow auth use-credential \
+  --base-url https://qingflow.com/api \
+  --credential-stdin
+```
+
+然后把 `credential` 写到 stdin。
+
+等价 MCP 工具调用参数：
+
+```json
+{
+  "profile": "default",
+  "base_url": "https://qingflow.com/api",
+  "credential": "1602853_277941",
+  "persist": false
+}
+```
+
+说明：
+
+- `persist=true` 时，本地会优先把解析后的 `token` 和原始 `credential` 写入系统 keychain
+- 当前工作区以 `/mcp/auth/context` 返回的 `wsId` 为准，不再通过本地 MCP 显式切换

package/entry_point.py

@@ -0,0 +1,13 @@
+import sys
+import os
+
+# Ensure the 'src' directory is in the Python search path
+# PyInstaller will pick up everything in src/qingflow_mcp as the package
+src_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "src"))
+if src_path not in sys.path:
+    sys.path.insert(0, src_path)
+
+from qingflow_mcp.server import main
+
+if __name__ == "__main__":
+    main()

package/npm/bin/qingflow-app-user-mcp.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+import { getPackageRoot, spawnServer } from "../lib/runtime.mjs";
+
+const packageRoot = getPackageRoot(import.meta.url);
+
+spawnServer(packageRoot, process.argv.slice(2), "qingflow-app-user-mcp", { allowRuntimeBootstrap: false });