@josephyan/qingflow-app-builder-mcp 0.2.0-beta.25 → 0.2.0-beta.27

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.25
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.27
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.25 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.27 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.25",
+  "version": "0.2.0-beta.27",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b25"
+version = "0.2.0b27"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b25"
+__version__ = "0.2.0b27"

package/src/qingflow_mcp/server.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from datetime import date
+
 from mcp.server.fastmcp import FastMCP
 
 from .backend_client import BackendClient
@@ -23,25 +25,88 @@ from .tools.workspace_tools import WorkspaceTools
 
 
 def build_server() -> FastMCP:
+    today = date.today()
+    current_year = today.year
     server = FastMCP(
         "Qingflow MCP",
-        instructions=(
-            "Use auth_login first, then workspace_list and workspace_select. "
-            "All resource tools operate with the logged-in user's Qingflow permissions.\n\n"
-            "If app_key is unknown, use app_list or app_search first to discover current-user visible apps in the selected workspace. "
-            "For analytics, use record_schema_get first, let the model build field_id-based DSL, "
-            "then call record_analyze. record_analyze returns compact business-first output as query/result/ranking/ratios/completeness/presentation; use verbose only for route/debug details. "
-            "record_schema_get returns the current user's applicant-node visible schema only; hidden fields are omitted and missing fields should be treated as not visible in the current permission scope. "
-            "For operational record reads, use record_schema_get first, then record_list or record_get. "
-            "For writes, use record_schema_get and then call record_write once; it performs internal preflight before any apply and refuses fields outside the applicant-node writable schema.\n\n"
-            "Task Center (待办/已办) handling:\n"
-            "- Use task_summary to get headline counts.\n"
-            "- Use task_list for flat task browsing with task_box and flow_status.\n"
-            "- Use task_facets when worksheet or workflow-node buckets matter.\n"
-            "- Use task_mark_read to mark a specific task as read.\n"
-            "- Use task_urge to send an urgent reminder for a pending task.\n"
-            "- After identifying the exact task node and record, use task_approve, task_reject, task_rollback, or task_transfer as needed."
-        ),
+        instructions=f"""Use this server for Qingflow operational workflows. Current date: `{today.isoformat()}`.
+
+## Authentication
+
+Use `auth_login` first, then `workspace_list` and `workspace_select`.
+All resource tools operate with the logged-in user's Qingflow permissions.
+
+## App Discovery
+
+If `app_key` is unknown, use `app_list` or `app_search` first.
+
+## Schema-First Rule
+
+Always call `record_schema_get` before `record_list`, `record_get`, `record_write`, or `record_analyze`.
+
+- All `field_id` values must come from the schema response.
+- Never guess field names or ids.
+
+## Schema Scope
+
+`record_schema_get` returns the current user's applicant-node visible fields only.
+
+- Hidden fields are omitted.
+- Missing fields mean the field is not visible in the current permission scope.
+
+## Analytics Path
+
+`record_schema_get -> record_analyze`
+
+Use this DSL shape:
+
+- `dimensions`: `{{field_id, alias, bucket}}`
+- `metrics`: `{{op, field_id, alias}}`
+- `filters`: `{{field_id, op, value}}`
+- `sort`: `{{by, order}}`
+
+Important key rules:
+
+- Use `op`
+- Do **not** use `type`
+- Do **not** use `agg`
+- Do **not** use `aggregation`
+- Do **not** use `operator`
+
+Analysis answers must include concrete numbers. When applicable, include percentages based on the returned totals.
+
+## Record CRUD Path
+
+`record_schema_get -> record_list / record_get / record_write`
+
+`record_write` uses SQL-like JSON clauses:
+
+- `insert` -> `values`
+- `update` -> `record_id + set`
+- `delete` -> `record_id` or `record_ids`
+
+- Read relation targets from `record_schema_get.target_app_key` / `target_app_name` before preparing relation writes.
+- If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
+
+## Task Center Path
+
+`task_summary -> task_list / task_facets -> task action`
+
+## Time Handling
+
+Normalize relative dates before building DSL.
+
+- If the user says `3月` without a year, use the current year: `{current_year}`
+- Convert month-only phrases into explicit legal date ranges
+- Never send impossible dates such as `2026-02-29`
+
+## Environment
+
+Default to `prod` unless the user explicitly specifies `test`.
+
+## Constraints
+
+Avoid builder-side app or schema changes here.""",
     )
     sessions = SessionStore()
     backend = BackendClient()

package/src/qingflow_mcp/server_app_user.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from datetime import date
+
 from mcp.server.fastmcp import FastMCP
 
 from .backend_client import BackendClient
@@ -16,17 +18,83 @@ from .tools.workspace_tools import WorkspaceTools
 
 
 def build_user_server() -> FastMCP:
