@josephyan/qingflow-cli 0.2.0-beta.58 → 0.2.0-beta.60

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-cli@0.2.0-beta.58
+npm install @josephyan/qingflow-cli@0.2.0-beta.60
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-cli@0.2.0-beta.58 qingflow
+npx -y -p @josephyan/qingflow-cli@0.2.0-beta.60 qingflow
 ```
 
 Environment:
@@ -28,3 +28,4 @@ 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

@@ -233,3 +233,12 @@ 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`。如果运行时缺失或版本不一致，入口会直接报错并提示重装，而不是静默自修复。

package/npm/bin/qingflow.mjs

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

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(" ")}`);
   }
 }
 
@@ -92,6 +94,95 @@ function readPackageVersion(packageRoot) {
   }
 }
 
+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")
@@ -129,20 +220,9 @@ 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 = readPackageVersion(packageRoot);
-  let stampVersion = null;
-  if (fs.existsSync(stampPath)) {
-    try {
-      const payload = JSON.parse(fs.readFileSync(stampPath, "utf8"));
-      stampVersion = typeof payload.package_version === "string" && payload.package_version.trim() ? payload.package_version.trim() : null;
-    } catch {
-      stampVersion = null;
-    }
-  }
+  const { packageVersion, serverCommand, stampPath, venvDir, stampVersion } = runtime;
 
   if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath) && stampVersion && stampVersion === packageVersion) {
     return serverCommand;
@@ -179,17 +259,72 @@ 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 } = {}) {
+  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: ["pipe", "pipe", "pipe"],
     env: process.env,
+    windowsHide: true,
   });
 
-  child.on("exit", (code, signal) => {
+  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-cli",
-  "version": "0.2.0-beta.58",
+  "version": "0.2.0-beta.60",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b58"
+version = "0.2.0b60"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"