@josephyan/qingflow-app-builder-mcp 0.2.0-beta.26 → 0.2.0-beta.28

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.26",
+  "version": "0.2.0-beta.28",
   "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.0b26"
+version = "0.2.0b28"
 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.0b26"
+__version__ = "0.2.0b28"

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,91 @@ 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.
+- Read `fields` and `suggested_*` from the top level of the schema response.
+
+## 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`
+
+- For `columns`, prefer `[{{field_id}}]`; bare integer field ids remain supported for compatibility.
+
+`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,86 @@ 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.
+- Read `fields` and `suggested_*` from the top level of the schema response.
+
+## 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`
+
+- For `columns`, prefer `[{{field_id}}]`; bare integer field ids remain supported for compatibility.
+
+`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()