@josephyan/qingflow-app-user-mcp 1.0.6 → 1.0.7

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@1.0.6
+npm install @josephyan/qingflow-app-user-mcp@1.0.7
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@1.0.6 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@1.0.7 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "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 = "1.0.6"
+version = "1.0.7"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -73,7 +73,7 @@ Use `record_access` to fetch detail rows into local CSV shards. It does not anal
 }
 ```
 
-Then run Python against every `files[].local_path`. CSV columns are stable: `record_id`, then `field_<field_id>`. Use `fields[]` metadata to map titles and types.
+Then run Python against every `files[].local_path`. CSV columns are stable: `record_id`, then `field_<field_id>`. Use `fields[]` plus `metadata_files.schema` / `metadata_files.readme` in the same output directory to map titles and types, especially when reusing the CSV later.
 
 - Never ask for `page`, `page_size`, `limit`, or `max_rows`; `record_access` owns paging internally and follows the backend's native paging capability.
 - If multiple CSV files are returned, read them all.

package/skills/qingflow-record-analysis/references/analysis-gotchas.md

@@ -94,6 +94,7 @@ Examples of the right recovery question:
 - Do not invent `page_size`
 - Do not invent `requested_pages`
 - Do not invent `scan_max_pages`
+- Do not rename CSV columns before analysis; use `metadata_files.schema` / `metadata_files.readme` to interpret `field_<id>` columns.
 - Do not invent `auto_expand_pages`
 - Do not invent `max_rows`
 

package/skills/qingflow-record-analysis/references/analysis-patterns.md

@@ -28,9 +28,10 @@ Result reading order:
 1. `record_access.complete`
 2. `record_access.safe_for_final_conclusion`
 3. `record_access.files[].local_path`
-4. Python outputs
-5. `record_access.fields`
-6. `record_access.warnings`
+4. `record_access.metadata_files.schema`
+5. Python outputs
+6. `record_access.fields`
+7. `record_access.warnings`
 
 Treat `record_browse_schema_get` as the browse-schema source of truth. Missing fields are permission boundaries, not invitations to guess hidden ids.
 

package/src/qingflow_mcp/response_trim.py

@@ -455,11 +455,13 @@ def _trim_record_access(payload: JSONObject) -> None:
         "app_key",
         "view_id",
         "format",
+        "local_dir",
         "row_count",
         "complete",
         "truncated",
         "safe_for_final_conclusion",
         "files",
+        "metadata_files",
         "fields",
         "warnings",
         "verification",

package/src/qingflow_mcp/server_app_user.py

@@ -74,7 +74,7 @@ Inside `optional_fields`, any field with `may_become_required=true` is still wri
 
 Prefer `view_id` entries from `accessible_views` where `analysis_supported=true`.
 
-Use `record_access` to write local CSV shard files, then use Python to compute counts, rankings, ratios, trends, and final conclusions. `record_access` does not return bulk `items`; read `files[].local_path`.
+Use `record_access` to write local CSV shard files, then use Python to compute counts, rankings, ratios, trends, and final conclusions. `record_access` does not return bulk `items`; read `files[].local_path`. Use `fields[]` and the same-directory `metadata_files.schema` / `metadata_files.readme` to map stable `field_<id>` CSV columns back to titles and types.
 Use `chart_get` only when the user provides a report URL / chart_id or explicitly asks to read an existing report. Do not use QingBI as the default analysis route.
 
 Use this data-access DSL shape:

package/src/qingflow_mcp/tools/record_tools.py

@@ -1932,6 +1932,7 @@ class RecordTools(ToolBase):
             current_page = 1
             has_more = False
             reported_total: int | None = None
+            created_at = datetime.now(UTC).isoformat()
             try:
                 while True:
                     if used_list_type is None:
@@ -2049,6 +2050,25 @@ class RecordTools(ToolBase):
             safe_for_final_conclusion = complete and not any(
                 warning.get("code") == "CUSTOM_VIEW_FILTER_UNVERIFIED" for warning in warnings
             )
+            fields_payload = [_record_access_field_payload(field) for field in selected_fields]
+            verification_payload: JSONObject = {
+                **_view_filter_verification_payload(view_route),
+                "reported_total": reported_total,
+                "list_type_used": used_list_type,
+            }
+            metadata_files = _write_record_access_metadata_files(
+                run_dir=run_dir,
+                created_at=created_at,
+                app_key=app_key,
+                view_route=view_route,
+                row_count=row_count,
+                complete=complete,
+                safe_for_final_conclusion=safe_for_final_conclusion,
+                files=files,
+                fields=fields_payload,
+                warnings=warnings,
+                verification=verification_payload,
+            )
             return {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
@@ -2057,18 +2077,16 @@ class RecordTools(ToolBase):
                 "app_key": app_key,
                 "view_id": view_route.view_id,
                 "format": "csv",
+                "local_dir": str(run_dir),
                 "row_count": row_count,
                 "complete": complete,
                 "truncated": not complete,
                 "safe_for_final_conclusion": safe_for_final_conclusion,
                 "files": files,
-                "fields": [_record_access_field_payload(field) for field in selected_fields],
+                "metadata_files": metadata_files,
+                "fields": fields_payload,
                 "warnings": warnings,
-                "verification": {
-                    **_view_filter_verification_payload(view_route),
-                    "reported_total": reported_total,
-                    "list_type_used": used_list_type,
-                },
+                "verification": verification_payload,
                 "request_route": self._request_route_payload(context),
             }
 
@@ -11503,6 +11521,133 @@ def _record_access_field_payload(field: FormField) -> JSONObject:
     }
 
 
+def _write_record_access_metadata_files(
+    *,
+    run_dir: Path,
+    created_at: str,
+    app_key: str,
+    view_route: AccessibleViewRoute,
+    row_count: int,
+    complete: bool,
+    safe_for_final_conclusion: bool,
+    files: list[JSONObject],
+    fields: list[JSONObject],
+    warnings: list[JSONObject],
+    verification: JSONObject,
+) -> JSONObject:
+    schema_path = run_dir / "schema.json"
+    readme_path = run_dir / "README.md"
+    schema_payload: JSONObject = {
+        "created_at": created_at,
+        "app_key": app_key,
+        "view_id": view_route.view_id,
+        "view_name": view_route.name,
+        "view_type": view_route.view_type,
+        "format": "csv",
+        "row_count": row_count,
+        "complete": complete,
+        "truncated": not complete,
+        "safe_for_final_conclusion": safe_for_final_conclusion,
+        "files": files,
+        "fields": fields,
+        "warnings": warnings,
+        "verification": verification,
+        "csv_columns": ["record_id"] + [str(field["column_name"]) for field in fields if field.get("column_name")],
+    }
+    schema_path.write_text(json.dumps(schema_payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    readme_path.write_text(
+        _record_access_readme(
+            created_at=created_at,
+            app_key=app_key,
+            view_route=view_route,
+            row_count=row_count,
+            complete=complete,
+            safe_for_final_conclusion=safe_for_final_conclusion,
+            files=files,
+            fields=fields,
+            warnings=warnings,
+        ),
+        encoding="utf-8",
+    )
+    return {
+        "schema": str(schema_path),
+        "readme": str(readme_path),
+    }
+
+
+def _record_access_readme(
+    *,
+    created_at: str,
+    app_key: str,
+    view_route: AccessibleViewRoute,
+    row_count: int,
+    complete: bool,
+    safe_for_final_conclusion: bool,
+    files: list[JSONObject],
+    fields: list[JSONObject],
+    warnings: list[JSONObject],
+) -> str:
+    lines = [
+        "# Qingflow Record Access",
+        "",
+        f"- Created at: {created_at}",
+        f"- App key: `{app_key}`",
+        f"- View: {view_route.name} (`{view_route.view_id}`)",
+        f"- Format: CSV",
+        f"- Rows: {row_count}",
+        f"- Complete: {str(complete).lower()}",
+        f"- Safe for final conclusion: {str(safe_for_final_conclusion).lower()}",
+        "",
+        "## Data Files",
+        "",
+    ]
+    if files:
+        for file_info in files:
+            local_path = _normalize_optional_text(file_info.get("local_path")) or ""
+            part = file_info.get("part")
+            file_rows = file_info.get("row_count")
+            lines.append(f"- `{Path(local_path).name}`: part {part}, {file_rows} rows")
+    else:
+        lines.append("- No CSV shard files were written because the query returned 0 rows.")
+    lines.extend(
+        [
+            "",
+            "## Columns",
+            "",
+            "| CSV column | Field ID | Title | Type |",
+            "|---|---:|---|---|",
+            "| `record_id` | - | Record ID | record_id |",
+        ]
+    )
+    for field in fields:
+        column_name = _markdown_escape(str(field.get("column_name", "")))
+        field_id = field.get("field_id", "")
+        title = _markdown_escape(str(field.get("title", "")))
+        field_type = _markdown_escape(str(field.get("type", "")))
+        lines.append(f"| `{column_name}` | {field_id} | {title} | {field_type} |")
+    if warnings:
+        lines.extend(["", "## Warnings", ""])
+        for warning in warnings:
+            code = _normalize_optional_text(warning.get("code")) or "WARNING"
+            message = _normalize_optional_text(warning.get("message")) or ""
+            lines.append(f"- `{code}`: {message}")
+    lines.extend(
+        [
+            "",
+            "## Usage Notes",
+            "",
+            "- Use `records-*.csv` for Python or pandas processing; column names are stable and field-id based.",
+            "- Use `schema.json` or this README to map `field_<field_id>` columns back to Qingflow field titles and types.",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _markdown_escape(value: str) -> str:
+    return value.replace("\\", "\\\\").replace("|", "\\|").replace("\n", " ")
+
+
 def _record_access_field_type(field: FormField) -> str:
     if field.que_type in DATE_QUE_TYPES:
         return "datetime"