@qingflow-tech/qingflow-cli 1.0.11 → 1.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/README.md +8 -4
  2. package/docs/local-agent-install.md +54 -3
  3. package/entry_point.py +1 -1
  4. package/npm/bin/qingflow-skills.mjs +5 -0
  5. package/npm/bin/qingflow.mjs +7 -2
  6. package/npm/lib/runtime.mjs +304 -13
  7. package/npm/scripts/postinstall.mjs +1 -5
  8. package/package.json +3 -2
  9. package/pyproject.toml +1 -1
  10. package/skills/qingflow-cli/SKILL.md +431 -0
  11. package/skills/qingflow-cli/manifest.yaml +10 -0
  12. package/skills/qingflow-cli/reference/QINGFLOW_CLI_ADMIN_CHEATSHEET.md +94 -0
  13. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_APP_DELIVERY_WORKFLOW.md +432 -0
  14. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_CHARTS_WORKFLOW.md +177 -0
  15. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_MATCH_RULES.md +119 -0
  16. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_PORTAL_WORKFLOW.md +200 -0
  17. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_VIEWS_WORKFLOW.md +288 -0
  18. package/skills/qingflow-cli/reference/QINGFLOW_CLI_BUILDER_WORKSPACE_ICONS.md +40 -0
  19. package/skills/qingflow-cli/reference/QINGFLOW_CLI_DATA_RETRIEVAL_WORKFLOW.md +129 -0
  20. package/skills/qingflow-cli/reference/QINGFLOW_CLI_EXPLORATION_REPORT.md +84 -0
  21. package/skills/qingflow-cli/reference/QINGFLOW_CLI_FIELD_DATA_TYPES.md +129 -0
  22. package/skills/qingflow-cli/reference/QINGFLOW_CLI_MEMBER_CHEATSHEET.md +196 -0
  23. package/skills/qingflow-cli/reference/QINGFLOW_CLI_ONE_SHOT_CHEATSHEET.md +159 -0
  24. package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md +14 -0
  25. package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md +150 -0
  26. package/skills/qingflow-cli/reference/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md +163 -0
  27. package/skills/qingflow-cli/reference/QINGFLOW_CLI_SCHEMA_APPLY_FIELD_TYPES_AND_SCENARIOS.md +95 -0
  28. package/skills/qingflow-cli/reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md +150 -0
  29. package/skills/qingflow-cli/reference/_batch_schema_complex.json +18 -0
  30. package/skills/qingflow-cli/reference/_batch_schema_scalar.json +17 -0
  31. package/skills/qingflow-cli/reference/charts_remove.example.json +1 -0
  32. package/skills/qingflow-cli/reference/charts_reorder.example.json +1 -0
  33. package/skills/qingflow-cli/reference/charts_upsert_bar.example.json +8 -0
  34. package/skills/qingflow-cli/reference/charts_upsert_dashboard_starter.example.json +37 -0
  35. package/skills/qingflow-cli/reference/charts_upsert_minimal.example.json +13 -0
  36. package/skills/qingflow-cli/reference/portal_sections_all_types.example.json +131 -0
  37. package/skills/qingflow-cli/reference/portal_sections_five_types.example.json +106 -0
  38. package/skills/qingflow-cli/reference/schema_add_fields_minimal.example.json +7 -0
  39. package/skills/qingflow-cli/reference/schema_apply_add_fields_all_types.json +78 -0
  40. package/skills/qingflow-cli/reference/views_upsert_table_minimal.example.json +7 -0
  41. package/skills/qingflow-cli/scripts/builder-package-from-app-list.py +140 -0
  42. package/skills/qingflow-cli/scripts/find-app-by-keyword.py +132 -0
  43. package/skills/qingflow-mcp-setup/SKILL.md +113 -0
  44. package/skills/qingflow-mcp-setup/agents/openai.yaml +4 -0
  45. package/skills/qingflow-mcp-setup/references/claude-desktop.md +34 -0
  46. package/skills/qingflow-mcp-setup/references/environments.md +62 -0
  47. package/skills/qingflow-mcp-setup/references/generic-stdio.md +32 -0
  48. package/skills/qingflow-mcp-setup/scripts/check_local_server.sh +38 -0
  49. package/src/qingflow_mcp/__main__.py +6 -2
  50. package/src/qingflow_mcp/builder_facade/service.py +1488 -288
  51. package/src/qingflow_mcp/cli/commands/builder.py +2 -2
  52. package/src/qingflow_mcp/cli/commands/exports.py +2 -2
  53. package/src/qingflow_mcp/cli/commands/imports.py +1 -1
  54. package/src/qingflow_mcp/cli/commands/record.py +39 -11
  55. package/src/qingflow_mcp/cli/context.py +0 -3
  56. package/src/qingflow_mcp/cli/formatters.py +206 -7
  57. package/src/qingflow_mcp/cli/main.py +47 -3
  58. package/src/qingflow_mcp/errors.py +43 -2
  59. package/src/qingflow_mcp/public_surface.py +21 -15
  60. package/src/qingflow_mcp/response_trim.py +68 -13
  61. package/src/qingflow_mcp/server.py +11 -9
  62. package/src/qingflow_mcp/server_app_builder.py +3 -2
  63. package/src/qingflow_mcp/server_app_user.py +15 -13
  64. package/src/qingflow_mcp/solution/executor.py +112 -15
  65. package/src/qingflow_mcp/tools/ai_builder_tools.py +36 -11
  66. package/src/qingflow_mcp/tools/app_tools.py +184 -43
  67. package/src/qingflow_mcp/tools/approval_tools.py +196 -34
  68. package/src/qingflow_mcp/tools/auth_tools.py +92 -16
  69. package/src/qingflow_mcp/tools/code_block_tools.py +296 -39
  70. package/src/qingflow_mcp/tools/custom_button_tools.py +64 -10
  71. package/src/qingflow_mcp/tools/directory_tools.py +236 -72
  72. package/src/qingflow_mcp/tools/export_tools.py +230 -33
  73. package/src/qingflow_mcp/tools/file_tools.py +7 -3
  74. package/src/qingflow_mcp/tools/import_tools.py +293 -40
  75. package/src/qingflow_mcp/tools/navigation_tools.py +91 -12
  76. package/src/qingflow_mcp/tools/package_tools.py +118 -6
  77. package/src/qingflow_mcp/tools/portal_tools.py +39 -3
  78. package/src/qingflow_mcp/tools/qingbi_report_tools.py +116 -7
  79. package/src/qingflow_mcp/tools/record_tools.py +1042 -338
  80. package/src/qingflow_mcp/tools/resource_read_tools.py +188 -39
  81. package/src/qingflow_mcp/tools/role_tools.py +80 -9
  82. package/src/qingflow_mcp/tools/solution_tools.py +57 -15
  83. package/src/qingflow_mcp/tools/task_context_tools.py +569 -119
  84. package/src/qingflow_mcp/tools/task_tools.py +113 -29
  85. package/src/qingflow_mcp/tools/view_tools.py +106 -3
  86. package/src/qingflow_mcp/tools/workflow_tools.py +17 -1
  87. package/src/qingflow_mcp/tools/workspace_tools.py +71 -3
