@josephyan/qingflow-cli 1.1.3 → 1.1.5

package/skills/qingflow-mcp-setup/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: qingflow-mcp-setup
+description: Install, connect, authenticate, and troubleshoot the Qingflow MCP server in local AI clients such as Claude Desktop or any stdio-compatible MCP client. Use when the user wants to configure the MCP, verify local startup, log in with token/password, select a workspace, or fix connection/authentication issues.
+metadata:
+  short-description: Install and connect the Qingflow MCP locally
+---
+
+# Qingflow MCP Setup
+
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
+## Overview
+
+This skill sets up the local Qingflow MCP server, connects it to a local AI client, and verifies authentication and workspace selection. Use it for installation, client configuration, token login, and connection troubleshooting.
+
+## Workflow
+
+Follow these steps in order.
+
+`feedback_submit` is also available as a cross-cutting helper when setup or MCP capability gaps still block the user after reasonable troubleshooting. It does not require Qingflow login or workspace selection, and should be called only after explicit user confirmation.
+
+Before configuration or live calls, identify the target environment explicitly as `test` or `prod`, then read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
+
+### Step 1: Verify the local project path
+
+Resolve the repository root first. In this repo, the MCP server should live at:
+
+- `<repo_root>/qingflow-support/mcp-server`
+
+Key entrypoint:
+
+- `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
+
+If the path differs, stop and update all client config snippets before proceeding.
+If the skill is installed under `$CODEX_HOME/skills` instead of the repo-local `.codex/skills`, set `QINGFLOW_MCP_ROOT=<repo_root>/qingflow-support/mcp-server` before running `scripts/check_local_server.sh`.
+
+### Step 2: Install local dependencies
+
+Run:
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+python3 -m venv .venv
+./.venv/bin/pip install -e '.[dev]'
+```
+
+Use `scripts/check_local_server.sh` to verify the entrypoint and virtualenv. The script will first try `QINGFLOW_MCP_ROOT`, then the current git repo, then a repo-local `.codex/skills` layout.
+
+### Step 3: Configure the local AI client
+
+For any stdio-compatible MCP client, map these values:
+
+- `command`: `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
+- `args`: `[]`
+- `env.QINGFLOW_MCP_DEFAULT_BASE_URL`: the target backend URL for the active environment
+- `env.QINGFLOW_MCP_DEFAULT_QF_VERSION`: set this when the environment must route to a specific version such as `canary`
+
+Client-specific snippets:
+
+- Claude Desktop: read [references/claude-desktop.md](references/claude-desktop.md)
+- Generic stdio MCP clients: read [references/generic-stdio.md](references/generic-stdio.md)
+
+When both test and production are in play, keep separate config snippets or clearly labeled `env` blocks so the user can switch without ambiguity.
+
+### Step 4: Validate startup
+
+The server is a stdio MCP process. A direct terminal launch may print nothing and wait for a client. That is normal.
+
+Manual startup command:
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+./qingflow-mcp
+```
+
+Prefer validating through the client after config is added.
+
+### Step 5: Use injected session first; authenticate only for setup or recovery
+
+For Wingent Momo runtime conversations, the session normally already carries the credential-derived token, workspace, and route context. Do not run `auth_use_credential`, `auth_login`, `workspace_list`, or `workspace_select` before ordinary business tools. Start with the smallest read-only business call that fits the task; if it succeeds, continue.
+
+For a standalone local MCP client that has no injected session, use this setup order:
+
+1. `auth_use_credential` or `auth_login`
+2. `workspace_list`
+3. `workspace_select`
+4. Run a small read-only business tool
+
+`auth_use_credential` gets the selected workspace from the credential context. If the user needs a different workspace after authentication, use `workspace_list` and then `workspace_select`.
+After auth, prefer one read-only tool call that returns `request_route` so you can confirm the live `base_url` and `qf_version` before proceeding.
+`auth_use_credential` is a tool call, not a custom HTTP header. It exchanges the createClaw credential for a Qingflow token, `wsId`, and when needed `Cookie: qfVersion=...` after the session is established.
+Do not run `workspace_select` on production paths unless the user explicitly asks to switch workspace or a business tool clearly reports that no workspace is selected. If `/user` does not return a version lane, the session now falls back to the workspace `systemVersion`.
+
+### Step 6: Troubleshoot in the right layer
+
+- If the client cannot launch the server, check path, execute permission, and `.venv`
+- If tools return `auth required`, re-run `auth_use_credential` or `auth_login`
+- If tools return `workspace not selected`, call `workspace_list` and `workspace_select`
+- If calls fail after a working session, assume token expiry and re-authenticate
+- If the browser shows data but MCP does not, compare `request_route` against the browser environment and check whether `qf_version` should be `canary`
+
+## Guardrails
+
+- Never write tokens into the skill files
+- In Wingent Momo runtime, trust injected workspace context until a business tool proves otherwise; for standalone clients, confirm workspace with `auth_whoami`, `workspace_select`, or a successful read-only business call.
+- When debugging, distinguish server startup issues from Qingflow auth issues
+- When the user mentions production, restate the exact `base_url`, `qf_version`, and workspace before any live validation
+- If setup is complete but the current MCP capability is still unsupported or the user's need still cannot be satisfied, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation
+
+## Resources
+
+- Environment switching: [references/environments.md](references/environments.md)
+- Claude Desktop config: [references/claude-desktop.md](references/claude-desktop.md)
+- Generic stdio config: [references/generic-stdio.md](references/generic-stdio.md)
+- Local checks: [scripts/check_local_server.sh](scripts/check_local_server.sh)

