@qingflow-tech/qingflow-app-user-mcp 1.0.0

package/src/qingflow_mcp/errors.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+
+from .json_types import JSONObject, JSONScalar
+
+
+INVALID_TOKEN_MARKERS = (
+    "invalid token",
+    "token invalid",
+    "token失效",
+    "无效token",
+    "登录失效",
+    "login token invalid",
+    "access token invalid",
+)
+
+
+@dataclass(slots=True)
+class QingflowApiError(Exception):
+    category: str
+    message: str
+    backend_code: JSONScalar = None
+    request_id: str | None = None
+    http_status: int | None = None
+    details: JSONObject | None = None
+
+    def to_dict(self) -> JSONObject:
+        return asdict(self)
+
+    def as_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False)
+
+    def __str__(self) -> str:
+        return self.as_json()
+
+    def looks_like_invalid_token(self) -> bool:
+        text = self.message.lower()
+        return any(marker in text for marker in INVALID_TOKEN_MARKERS)
+
+    @classmethod
+    def auth_required(cls, profile: str) -> "QingflowApiError":
+        return cls(
+            category="auth",
+            message=f"Profile '{profile}' is not logged in. Run auth_use_credential first.",
+        )
+
+    @classmethod
+    def workspace_not_selected(cls, profile: str) -> "QingflowApiError":
+        return cls(
+            category="workspace",
+            message=f"WORKSPACE_NOT_SELECTED: profile '{profile}' has no workspace from auth context. Re-run auth_use_credential.",
+        )
+
+    @classmethod
+    def config_error(cls, message: str) -> "QingflowApiError":
+        return cls(category="config", message=message)
+
+    @classmethod
+    def not_supported(cls, message: str) -> "QingflowApiError":
+        return cls(category="not_supported", message=message)
+
+
+def raise_tool_error(error: QingflowApiError) -> None:
+    raise RuntimeError(error.as_json())

