@josephyan/qingflow-app-user-mcp 0.2.0-beta.36 → 0.2.0-beta.38

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.36",
+  "version": "0.2.0-beta.38",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

package/skills/qingflow-app-user/SKILL.md

@@ -31,6 +31,7 @@ Route to exactly one of these specialized paths:
 ## Routing Rules
 
 - If the user does not know the target `app_key`, discover apps first with `app_list` or `app_search`, then route to the specialized skill
+- If the app is known but the available data range is unclear, call `app_get` first and inspect `accessible_views`
 - If the task is about browsing, reading, creating, updating, deleting, attachments, relations, subtable writes, or member/department-field candidate lookup, switch to `$qingflow-record-crud`
 - If the task is about todo discovery, task context, approval actions, rollback or transfer, associated report review, or workflow log review, switch to `$qingflow-task-ops`
 - If the task is about grouped distributions, ratios, rankings, trends, insights, or any final statistical conclusion, switch to `$qingflow-record-analysis`

package/skills/qingflow-record-analysis/SKILL.md

@@ -9,13 +9,15 @@ metadata:
 
 This skill is for final statistical conclusions only.
 Assumes MCP is connected, authenticated, and on the correct workspace.
-Analysis tasks must start with `record_schema_get`. Read top-level `fields` and `suggested_*`, then build field_id-based DSLs only.
+Analysis tasks must start with `app_get`, then `record_schema_get(schema_mode="browse", view_id=...)`. Read top-level `fields` and `suggested_*`, then build field_id-based DSLs only.
+Analysis tasks must start with `record_schema_get`.
+If `app_get.accessible_views` marks a view with `analysis_supported=false`, do not use that view for `record_list` or `record_analyze`. `boardView` and `ganttView` are special UI views, not list/analyze targets.
 
-## Step 1: `record_schema_get` → Step 2: build DSL → Step 3: `record_analyze`
+## Step 1: `app_get` → Step 2: `record_schema_get(schema_mode="browse", view_id=...)` → Step 3: build DSL → Step 4: `record_analyze`
 
-This is the ONLY execution order. Never skip step 1. Never call `record_analyze` without a schema.
+This is the ONLY execution order. Never skip `app_get` when the browse range is unclear. Never call `record_analyze` without a browse schema.
 
-Core tools: `record_schema_get`, `record_analyze`. Use `record_list`/`record_get` only for post-analysis samples; task/comment work stays in [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md).
+Core tools: `app_get`, `record_schema_get`, `record_analyze`. Use `record_list`/`record_get` only for post-analysis samples; task/comment work stays in [$qingflow-task-ops](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-task-ops/SKILL.md).
 
 ---
 
@@ -105,7 +107,8 @@ Top-level arguments:
 - `dimensions`: `[]` = whole-table summary; `[{...}]` = grouped.
 - `strict_full`: `true` for final conclusions. `false` allows partial results.
 - `limit`: limits returned rows only, not scan scope.
-- `view_key`/`view_name`: optional scope narrowing.
+- `view_id`: the canonical browse selector. Prefer choosing it from `app_get.accessible_views`.
+- Prefer `view_id` entries where `analysis_supported=true`. If a view is `boardView` or `ganttView`, switch to a system or table-style custom view before calling `record_analyze`.
 - `bucket` in dimensions: only for `suggested_time_fields`. Values: `day`/`week`/`month`/`quarter`/`year`/`null`.
 
 ---

package/skills/qingflow-record-crud/SKILL.md

@@ -16,9 +16,9 @@ Assumes MCP is connected, authenticated, and on the correct workspace.
 
 Use exactly one of these default paths:
 
-1. Browse records: `record_schema_get -> record_list`
-2. Read one record: `record_schema_get -> record_get`
-3. Write records: `record_schema_get -> record_write`
+1. Browse records: `app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_list`
+2. Read one record: `app_get -> record_schema_get(schema_mode="browse", view_id=...) -> record_get`
+3. Write records: `record_schema_get(schema_mode="applicant") -> record_write`
 
 ## Core Tools
 
