@josephyan/qingflow-cli 0.2.0-beta.73 → 0.2.0-beta.75

package/src/qingflow_mcp/cli/commands/builder.py

@@ -77,6 +77,14 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     package_resolve.add_argument("--package-name", required=True)
     package_resolve.set_defaults(handler=_handle_package_resolve, format_hint="builder_summary")
 
+    solution = builder_subparsers.add_parser("solution", help="解决方案")
+    solution_subparsers = solution.add_subparsers(dest="builder_solution_command", required=True)
+    solution_install = solution_subparsers.add_parser("install", help="安装解决方案")
+    solution_install.add_argument("--solution-key", required=True)
+    solution_install.add_argument("--being-copy-data", action=argparse.BooleanOptionalAction, default=True)
+    solution_install.add_argument("--solution-source", default="solutionDetail")
+    solution_install.set_defaults(handler=_handle_solution_install, format_hint="builder_summary")
+
     package_create = package_subparsers.add_parser("create", help="创建应用包")
     package_create.add_argument("--package-name", required=True)
     package_create.add_argument("--icon")
@@ -114,6 +122,12 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     app_get.add_argument("--app-key", required=True)
     app_get.set_defaults(handler=_handle_app_get, format_hint="builder_summary")
 
+    app_repair_code_blocks = app_subparsers.add_parser("repair-code-blocks", help="扫描或修复现有代码块配置")
+    app_repair_code_blocks.add_argument("--app-key", required=True)
+    app_repair_code_blocks.add_argument("--field")
+    app_repair_code_blocks.add_argument("--apply", action="store_true")
+    app_repair_code_blocks.set_defaults(handler=_handle_app_repair_code_blocks, format_hint="builder_summary")
+
     button = builder_subparsers.add_parser("button", help="自定义按钮")
     button_subparsers = button.add_subparsers(dest="builder_button_command", required=True)
 
@@ -144,7 +158,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     portal = builder_subparsers.add_parser("portal", help="门户")
     portal_subparsers = portal.add_subparsers(dest="builder_portal_command", required=True)
-    portal_list = portal_subparsers.add_parser("list", help="列出可访问门户")
+    portal_list = portal_subparsers.add_parser("list", help="列出可配置门户")
     portal_list.set_defaults(handler=_handle_portal_list, format_hint="builder_summary")
 
     portal_get = portal_subparsers.add_parser("get", help="读取门户详情")
@@ -310,6 +324,15 @@ def _handle_package_resolve(args: argparse.Namespace, context: CliContext) -> di
     return context.builder.package_resolve(profile=args.profile, package_name=args.package_name)
 
 
