@josephyan/qingflow-mcp 0.1.0-beta.2

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

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) {
+  return WINDOWS
+    ? path.join(getVenvDir(packageRoot), "Scripts", "qingflow-mcp.exe")
+    : path.join(getVenvDir(packageRoot), "bin", "qingflow-mcp");
+}
+
+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 } = {}) {
+  const python = findPython();
+  const venvDir = getVenvDir(packageRoot);
+  const venvPython = getVenvPython(packageRoot);
+  const serverCommand = getVenvServerCommand(packageRoot);
+  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) {
+  const serverCommand = fs.existsSync(getVenvServerCommand(packageRoot))
+    ? getVenvServerCommand(packageRoot)
+    : ensurePythonEnv(packageRoot);
+
+  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);
+  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,34 @@
+{
+  "name": "@josephyan/qingflow-mcp",
+  "version": "0.1.0-beta.2",
+  "description": "Local-agent installer wrapper for the Qingflow MCP server",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "qingflow-mcp": "./npm/bin/qingflow-mcp.mjs"
+  },
+  "scripts": {
+    "postinstall": "node ./npm/scripts/postinstall.mjs",
+    "pack:npm": "node -e \"require('fs').mkdirSync('dist/npm',{recursive:true})\" && npm pack --pack-destination dist/npm"
+  },
+  "files": [
+    "README.md",
+    "pyproject.toml",
+    "entry_point.py",
+    "src/qingflow_mcp/**/*.py",
+    "src/qingflow_mcp/py.typed",
+    "qingflow-mcp",
+    "docs/local-agent-install.md",
+    "npm/"
+  ],
+  "engines": {
+    "node": ">=16.16.0"
+  },
+  "keywords": [
+    "mcp",
+    "qingflow",
+    "agent",
+    "stdio",
+    "installer"
+  ]
+}

package/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qingflow-mcp"
+version = "0.1.0b2"
+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-mcp = "qingflow_mcp.server: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-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-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 "$@"

package/src/qingflow_mcp/__init__.py

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

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()

