@josephyan/qingflow-app-user-mcp 0.2.0-beta.10 → 0.2.0-beta.1000

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.10
+npm install @josephyan/qingflow-app-user-mcp@0.2.0-beta.1000
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.10 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@0.2.0-beta.1000 qingflow-app-user-mcp
 ```
 
 Environment:
@@ -20,11 +20,18 @@ Environment:
 
 This package bootstraps a local Python runtime on first install and then starts the `qingflow-app-user-mcp` stdio MCP server.
 
-Bundled skill:
+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

@@ -1,9 +1,30 @@
 # 本地智能体安装
 
-这个目录下现在只保留两个本地命令入口：
+这个目录下现在有三个本地命令入口：
 
-1. 记录/待办优先的 `qingflow-app-user-mcp`
-2. 精简 builder 的 `qingflow-app-builder-mcp`
+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` 是本地唯一鉴权主路径。
+
+补充说明：
+
+- 对 stdio MCP 来说，主路径仍然只有 `auth_use_credential`。
+- 如果你是在终端里直接使用 `qingflow` CLI，可以额外使用 `qingflow auth login` 作为“人类登录”入口；默认会提示轻流邮箱和隐藏密码，拿到 `token` 后建立本地 CLI 会话。
+- 也就是说，这次新增的是 CLI 的登录入口，不是给 MCP 增加第二套会话模型。
 
 ## npm 安装器适用场景
 
@@ -62,15 +83,17 @@ npm run pack:npm
 会生成：
 
 ```bash
-dist/npm/josephyan-qingflow-app-user-mcp-<version>.tgz
-dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
+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/josephyan-qingflow-app-user-mcp-<version>.tgz
-npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-builder-mcp-<version>.tgz
+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
 ```
 
 安装时会自动：
@@ -78,7 +101,7 @@ npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-builder-mcp-<versi
 1. 创建 `.npm-python/`
 2. 在其中建立 Python 虚拟环境
 3. 执行 `pip install .`
-4. 在安装位置暴露 `qingflow-app-user-mcp`、`qingflow-app-builder-mcp` 命令
+4. 在安装位置暴露 `qingflow`、`qingflow-app-user-mcp`、`qingflow-app-builder-mcp` 命令
 
 ## 本地验证
 
@@ -86,6 +109,7 @@ npm install /absolute/path/to/dist/npm/josephyan-qingflow-app-builder-mcp-<versi
 
 ```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
 ```
@@ -93,6 +117,7 @@ node ./npm/bin/qingflow-app-builder-mcp.mjs
 如果你是全局安装：
 
 ```bash
+qingflow --help
 qingflow-app-user-mcp
 qingflow-app-builder-mcp
 ```
@@ -100,6 +125,7 @@ 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
 ```
@@ -107,6 +133,7 @@ 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
 ```
@@ -129,7 +156,10 @@ qingflow-app-builder-mcp
       ],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     }
   }
@@ -146,7 +176,10 @@ qingflow-app-builder-mcp
       "args": [],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     }
   }
@@ -163,7 +196,10 @@ qingflow-app-builder-mcp
       "args": [],
       "env": {
         "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
-        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp"
+        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     }
   }
@@ -184,7 +220,10 @@ qingflow-app-builder-mcp
         "@josephyan/qingflow-app-user-mcp"
       ],
       "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api"
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     },
     "qingflow-builder": {
@@ -194,7 +233,10 @@ qingflow-app-builder-mcp
         "@josephyan/qingflow-app-builder-mcp"
       ],
       "env": {
-        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api"
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
+        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
+        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
+        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
       }
     }
   }
@@ -202,9 +244,10 @@ qingflow-app-builder-mcp
 ```
 
 说明：
-- 源码目录 `npm install` 不会把命令加到全局 PATH；这种模式请用 `node ./npm/bin/qingflow-app-user-mcp.mjs` 或 `node ./npm/bin/qingflow-app-builder-mcp.mjs`
+- 源码目录 `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
 - 全局安装方式更适合长期固定使用的本机开发环境
+- 计费接口使用当前登录会话的 `token` 与 `wsId` 请求头，可通过 `QINGFLOW_MCP_CREDIT_APAAS_BASE_URL/PATH` 覆盖调用记录接口地址
 
 ## 排障
 
@@ -226,3 +269,41 @@ rm -rf .npm-python
 ```bash
 npm install
 ```
+
+如果 MCP 客户端一调用工具就报 `Transport closed`，优先检查这几件事：
+
+1. 不要混用不同版本的 `@josephyan/qingflow-cli`、`@josephyan/qingflow-app-user-mcp`、`@josephyan/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
+}
+```
+
+说明：
+
+- 本地会把解析后的 `token` 和原始 `credential` 写入 profile 文件，用于后续 CLI 命令恢复会话
+- `persist=true` 时，本地还会优先把解析后的 `token` 和原始 `credential` 同步写入系统 keychain
+- 当前工作区以 `/mcp/auth/context` 返回的 `wsId` 为准，不再通过本地 MCP 显式切换

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

