@josephyan/qingflow-app-user-mcp 0.1.0-beta.9

package/README.md

@@ -0,0 +1,21 @@
+# Qingflow App User MCP
+
+Install:
+
+```bash
+npm install @josephyan/qingflow-app-user-mcp@0.1.0-beta.9
+```
+
+Run:
+
+```bash
+npx -y -p @josephyan/qingflow-app-user-mcp@0.1.0-beta.9 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.

package/docs/local-agent-install.md

@@ -0,0 +1,228 @@
+# 本地智能体安装
+
+这个目录下现在只保留两个本地命令入口：
+
+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-app-user-mcp-<version>.tgz
+dist/npm/josephyan-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
+```
+
+安装时会自动：
+
+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，命令通常位于：
+
+```bash
+/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-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
+
+如果不做全局安装，也可以直接运行独立包：
+
+```json
+{
+  "mcpServers": {
+    "qingflow-user": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@josephyan/qingflow-app-user-mcp"
+      ],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api"
+      }
+    },
+    "qingflow-builder": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@josephyan/qingflow-app-builder-mcp"
+      ],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api"
+      }
+    }
+  }
+}
+```
+
+说明：
+- 源码目录 `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
+```

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");

package/npm/lib/runtime.mjs

@@ -0,0 +1,146 @@
+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, {
+    stdio: "inherit",
+    ...options,
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(`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 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 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 venvDir = getVenvDir(packageRoot);
+  const venvPython = getVenvPython(packageRoot);
+  const serverCommand = getVenvServerCommand(packageRoot, commandName);
+  const stampPath = path.join(venvDir, ".bootstrap.json");
+
+  if (!force && fs.existsSync(serverCommand) && fs.existsSync(stampPath)) {
+    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",
+      },
+      null,
+      2
+    )
+  );
+
+  if (!fs.existsSync(serverCommand)) {
+    throw new Error(`Bootstrap finished but ${serverCommand} was not created.`);
+  }
+
+  return serverCommand;
+}
+
+export function spawnServer(packageRoot, args, commandName = "qingflow-mcp") {
+  const serverCommand = fs.existsSync(getVenvServerCommand(packageRoot, commandName))
+    ? getVenvServerCommand(packageRoot, commandName)
+    : ensurePythonEnv(packageRoot, { commandName });
+
+  const child = spawn(serverCommand, args, {
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  child.on("exit", (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,12 @@
+import { ensurePythonEnv, getPackageRoot } from "../lib/runtime.mjs";
+
+const packageRoot = getPackageRoot(import.meta.url);
+
+try {
+  console.log("[qingflow-mcp] Bootstrapping Python runtime...");
+  ensurePythonEnv(packageRoot, { commandName: "qingflow-app-user-mcp" });
+  console.log("[qingflow-mcp] Python runtime is ready.");
+} catch (error) {
+  console.error(`[qingflow-mcp] postinstall failed: ${error.message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@josephyan/qingflow-app-user-mcp",
+  "version": "0.1.0-beta.9",
+  "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "qingflow-app-user-mcp": "./npm/bin/qingflow-app-user-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-user-mcp",
+    "npm/",
+    "docs/local-agent-install.md"
+  ],
+  "engines": {
+    "node": ">=16.16.0"
+  },
+  "keywords": [
+    "mcp",
+    "qingflow",
+    "agent",
+    "stdio",
+    "app-user"
+  ]
+}

package/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qingflow-mcp"
+version = "0.1.0b9"
+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",
+  "pydantic>=2.8,<3.0",
+  "pycryptodome>=3.20,<4.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"
+
+[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-user-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-user-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_user "$@"

package/src/qingflow_mcp/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0b9"

package/src/qingflow_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for running qingflow_mcp as a module."""
+from qingflow_mcp.server import main
+
+if __name__ == "__main__":
+    main()