+    today = date.today()
+    current_year = today.year
     server = FastMCP(
         "Qingflow App User MCP",
-        instructions=(
-            "Use this server for Qingflow operational workflows with a schema-first path. "
-            "If app_key is unknown, use app_list or app_search first to discover current-user visible apps in the selected workspace. "
-            "For records, start with record_schema_get, then choose record_list, record_get, or record_write. "
-            "record_schema_get returns the current user's applicant-node visible schema only; hidden fields are omitted and missing fields should be treated as not visible in the current permission scope. "
-            "For analytics, switch to record_schema_get and record_analyze; its default output is compact query/result/ranking/ratios/completeness/presentation, with route/debug only in verbose mode. "
-            "For task center, use task_summary, task_list, and task_facets before any explicit task action. "
-            "Avoid builder-side app or schema changes here."
-        ),
+        instructions=f"""Use this server for Qingflow operational workflows. Current date: `{today.isoformat()}`.
+
+## App Discovery
+
+If `app_key` is unknown, use `app_list` or `app_search` first.
+
+## Schema-First Rule
+
+Always call `record_schema_get` before `record_list`, `record_get`, `record_write`, or `record_analyze`.
+
+- All `field_id` values must come from the schema response.
+- Never guess field names or ids.
+
+## Schema Scope
+
+`record_schema_get` returns the current user's applicant-node visible fields only.
+
+- Hidden fields are omitted.
+- Missing fields mean the field is not visible in the current permission scope.
+
+## Analytics Path
+
+`record_schema_get -> record_analyze`
+
+Use this DSL shape:
+
+- `dimensions`: `{{field_id, alias, bucket}}`
+- `metrics`: `{{op, field_id, alias}}`
+- `filters`: `{{field_id, op, value}}`
+- `sort`: `{{by, order}}`
+
+Important key rules:
+
+- Use `op`
+- Do **not** use `type`
+- Do **not** use `agg`
+- Do **not** use `aggregation`
+- Do **not** use `operator`
+
+Analysis answers must include concrete numbers. When applicable, include percentages based on the returned totals.
+
+## Record CRUD Path
+
+`record_schema_get -> record_list / record_get / record_write`
+
+`record_write` uses SQL-like JSON clauses:
+
+- `insert` -> `values`
+- `update` -> `record_id + set`
+- `delete` -> `record_id` or `record_ids`
+
+- Read relation targets from `record_schema_get.target_app_key` / `target_app_name` before preparing relation writes.
+- If a member or department field id is known but candidate ids are not, use `record_member_candidates` or `record_department_candidates` before `record_write`.
+
+## Task Center Path
+
+`task_summary -> task_list / task_facets -> task action`
+
+## Time Handling
+
+Normalize relative dates before building DSL.
+
+- If the user says `3月` without a year, use the current year: `{current_year}`
+- Convert month-only phrases into explicit legal date ranges
+- Never send impossible dates such as `2026-02-29`
+
+## Environment
+
+Default to `prod` unless the user explicitly specifies `test`.
+
+## Constraints
+
+Avoid builder-side app or schema changes here.""",
     )
     sessions = SessionStore()
     backend = BackendClient()

package/src/qingflow_mcp/tools/directory_tools.py

@@ -303,15 +303,57 @@ class DirectoryTools(ToolBase):
         page_num: int,
         page_size: int,
     ) -> dict[str, Any]:
-        if not keyword:
-            raise_tool_error(QingflowApiError.config_error("keyword is required"))
+        if page_num <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_num must be positive"))
+        if page_size <= 0:
+            raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
+        normalized_keyword = keyword.strip()
+
+        if not normalized_keyword:
+            def runner(session_profile, context):
+                fetch_limit = max((page_num + 1) * page_size + 1, page_size + 1)
+                items, truncated, deepest_depth = self._walk_department_tree(
+                    context,
+                    parent_dept_id=None,
+                    max_depth=20,
+                    max_items=fetch_limit,
+                )
+                start = (page_num - 1) * page_size
+                page_items = items[start : start + page_size]
+                reported_total = None if truncated else len(items)
+                page_amount = None if truncated else ((len(items) + page_size - 1) // page_size if items else 0)
+                if truncated and page_items:
+                    page_amount = max(page_num + 1, (start + len(page_items) + page_size - 1) // page_size)
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "request_route": self._request_route_payload(context),
+                    "items": page_items,
+                    "pagination": {
+                        "page": page_num,
+                        "page_size": page_size,
+                        "returned_items": len(page_items),
+                        "reported_total": reported_total,
+                        "page_amount": page_amount,
+                        "depth_scanned": deepest_depth + 1 if page_items else 0,
+                    },
+                }
+
+            raw = self._run(profile, runner)
+            items = [item for item in raw.get("items", []) if isinstance(item, dict)]
+            return self._public_directory_response(
+                raw,
+                items=items,
+                pagination=raw.get("pagination", {}),
+                selection={"keyword": None},
+            )
 
         def runner(session_profile, context):
             result = self.backend.request(
                 "GET",
                 context,
                 "/contact/deptByPage",
-                params={"keyword": keyword, "pageNum": page_num, "pageSize": page_size},
+                params={"keyword": normalized_keyword, "pageNum": page_num, "pageSize": page_size},
             )
             return {
                 "profile": profile,
@@ -332,7 +374,7 @@ class DirectoryTools(ToolBase):
                 "reported_total": _coerce_int(_payload_value(raw.get("page"), "total")),
                 "page_amount": _coerce_int(_payload_value(raw.get("page"), "pageAmount")),
             },
-            selection={"keyword": keyword},
+            selection={"keyword": normalized_keyword},
         )
 
     def directory_list_all_departments(