+def _handle_solution_install(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.solution_install(
+        profile=args.profile,
+        solution_key=args.solution_key,
+        being_copy_data=bool(args.being_copy_data),
+        solution_source=args.solution_source,
+    )
+
+
 def _handle_package_create(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.package_create(
         profile=args.profile,
@@ -404,6 +427,15 @@ def _handle_app_get(args: argparse.Namespace, context: CliContext) -> dict:
     return handlers[args.builder_app_get_section](profile=args.profile, app_key=args.app_key)
 
 
+def _handle_app_repair_code_blocks(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_repair_code_blocks(
+        profile=args.profile,
+        app_key=args.app_key,
+        field=args.field,
+        apply=bool(args.apply),
+    )
+
+
 def _handle_portal_list(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.portal_list(profile=args.profile)
 

package/src/qingflow_mcp/cli/commands/repo.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import argparse
+
+from ..context import CliContext
+from .common import raise_config_error, require_list_arg, require_object_arg
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("repo", help="代码仓库开发工具")
+    repo_subparsers = parser.add_subparsers(dest="repo_command", required=True)
+
+    init_parser = repo_subparsers.add_parser("init", help="从模板初始化仓库")
+    init_parser.add_argument("--group-name", required=True)
+    init_parser.add_argument("--repo-template", required=True)
+    init_parser.set_defaults(handler=_handle_init, format_hint="generic")
+
+    generate_parser = repo_subparsers.add_parser("generate", help="沿用官方 generate 链路生成并提交页面代码")
+    generate_parser.add_argument("--repo-name", required=True)
+    generate_parser.add_argument("--query", required=True)
+    generate_parser.add_argument("--tag-id", type=int)
+    generate_parser.add_argument("--app-keys-file")
+    generate_parser.add_argument("--extra-info-file")
+    generate_parser.add_argument("--file-messages-file")
+    generate_parser.add_argument("--agent-id", type=int)
+    generate_parser.add_argument("--allow-create-table", action="store_true")
+    generate_parser.add_argument("--route-prefix")
+    generate_parser.add_argument("--token-name")
+    generate_parser.add_argument("--session-id")
+    generate_parser.add_argument("--round-version", type=int)
+    generate_parser.add_argument("--disable-trace-log", action="store_true")
+    generate_parser.set_defaults(handler=_handle_generate, format_hint="generic")
+
+    publish_parser = repo_subparsers.add_parser("publish-prod", help="发布 develop 到生产分支")
+    publish_parser.add_argument("--repo-name", required=True)
+    publish_parser.add_argument("--confirm", action="store_true")
+    publish_parser.set_defaults(handler=_handle_publish_prod, format_hint="generic")
+
+
+def _handle_init(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.repo.repository_init(
+        profile=args.profile,
+        group_name=args.group_name,
+        repo_template=args.repo_template,
+    )
+
+
+def _handle_generate(args: argparse.Namespace, context: CliContext) -> dict:
+    app_keys = require_list_arg(args.app_keys_file, option_name="--app-keys-file") if args.app_keys_file else []
+    extra_info = require_object_arg(args.extra_info_file, option_name="--extra-info-file") if args.extra_info_file else None
+    file_messages = require_list_arg(args.file_messages_file, option_name="--file-messages-file") if args.file_messages_file else []
+    return context.repo.repository_generate(
+        profile=args.profile,
+        repo_name=args.repo_name,
+        query=args.query,
+        tag_id=args.tag_id,
+        app_keys=app_keys,
+        extra_info=extra_info,
+        file_messages=file_messages,
+        being_trace_log_enabled=not args.disable_trace_log,
+        agent_id=args.agent_id,
+        allow_create_table=args.allow_create_table,
+        route_prefix=args.route_prefix,
+        token_name=args.token_name,
+        session_id=args.session_id,
+        round_version=args.round_version,
+    )
+
+
+def _handle_publish_prod(args: argparse.Namespace, context: CliContext) -> dict:
+    if args.confirm is not True:
+        raise_config_error(
+            "repository_publish_prod requires explicit confirmation.",
+            fix_hint="Re-run with `--confirm` after verifying the target repo and release intent.",
+        )
+    return context.repo.repository_publish_prod(
+        profile=args.profile,
+        repo_name=args.repo_name,
+        confirm=args.confirm,
+    )

package/src/qingflow_mcp/cli/commands/task.py

@@ -37,6 +37,13 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     action.add_argument("--fields-file")
     action.set_defaults(handler=_handle_action, format_hint="")
 
+    save_only = task_subparsers.add_parser("save-only", help="仅保存当前待办字段，不提交流程")
+    save_only.add_argument("--app-key", required=True)
+    save_only.add_argument("--record-id", required=True, type=int)
+    save_only.add_argument("--workflow-node-id", required=True, type=int)
+    save_only.add_argument("--fields-file", required=True)
+    save_only.set_defaults(handler=_handle_save_only, format_hint="")
+
     log = task_subparsers.add_parser("log", help="读取流程日志")
     log.add_argument("--app-key", required=True)
     log.add_argument("--record-id", required=True, type=int)
@@ -80,6 +87,16 @@ def _handle_action(args: argparse.Namespace, context: CliContext) -> dict:
     )
 
 
+def _handle_save_only(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.task.task_save_only(
+        profile=args.profile,
+        app_key=args.app_key,
+        record_id=args.record_id,
+        workflow_node_id=args.workflow_node_id,
+        fields=load_object_arg(args.fields_file, option_name="--fields-file") or {},
+    )
+
+
 def _handle_log(args: argparse.Namespace, context: CliContext) -> dict:
     return context.task.task_workflow_log_get(
         profile=args.profile,

package/src/qingflow_mcp/cli/context.py

@@ -12,6 +12,7 @@ from ..tools.feedback_tools import FeedbackTools
 from ..tools.file_tools import FileTools
 from ..tools.import_tools import ImportTools
 from ..tools.record_tools import RecordTools
+from ..tools.repository_dev_tools import RepositoryDevTools
 from ..tools.resource_read_tools import ResourceReadTools
 from ..tools.task_context_tools import TaskContextTools
 from ..tools.workspace_tools import WorkspaceTools
@@ -32,6 +33,7 @@ class CliContext:
     files: FileTools
     builder_feedback: FeedbackTools
     builder: AiBuilderTools
+    repo: RepositoryDevTools
 
     def close(self) -> None:
         self.backend.close()
@@ -54,4 +56,5 @@ def build_cli_context() -> CliContext:
         files=FileTools(sessions, backend),
         builder_feedback=FeedbackTools(backend, mcp_side="App Builder MCP"),
         builder=AiBuilderTools(sessions, backend),
+        repo=RepositoryDevTools(sessions, backend),
     )

package/src/qingflow_mcp/config.py

@@ -14,6 +14,13 @@ ATTACHMENT_QUESTION_TYPE = 13
 DEFAULT_BASE_URL = "https://qingflow.com/api"
 DEFAULT_FEEDBACK_APP_KEY = "e0d017kju002"
 DEFAULT_FEEDBACK_QSOURCE_TOKEN = "mcp-feedback-7755d14748fc"
+DEFAULT_REPOSITORY_GIT_REMOTE_TEMPLATE = "git@hackers.oalite.com:{group}/{repo}.git"
+DEFAULT_REPOSITORY_PREVIEW_ADDRESS_TEMPLATE = "https://%s.preview.oalite.com"
+DEFAULT_REPOSITORY_DEVELOP_BRANCH = "develop"
+DEFAULT_REPOSITORY_PROD_BRANCH = "prod"
+DEFAULT_REPOSITORY_AUTHOR_NAME = "qingflow-mcp"
+DEFAULT_REPOSITORY_AUTHOR_EMAIL = "qingflow-mcp@local.invalid"
+DEFAULT_REPOSITORY_INTERNAL_SHARE_TOKEN_KEY = "tokenKey"
 
 
 def get_mcp_home() -> Path:
@@ -25,6 +32,10 @@ def get_profiles_path() -> Path:
     return get_mcp_home() / "profiles.json"
 
 
+def get_repository_metadata_dir() -> Path:
+    return get_mcp_home() / "repository-metadata"
+
+
 def get_config_file_paths() -> list[Path]:
     """
     获取可能的配置文件路径列表，按优先级排序：
@@ -197,6 +208,142 @@ def get_log_level() -> str:
     )
 
 
+def get_repository_default_group() -> str | None:
+    value = get_config_value(
+        "repository.default_group",
+        env_var="QINGFLOW_MCP_REPOSITORY_DEFAULT_GROUP",
+        default=None,
+    )
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
+def get_repository_git_remote_template() -> str:
+    value = get_config_value(
+        "repository.git_remote_template",
+        env_var="QINGFLOW_MCP_REPOSITORY_GIT_REMOTE_TEMPLATE",
+        default=DEFAULT_REPOSITORY_GIT_REMOTE_TEMPLATE,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_GIT_REMOTE_TEMPLATE
+
+
+def get_repository_preview_address_template() -> str:
+    value = get_config_value(
+        "repository.preview_address_template",
+        env_var="QINGFLOW_MCP_REPOSITORY_PREVIEW_ADDRESS_TEMPLATE",
+        default=DEFAULT_REPOSITORY_PREVIEW_ADDRESS_TEMPLATE,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_PREVIEW_ADDRESS_TEMPLATE
+
+
+def get_repository_develop_branch() -> str:
+    value = get_config_value(
+        "repository.develop_branch",
+        env_var="QINGFLOW_MCP_REPOSITORY_DEVELOP_BRANCH",
+        default=DEFAULT_REPOSITORY_DEVELOP_BRANCH,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_DEVELOP_BRANCH
+
+
+def get_repository_prod_branch() -> str:
+    value = get_config_value(
+        "repository.prod_branch",
+        env_var="QINGFLOW_MCP_REPOSITORY_PROD_BRANCH",
+        default=DEFAULT_REPOSITORY_PROD_BRANCH,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_PROD_BRANCH
+
+
+def get_repository_author_name() -> str:
+    value = get_config_value(
+        "repository.author_name",
+        env_var="QINGFLOW_MCP_REPOSITORY_AUTHOR_NAME",
+        default=DEFAULT_REPOSITORY_AUTHOR_NAME,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_AUTHOR_NAME
+
+
+def get_repository_author_email() -> str:
+    value = get_config_value(
+        "repository.author_email",
+        env_var="QINGFLOW_MCP_REPOSITORY_AUTHOR_EMAIL",
+        default=DEFAULT_REPOSITORY_AUTHOR_EMAIL,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_AUTHOR_EMAIL
+
+
+def get_repository_internal_base_url() -> str | None:
+    value = get_config_value(
+        "repository.internal_base_url",
+        env_var="QINGFLOW_MCP_REPOSITORY_INTERNAL_BASE_URL",
+        default=None,
+    )
+    if value is None:
+        return None
+    normalized = normalize_base_url(str(value).strip())
+    return normalized or None
+
+
+def get_repository_internal_share_token() -> str | None:
+    value = get_config_value(
+        "repository.internal_share_token",
+        env_var="QINGFLOW_MCP_REPOSITORY_INTERNAL_SHARE_TOKEN",
+        default=None,
+    )
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
+def get_repository_internal_share_token_key() -> str:
+    value = get_config_value(
+        "repository.internal_share_token_key",
+        env_var="QINGFLOW_MCP_REPOSITORY_INTERNAL_SHARE_TOKEN_KEY",
+        default=DEFAULT_REPOSITORY_INTERNAL_SHARE_TOKEN_KEY,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_INTERNAL_SHARE_TOKEN_KEY
+
+
+def get_repository_generate_default_agent_id() -> int | None:
+    value = get_config_value(
+        "repository.generate.default_agent_id",
+        env_var="QINGFLOW_MCP_REPOSITORY_GENERATE_DEFAULT_AGENT_ID",
+        default=None,
+    )
+    if value is None:
+        return None
+    try:
+        return int(str(value).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def get_repository_generate_default_route_prefix() -> str | None:
+    value = get_config_value(
+        "repository.generate.default_route_prefix",
+        env_var="QINGFLOW_MCP_REPOSITORY_GENERATE_DEFAULT_ROUTE_PREFIX",
+        default=None,
+    )
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
+def get_repository_generate_default_token_name() -> str | None:
+    value = get_config_value(
+        "repository.generate.default_token_name",
+        env_var="QINGFLOW_MCP_REPOSITORY_GENERATE_DEFAULT_TOKEN_NAME",
+        default=None,
+    )
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
 def normalize_base_url(base_url: str | None) -> str | None:
     """规范化 base URL"""
     if base_url is None:

package/src/qingflow_mcp/public_surface.py

@@ -0,0 +1,231 @@
+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
+
+    @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_login", ("auth_login",), ("auth", "login")),
+    PublicToolSpec(USER_DOMAIN, "auth_use_token", ("auth_use_token",), ("auth", "use-token")),
+    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, "workspace_select", ("workspace_select",), ("workspace", "select")),
+    PublicToolSpec(USER_DOMAIN, "app_list", ("app_list",), ("app", "list")),
+    PublicToolSpec(USER_DOMAIN, "app_search", ("app_search",), ("app", "search")),
+    PublicToolSpec(USER_DOMAIN, "app_get", ("app_get",), ("app", "get")),
+    PublicToolSpec(USER_DOMAIN, "portal_list", ("portal_list",), ("portal", "list")),
+    PublicToolSpec(USER_DOMAIN, "portal_get", ("portal_get",), ("portal", "get")),
+    PublicToolSpec(USER_DOMAIN, "view_get", ("view_get",), ("view", "get")),
+    PublicToolSpec(USER_DOMAIN, "chart_get", ("chart_get",), ("chart", "get")),
+    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")),
+    PublicToolSpec(USER_DOMAIN, "record_get", ("record_get_public",), ("record", "get")),
+    PublicToolSpec(USER_DOMAIN, "record_insert", ("record_insert_public",), ("record", "insert")),
+    PublicToolSpec(USER_DOMAIN, "record_update", ("record_update_public",), ("record", "update")),
+    PublicToolSpec(USER_DOMAIN, "record_delete", ("record_delete_public",), ("record", "delete")),
+    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")),
+    PublicToolSpec(USER_DOMAIN, "task_list", ("task_list",), ("task", "list")),
+    PublicToolSpec(USER_DOMAIN, "task_get", ("task_get",), ("task", "get")),
+    PublicToolSpec(USER_DOMAIN, "task_save_only", ("task_save_only",), ("task", "save-only")),
+    PublicToolSpec(USER_DOMAIN, "task_action_execute", ("task_action_execute",), ("task", "action")),
+    PublicToolSpec(USER_DOMAIN, "task_associated_report_detail_get", ("task_associated_report_detail_get",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "task_workflow_log_get", ("task_workflow_log_get",), ("task", "log")),
+    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_login", ("auth_login",), ("builder", "auth", "login"), cli_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "auth_use_token", ("auth_use_token",), ("builder", "auth", "use-token"), 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, "workspace_select", ("workspace_select",), ("builder", "workspace", "select"), cli_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "file_upload_local", ("file_upload_local",), ("builder", "file", "upload-local"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "feedback_submit", ("feedback_submit",), ("builder", "feedback", "submit"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "package_list", ("package_list",), ("builder", "package", "list"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "package_resolve", ("package_resolve",), ("builder", "package", "resolve"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "builder_tool_contract", ("builder_tool_contract",), ("builder", "contract"), has_contract=False),
+    PublicToolSpec(BUILDER_DOMAIN, "package_create", ("package_create",), ("builder", "package", "create"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "solution_install", ("solution_install",), ("builder", "solution", "install"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "member_search", ("member_search",), ("builder", "member", "search"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "role_search", ("role_search",), ("builder", "role", "search"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "role_create", ("role_create",), ("builder", "role", "create"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "package_attach_app", ("package_attach_app",), ("builder", "package", "attach-app"), has_contract=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),
+    PublicToolSpec(BUILDER_DOMAIN, "app_resolve", ("app_resolve",), ("builder", "app", "resolve"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_list", ("app_custom_button_list",), ("builder", "button", "list"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_get", ("app_custom_button_get",), ("builder", "button", "get"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_create", ("app_custom_button_create",), ("builder", "button", "create"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_update", ("app_custom_button_update",), ("builder", "button", "update"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_delete", ("app_custom_button_delete",), ("builder", "button", "delete"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get", ("app_get",), ("builder", "app", "get", "summary"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_fields", ("app_get_fields",), ("builder", "app", "get", "fields"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_repair_code_blocks", ("app_repair_code_blocks",), ("builder", "app", "repair-code-blocks"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_layout", ("app_get_layout",), ("builder", "app", "get", "layout"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_views", ("app_get_views",), ("builder", "app", "get", "views"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_flow", ("app_get_flow",), ("builder", "app", "get", "flow"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_get_charts", ("app_get_charts",), ("builder", "app", "get", "charts"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "portal_list", ("portal_list",), ("builder", "portal", "list"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "portal_get", ("portal_get",), ("builder", "portal", "get"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "view_get", ("view_get",), ("builder", "view", "get"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "chart_get", ("chart_get",), ("builder", "chart", "get"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_schema_apply", ("app_schema_apply",), ("builder", "schema", "apply"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_layout_apply", ("app_layout_apply",), ("builder", "layout", "apply"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_flow_apply", ("app_flow_apply",), ("builder", "flow", "apply"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_views_apply", ("app_views_apply",), ("builder", "views", "apply"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_charts_apply", ("app_charts_apply",), ("builder", "charts", "apply"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "portal_apply", ("portal_apply",), ("builder", "portal", "apply"), has_contract=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_publish_verify", ("app_publish_verify",), ("builder", "publish", "verify"), has_contract=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_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