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

package/npm/lib/runtime.mjs

@@ -0,0 +1,339 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const WINDOWS = process.platform === "win32";
+
+function runChecked(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    ...options,
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    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(" ")}`);
+  }
+}
+
+function commandWorks(command, args) {
+  const result = spawnSync(command, args, {
+    stdio: "ignore",
+  });
+  return result.status === 0;
+}
+
+export function getPackageRoot(metaUrl) {
+  return path.resolve(path.dirname(fileURLToPath(metaUrl)), "..", "..");
+}
+
+export function getCodexHome() {
+  const configured = process.env.CODEX_HOME?.trim();
+  if (configured) {
+    return path.resolve(configured);
+  }
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error("Cannot resolve CODEX_HOME because HOME is not set.");
+  }
+  return path.join(home, ".codex");
+}
+
+export function installBundledSkills(packageRoot) {
+  const skillsSrc = path.join(packageRoot, "skills");
+  if (!fs.existsSync(skillsSrc)) {
+    return { installed: [], skipped: true, destination: null };
+  }
+
+  const codexHome = getCodexHome();
+  const skillsDestRoot = path.join(codexHome, "skills");
+  fs.mkdirSync(skillsDestRoot, { recursive: true });
+
+  const installed = [];
+  for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const src = path.join(skillsSrc, entry.name);
+    const dest = path.join(skillsDestRoot, entry.name);
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.cpSync(src, dest, { recursive: true });
+    installed.push(entry.name);
+  }
+
+  return { installed, skipped: false, destination: skillsDestRoot };
+}
+
+export function getVenvDir(packageRoot) {
+  return path.join(packageRoot, ".npm-python");
+}
+
+export function getVenvPython(packageRoot) {
+  return WINDOWS
+    ? path.join(getVenvDir(packageRoot), "Scripts", "python.exe")
+    : path.join(getVenvDir(packageRoot), "bin", "python");
+}
+
+export function getVenvServerCommand(packageRoot, commandName = "qingflow-mcp") {
+  return WINDOWS
+    ? path.join(getVenvDir(packageRoot), "Scripts", `${commandName}.exe`)
+    : 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")
+    : path.join(getVenvDir(packageRoot), "bin", "pip");
+}
+
+export function findPython() {
+  const preferred = process.env.QINGFLOW_MCP_PYTHON?.trim();
+  const candidates = preferred
+    ? [{ command: preferred, args: [], label: preferred }]
+    : WINDOWS
+      ? [
+          { command: "py", args: ["-3", "-V"], label: "py -3" },
+          { command: "python", args: ["-V"], label: "python" },
+          { command: "python3", args: ["-V"], label: "python3" },
+        ]
+      : [
+          { command: "python3", args: ["-V"], label: "python3" },
+          { command: "python", args: ["-V"], label: "python" },
+        ];
+
+  for (const candidate of candidates) {
+    if (commandWorks(candidate.command, candidate.args)) {
+      if (candidate.command === "py") {
+        return { command: "py", args: ["-3"], label: candidate.label };
+      }
+      return { command: candidate.command, args: [], label: candidate.label };
+    }
+  }
+
+  throw new Error(
+    "Python 3.11+ was not found. Set QINGFLOW_MCP_PYTHON to a Python 3 executable before running npm install."
+  );
+}
+
+export function ensurePythonEnv(packageRoot, { force = false, commandName = "qingflow-mcp" } = {}) {
+  const python = findPython();
+  const runtime = inspectPythonEnv(packageRoot, commandName);
+  const venvPython = getVenvPython(packageRoot);
+  const { packageVersion, serverCommand, stampPath, venvDir, stampVersion } = runtime;
+
+  if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath) && stampVersion && stampVersion === packageVersion) {
+    return serverCommand;
+  }
+
+  if (force && fs.existsSync(venvDir)) {
+    fs.rmSync(venvDir, { recursive: true, force: true });
+  }
+
+  if (!fs.existsSync(venvPython)) {
+    runChecked(python.command, [...python.args, "-m", "venv", venvDir], { cwd: packageRoot });
+  }
+
+  const pip = getVenvPip(packageRoot);
+  runChecked(pip, ["install", "--disable-pip-version-check", "."], { cwd: packageRoot });
+
+  fs.writeFileSync(
+    stampPath,
+    JSON.stringify(
+      {
+        installed_at: new Date().toISOString(),
+        installer: "npm",
+        package_version: packageVersion,
+      },
+      null,
+      2
+    )
+  );
+
+  if (!fs.existsSync(serverCommand)) {
+    throw new Error(`Bootstrap finished but ${serverCommand} was not created.`);
+  }
+
+  return serverCommand;
+}
+
+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: ["pipe", "pipe", "pipe"],
+    env: process.env,
+    windowsHide: true,
+  });
+
+  proxyStreams(child);
+  forwardSignal(child, "SIGINT");
+  forwardSignal(child, "SIGTERM");
+
+  child.on("close", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+
+  child.on("error", (error) => {
+    console.error(`[qingflow-mcp] Failed to start server: ${error.message}`);
+    process.exit(1);
+  });
+}

package/npm/scripts/postinstall.mjs

@@ -0,0 +1,16 @@
+import { ensurePythonEnv, getPackageRoot, installBundledSkills } from "../lib/runtime.mjs";
+
+const packageRoot = getPackageRoot(import.meta.url);
+
+try {
+  console.log("[qingflow-mcp] Bootstrapping Python runtime...");
+  ensurePythonEnv(packageRoot, { commandName: "qingflow-app-builder-mcp" });
+  console.log("[qingflow-mcp] Python runtime is ready.");
+  const skills = installBundledSkills(packageRoot);
+  if (!skills.skipped) {
+    console.log(`[qingflow-mcp] Installed skills to ${skills.destination}: ${skills.installed.join(", ")}`);
+  }
+} catch (error) {
+  console.error(`[qingflow-mcp] postinstall failed: ${error.message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@qingflow-tech/qingflow-app-builder-mcp",
+  "version": "1.0.0",
+  "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "qingflow-app-builder-mcp": "./npm/bin/qingflow-app-builder-mcp.mjs"
+  },
+  "scripts": {
+    "postinstall": "node ./npm/scripts/postinstall.mjs"
+  },
+  "files": [
+    "README.md",
+    "pyproject.toml",
+    "entry_point.py",
+    "src/qingflow_mcp/**/*.py",
+    "src/qingflow_mcp/py.typed",
+    "qingflow-app-builder-mcp",
+    "npm/",
+    "docs/local-agent-install.md",
+    "skills/"
+  ],
+  "engines": {
+    "node": ">=16.16.0"
+  },
+  "keywords": [
+    "mcp",
+    "qingflow",
+    "agent",
+    "stdio",
+    "app-builder"
+  ]
+}