@@ -0,0 +1,140 @@
1
+ #!/usr/bin/env python3
2
+ """纯 CLI 曲线:在 **无** `package_list` / `package_resolve` 子命令时,用 `app list` + `builder app resolve` 解析包。
3
+
4
+ - `app list`(`GET /tag/apps` 扁平结果)常见含 **`package_name`**(分组显示名),**不一定**含数值 **`tag_id`**。
5
+ - `builder app resolve --app-key` 的 JSON 里常有 **`package_ids`**(与 MCP `package_get` 所用的 `tag_id` 同源)。
6
+
7
+ 子命令:
8
+ list-names 打印去重后的 `package_name` 列表(JSON 数组)
9
+ resolve-id <显示名> **精确匹配** `package_name`,取该组下第一个 `app_key`,再 `builder app resolve`,打印含 `package_ids` 的 JSON object
10
+
11
+ 环境(可选): `QINGFLOW_PROFILE` → 等价于 `qingflow --profile <名称>`
12
+
13
+ 注意:
14
+ - 若工作区内存在 **同名分组**(多个 `tag_id` 共用显示名),本脚本 **无法**区分,请用管理端或 MCP `package_list`。
15
+ - 某包下 **尚未有任何可见应用** 时,无法从 `app list` 曲线解析。
16
+
17
+ 用法:
18
+ ./scripts/builder-package-from-app-list.py list-names
19
+ ./scripts/builder-package-from-app-list.py resolve-id 'test'
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import json
25
+ import os
26
+ import shutil
27
+ import subprocess
28
+ import sys
29
+ from typing import Any
30
+
31
+
32
+ def _qf_base() -> list[str]:
33
+ cmd = ["qingflow"]
34
+ pf = os.environ.get("QINGFLOW_PROFILE") or os.environ.get("QING_FLOW_PROFILE")
35
+ if pf:
36
+ cmd.extend(["--profile", pf])
37
+ return cmd
38
+
39
+
40
+ def _run_json(cmd: list[str]) -> dict[str, Any]:
41
+ proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=None)
42
+ if proc.returncode != 0:
43
+ sys.stdout.buffer.write(proc.stdout)
44
+ sys.stdout.flush()
45
+ raise SystemExit(proc.returncode)
46
+ try:
47
+ text = proc.stdout.decode("utf-8")
48
+ payload = json.loads(text)
49
+ except (UnicodeDecodeError, json.JSONDecodeError) as e:
50
+ print(f"qingflow JSON 解析失败: {e}", file=sys.stderr)
51
+ sys.stdout.buffer.write(proc.stdout)
52
+ sys.stdout.flush()
53
+ raise SystemExit(1) from e
54
+ if not isinstance(payload, dict):
55
+ print("qingflow JSON 根不是 object", file=sys.stderr)
56
+ raise SystemExit(1)
57
+ return payload
58
+
59
+
60
+ def _app_list_items(payload: dict[str, Any]) -> list[dict[str, Any]]:
61
+ it = payload.get("items")
62
+ if isinstance(it, list):
63
+ return [x for x in it if isinstance(x, dict)]
64
+ nested = payload.get("data")
65
+ if isinstance(nested, dict):
66
+ it2 = nested.get("items")
67
+ if isinstance(it2, list):
68
+ return [x for x in it2 if isinstance(x, dict)]
69
+ return []
70
+
71
+
72
+ def cmd_list_names() -> None:
73
+ if not shutil.which("qingflow"):
74
+ print("qingflow: command not found", file=sys.stderr)
75
+ sys.exit(127)
76
+ payload = _run_json(_qf_base() + ["--json", "app", "list"])
77
+ rows = _app_list_items(payload)
78
+ names: set[str] = set()
79
+ for o in rows:
80
+ pn = o.get("package_name")
81
+ if isinstance(pn, str) and pn.strip():
82
+ names.add(pn.strip())
83
+ json.dump(sorted(names), sys.stdout, ensure_ascii=False, indent=2)
84
+ sys.stdout.write("\n")
85
+
86
+
87
+ def cmd_resolve_id(display_name: str) -> None:
88
+ if not shutil.which("qingflow"):
89
+ print("qingflow: command not found", file=sys.stderr)
90
+ sys.exit(127)
91
+ want = display_name.strip()
92
+ if not want:
93
+ print("显示名不能为空", file=sys.stderr)
94
+ sys.exit(2)
95
+
96
+ payload = _run_json(_qf_base() + ["--json", "app", "list"])
97
+ rows = _app_list_items(payload)
98
+ app_key: str | None = None
99
+ for o in rows:
100
+ pn = o.get("package_name")
101
+ if isinstance(pn, str) and pn.strip() == want:
102
+ ak = o.get("app_key")
103
+ if isinstance(ak, str) and ak.strip():
104
+ app_key = ak.strip()
105
+ break
106
+ if not app_key:
107
+ print(json.dumps({"error": "no_app_under_package_name", "package_name": want}, ensure_ascii=False, indent=2))
108
+ sys.exit(3)
109
+
110
+ resolved = _run_json(_qf_base() + ["--json", "builder", "app", "resolve", "--app-key", app_key])
111
+ out = {
112
+ "package_name": want,
113
+ "sample_app_key": app_key,
114
+ "package_ids": resolved.get("package_ids"),
115
+ "resolve": resolved,
116
+ }
117
+ json.dump(out, sys.stdout, ensure_ascii=False, indent=2)
118
+ sys.stdout.write("\n")
119
+
120
+
121
+ def main() -> None:
122
+ if len(sys.argv) < 2:
123
+ print(__doc__.strip(), file=sys.stderr)
124
+ sys.exit(2)
125
+ sub = sys.argv[1].strip().lower()
126
+ if sub in {"list-names", "list_names", "names"}:
127
+ cmd_list_names()
128
+ return
129
+ if sub in {"resolve-id", "resolve_id", "resolve"}:
130
+ if len(sys.argv) != 3:
131
+ print("用法: … resolve-id '<package显示名>'", file=sys.stderr)
132
+ sys.exit(2)
133
+ cmd_resolve_id(sys.argv[2])
134
+ return
135
+ print(__doc__.strip(), file=sys.stderr)
136
+ sys.exit(2)
137
+
138
+
139
+ if __name__ == "__main__":
140
+ main()
@@ -0,0 +1,132 @@
1
+ #!/usr/bin/env python3
2
+ """旧版 CLI 兼容:在本地对已登录会话的「应用列表」做关键字过滤。
3
+ 新版 CLI 默认使用 `qingflow --json app list --query <keyword>`;本脚本仅调用
4
+ `qingflow --json app list`。仅用标准库 json/subprocess/os/shutil。
5
+
6
+ qingflow stderr 不重定向,与直接执行 CLI 时一致。
7
+ qingflow 非零退出码时:本脚本将 **stdout 原文**写入当前进程 stdout;退出码与该进程相同。
8
+
9
+ 用法:
10
+ python3 scripts/find-app-by-keyword.py '<keyword>'
11
+ ./scripts/find-app-by-keyword.py '<keyword>'
12
+
13
+ 环境(可选): QINGFLOW_PROFILE → 等价于 qingflow --profile <名称>
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import json
19
+ import os
20
+ import shutil
21
+ import subprocess
22
+ import sys
23
+ from typing import Any
24
+
25
+
26
+ def _usage() -> None:
27
+ bn = os.path.basename(sys.argv[0]) if sys.argv else "find-app-by-keyword.py"
28
+ print(f"用法: {bn} <keyword>", file=sys.stderr)
29
+ print(
30
+ " 匹配 app_name、package_name、app_key 子串(不区分大小写)。"
31
+ " 仅 subprocess: qingflow [--profile …] --json app list",
32
+ file=sys.stderr,
33
+ )
34
+
35
+
36
+ def _merge_and_dedupe(data: dict[str, Any]) -> list[dict[str, Any]]:
37
+ parts: list[dict[str, Any]] = []
38
+ it = data.get("items")
39
+ if isinstance(it, list):
40
+ for x in it:
41
+ if isinstance(x, dict):
42
+ parts.append(x)
43
+ nested = data.get("data")
44
+ if isinstance(nested, dict):
45
+ it2 = nested.get("items")
46
+ if isinstance(it2, list):
47
+ for x in it2:
48
+ if isinstance(x, dict):
49
+ parts.append(x)
50
+ # 与 jq unique_by(.app_key) / 首次出现获胜 对齐
51
+ seen: set[Any] = set()
52
+ out: list[dict[str, Any]] = []
53
+ for obj in parts:
54
+ k = obj.get("app_key")
55
+ if k in seen:
56
+ continue
57
+ seen.add(k)
58
+ out.append(obj)
59
+ return out
60
+
61
+
62
+ def _filtered(keyword_lc: str, rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
63
+ hits: list[dict[str, Any]] = []
64
+ for o in rows:
65
+ for field in ("app_name", "package_name", "app_key"):
66
+ v = o.get(field)
67
+ if isinstance(v, str) and keyword_lc in v.lower():
68
+ hits.append(o)
69
+ break
70
+ return hits
71
+
72
+
73
+ def main() -> None:
74
+ if len(sys.argv) != 2:
75
+ _usage()
76
+ sys.exit(2)
77
+ kw = sys.argv[1].strip()
78
+ if not kw:
79
+ bn = os.path.basename(sys.argv[0]) if sys.argv else "find-app-by-keyword.py"
80
+ print(f"{bn}: keyword 不能为空", file=sys.stderr)
81
+ _usage()
82
+ sys.exit(2)
83
+
84
+ if not shutil.which("qingflow"):
85
+ print("qingflow: command not found", file=sys.stderr)
86
+ sys.exit(127)
87
+
88
+ cmd = ["qingflow"]
89
+ pf = os.environ.get("QINGFLOW_PROFILE") or os.environ.get("QING_FLOW_PROFILE")
90
+ if pf:
91
+ cmd.extend(["--profile", pf])
92
+ cmd.extend(["--json", "app", "list"])
93
+
94
+ proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=None)
95
+ buf = proc.stdout
96
+
97
+ if proc.returncode != 0:
98
+ sys.stdout.buffer.write(buf)
99
+ sys.stdout.flush()
100
+ raise SystemExit(proc.returncode)
101
+
102
+ try:
103
+ text = buf.decode("utf-8")
104
+ except UnicodeDecodeError as e:
105
+ print(f"qingflow stdout UTF-8 解码失败: {e}", file=sys.stderr)
106
+ sys.stdout.buffer.write(buf)
107
+ sys.stdout.flush()
108
+ raise SystemExit(1)
109
+
110
+ try:
111
+ payload = json.loads(text)
112
+ except json.JSONDecodeError as e:
113
+ print(f"qingflow stdout 不是合法 JSON: {e}", file=sys.stderr)
114
+ sys.stdout.buffer.write(buf)
115
+ sys.stdout.flush()
116
+ raise SystemExit(1)
117
+
118
+ if not isinstance(payload, dict):
119
+ print("qingflow JSON 根不是 object", file=sys.stderr)
120
+ sys.stdout.buffer.write(buf)
121
+ sys.stdout.flush()
122
+ raise SystemExit(1)
123
+
124
+ merged = _merge_and_dedupe(payload)
125
+ hits = _filtered(kw.lower(), merged)
126
+ out = {"keyword": kw, "match_count": len(hits), "items": hits}
127
+ json.dump(out, sys.stdout, ensure_ascii=False, indent=2)
128
+ sys.stdout.write("\n")
129
+
130
+
131
+ if __name__ == "__main__":
132
+ main()
@@ -0,0 +1,113 @@
1
+ ---
2
+ name: qingflow-mcp-setup
3
+ 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.
4
+ metadata:
5
+ short-description: Install and connect the Qingflow MCP locally
6
+ ---
7
+
8
+ # Qingflow MCP Setup
9
+
10
+ ## Overview
11
+
12
+ 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.
13
+
14
+ ## Workflow
15
+
16
+ Follow these steps in order.
17
+
18
+ `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.
19
+
20
+ 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`.
21
+
22
+ ### Step 1: Verify the local project path
23
+
24
+ Resolve the repository root first. In this repo, the MCP server should live at:
25
+
26
+ - `<repo_root>/qingflow-support/mcp-server`
27
+
28
+ Key entrypoint:
29
+
30
+ - `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
31
+
32
+ If the path differs, stop and update all client config snippets before proceeding.
33
+ 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`.
34
+
35
+ ### Step 2: Install local dependencies
36
+
37
+ Run:
38
+
39
+ ```bash
40
+ cd <repo_root>/qingflow-support/mcp-server
41
+ python3 -m venv .venv
42
+ ./.venv/bin/pip install -e '.[dev]'
43
+ ```
44
+
45
+ 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.
46
+
47
+ ### Step 3: Configure the local AI client
48
+
49
+ For any stdio-compatible MCP client, map these values:
50
+
51
+ - `command`: `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
52
+ - `args`: `[]`
53
+ - `env.QINGFLOW_MCP_DEFAULT_BASE_URL`: the target backend URL for the active environment
54
+ - `env.QINGFLOW_MCP_DEFAULT_QF_VERSION`: set this when the environment must route to a specific version such as `canary`
55
+
56
+ Client-specific snippets:
57
+
58
+ - Claude Desktop: read [references/claude-desktop.md](references/claude-desktop.md)
59
+ - Generic stdio MCP clients: read [references/generic-stdio.md](references/generic-stdio.md)
60
+
61
+ When both test and production are in play, keep separate config snippets or clearly labeled `env` blocks so the user can switch without ambiguity.
62
+
63
+ ### Step 4: Validate startup
64
+
65
+ The server is a stdio MCP process. A direct terminal launch may print nothing and wait for a client. That is normal.
66
+
67
+ Manual startup command:
68
+
69
+ ```bash
70
+ cd <repo_root>/qingflow-support/mcp-server
71
+ ./qingflow-mcp
72
+ ```
73
+
74
+ Prefer validating through the client after config is added.
75
+
76
+ ### Step 5: Use injected session first; authenticate only for setup or recovery
77
+
78
+ 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.
79
+
80
+ For a standalone local MCP client that has no injected session, use this setup order:
81
+
82
+ 1. `auth_use_credential` or `auth_login`
83
+ 2. `workspace_list`
84
+ 3. `workspace_select`
85
+ 4. Run a small read-only business tool
86
+
87
+ `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`.
88
+ 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.
89
+ `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.
90
+ 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`.
91
+
92
+ ### Step 6: Troubleshoot in the right layer
93
+
94
+ - If the client cannot launch the server, check path, execute permission, and `.venv`
95
+ - If tools return `auth required`, re-run `auth_use_credential` or `auth_login`
96
+ - If tools return `workspace not selected`, call `workspace_list` and `workspace_select`
97
+ - If calls fail after a working session, assume token expiry and re-authenticate
98
+ - If the browser shows data but MCP does not, compare `request_route` against the browser environment and check whether `qf_version` should be `canary`
99
+
100
+ ## Guardrails
101
+
102
+ - Never write tokens into the skill files
103
+ - 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.
104
+ - When debugging, distinguish server startup issues from Qingflow auth issues
105
+ - When the user mentions production, restate the exact `base_url`, `qf_version`, and workspace before any live validation
106
+ - 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
107
+
108
+ ## Resources
109
+
110
+ - Environment switching: [references/environments.md](references/environments.md)
111
+ - Claude Desktop config: [references/claude-desktop.md](references/claude-desktop.md)
112
+ - Generic stdio config: [references/generic-stdio.md](references/generic-stdio.md)
113
+ - Local checks: [scripts/check_local_server.sh](scripts/check_local_server.sh)
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Qingflow MCP Setup"
3
+ short_description: "Install and connect the Qingflow MCP locally"
4
+ 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."
@@ -0,0 +1,34 @@
1
+ # Claude Desktop
2
+
3
+ Use this when the user wants to install Qingflow MCP in Claude Desktop.
4
+
5
+ ## Config snippet
6
+
7
+ ```json
8
+ {
9
+ "mcpServers": {
10
+ "qingflow": {
11
+ "command": "<ABSOLUTE_PATH_TO_REPO>/qingflow-support/mcp-server/qingflow-mcp",
12
+ "args": [],
13
+ "env": {
14
+ "QINGFLOW_MCP_DEFAULT_BASE_URL": "<QINGFLOW_BASE_URL>"
15
+ }
16
+ }
17
+ }
18
+ }
19
+ ```
20
+
21
+ ## Environment examples
22
+
23
+ - `prod` (default): set `QINGFLOW_MCP_DEFAULT_BASE_URL` to `https://qingflow.com/api`
24
+ - `test`: if needed, set `QINGFLOW_MCP_DEFAULT_BASE_URL` to the explicitly provided non-production backend
25
+
26
+ Keep separate snippets for `test` and `prod` so switching environments does not require editing values in-place under pressure.
27
+
28
+ ## Notes
29
+
30
+ - After updating the config, restart Claude Desktop
31
+ - Replace `<ABSOLUTE_PATH_TO_REPO>` with the real checkout path on the current machine
32
+ - If the server path changes, update the `command` field
33
+ - The server is local stdio MCP, so no remote URL is required
34
+ - 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
@@ -0,0 +1,62 @@
1
+ # Environment Switching
2
+
3
+ Use this reference before any setup, authentication, or live validation flow.
4
+
5
+ ## Step 1: Resolve the active environment
6
+
7
+ Decide explicitly whether the user is targeting:
8
+
9
+ - `test`: for smoke tests, trial setup, DSL validation, mock data, and integration debugging
10
+ - `prod`: for real business usage in the formal environment
11
+
12
+ If the user did not specify an environment, default to `prod`.
13
+
14
+ ## Test Environment
15
+
16
+ Default characteristics:
17
+
18
+ - preferred for first-time setup and local MCP validation
19
+ - mock or smoke data is acceptable when the user asks for it
20
+ - use read/write verification freely inside the intended test workspace
21
+
22
+ Known values in the current workspace:
23
+
24
+ - use an explicitly provided non-production backend
25
+ - common test workspace example: `ws_id=2`
26
+ - `qf_version`: usually unset unless the user explicitly needs a routed version
27
+
28
+ Setup behavior:
29
+
30
+ - prefer this environment for Claude Desktop or local MCP client onboarding
31
+ - for Wingent Momo runtime, use the injected session and skip auth/workspace preflight
32
+ - for standalone MCP client setup, use `auth_use_credential` or `auth_login`, then `workspace_list`, then `workspace_select`
33
+ - if the user asks to verify installation, a real read-only smoke path is acceptable
34
+
35
+ ## Production Environment
36
+
37
+ 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.
38
+
39
+ Expected behavior:
40
+
41
+ - default `base_url`: `https://qingflow.com/api`
42
+ - confirm the production `qf_version` explicitly when browser traffic depends on routed versions such as `canary`
43
+ - confirm the exact workspace before any live validation
44
+ - prefer read-only checks first
45
+ - avoid mock data, smoke writes, or destructive tests unless the user explicitly asks for them
46
+
47
+ Production guardrails:
48
+
49
+ - do not store credentials in skill files or examples
50
+ - do not assume the same workspace ids as test
51
+ - treat startup verification and auth verification as separate steps
52
+ - when sharing snippets, label them as `prod` and `test` clearly
53
+ - when MCP and browser results diverge, compare `request_route` with the browser route before blaming the query logic
54
+
55
+ ## Reporting Rule
56
+
57
+ When you give setup instructions, always state:
58
+
59
+ - active environment
60
+ - selected `base_url`
61
+ - selected `qf_version` when relevant
62
+ - whether the next step is read-only or write-impacting
@@ -0,0 +1,32 @@
1
+ # Generic Stdio MCP Clients
2
+
3
+ Use this for any local AI client that supports MCP over stdio.
4
+
5
+ ## Required mapping
6
+
7
+ - `command`: `<ABSOLUTE_PATH_TO_REPO>/qingflow-support/mcp-server/qingflow-mcp`
8
+ - `args`: `[]`
9
+ - `env.QINGFLOW_MCP_DEFAULT_BASE_URL`: backend base URL for the active environment
10
+
11
+ Environment examples:
12
+
13
+ - `prod` (default): `https://qingflow.com/api`
14
+ - `test`: use the explicitly provided non-production backend
15
+
16
+ Keep separate client entries or separate config snippets for `test` and `prod`.
17
+
18
+ ## Validation sequence
19
+
20
+ 1. Start the client
21
+ 2. Confirm the `qingflow` MCP server is visible
22
+ 3. In Wingent Momo runtime, skip auth/workspace preflight and run a read-only tool such as `app_list`
23
+ 4. In a standalone client without injected credentials, run `auth_use_credential` or `auth_login`
24
+ 5. Then run `workspace_list`
25
+ 6. Then run `workspace_select`
26
+ 7. Run a read-only tool such as `app_list`
27
+
28
+ ## Common failures
29
+
30
+ - Launch failure: bad `command` path or missing `.venv`
31
+ - Auth failure: invalid or expired credential/token
32
+ - Business tool failure before setup: workspace not selected
@@ -0,0 +1,38 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+
4
+ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
5
+ ROOT="${QINGFLOW_MCP_ROOT:-}"
6
+
7
+ if [[ -z "$ROOT" ]]; then
8
+ if git_root="$(git rev-parse --show-toplevel 2>/dev/null)" && [[ -d "$git_root/qingflow-support/mcp-server" ]]; then
9
+ ROOT="$git_root/qingflow-support/mcp-server"
10
+ elif [[ -d "$PWD/qingflow-support/mcp-server" ]]; then
11
+ ROOT="$PWD/qingflow-support/mcp-server"
12
+ else
13
+ repo_root="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
14
+ if [[ -d "$repo_root/qingflow-support/mcp-server" ]]; then
15
+ ROOT="$repo_root/qingflow-support/mcp-server"
16
+ fi
17
+ fi
18
+ fi
19
+
20
+ if [[ -z "$ROOT" ]]; then
21
+ echo "Unable to locate qingflow-support/mcp-server. Set QINGFLOW_MCP_ROOT to the repo copy of the MCP server." >&2
22
+ exit 1
23
+ fi
24
+
25
+ ENTRY="$ROOT/qingflow-mcp"
26
+ PY="$ROOT/.venv/bin/python"
27
+
28
+ echo "ROOT=$ROOT"
29
+ test -d "$ROOT"
30
+ echo "OK root exists"
31
+
32
+ test -x "$ENTRY"
33
+ echo "OK entrypoint exists and is executable"
34
+
35
+ test -x "$PY"
36
+ echo "OK virtualenv python exists"
37
+
38
+ PYTHONPATH="$ROOT/src" "$PY" -c "import qingflow_mcp.server; print('OK import qingflow_mcp.server')"
@@ -1,5 +1,9 @@
1
- """Entry point for running qingflow_mcp as a module."""
2
- from qingflow_mcp.server import main
1
+ """Entry point for running qingflow_mcp as a module.
2
+
3
+ Default to the curated user-facing MCP surface. Split package and console
4
+ entrypoints can still start the builder server explicitly.
5
+ """
6
+ from qingflow_mcp.server_app_user import main
3
7
 
4
8
  if __name__ == "__main__":
5
9
  main()