@@ -27,12 +27,15 @@ Use exactly one of these default paths:
 - `record_get`
 - `record_write`
 
-`record_schema_get` only exposes the current user's applicant-node visible fields. Read top-level `fields` and `suggested_*`; if a field is missing, treat it as unavailable in the current permission scope.
+`record_schema_get(schema_mode="applicant")` exposes the current user's applicant-node visible write/create fields.
+`record_schema_get(schema_mode="browse", view_id=...)` exposes browse-schema fields for the selected accessible view.
+Read top-level `fields` and `suggested_*`; if a field is missing, treat it as unavailable in the current permission scope.
 
 ## Supporting Tools
 
 - `app_list`
 - `app_search`
+- `app_get`
 - `record_member_candidates`
 - `record_department_candidates`
 - `directory_search`
@@ -50,7 +53,9 @@ Use `record_member_candidates` / `record_department_candidates` as the default l
 2. Ensure workspace is selected
 3. Confirm target app and whether the task is browse / detail / write / analysis
 4. If `app_key` is unknown, use `app_list` or `app_search` first
-5. Run `record_schema_get` before any non-trivial record read or write
+5. If browse/read range is unclear, run `app_get` and choose from `accessible_views`
+6. Run `record_schema_get(schema_mode="browse", view_id=...)` before browse/read
+7. Run `record_schema_get(schema_mode="applicant")` before write
 6. If the request is analysis-like, switch to [$qingflow-record-analysis](/Users/yanqidong/Documents/qingflow-next/.codex/skills/qingflow-record-analysis/SKILL.md)
 7. If the request is write-like, decide `insert / update / delete` before building any payload
 8. If fields are still ambiguous after `record_schema_get`, ask the user to confirm from a short candidate list instead of guessing
@@ -60,6 +65,7 @@ Use `record_member_candidates` / `record_department_candidates` as the default l
 ## Record Read Rules
 
 - Use `record_list` for browse/export/sample inspection only
+- Prefer choosing a `view_id` from `app_get.accessible_views`
 - For `columns`, use `[{ "field_id": 12 }]`
 - For `where`, use `{ "field_id": 12, "op": "eq", "value": "进行中" }`
 - For `order_by`, use `{ "field_id": 18, "direction": "desc" }`
@@ -73,7 +79,7 @@ Use `record_write` as the only default write tool.
 
 ### Write workflow
 
-1. Run `record_schema_get`
+1. Run `record_schema_get(schema_mode="applicant")`
 2. Decide whether the task is `insert`, `update`, or `delete`
 3. For relation fields, read `target_app_key / target_app_name` from schema first
 4. For member fields with unknown ids, run `record_member_candidates`

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/builder_facade/models.py

@@ -69,6 +69,14 @@ class PublicViewType(str, Enum):
     gantt = "gantt"
 
 
+class PublicChartType(str, Enum):
+    target = "target"
+    pie = "pie"
+    bar = "bar"
+    line = "line"
+    table = "table"
+
+
 class LayoutApplyMode(str, Enum):
     merge = "merge"
     replace = "replace"
@@ -491,6 +499,215 @@ class ViewUpsertPatch(StrictModel):
         return self
 
 