package/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qingflow-mcp"
+version = "0.2.0b87"
+description = "User-authenticated MCP server for Qingflow"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+  { name = "Qingflow", email = "support@qingflow.com" }
+]
+keywords = ["mcp", "qingflow", "automation", "workflow"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+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]
+dev = [
+  "pytest>=8.3,<9.0",
+  "respx>=0.22,<1.0",
+]
+build = [
+  "pyinstaller>=6.0,<7.0",
+  "build>=1.0,<2.0",
+  "twine>=5.0,<6.0",
+]
+
+[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"
+Documentation = "https://github.com/qingflow/qingflow-mcp#readme"
+Repository = "https://github.com/qingflow/qingflow-mcp"
+Issues = "https://github.com/qingflow/qingflow-mcp/issues"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+qingflow_mcp = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

package/qingflow-app-builder-mcp

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [[ -n "${PYTHON_BIN:-}" ]]; then
+  PYTHON="${PYTHON_BIN}"
+elif [[ -x "$ROOT_DIR/.venv/bin/python" ]]; then
+  PYTHON="$ROOT_DIR/.venv/bin/python"
+elif command -v python3 >/dev/null 2>&1; then
+  PYTHON="$(command -v python3)"
+else
+  echo "qingflow-app-builder-mcp: python interpreter not found. Set PYTHON_BIN or create $ROOT_DIR/.venv" >&2
+  exit 1
+fi
+export PYTHONPATH="$ROOT_DIR/src${PYTHONPATH:+:$PYTHONPATH}"
+exec "$PYTHON" -m qingflow_mcp.server_app_builder "$@"