package/skills/qingflow-mcp-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow MCP Setup"
+  short_description: "Install and connect the Qingflow MCP locally"
+  default_prompt: "Use $qingflow-mcp-setup to install and connect the Qingflow MCP in a local AI client, and to verify the active base_url, qf_version, auth state, and workspace selection."

package/skills/qingflow-mcp-setup/references/claude-desktop.md

@@ -0,0 +1,34 @@
+# Claude Desktop
+
+Use this when the user wants to install Qingflow MCP in Claude Desktop.
+
+## Config snippet
+
+```json
+{
+  "mcpServers": {
+    "qingflow": {
+      "command": "<ABSOLUTE_PATH_TO_REPO>/qingflow-support/mcp-server/qingflow-mcp",
+      "args": [],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "<QINGFLOW_BASE_URL>"
+      }
+    }
+  }
+}
+```
+
+## Environment examples
+
+- `prod` (default): set `QINGFLOW_MCP_DEFAULT_BASE_URL` to `https://qingflow.com/api`
+- `test`: if needed, set `QINGFLOW_MCP_DEFAULT_BASE_URL` to the explicitly provided non-production backend
+
+Keep separate snippets for `test` and `prod` so switching environments does not require editing values in-place under pressure.
+
+## Notes
+
+- After updating the config, restart Claude Desktop
+- Replace `<ABSOLUTE_PATH_TO_REPO>` with the real checkout path on the current machine
+- If the server path changes, update the `command` field
+- The server is local stdio MCP, so no remote URL is required
+- Do not store Qingflow credentials in Claude Desktop config; pass the createClaw credential through `auth_use_credential` inside the chat, or use `auth_login` when credential exchange is unavailable

package/skills/qingflow-mcp-setup/references/environments.md

@@ -0,0 +1,62 @@
+# Environment Switching
+
+Use this reference before any setup, authentication, or live validation flow.
+
+## Step 1: Resolve the active environment
+
+Decide explicitly whether the user is targeting:
+
+- `test`: for smoke tests, trial setup, DSL validation, mock data, and integration debugging
+- `prod`: for real business usage in the formal environment
+
+If the user did not specify an environment, default to `prod`.
+
+## Test Environment
+
+Default characteristics:
+
+- preferred for first-time setup and local MCP validation
+- mock or smoke data is acceptable when the user asks for it
+- use read/write verification freely inside the intended test workspace
+
+Known values in the current workspace:
+
+- use an explicitly provided non-production backend
+- common test workspace example: `ws_id=2`
+- `qf_version`: usually unset unless the user explicitly needs a routed version
+
+Setup behavior:
+
+- prefer this environment for Claude Desktop or local MCP client onboarding
+- for Wingent Momo runtime, use the injected session and skip auth/workspace preflight
+- for standalone MCP client setup, use `auth_use_credential` or `auth_login`, then `workspace_list`, then `workspace_select`
+- if the user asks to verify installation, a real read-only smoke path is acceptable
+
+## Production Environment
+
+Production is the default environment when the user does not specify one. If the user explicitly says `test`, switch to the dedicated non-production backend they provide.
+
+Expected behavior:
+
+- default `base_url`: `https://qingflow.com/api`
+- confirm the production `qf_version` explicitly when browser traffic depends on routed versions such as `canary`
+- confirm the exact workspace before any live validation
+- prefer read-only checks first
+- avoid mock data, smoke writes, or destructive tests unless the user explicitly asks for them
+
+Production guardrails:
+
+- do not store credentials in skill files or examples
+- do not assume the same workspace ids as test
+- treat startup verification and auth verification as separate steps
+- when sharing snippets, label them as `prod` and `test` clearly
+- when MCP and browser results diverge, compare `request_route` with the browser route before blaming the query logic
+
+## Reporting Rule
+
+When you give setup instructions, always state:
+
+- active environment
+- selected `base_url`
+- selected `qf_version` when relevant
+- whether the next step is read-only or write-impacting