+class ChartFilterRulePatch(StrictModel):
+    field_name: str = Field(validation_alias=AliasChoices("field_name", "fieldName", "field", "name"))
+    operator: ViewFilterOperator = Field(validation_alias=AliasChoices("operator", "op"))
+    values: list[Any] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "value" in payload and "values" not in payload:
+            payload["values"] = [payload.pop("value")]
+        raw_operator = payload.get("operator", payload.get("op"))
+        if isinstance(raw_operator, str):
+            normalized = raw_operator.strip().lower()
+            operator_aliases = {
+                "equals": ViewFilterOperator.eq.value,
+                "equal": ViewFilterOperator.eq.value,
+                "=": ViewFilterOperator.eq.value,
+                "not_equals": ViewFilterOperator.neq.value,
+                "not_equal": ViewFilterOperator.neq.value,
+                "!=": ViewFilterOperator.neq.value,
+                ">=": ViewFilterOperator.gte.value,
+                "<=": ViewFilterOperator.lte.value,
+                "any_of": ViewFilterOperator.in_.value,
+                "one_of": ViewFilterOperator.in_.value,
+                "between_any": ViewFilterOperator.in_.value,
+                "empty": ViewFilterOperator.is_empty.value,
+                "is blank": ViewFilterOperator.is_empty.value,
+                "blank": ViewFilterOperator.is_empty.value,
+                "not_empty": ViewFilterOperator.not_empty.value,
+                "not blank": ViewFilterOperator.not_empty.value,
+            }
+            if normalized in operator_aliases:
+                payload["operator"] = operator_aliases[normalized]
+            elif "operator" not in payload:
+                payload["operator"] = normalized
+        payload.pop("op", None)
+        return payload
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "ChartFilterRulePatch":
+        if self.operator in {ViewFilterOperator.is_empty, ViewFilterOperator.not_empty}:
+            self.values = []
+            return self
+        if not self.values:
+            raise ValueError("chart filter rule requires values")
+        return self
+
+
+class ChartUpsertPatch(StrictModel):
+    chart_id: str | None = None
+    name: str
+    chart_type: PublicChartType
+    dimension_field_ids: list[str] = Field(default_factory=list)
+    indicator_field_ids: list[str] = Field(default_factory=list)
+    filters: list[ChartFilterRulePatch] = Field(default_factory=list)
+    question_config: list[dict[str, Any]] = Field(default_factory=list)
+    user_config: list[dict[str, Any]] = Field(default_factory=list)
+    config: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "id" in payload and "chart_id" not in payload:
+            payload["chart_id"] = payload.pop("id")
+        if "type" in payload and "chart_type" not in payload:
+            payload["chart_type"] = payload.pop("type")
+        if "dimension_fields" in payload and "dimension_field_ids" not in payload:
+            payload["dimension_field_ids"] = payload.pop("dimension_fields")
+        if "indicator_fields" in payload and "indicator_field_ids" not in payload:
+            payload["indicator_field_ids"] = payload.pop("indicator_fields")
+        if "metric_field_ids" in payload and "indicator_field_ids" not in payload:
+            payload["indicator_field_ids"] = payload.pop("metric_field_ids")
+        raw_type = payload.get("chart_type")
+        if isinstance(raw_type, str):
+            normalized = raw_type.strip().lower()
+            aliases = {
+                "targetchart": PublicChartType.target.value,
+                "piechart": PublicChartType.pie.value,
+                "barchart": PublicChartType.bar.value,
+                "linechart": PublicChartType.line.value,
+                "tablechart": PublicChartType.table.value,
+            }
+            if normalized in aliases:
+                payload["chart_type"] = aliases[normalized]
+        return payload
+
+
+class ChartApplyRequest(StrictModel):
+    app_key: str
+    upsert_charts: list[ChartUpsertPatch] = Field(default_factory=list)
+    remove_chart_ids: list[str] = Field(default_factory=list)
+    reorder_chart_ids: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "ChartApplyRequest":
+        if not self.upsert_charts and not self.remove_chart_ids and not self.reorder_chart_ids:
+            raise ValueError("chart apply requires at least one upsert, remove, or reorder operation")
+        return self
+
+
+class PortalComponentPositionPatch(StrictModel):
+    pc_x: int = Field(default=0, validation_alias=AliasChoices("pc_x", "pcX", "x"))
+    pc_y: int = Field(default=0, validation_alias=AliasChoices("pc_y", "pcY", "y"))
+    pc_w: int = Field(default=12, validation_alias=AliasChoices("pc_w", "pcW", "w"))
+    pc_h: int = Field(default=8, validation_alias=AliasChoices("pc_h", "pcH", "h"))
+    mobile_x: int = Field(default=0, validation_alias=AliasChoices("mobile_x", "mobileX"))
+    mobile_y: int = Field(default=0, validation_alias=AliasChoices("mobile_y", "mobileY"))
+    mobile_w: int = Field(default=12, validation_alias=AliasChoices("mobile_w", "mobileW"))
+    mobile_h: int = Field(default=8, validation_alias=AliasChoices("mobile_h", "mobileH"))
+
+
+class PortalChartRefPatch(StrictModel):
+    app_key: str
+    chart_id: str | None = None
+    chart_name: str | None = None
+
+    @model_validator(mode="after")
+    def validate_target(self) -> "PortalChartRefPatch":
+        if not (self.chart_id or self.chart_name):
+            raise ValueError("chart_ref requires chart_id or chart_name")
+        return self
+
+
+class PortalViewRefPatch(StrictModel):
+    app_key: str
+    view_key: str | None = None
+    view_name: str | None = None
+
+    @model_validator(mode="after")
+    def validate_target(self) -> "PortalViewRefPatch":
+        if not (self.view_key or self.view_name):
+            raise ValueError("view_ref requires view_key or view_name")
+        return self
+
+
+class PortalSectionPatch(StrictModel):
+    title: str
+    source_type: str = Field(validation_alias=AliasChoices("source_type", "sourceType"))
+    position: PortalComponentPositionPatch | None = None
+    dash_style_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("dash_style_config", "dashStyleConfigBO"))
+    config: dict[str, Any] = Field(default_factory=dict)
+    chart_ref: PortalChartRefPatch | None = None
+    view_ref: PortalViewRefPatch | None = None
+    text: str | None = None
+    url: str | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        raw_type = payload.get("source_type", payload.get("sourceType"))
+        if isinstance(raw_type, str):
+            payload["source_type"] = raw_type.strip().lower()
+        if "chartRef" in payload and "chart_ref" not in payload:
+            payload["chart_ref"] = payload.pop("chartRef")
+        if "viewRef" in payload and "view_ref" not in payload:
+            payload["view_ref"] = payload.pop("viewRef")
+        if "dashStyleConfigBO" in payload and "dash_style_config" not in payload:
+            payload["dash_style_config"] = payload.pop("dashStyleConfigBO")
+        return payload
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "PortalSectionPatch":
+        supported = {"chart", "view", "grid", "filter", "text", "link"}
+        if self.source_type not in supported:
+            raise ValueError(f"unsupported portal source_type '{self.source_type}'")
+        if self.source_type == "chart" and self.chart_ref is None:
+            raise ValueError("chart section requires chart_ref")
+        if self.source_type == "view" and self.view_ref is None:
+            raise ValueError("view section requires view_ref")
+        if self.source_type == "text" and self.text is None:
+            raise ValueError("text section requires text")
+        if self.source_type == "link" and self.url is None:
+            raise ValueError("link section requires url")
+        return self
+
+
+class PortalApplyRequest(StrictModel):
+    dash_key: str | None = None
+    dash_name: str | None = None
+    package_tag_id: int | None = None
+    publish: bool = True
+    sections: list[PortalSectionPatch] = Field(default_factory=list)
+    auth: dict[str, Any] | None = None
+    icon: str | None = None
+    color: str | None = None
+    hide_copyright: bool | None = Field(default=None, validation_alias=AliasChoices("hide_copyright", "hideCopyright"))
+    dash_global_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("dash_global_config", "dashGlobalConfig"))
+    config: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "PortalApplyRequest":
+        if not self.dash_key and not self.package_tag_id:
+            raise ValueError("package_tag_id is required when dash_key is empty")
+        if not self.dash_key and not self.dash_name:
+            raise ValueError("dash_name is required when creating a portal")
+        if not self.sections:
+            raise ValueError("portal apply requires a non-empty sections list")
+        return self
+
+
 FieldPatch.model_rebuild()