package/src/qingflow_mcp/import_store.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+from .config import get_mcp_home
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _parse_utc(value: Any) -> datetime | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    normalized = value.strip().replace("Z", "+00:00")
+    try:
+        parsed = datetime.fromisoformat(normalized)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def _json_safe_key(value: str) -> str:
+    keep = []
+    for char in value:
+        if char.isalnum() or char in {"-", "_"}:
+            keep.append(char)
+        else:
+            keep.append("_")
+    result = "".join(keep).strip("_")
+    return result or "entry"
+
+
+def _store_dir(env_var: str, default_name: str) -> Path:
+    custom = os.getenv(env_var)
+    if custom:
+        return Path(custom).expanduser()
+    return get_mcp_home() / default_name
+
+
+@dataclass(slots=True)
+class _JsonEntryStore:
+    base_dir: Path
+    ttl: timedelta
+
+    def __post_init__(self) -> None:
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        self.prune()
+
+    def put(self, entry_id: str, payload: dict[str, Any]) -> None:
+        data = dict(payload)
+        data["id"] = entry_id
+        data["updated_at"] = _utc_now().isoformat()
+        self._path(entry_id).write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    def get(self, entry_id: str) -> dict[str, Any] | None:
+        path = self._path(entry_id)
+        if not path.exists():
+            return None
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            path.unlink(missing_ok=True)
+            return None
+        created_at = _parse_utc(payload.get("created_at")) or _parse_utc(payload.get("updated_at"))
+        if created_at is None or _utc_now() - created_at > self.ttl:
+            path.unlink(missing_ok=True)
+            return None
+        return payload
+
+    def prune(self) -> None:
+        for path in self.base_dir.glob("*.json"):
+            try:
+                payload = json.loads(path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                path.unlink(missing_ok=True)
+                continue
+            created_at = _parse_utc(payload.get("created_at")) or _parse_utc(payload.get("updated_at"))
+            if created_at is None or _utc_now() - created_at > self.ttl:
+                path.unlink(missing_ok=True)
+
+    def list(self) -> list[dict[str, Any]]:
+        entries: list[dict[str, Any]] = []
+        self.prune()
+        for path in self.base_dir.glob("*.json"):
+            try:
+                payload = json.loads(path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            created_at = _parse_utc(payload.get("created_at")) or _parse_utc(payload.get("updated_at"))
+            if created_at is None:
+                continue
+            entries.append(payload)
+        entries.sort(key=lambda item: item.get("created_at") or item.get("updated_at") or "", reverse=True)
+        return entries
+
+    def _path(self, entry_id: str) -> Path:
+        return self.base_dir / f"{_json_safe_key(entry_id)}.json"
+
+
+class ImportVerificationStore(_JsonEntryStore):
+    def __init__(self, base_dir: Path | None = None, *, ttl_seconds: int = 3600) -> None:
+        super().__init__(
+            base_dir=base_dir or _store_dir("QINGFLOW_MCP_IMPORT_VERIFY_HOME", "import-verifications"),
+            ttl=timedelta(seconds=ttl_seconds),
+        )
+
+
+class ImportJobStore(_JsonEntryStore):
+    def __init__(self, base_dir: Path | None = None, *, ttl_seconds: int = 24 * 3600) -> None:
+        super().__init__(
+            base_dir=base_dir or _store_dir("QINGFLOW_MCP_IMPORT_JOB_HOME", "import-jobs"),
+            ttl=timedelta(seconds=ttl_seconds),
+        )

package/src/qingflow_mcp/json_types.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Protocol, Any
+
+# Use Any for JSON types to avoid Pydantic recursion issues
+# These are used for MCP tool signatures where exact typing is less critical
+JSONScalar = Any
+JSONValue = Any
+JSONObject = dict[str, Any]
+JSONArray = list[Any]
+
+
+class KeyringBackend(Protocol):
+    def set_password(self, service: str, key: str, value: str) -> None: ...
+
+    def get_password(self, service: str, key: str) -> str | None: ...
+
+    def delete_password(self, service: str, key: str) -> None: ...

package/src/qingflow_mcp/list_type_labels.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+
+RECORD_LIST_TYPE_LABELS: dict[int, str] = {
+    1: "待办",
+    2: "已办",
+    3: "我发起的-已通过",
+    4: "我发起的-已拒绝",
+    5: "我发起的-草稿",
+    6: "我发起的-待完善",
+    7: "我发起的-流程中",
+    8: "数据管理-全部数据",
+    9: "数据管理-已通过",
+    10: "数据管理-已拒绝",
+    11: "数据管理-流程中",
+    12: "抄送",
+    13: "图表分享者",
+    14: "我发起的",
+    15: "数据管理-已结束",
+    16: "我发起的-已结束",
+}
+
+SYSTEM_VIEW_DEFINITIONS: tuple[tuple[str, int, str], ...] = (
+    ("system:all", 8, "全部数据"),
+    ("system:initiated", 14, "我发起的"),
+    ("system:todo", 1, "待办"),
+    ("system:done", 2, "已办"),
+    ("system:cc", 12, "抄送我的"),
+)
+
+SYSTEM_VIEW_ID_TO_LIST_TYPE: dict[str, int] = {view_id: list_type for view_id, list_type, _ in SYSTEM_VIEW_DEFINITIONS}
+SYSTEM_VIEW_ID_TO_NAME: dict[str, str] = {view_id: name for view_id, _, name in SYSTEM_VIEW_DEFINITIONS}
+SYSTEM_LIST_TYPE_TO_VIEW_ID: dict[int, str] = {list_type: view_id for view_id, list_type, _ in SYSTEM_VIEW_DEFINITIONS}
+
+TASK_TYPE_LABELS: dict[int, str] = {
+    1: "待办",
+    2: "我发起的",
+    3: "抄送",
+    5: "已办",
+}
+
+APP_PUBLISH_STATUS_LABELS: dict[int, str] = {
+    0: "未发布",
+    1: "已发布-有修改",
+    2: "已发布",
+}
+
+
+def get_record_list_type_label(list_type: int | None) -> str | None:
+    if list_type is None:
+        return None
+    return RECORD_LIST_TYPE_LABELS.get(list_type)
+
+
+def get_system_view_id(list_type: int | None) -> str | None:
+    if list_type is None:
+        return None
+    return SYSTEM_LIST_TYPE_TO_VIEW_ID.get(list_type)
+
+
+def get_system_view_name(view_id: str | None) -> str | None:
+    if view_id is None:
+        return None
+    return SYSTEM_VIEW_ID_TO_NAME.get(view_id)
+
+
+def get_task_type_label(type_value: int | None) -> str | None:
+    if type_value is None:
+        return None
+    return TASK_TYPE_LABELS.get(type_value)
+
+
+def get_app_publish_status_label(status: int | None) -> str | None:
+    if status is None:
+        return None
+    return APP_PUBLISH_STATUS_LABELS.get(status)

package/src/qingflow_mcp/public_surface.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+from argparse import Namespace
+from dataclasses import dataclass
+
+
+USER_DOMAIN = "user"
+BUILDER_DOMAIN = "builder"
+
+
+@dataclass(frozen=True, slots=True)
+class PublicToolSpec:
+    domain: str
+    tool_name: str
+    method_names: tuple[str, ...] = ()
+    cli_route: tuple[str, ...] | None = None
+    mcp_public: bool = True
+    cli_public: bool = True
+    has_contract: bool = False
+    cli_show_effective_context: bool = False
+    cli_context_write: bool = False
+
+    @property
+    def trim_key(self) -> str:
+        return tool_key(self.domain, self.tool_name)
+
+
+def tool_key(domain: str, tool_name: str) -> str:
+    return f"{domain}:{tool_name}"
+
+
+USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
+    PublicToolSpec(USER_DOMAIN, "auth_use_credential", ("auth_use_credential",), ("auth", "use-credential")),
+    PublicToolSpec(USER_DOMAIN, "auth_whoami", ("auth_whoami",), ("auth", "whoami")),
+    PublicToolSpec(USER_DOMAIN, "auth_logout", ("auth_logout",), ("auth", "logout")),
+    PublicToolSpec(USER_DOMAIN, "workspace_list", ("workspace_list",), ("workspace", "list")),
+    PublicToolSpec(USER_DOMAIN, "app_list", ("app_list",), ("app", "list"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "app_search", ("app_search",), ("app", "search"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "app_get", ("app_get",), ("app", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "portal_list", ("portal_list",), ("portal", "list"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "portal_get", ("portal_get",), ("portal", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "view_get", ("view_get",), ("view", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "chart_get", ("chart_get",), ("chart", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "file_get_upload_info", ("file_get_upload_info",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "file_upload_local", ("file_upload_local",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "feedback_submit", ("feedback_submit",), cli_public=False),
+    PublicToolSpec(
+        USER_DOMAIN,
+        "record_schema_get",
+        cli_route=("record", "schema", "applicant"),
+        mcp_public=False,
+    ),
+    PublicToolSpec(
+        USER_DOMAIN,
+        "record_browse_schema_get",
+        ("record_browse_schema_get_public",),
+        ("record", "schema", "browse"),
+    ),
+    PublicToolSpec(
+        USER_DOMAIN,
+        "record_insert_schema_get",
+        ("record_insert_schema_get_public",),
+        ("record", "schema", "insert"),
+    ),
+    PublicToolSpec(
+        USER_DOMAIN,
+        "record_update_schema_get",
+        ("record_update_schema_get_public",),
+        ("record", "schema", "update"),
+    ),
+    PublicToolSpec(USER_DOMAIN, "record_import_schema_get", ("record_import_schema_get",), ("record", "schema", "import")),
+    PublicToolSpec(
+        USER_DOMAIN,
+        "record_code_block_schema_get",
+        ("record_code_block_schema_get_public",),
+        ("record", "schema", "code-block"),
+    ),
+    PublicToolSpec(USER_DOMAIN, "record_member_candidates", ("record_member_candidates",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "record_department_candidates", ("record_department_candidates",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "record_analyze", ("record_analyze",), ("record", "analyze")),
+    PublicToolSpec(USER_DOMAIN, "record_list", ("record_list",), ("record", "list"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_get", ("record_get_public",), ("record", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_insert", ("record_insert_public",), ("record", "insert"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "record_update", ("record_update_public",), ("record", "update"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "record_delete", ("record_delete_public",), ("record", "delete"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "record_import_template_get", ("record_import_template_get",), ("import", "template")),
+    PublicToolSpec(USER_DOMAIN, "record_import_verify", ("record_import_verify",), ("import", "verify")),
+    PublicToolSpec(USER_DOMAIN, "record_import_repair_local", ("record_import_repair_local",), ("import", "repair")),
+    PublicToolSpec(USER_DOMAIN, "record_import_start", ("record_import_start",), ("import", "start")),
+    PublicToolSpec(USER_DOMAIN, "record_import_status_get", ("record_import_status_get",), ("import", "status")),
+    PublicToolSpec(USER_DOMAIN, "record_code_block_run", ("record_code_block_run",), ("record", "code-block-run"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "task_list", ("task_list",), ("task", "list"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "task_get", ("task_get",), ("task", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "task_action_execute", ("task_action_execute",), ("task", "action"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "task_associated_report_detail_get", ("task_associated_report_detail_get",), cli_public=False, cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "task_workflow_log_get", ("task_workflow_log_get",), ("task", "log"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "directory_search", ("directory_search",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "directory_list_internal_users", ("directory_list_internal_users",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "directory_list_all_internal_users", ("directory_list_all_internal_users",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "directory_list_internal_departments", ("directory_list_internal_departments",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "directory_list_all_departments", ("directory_list_all_departments",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "directory_list_sub_departments", ("directory_list_sub_departments",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "directory_list_external_members", ("directory_list_external_members",), cli_public=False),
+)
+
+
+BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
+    PublicToolSpec(BUILDER_DOMAIN, "auth_use_credential", ("auth_use_credential",), ("builder", "auth", "use-credential"), cli_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "auth_whoami", ("auth_whoami",), ("builder", "auth", "whoami"), cli_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "auth_logout", ("auth_logout",), ("builder", "auth", "logout"), cli_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "workspace_list", ("workspace_list",), ("builder", "workspace", "list"), cli_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "file_upload_local", ("file_upload_local",), ("builder", "file", "upload-local"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "feedback_submit", ("feedback_submit",), ("builder", "feedback", "submit"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "builder_tool_contract", ("builder_tool_contract",), ("builder", "contract"), has_contract=False),
+    PublicToolSpec(BUILDER_DOMAIN, "package_get", ("package_get",), ("builder", "package", "get"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "package_apply", ("package_apply",), ("builder", "package", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "solution_install", ("solution_install",), ("builder", "solution", "install"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "member_search", ("member_search",), ("builder", "member", "search"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "role_search", ("role_search",), ("builder", "role", "search"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "role_create", ("role_create",), ("builder", "role", "create"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_release_edit_lock_if_mine", ("app_release_edit_lock_if_mine",), ("builder", "app", "release-edit-lock-if-mine"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_resolve", ("app_resolve",), ("builder", "app", "resolve"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_list", ("app_custom_button_list",), ("builder", "button", "list"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_get", ("app_custom_button_get",), ("builder", "button", "get"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_create", ("app_custom_button_create",), ("builder", "button", "create"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_update", ("app_custom_button_update",), ("builder", "button", "update"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_delete", ("app_custom_button_delete",), ("builder", "button", "delete"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get", ("app_get",), ("builder", "app", "get", "summary"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_fields", ("app_get_fields",), ("builder", "app", "get", "fields"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_repair_code_blocks", ("app_repair_code_blocks",), ("builder", "app", "repair-code-blocks"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_layout", ("app_get_layout",), ("builder", "app", "get", "layout"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_views", ("app_get_views",), ("builder", "app", "get", "views"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_flow", ("app_get_flow",), ("builder", "app", "get", "flow"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_charts", ("app_get_charts",), ("builder", "app", "get", "charts"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "portal_list", ("portal_list",), ("builder", "portal", "list"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "portal_get", ("portal_get",), ("builder", "portal", "get"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "view_get", ("view_get",), ("builder", "view", "get"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "chart_get", ("chart_get",), ("builder", "chart", "get"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_schema_apply", ("app_schema_apply",), ("builder", "schema", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_layout_apply", ("app_layout_apply",), ("builder", "layout", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_flow_apply", ("app_flow_apply",), ("builder", "flow", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_views_apply", ("app_views_apply",), ("builder", "views", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_charts_apply", ("app_charts_apply",), ("builder", "charts", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "portal_apply", ("portal_apply",), ("builder", "portal", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_publish_verify", ("app_publish_verify",), ("builder", "publish", "verify"), has_contract=True, cli_show_effective_context=True),
+)
+
+
+ALL_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = USER_PUBLIC_TOOL_SPECS + BUILDER_PUBLIC_TOOL_SPECS
+PUBLIC_TOOL_BY_KEY: dict[str, PublicToolSpec] = {spec.trim_key: spec for spec in ALL_PUBLIC_TOOL_SPECS}
+PUBLIC_TOOL_BY_CLI_ROUTE: dict[tuple[str, ...], PublicToolSpec] = {
+    spec.cli_route: spec
+    for spec in ALL_PUBLIC_TOOL_SPECS
+    if spec.cli_public and spec.cli_route is not None
+}
+
+
+def public_tool_specs(domain: str | None = None) -> tuple[PublicToolSpec, ...]:
+    if domain is None:
+        return ALL_PUBLIC_TOOL_SPECS
+    return tuple(spec for spec in ALL_PUBLIC_TOOL_SPECS if spec.domain == domain)
+
+
+def public_mcp_tool_names(domain: str) -> set[str]:
+    return {spec.tool_name for spec in public_tool_specs(domain) if spec.mcp_public}
+
+
+def public_builder_contract_tool_names() -> list[str]:
+    return sorted(
+        spec.tool_name
+        for spec in BUILDER_PUBLIC_TOOL_SPECS
+        if spec.has_contract and (spec.mcp_public or spec.cli_public)
+    )
+
+
+def server_method_map(domain: str) -> dict[str, str]:
+    mapping: dict[str, str] = {}
+    for spec in public_tool_specs(domain):
+        if not spec.mcp_public:
+            continue
+        for method_name in spec.method_names:
+            mapping[method_name] = spec.trim_key
+    return mapping
+
+
+def cli_trim_key_from_namespace(args: Namespace) -> str | None:
+    route = cli_route_from_namespace(args)
+    if route is None:
+        return None
+    spec = PUBLIC_TOOL_BY_CLI_ROUTE.get(route)
+    return spec.trim_key if spec is not None else None
+
+
+def cli_public_tool_spec_from_namespace(args: Namespace) -> PublicToolSpec | None:
+    route = cli_route_from_namespace(args)
+    if route is None:
+        return None
+    return PUBLIC_TOOL_BY_CLI_ROUTE.get(route)
+
+
+def cli_route_from_namespace(args: Namespace) -> tuple[str, ...] | None:
+    command = getattr(args, "command", None)
+    if not isinstance(command, str) or not command:
+        return None
+    command = "builder" if command == "build" else command
+    if command == "record":
+        record_command = getattr(args, "record_command", None)
+        if record_command == "schema":
+            schema_command = getattr(args, "record_schema_command", None)
+            return (command, "schema", schema_command) if isinstance(schema_command, str) and schema_command else None
+        return (command, record_command) if isinstance(record_command, str) and record_command else None
+    if command == "task":
+        task_command = getattr(args, "task_command", None)
+        return (command, task_command) if isinstance(task_command, str) and task_command else None
+    if command != "builder":
+        child_attr = f"{command}_command"
+        child = getattr(args, child_attr, None)
+        return (command, child) if isinstance(child, str) and child else None
+
+    builder_command = getattr(args, "builder_command", None)
+    if not isinstance(builder_command, str) or not builder_command:
+        return None
+    if builder_command == "contract":
+        return ("builder", "contract")
+    if builder_command == "app":
+        app_command = getattr(args, "builder_app_command", None)
+        if app_command == "get":
+            section = getattr(args, "builder_app_get_section", "summary") or "summary"
+            return ("builder", "app", "get", str(section))
+        return ("builder", "app", app_command) if isinstance(app_command, str) and app_command else None
+    child_attr = f"builder_{builder_command.replace('-', '_')}_command"
+    child = getattr(args, child_attr, None)
+    return ("builder", builder_command, child) if isinstance(child, str) and child else None

package/src/qingflow_mcp/repository_store.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .config import get_repository_metadata_dir
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _safe_key(value: str) -> str:
+    keep: list[str] = []
+    for char in value:
+        if char.isalnum() or char in {"-", "_"}:
+            keep.append(char)
+        else:
+            keep.append("_")
+    normalized = "".join(keep).strip("_")
+    return normalized or "repository"
+
+
+@dataclass(slots=True)
+class RepositoryMetadataStore:
+    base_dir: Path | None = None
+    _dir: Path = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._dir = self.base_dir or get_repository_metadata_dir()
+        self._dir.mkdir(parents=True, exist_ok=True)
+
+    def put(self, repo_name: str, payload: dict[str, Any]) -> dict[str, Any]:
+        now = _utc_now()
+        existing = self.get(repo_name) or {}
+        data = dict(existing)
+        data.update(payload)
+        data["repo_name"] = repo_name
+        data["created_at"] = existing.get("created_at") or now
+        data["updated_at"] = now
+        self._path(repo_name).write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+        return data
+
+    def get(self, repo_name: str) -> dict[str, Any] | None:
+        path = self._path(repo_name)
+        if not path.exists():
+            return None
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            path.unlink(missing_ok=True)
+            return None
+        return payload if isinstance(payload, dict) else None
+
+    def list(self) -> list[dict[str, Any]]:
+        entries: list[dict[str, Any]] = []
+        for path in sorted(self._dir.glob("*.json")):
+            try:
+                payload = json.loads(path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            if isinstance(payload, dict):
+                entries.append(payload)
+        entries.sort(key=lambda item: str(item.get("updated_at") or ""), reverse=True)
+        return entries
+
+    def _path(self, repo_name: str) -> Path:
+        return self._dir / f"{_safe_key(repo_name)}.json"