@@ -4,4 +4,4 @@ import { getPackageRoot, spawnServer } from "../lib/runtime.mjs";
 
 const packageRoot = getPackageRoot(import.meta.url);
 
-spawnServer(packageRoot, process.argv.slice(2), "qingflow-app-user-mcp");
+spawnServer(packageRoot, process.argv.slice(2), "qingflow-app-user-mcp", { allowRuntimeBootstrap: false });

package/npm/lib/runtime.mjs

@@ -7,14 +7,16 @@ const WINDOWS = process.platform === "win32";
 
 function runChecked(command, args, options = {}) {
   const result = spawnSync(command, args, {
-    stdio: "inherit",
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
     ...options,
   });
   if (result.error) {
     throw result.error;
   }
   if (result.status !== 0) {
-    throw new Error(`Command failed: ${command} ${args.join(" ")}`);
+    const details = [result.stderr, result.stdout].filter((value) => typeof value === "string" && value.trim()).join("\n");
+    throw new Error(details ? `Command failed: ${command} ${args.join(" ")}\n${details}` : `Command failed: ${command} ${args.join(" ")}`);
   }
 }
 
@@ -82,6 +84,105 @@ export function getVenvServerCommand(packageRoot, commandName = "qingflow-mcp")
     : path.join(getVenvDir(packageRoot), "bin", commandName);
 }
 
+function readPackageVersion(packageRoot) {
+  const packageJsonPath = path.join(packageRoot, "package.json");
+  try {
+    const payload = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    return typeof payload.version === "string" && payload.version.trim() ? payload.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function readBootstrapStamp(stampPath) {
+  if (!fs.existsSync(stampPath)) {
+    return { exists: false, version: null };
+  }
+  try {
+    const payload = JSON.parse(fs.readFileSync(stampPath, "utf8"));
+    const version = typeof payload.package_version === "string" && payload.package_version.trim() ? payload.package_version.trim() : null;
+    return { exists: true, version };
+  } catch {
+    return { exists: true, version: null };
+  }
+}
+
+export function inspectPythonEnv(packageRoot, commandName = "qingflow-mcp") {
+  const venvDir = getVenvDir(packageRoot);
+  const serverCommand = getVenvServerCommand(packageRoot, commandName);
+  const stampPath = path.join(venvDir, ".bootstrap.json");
+  const packageVersion = readPackageVersion(packageRoot);
+  const stamp = readBootstrapStamp(stampPath);
+  const problems = [];
+
+  if (!packageVersion) {
+    problems.push("package-version-missing");
+  }
+  if (!fs.existsSync(serverCommand)) {
+    problems.push("server-command-missing");
+  }
+  if (!stamp.exists) {
+    problems.push("bootstrap-stamp-missing");
+  } else if (!stamp.version) {
+    problems.push("bootstrap-stamp-invalid");
+  } else if (packageVersion && stamp.version !== packageVersion) {
+    problems.push("bootstrap-version-mismatch");
+  }
+
+  return {
+    ready: problems.length === 0,
+    packageVersion,
+    stampVersion: stamp.version,
+    stampExists: stamp.exists,
+    stampPath,
+    serverCommand,
+    venvDir,
+    problems,
+  };
+}
+
+function formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap = false } = {}) {
+  const problemLines = [];
+  for (const problem of runtime.problems) {
+    switch (problem) {
+      case "package-version-missing":
+        problemLines.push("- package.json is missing a valid version field");
+        break;
+      case "server-command-missing":
+        problemLines.push(`- missing Python entrypoint: ${runtime.serverCommand}`);
+        break;
+      case "bootstrap-stamp-missing":
+        problemLines.push(`- missing bootstrap stamp: ${runtime.stampPath}`);
+        break;
+      case "bootstrap-stamp-invalid":
+        problemLines.push(`- bootstrap stamp is unreadable or invalid: ${runtime.stampPath}`);
+        break;
+      case "bootstrap-version-mismatch":
+        problemLines.push(
+          `- bootstrap version mismatch: package=${runtime.packageVersion ?? "unknown"}, runtime=${runtime.stampVersion ?? "unknown"}`
+        );
+        break;
+      default:
+        problemLines.push(`- ${problem}`);
+        break;
+    }
+  }
+
+  const action = allowRuntimeBootstrap
+    ? "Delete .npm-python and retry, or rerun npm install to rebuild the embedded Python runtime."
+    : "Delete .npm-python and rerun npm install, or reinstall the npm package before starting the MCP server.";
+
+  const bootstrapNote = allowRuntimeBootstrap
+    ? ""
+    : "\nRuntime bootstrap is disabled for stdio MCP entrypoints so install logs can never corrupt the MCP stdout transport.";
+
+  return [
+    `[qingflow-mcp] Python runtime for ${commandName} is not ready.`,
+    ...problemLines,
+    action + bootstrapNote,
+  ].join("\n");
+}
+
 function getVenvPip(packageRoot) {
   return WINDOWS
     ? path.join(getVenvDir(packageRoot), "Scripts", "pip.exe")
@@ -119,12 +220,11 @@ export function findPython() {
 
 export function ensurePythonEnv(packageRoot, { force = false, commandName = "qingflow-mcp" } = {}) {
   const python = findPython();
-  const venvDir = getVenvDir(packageRoot);
+  const runtime = inspectPythonEnv(packageRoot, commandName);
   const venvPython = getVenvPython(packageRoot);
-  const serverCommand = getVenvServerCommand(packageRoot, commandName);
-  const stampPath = path.join(venvDir, ".bootstrap.json");
+  const { packageVersion, serverCommand, stampPath, venvDir, stampVersion } = runtime;
 
-  if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath)) {
+  if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath) && stampVersion && stampVersion === packageVersion) {
     return serverCommand;
   }
 