package/src/qingflow_mcp/backend_client.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import uuid4
+
+import httpx
+
+from .config import DEFAULT_USER_AGENT, get_default_qf_version, get_timeout_seconds, normalize_base_url
+from .errors import QingflowApiError
+from .json_types import JSONObject, JSONScalar, JSONValue
+
+
+@dataclass(slots=True)
+class BackendRequestContext:
+    base_url: str
+    token: str
+    ws_id: int | None
+    qf_request_id: str | None = None
+    qf_version: str | None = None
+    qf_version_source: str | None = None
+
+
+@dataclass(slots=True)
+class BackendResponse:
+    data: JSONValue
+    headers: dict[str, str]
+    request_id: str
+    http_status: int
+    qf_response_version: str | None = None
+
+
+class BackendClient:
+    def __init__(self, timeout: float | None = None, client: httpx.Client | None = None) -> None:
+        self._owns_client = client is None
+        self._default_qf_version = get_default_qf_version()
+        self._client = client or httpx.Client(
+            timeout=timeout or get_timeout_seconds(),
+            follow_redirects=True,
+            trust_env=False,
+        )
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def public_request(
+        self,
+        method: str,
+        base_url: str,
+        path: str,
+        *,
+        params: JSONObject | None = None,
+        json_body: JSONValue = None,
+        unwrap: bool = True,
+        qf_version: str | None = None,
+        ) -> JSONValue:
+        return self.public_request_with_meta(
+            method,
+            base_url,
+            path,
+            params=params,
+            json_body=json_body,
+            unwrap=unwrap,
+            qf_version=qf_version,
+        ).data
+
+    def public_request_with_meta(
+        self,
+        method: str,
+        base_url: str,
+        path: str,
+        *,
+        params: JSONObject | None = None,
+        json_body: JSONValue = None,
+        unwrap: bool = True,
+        qf_version: str | None = None,
+    ) -> BackendResponse:
+        return self._request_with_meta(
+            method,
+            self._build_url(base_url, path),
+            params=params,
+            json_body=json_body,
+            headers=self._base_headers(None, None, qf_version=qf_version),
+            unwrap=unwrap,
+        )
+
+    def request(
+        self,
+        method: str,
+        context: BackendRequestContext,
+        path: str,
+        *,
+        params: JSONObject | None = None,
+        json_body: JSONValue = None,
+        unwrap: bool = True,
+    ) -> JSONValue:
+        return self.request_with_meta(
+            method,
+            context,
+            path,
+            params=params,
+            json_body=json_body,
+            unwrap=unwrap,
+        ).data
+
+    def request_with_meta(
+        self,
+        method: str,
+        context: BackendRequestContext,
+        path: str,
+        *,
+        params: JSONObject | None = None,
+        json_body: JSONValue = None,
+        unwrap: bool = True,
+    ) -> BackendResponse:
+        return self._request_with_meta(
+            method,
+            self._build_url(context.base_url, path),
+            params=params,
+            json_body=json_body,
+            headers=self._base_headers(
+                context.token,
+                context.ws_id,
+                context.qf_request_id,
+                qf_version=context.qf_version,
+            ),
+            unwrap=unwrap,
+        )
+
+    def describe_route(self, context: BackendRequestContext) -> JSONObject:
+        qf_version, source = self._resolve_qf_version(context.qf_version)
+        if context.qf_version is not None and context.qf_version_source:
+            source = context.qf_version_source
+        return {
+            "base_url": normalize_base_url(context.base_url) or context.base_url,
+            "qf_version": qf_version,
+            "qf_version_source": source,
+        }
+
+    def upload_binary(
+        self,
+        url: str,
+        content: bytes,
+        *,
+        content_type: str | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> JSONObject:
+        request_headers = dict(headers or {})
+        if content_type:
+            request_headers.setdefault("Content-Type", content_type)
+        try:
+            response = self._client.put(url, content=content, headers=request_headers or None)
+        except httpx.RequestError as exc:
+            raise QingflowApiError(category="network", message=str(exc))
+        if response.status_code >= 400:
+            raise QingflowApiError(
+                category="http",
+                message=self._extract_message(response.text) or f"HTTP {response.status_code}",
+                http_status=response.status_code,
+            )
+        return {
+            "status_code": response.status_code,
+            "headers": dict(response.headers),
+        }
+
+    def upload_form_file(
+        self,
+        url: str,
+        *,
+        form_fields: dict[str, str],
+        file_field: str,
+        file_name: str,
+        content: bytes,
+        content_type: str | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> JSONObject:
+        try:
+            response = self._client.post(
+                url,
+                data=form_fields,
+                files={file_field: (file_name, content, content_type or "application/octet-stream")},
+                headers=headers or None,
+            )
+        except httpx.RequestError as exc:
+            raise QingflowApiError(category="network", message=str(exc))
+        if response.status_code >= 400:
+            raise QingflowApiError(
+                category="http",
+                message=self._extract_message(response.text) or f"HTTP {response.status_code}",
+                http_status=response.status_code,
+            )
+        body: JSONValue = None
+        if response.content:
+            try:
+                body = response.json()
+            except ValueError:
+                body = response.text
+        return {
+            "status_code": response.status_code,
+            "headers": dict(response.headers),
+            "body": body,
+        }
+
+    def _request_with_meta(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: JSONObject | None,
+        json_body: JSONValue,
+        headers: dict[str, str],
+        unwrap: bool,
+    ) -> BackendResponse:
+        attempts = 2 if method.upper() == "GET" else 1
+        last_error: QingflowApiError | None = None
+        for _ in range(attempts):
+            try:
+                response = self._client.request(method.upper(), url, params=params, json=json_body, headers=headers)
+                parsed = self._parse_response(response, headers["Qf-Request-Id"], unwrap=unwrap)
+                return BackendResponse(
+                    data=parsed,
+                    headers=dict(response.headers),
+                    request_id=headers["Qf-Request-Id"],
+                    http_status=response.status_code,
+                    qf_response_version=self._extract_response_qf_version(response.headers),
+                )
+            except httpx.RequestError as exc:
+                last_error = QingflowApiError(category="network", message=str(exc), request_id=headers["Qf-Request-Id"])
+        assert last_error is not None
+        raise last_error
+
+    def _parse_response(self, response: httpx.Response, request_id: str, *, unwrap: bool) -> JSONValue:
+        payload: JSONValue
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = response.text
+        if response.status_code >= 400:
+            raise QingflowApiError(
+                category="http",
+                message=self._extract_message(payload) or f"HTTP {response.status_code}",
+                backend_code=self._extract_code(payload),
+                request_id=request_id,
+                http_status=response.status_code,
+            )
+        if not unwrap:
+            return payload
+        return self._unwrap_payload(payload, request_id, response.status_code)
+
+    def _unwrap_payload(self, payload: JSONValue, request_id: str, http_status: int) -> JSONValue:
+        if not isinstance(payload, dict):
+            return payload
+        if "success" in payload:
+            if not bool(payload.get("success")):
+                raise QingflowApiError(
+                    category="backend",
+                    message=self._extract_message(payload) or "Qingflow request failed",
+                    backend_code=self._extract_code(payload),
+                    request_id=request_id,
+                    http_status=http_status,
+                )
+            return self._extract_success_data(payload)
+        code = self._extract_code(payload)
+        if code not in (None, 0, "0"):
+            raise QingflowApiError(
+                category="backend",
+                message=self._extract_message(payload) or "Qingflow request failed",
+                backend_code=code,
+                request_id=request_id,
+                http_status=http_status,
+            )
+        if code in (0, "0"):
+            return self._extract_success_data(payload)
+        return payload
+
+    def _extract_success_data(self, payload: JSONObject) -> JSONValue:
+        for key in ("result", "data", "page", "obj"):
+            if key in payload:
+                return payload[key]
+        return payload
+
+    def _extract_message(self, payload: JSONValue) -> str | None:
+        if not isinstance(payload, dict):
+            return str(payload) if payload else None
+        for key in ("message", "msg", "errMsg", "error", "detail"):
+            value = payload.get(key)
+            if value:
+                return str(value)
+        return None
+
+    def _extract_code(self, payload: JSONValue) -> JSONScalar:
+        if isinstance(payload, dict):
+            return payload.get("code", payload.get("errCode"))
+        return None
+
+    def _base_headers(
+        self,
+        token: str | None,
+        ws_id: int | None,
+        request_id: str | None = None,
+        *,
+        qf_version: str | None = None,
+    ) -> dict[str, str]:
+        headers = {
+            "User-Agent": DEFAULT_USER_AGENT,
+            "Qf-Request-Id": request_id or str(uuid4()),
+        }
+        resolved_qf_version, _ = self._resolve_qf_version(qf_version)
+        if resolved_qf_version:
+            headers["Cookie"] = f"qfVersion={resolved_qf_version}"
+        if token:
+            headers["token"] = token
+        if ws_id is not None:
+            headers["wsId"] = str(ws_id)
+        return headers
+
+    def _resolve_qf_version(self, explicit_qf_version: str | None) -> tuple[str | None, str]:
+        if explicit_qf_version is not None:
+            normalized = str(explicit_qf_version).strip() or None
+            return normalized, "context"
+        if self._default_qf_version:
+            return self._default_qf_version, "default_config"
+        return None, "unset"
+
+    def _extract_response_qf_version(self, headers: httpx.Headers) -> str | None:
+        value = headers.get("x-q-response-version")
+        if value is None:
+            return None
+        normalized = str(value).strip()
+        return normalized or None
+
+    def _build_url(self, base_url: str, path: str) -> str:
+        normalized = normalize_base_url(base_url)
+        if not normalized:
+            raise QingflowApiError.config_error("base_url is required")
+        return f"{normalized}/{path.lstrip('/')}"