@josephyan/qingflow-app-user-mcp 0.1.0-beta.9 → 0.2.0-beta.2

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.1.0-beta.9",
+  "version": "0.2.0-beta.2",
   "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.1.0b9"
+version = "0.2.0b2"
 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.1.0b9"
+__version__ = "0.2.0b2"

package/src/qingflow_mcp/builder_facade/__init__.py

@@ -0,0 +1,3 @@
+from .service import AiBuilderFacade
+
+__all__ = ["AiBuilderFacade"]

package/src/qingflow_mcp/builder_facade/models.py

@@ -0,0 +1,346 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import AliasChoices, Field, model_validator
+
+from ..solution.spec_models import StrictModel
+
+
+class PublicFieldType(str, Enum):
+    text = "text"
+    long_text = "long_text"
+    number = "number"
+    amount = "amount"
+    date = "date"
+    datetime = "datetime"
+    member = "member"
+    department = "department"
+    single_select = "single_select"
+    multi_select = "multi_select"
+    phone = "phone"
+    email = "email"
+    address = "address"
+    attachment = "attachment"
+    boolean = "boolean"
+    relation = "relation"
+    subtable = "subtable"
+
+
+FIELD_TYPE_ALIASES: dict[str, PublicFieldType] = {
+    "textarea": PublicFieldType.long_text,
+    "amount": PublicFieldType.amount,
+    "currency": PublicFieldType.amount,
+    "mobile": PublicFieldType.phone,
+    "user": PublicFieldType.member,
+    "users": PublicFieldType.member,
+    "select": PublicFieldType.single_select,
+    "radio": PublicFieldType.single_select,
+    "checkbox": PublicFieldType.multi_select,
+    "multi_select": PublicFieldType.multi_select,
+    "multi-select": PublicFieldType.multi_select,
+    "departments": PublicFieldType.department,
+}
+
+
+class PublicViewType(str, Enum):
+    table = "table"
+    card = "card"
+    board = "board"
+
+
+class LayoutApplyMode(str, Enum):
+    merge = "merge"
+    replace = "replace"
+
+
+class LayoutPreset(str, Enum):
+    balanced = "balanced"
+    compact = "compact"
+    single_section = "single_section"
+
+
+class FlowPreset(str, Enum):
+    basic_approval = "basic_approval"
+    basic_fill_then_approve = "basic_fill_then_approve"
+
+
+class ViewsPreset(str, Enum):
+    default_table = "default_table"
+    status_board = "status_board"
+
+
+class PublicFlowNodeType(str, Enum):
+    start = "start"
+    approve = "approve"
+    fill = "fill"
+    copy = "copy"
+    branch = "branch"
+    condition = "condition"
+    webhook = "webhook"
+    end = "end"
+
+
+class FieldSelector(StrictModel):
+    field_id: str | None = None
+    que_id: int | None = None
+    name: str | None = Field(default=None, validation_alias=AliasChoices("name", "title", "label"))
+
+    @model_validator(mode="after")
+    def validate_selector(self) -> "FieldSelector":
+        if not any((self.field_id, self.que_id, self.name)):
+            raise ValueError("selector must include field_id, que_id, or name")
+        return self
+
+
+class FieldPatch(StrictModel):
+    name: str = Field(validation_alias=AliasChoices("name", "title", "label"))
+    type: PublicFieldType
+    required: bool = False
+    description: str | None = None
+    options: list[str] = Field(default_factory=list)
+    target_app_key: str | None = None
+    subfields: list["FieldPatch"] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "FieldPatch":
+        if self.type == PublicFieldType.relation and not self.target_app_key:
+            raise ValueError("relation field requires target_app_key")
+        if self.type != PublicFieldType.relation and self.target_app_key:
+            raise ValueError("target_app_key is only allowed for relation fields")
+        if self.type == PublicFieldType.subtable and not self.subfields:
+            raise ValueError("subtable field requires subfields")
+        if self.type != PublicFieldType.subtable and self.subfields:
+            raise ValueError("subfields are only allowed for subtable fields")
+        return self
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        return _normalize_field_payload(value)
+
+
+class FieldMutation(StrictModel):
+    name: str | None = Field(default=None, validation_alias=AliasChoices("name", "title", "label"))
+    type: PublicFieldType | None = None
+    required: bool | None = None
+    description: str | None = None
+    options: list[str] | None = None
+    target_app_key: str | None = None
+    subfields: list[FieldPatch] | None = None
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "FieldMutation":
+        if self.type == PublicFieldType.relation and not self.target_app_key:
+            raise ValueError("relation field requires target_app_key")
+        if self.type == PublicFieldType.subtable and not self.subfields:
+            raise ValueError("subtable field requires subfields")
+        return self
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        return _normalize_field_payload(value)
+
+
+class FieldUpdatePatch(StrictModel):
+    selector: FieldSelector
+    set: FieldMutation
+
+
+class FieldRemovePatch(StrictModel):
+    field_id: str | None = None
+    que_id: int | None = None
+    name: str | None = Field(default=None, validation_alias=AliasChoices("name", "title", "label"))
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "FieldRemovePatch":
+        if not any((self.field_id, self.que_id, self.name)):
+            raise ValueError("remove patch must include field_id, que_id, or name")
+        return self
+
+
+class LayoutSectionPatch(StrictModel):
+    section_id: str | None = Field(default=None, validation_alias=AliasChoices("section_id", "sectionId"))
+    title: str
+    rows: list[list[str]] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_rows(self) -> "LayoutSectionPatch":
+        if not self.rows:
+            raise ValueError("section rows must be a non-empty list")
+        if not self.section_id:
+            self.section_id = _slugify_title(self.title)
+        return self
+
+
+class FlowNodePatch(StrictModel):
+    id: str
+    type: PublicFlowNodeType
+    name: str
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class FlowTransitionPatch(StrictModel):
+    source: str = Field(alias="from")
+    target: str = Field(alias="to")
+
+
+class ViewUpsertPatch(StrictModel):
+    name: str
+    type: PublicViewType
+    columns: list[str] = Field(default_factory=list)
+    group_by: 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)
+        if "fields" in payload and "columns" not in payload:
+            payload["columns"] = payload.pop("fields")
+        raw_type = payload.get("type")
+        if isinstance(raw_type, str):
+            normalized = raw_type.strip().lower()
+            if normalized == "tableview":
+                payload["type"] = "table"
+            elif normalized == "cardview":
+                payload["type"] = "card"
+            elif normalized == "kanban":
+                payload["type"] = "board"
+        return payload
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "ViewUpsertPatch":
+        if self.type in {PublicViewType.table, PublicViewType.card} and not self.columns:
+            raise ValueError("table/card views require columns")
+        if self.type == PublicViewType.board and not self.group_by:
+            raise ValueError("board view requires group_by")
+        return self
+
+
+FieldPatch.model_rebuild()
+
+
+class AppReadSummaryResponse(StrictModel):
+    app_key: str
+    title: str | None = None
+    tag_ids: list[int] = Field(default_factory=list)
+    publish_status: int | None = None
+    field_count: int = 0
+    layout_section_count: int = 0
+    view_count: int = 0
+    workflow_enabled: bool = False
+    verification_hints: list[str] = Field(default_factory=list)
+
+
+class AppFieldsReadResponse(StrictModel):
+    app_key: str
+    fields: list[dict[str, Any]] = Field(default_factory=list)
+    field_count: int = 0
+
+
+class AppLayoutReadResponse(StrictModel):
+    app_key: str
+    sections: list[dict[str, Any]] = Field(default_factory=list)
+    unplaced_fields: list[str] = Field(default_factory=list)
+    layout_mode_detected: str = "empty"
+
+
+class AppViewsReadResponse(StrictModel):
+    app_key: str
+    views: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class AppFlowReadResponse(StrictModel):
+    app_key: str
+    enabled: bool = False
+    nodes: list[dict[str, Any]] = Field(default_factory=list)
+    transitions: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class SchemaPlanRequest(StrictModel):
+    app_key: str = ""
+    package_tag_id: int | None = None
+    app_name: str = Field(default="", validation_alias=AliasChoices("app_name", "app_title", "title"))
+    create_if_missing: bool = False
+    add_fields: list[FieldPatch] = Field(default_factory=list)
+    update_fields: list[FieldUpdatePatch] = Field(default_factory=list)
+    remove_fields: list[FieldRemovePatch] = Field(default_factory=list)
+
+
+class LayoutPlanRequest(StrictModel):
+    app_key: str
+    mode: LayoutApplyMode = LayoutApplyMode.merge
+    sections: list[LayoutSectionPatch] = Field(default_factory=list)
+    preset: LayoutPreset | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_mode_alias(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if str(payload.get("mode") or "").strip().lower() == "overwrite":
+            payload["mode"] = "replace"
+        return payload
+
+
+class FlowPlanRequest(StrictModel):
+    app_key: str
+    mode: str = "replace"
+    nodes: list[FlowNodePatch] = Field(default_factory=list)
+    transitions: list[FlowTransitionPatch] = Field(default_factory=list)
+    preset: FlowPreset | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_mode_alias(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if str(payload.get("mode") or "").strip().lower() == "overwrite":
+            payload["mode"] = "replace"
+        return payload
+
+
+class ViewsPlanRequest(StrictModel):
+    app_key: str
+    upsert_views: list[ViewUpsertPatch] = Field(default_factory=list)
+    remove_views: list[str] = Field(default_factory=list)
+    preset: ViewsPreset | None = None
+
+
+class OperationResultEnvelope(StrictModel):
+    status: str
+    error_code: str | None = None
+    recoverable: bool = False
+    message: str
+    normalized_args: dict[str, Any] = Field(default_factory=dict)
+    missing_fields: list[str] = Field(default_factory=list)
+    allowed_values: dict[str, Any] = Field(default_factory=dict)
+    details: dict[str, Any] = Field(default_factory=dict)
+    request_id: str | None = None
+    suggested_next_call: dict[str, Any] | None = None
+    noop: bool = False
+    verification: dict[str, Any] = Field(default_factory=dict)
+
+
+def _normalize_field_payload(value: Any) -> Any:
+    if not isinstance(value, dict):
+        return value
+    payload = dict(value)
+    raw_type = payload.get("type")
+    if isinstance(raw_type, str):
+        normalized = FIELD_TYPE_ALIASES.get(raw_type.strip().lower())
+        if normalized is not None:
+            payload["type"] = normalized.value
+    return payload
+
+
+def _slugify_title(title: str) -> str:
+    normalized = "".join(ch.lower() if ch.isalnum() else "_" for ch in str(title or ""))
+    collapsed = "_".join(part for part in normalized.split("_") if part)
+    return collapsed or "section"