@@ -145,6 +245,7 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
       {
         installed_at: new Date().toISOString(),
         installer: "npm",
+        package_version: packageVersion,
       },
       null,
       2
@@ -158,17 +259,79 @@ export function ensurePythonEnv(packageRoot, { force = false, commandName = "qin
   return serverCommand;
 }
 
-export function spawnServer(packageRoot, args, commandName = "qingflow-mcp") {
-  const serverCommand = fs.existsSync(getVenvServerCommand(packageRoot, commandName))
-    ? getVenvServerCommand(packageRoot, commandName)
-    : ensurePythonEnv(packageRoot, { commandName });
+function proxyStreams(child) {
+  if (process.stdin.readable && child.stdin) {
+    process.stdin.pipe(child.stdin);
+    child.stdin.on("error", (error) => {
+      if (error.code !== "EPIPE") {
+        console.error(`[qingflow-mcp] Failed to forward stdin: ${error.message}`);
+      }
+    });
+  } else if (child.stdin) {
+    child.stdin.end();
+  }
+
+  if (child.stdout) {
+    child.stdout.pipe(process.stdout);
+  }
+  if (child.stderr) {
+    child.stderr.pipe(process.stderr);
+  }
+}
+
+function forwardSignal(child, signal) {
+  process.on(signal, () => {
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  });
+}
+
+export function spawnServer(
+  packageRoot,
+  args,
+  commandName = "qingflow-mcp",
+  { allowRuntimeBootstrap = false, stdio = "proxy" } = {},
+) {
+  let runtime = inspectPythonEnv(packageRoot, commandName);
+  let serverCommand = runtime.serverCommand;
+
+  if (!runtime.ready) {
+    if (!allowRuntimeBootstrap) {
+      console.error(formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap }));
+      process.exit(1);
+      return;
+    }
+
+    try {
+      serverCommand = ensurePythonEnv(packageRoot, { commandName });
+      runtime = inspectPythonEnv(packageRoot, commandName);
+    } catch (error) {
+      console.error(`[qingflow-mcp] Failed to prepare Python runtime for ${commandName}: ${error.message}`);
+      process.exit(1);
+      return;
+    }
+
+    if (!runtime.ready) {
+      console.error(formatRuntimeProblem(runtime, commandName, { allowRuntimeBootstrap }));
+      process.exit(1);
+      return;
+    }
+  }
 
   const child = spawn(serverCommand, args, {
-    stdio: "inherit",
+    stdio: stdio === "inherit" ? "inherit" : ["pipe", "pipe", "pipe"],
     env: process.env,
+    windowsHide: true,
   });
 
-  child.on("exit", (code, signal) => {
+  if (stdio !== "inherit") {
+    proxyStreams(child);
+  }
+  forwardSignal(child, "SIGINT");
+  forwardSignal(child, "SIGTERM");
+
+  child.on("close", (code, signal) => {
     if (signal) {
       process.kill(process.pid, signal);
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.10",
+  "version": "0.2.0-beta.1000",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b10"
+version = "0.2.0b1000"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -26,8 +26,10 @@ dependencies = [
   "mcp>=1.9.4,<2.0.0",
   "httpx>=0.27,<1.0",
   "keyring>=25.5,<26.0",
+  "openpyxl>=3.1,<4.0",
   "pydantic>=2.8,<3.0",
   "pycryptodome>=3.20,<4.0",
+  "python-socketio[client]>=5.11,<6.0",
 ]
 
 [project.optional-dependencies]
@@ -44,6 +46,7 @@ build = [
 [project.scripts]
 qingflow-app-user-mcp = "qingflow_mcp.server_app_user:main"
 qingflow-app-builder-mcp = "qingflow_mcp.server_app_builder:main"
+qingflow = "qingflow_mcp.cli.main:main"
 
 [project.urls]
 Homepage = "https://github.com/qingflow/qingflow-mcp"