package/skills/qingflow-mcp-setup/references/generic-stdio.md

@@ -0,0 +1,32 @@
+# Generic Stdio MCP Clients
+
+Use this for any local AI client that supports MCP over stdio.
+
+## Required mapping
+
+- `command`: `<ABSOLUTE_PATH_TO_REPO>/qingflow-support/mcp-server/qingflow-mcp`
+- `args`: `[]`
+- `env.QINGFLOW_MCP_DEFAULT_BASE_URL`: backend base URL for the active environment
+
+Environment examples:
+
+- `prod` (default): `https://qingflow.com/api`
+- `test`: use the explicitly provided non-production backend
+
+Keep separate client entries or separate config snippets for `test` and `prod`.
+
+## Validation sequence
+
+1. Start the client
+2. Confirm the `qingflow` MCP server is visible
+3. In Wingent Momo runtime, skip auth/workspace preflight and run a read-only tool such as `app_list`
+4. In a standalone client without injected credentials, run `auth_use_credential` or `auth_login`
+5. Then run `workspace_list`
+6. Then run `workspace_select`
+7. Run a read-only tool such as `app_list`
+
+## Common failures
+
+- Launch failure: bad `command` path or missing `.venv`
+- Auth failure: invalid or expired credential/token
+- Business tool failure before setup: workspace not selected

package/skills/qingflow-mcp-setup/scripts/check_local_server.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="${QINGFLOW_MCP_ROOT:-}"
+
+if [[ -z "$ROOT" ]]; then
+  if git_root="$(git rev-parse --show-toplevel 2>/dev/null)" && [[ -d "$git_root/qingflow-support/mcp-server" ]]; then
+    ROOT="$git_root/qingflow-support/mcp-server"
+  elif [[ -d "$PWD/qingflow-support/mcp-server" ]]; then
+    ROOT="$PWD/qingflow-support/mcp-server"
+  else
+    repo_root="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+    if [[ -d "$repo_root/qingflow-support/mcp-server" ]]; then
+      ROOT="$repo_root/qingflow-support/mcp-server"
+    fi
+  fi
+fi
+
+if [[ -z "$ROOT" ]]; then
+  echo "Unable to locate qingflow-support/mcp-server. Set QINGFLOW_MCP_ROOT to the repo copy of the MCP server." >&2
+  exit 1
+fi
+
+ENTRY="$ROOT/qingflow-mcp"
+PY="$ROOT/.venv/bin/python"
+
+echo "ROOT=$ROOT"
+test -d "$ROOT"
+echo "OK root exists"
+
+test -x "$ENTRY"
+echo "OK entrypoint exists and is executable"
+
+test -x "$PY"
+echo "OK virtualenv python exists"
+
+PYTHONPATH="$ROOT/src" "$PY" -c "import qingflow_mcp.server; print('OK import qingflow_mcp.server')"

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b1099"
+_FALLBACK_VERSION = "0.2.0b1017"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/__main__.py

@@ -1,5 +1,9 @@
-"""Entry point for running qingflow_mcp as a module."""
-from qingflow_mcp.server import main
+"""Entry point for running qingflow_mcp as a module.
+
+Default to the curated user-facing MCP surface. Split package and console
+entrypoints can still start the builder server explicitly.
+"""
+from qingflow_mcp.server_app_user import main
 
 if __name__ == "__main__":
     main()