python-hwpx-automation 6.0.3__py3-none-any.whl

hwpx_automation/runtime.py

@@ -0,0 +1,321 @@
+# SPDX-License-Identifier: Apache-2.0
+"""FastMCP runtime adapter for the canonical automation application."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, cast
+
+import mcp.types as mcp_types
+from mcp.server.fastmcp import FastMCP
+from hwpx_automation.office.agent import AgentContractError
+
+from . import __version__
+from .configuration import env_value
+from . import quality as quality_contract
+from .errors import build_error_payload, mcp_code_for_error
+from .hwpx_ops import HwpxOperationError
+from .network_policy import NetworkPolicyError
+from .tool_contract import (
+    register_fastmcp_tools,
+)
+from .workspace import (
+    WorkspaceConfigurationError,
+    WorkspacePathError,
+)
+from .fastmcp_adapter import configure_runtime
+from .runtime_services import RUNTIME_SERVICES
+from .tool_bindings import TOOL_BINDINGS
+
+
+def _error_data(
+    payload: dict[str, Any],
+    *,
+    tool_name: str | None = None,
+    extra_data: dict | None = None,
+) -> mcp_types.ErrorData:
+    error_code = str(payload["code"])
+    data: dict[str, object] = {
+        "errorCode": error_code,
+        "error": payload,
+    }
+    if tool_name is not None:
+        data["tool"] = tool_name
+    if extra_data:
+        data.update(extra_data)
+    return mcp_types.ErrorData(
+        code=mcp_code_for_error(error_code),
+        message=f"{error_code}: {payload['message']}",
+        data=data,
+    )
+
+
+def _first_text_content(content: object) -> str | None:
+    if not isinstance(content, list):
+        return None
+    for item in content:
+        text = getattr(item, "text", None)
+        if isinstance(text, str):
+            stripped = text.strip()
+            if stripped:
+                return stripped
+        if isinstance(item, dict):
+            value = item.get("text")
+            if isinstance(value, str):
+                stripped = value.strip()
+                if stripped:
+                    return stripped
+    return None
+
+
+def _exception_chain(exc: BaseException) -> list[BaseException]:
+    chain: list[BaseException] = []
+    current: BaseException | None = exc
+    while current is not None and current not in chain:
+        chain.append(current)
+        current = current.__cause__ or current.__context__
+    return chain
+
+
+def _classified_error_payload(exc: BaseException | None) -> dict[str, Any]:
+    if exc is not None:
+        for item in _exception_chain(exc):
+            if isinstance(item, HwpxOperationError):
+                return item.to_payload()
+            if isinstance(item, AgentContractError):
+                return build_error_payload(
+                    code=item.code,
+                    message="문서 에이전트 계약을 안전하게 해석할 수 없습니다.",
+                )
+            if isinstance(item, WorkspacePathError):
+                return build_error_payload(
+                    code=item.code,
+                    message="요청한 경로가 허용된 HWPX 작업공간 경계를 벗어났습니다.",
+                    details=item.safe_details(),
+                )
+            if isinstance(item, WorkspaceConfigurationError):
+                return build_error_payload(
+                    code=item.code,
+                    message="HWPX 작업공간 루트 구성이 유효하지 않습니다.",
+                )
+            if isinstance(item, NetworkPolicyError):
+                return build_error_payload(
+                    code=item.code,
+                    message="기본 네트워크 정책이 요청한 대상을 차단했습니다.",
+                    details=item.safe_details(),
+                )
+            if isinstance(item, FileNotFoundError):
+                return build_error_payload(
+                    code="DOCUMENT_NOT_FOUND",
+                    message="요청한 문서를 허용된 작업공간에서 찾을 수 없습니다.",
+                )
+            if isinstance(item, PermissionError):
+                return build_error_payload(
+                    code="PERMISSION_DENIED",
+                    message="요청한 문서에 접근할 권한이 없습니다.",
+                )
+            if isinstance(item, ValueError):
+                return build_error_payload(
+                    code="INVALID_ARGUMENT",
+                    message="도구 인자가 스키마 또는 값 제약을 만족하지 않습니다.",
+                )
+    return build_error_payload(
+        code="TOOL_EXECUTION_FAILED",
+        message="도구 실행이 안전하게 완료되지 않았습니다.",
+    )
+
+
+def _gate_or_plain_error(
+    tool_name: str,
+    *,
+    exc: BaseException | None = None,
+) -> mcp_types.ErrorData:
+    """Rebuild a structured gate/skew error from the stash, else a plain error."""
+
+    gate = quality_contract.take_last_gate_error()
+    if isinstance(gate, quality_contract.CapabilitySkewError):
+        return _error_data(
+            build_error_payload(
+                code=gate.code,
+                message="설치된 core/automation/plugin 기능 계약이 일치하지 않아 쓰기를 차단했습니다.",
+                details={"capability": gate.state},
+            ),
+            tool_name=tool_name,
+            extra_data={"errorCode": gate.code, "capability": gate.state},
+        )
+    if isinstance(gate, quality_contract.QualityGateError):
+        return _error_data(
+            build_error_payload(
+                code=gate.code,
+                message="문서 품질 게이트가 출력을 거부했습니다.",
+                details={"visualComplete": gate.block},
+                retryable=True,
+            ),
+            tool_name=tool_name,
+            extra_data={
+                "errorCode": gate.code,
+                "visualComplete": gate.block,
+                "suggestedRetry": gate.block.get("suggestedRetry"),
+            },
+        )
+    return _error_data(_classified_error_payload(exc), tool_name=tool_name)
+
+
+def _failure_code_from_payload(payload: object) -> str | None:
+    if not isinstance(payload, dict):
+        return None
+    failed = payload.get("ok") is False or payload.get("success") is False
+    failed = failed or payload.get("isError") is True
+    if not failed:
+        return None
+    candidates: list[object] = [payload.get("errorCode"), payload.get("code")]
+    nested_error = payload.get("error")
+    if isinstance(nested_error, dict):
+        candidates.extend([nested_error.get("errorCode"), nested_error.get("code")])
+    nested_errors = payload.get("errors")
+    if (
+        isinstance(nested_errors, list)
+        and nested_errors
+        and isinstance(nested_errors[0], dict)
+    ):
+        candidates.extend(
+            [nested_errors[0].get("errorCode"), nested_errors[0].get("code")]
+        )
+    for candidate in candidates:
+        if isinstance(candidate, str) and re.fullmatch(
+            r"[A-Z][A-Z0-9_]{2,63}", candidate
+        ):
+            return candidate
+    return "TOOL_EXECUTION_FAILED"
+
+
+def _result_failure_error(
+    tool_name: str, payload: object
+) -> mcp_types.ErrorData | None:
+    error_code = _failure_code_from_payload(payload)
+    if error_code is None:
+        return None
+    gate_error = _gate_or_plain_error(tool_name)
+    if cast(dict[str, Any], gate_error.data).get("errorCode") != "TOOL_EXECUTION_FAILED":
+        return gate_error
+    return _error_data(
+        build_error_payload(
+            code=error_code,
+            message="도구가 요청을 안전하게 완료하지 못했습니다.",
+        ),
+        tool_name=tool_name,
+    )
+
+
+async def _strict_call_tool_handler(req: mcp_types.CallToolRequest):
+    tool_name = req.params.name
+    arguments = req.params.arguments or {}
+    quality_contract.clear_last_gate_error()
+    try:
+        result = await RUNTIME_SERVICES.require_mcp().call_tool(tool_name, arguments)
+    except Exception as exc:
+        # FastMCP wraps a tool's exception in ToolError, so the structured gate/
+        # skew error never matches a specific `except` here — recover it from the
+        # stash the exception left on construction (plan §2 Phase F).
+        return _gate_or_plain_error(tool_name, exc=exc)
+
+    if isinstance(result, mcp_types.CreateTaskResult):
+        return mcp_types.ServerResult(result)
+
+    if isinstance(result, mcp_types.CallToolResult):
+        if bool(result.isError):
+            return _gate_or_plain_error(tool_name)
+        embedded_failure = _result_failure_error(tool_name, result.structuredContent)
+        if embedded_failure is not None:
+            return embedded_failure
+        return mcp_types.ServerResult(result)
+
+    if isinstance(result, tuple) and len(result) == 2:
+        unstructured_content = list(result[0])
+        structured_content = result[1]
+    elif isinstance(result, dict):
+        structured_content = result
+        unstructured_content = [
+            mcp_types.TextContent(
+                type="text", text=json.dumps(result, ensure_ascii=False, indent=2)
+            )
+        ]
+    elif isinstance(result, str):
+        structured_content = None
+        unstructured_content = [mcp_types.TextContent(type="text", text=result)]
+    elif hasattr(result, "__iter__"):
+        structured_content = None
+        unstructured_content = list(result)
+    else:
+        return _error_data(
+            build_error_payload(
+                code="TOOL_EXECUTION_FAILED",
+                message="도구가 지원되지 않는 결과 형식을 반환했습니다.",
+                details={"resultType": type(result).__name__},
+            ),
+            tool_name=tool_name,
+        )
+
+    embedded_failure = _result_failure_error(tool_name, structured_content)
+    if embedded_failure is not None:
+        return embedded_failure
+
+    return mcp_types.ServerResult(
+        mcp_types.CallToolResult(
+            content=cast(list[mcp_types.ContentBlock], unstructured_content),
+            structuredContent=cast(dict[str, Any] | None, structured_content),
+            isError=False,
+        )
+    )
+
+
+def _advanced_enabled() -> bool:
+    return env_value("ADVANCED", "0") == "1"
+
+
+def _compose_runtime(*, advanced: bool, replace: bool) -> tuple[FastMCP, Any]:
+    composed = FastMCP("python-hwpx-automation")
+    if replace:
+        RUNTIME_SERVICES.reconfigure_runtime(
+            mcp=composed,
+            active_advanced=advanced,
+            tool_bindings=TOOL_BINDINGS,
+        )
+    else:
+        RUNTIME_SERVICES.configure_runtime(
+            mcp=composed,
+            active_advanced=advanced,
+            tool_bindings=TOOL_BINDINGS,
+        )
+    configure_runtime(composed, __version__, _strict_call_tool_handler)
+    registry = register_fastmcp_tools(composed, TOOL_BINDINGS, advanced=advanced)
+    RUNTIME_SERVICES.install_registry(registry)
+    return composed, registry
+
+
+def refresh_runtime_for_environment() -> None:
+    """Recompose only when the released import-time profile flag changed."""
+
+    global ACTIVE_ADVANCED, TOOL_REGISTRY, mcp
+    requested = _advanced_enabled()
+    if requested == ACTIVE_ADVANCED:
+        return
+    mcp, TOOL_REGISTRY = _compose_runtime(advanced=requested, replace=True)
+    ACTIVE_ADVANCED = requested
+
+
+ACTIVE_ADVANCED = _advanced_enabled()
+mcp, TOOL_REGISTRY = _compose_runtime(
+    advanced=ACTIVE_ADVANCED,
+    replace=RUNTIME_SERVICES.mcp is not None,
+)
+
+
+__all__ = [
+    "ACTIVE_ADVANCED",
+    "TOOL_REGISTRY",
+    "mcp",
+    "refresh_runtime_for_environment",
+    "_strict_call_tool_handler",
+]

hwpx_automation/runtime_services.py

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Typed process services shared by plain MCP handler callables.
+
+The container owns mutable process configuration, while the canonical handler
+callables and ToolSpec binding map remain immutable.  Handler modules depend on
+this neutral container and never import the server facade or runtime composer.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, TYPE_CHECKING
+
+from .hwpx_ops import HwpxOps
+
+if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+
+    from .tool_contract import RegisteredToolRegistry
+
+
+ToolBindings = Mapping[str, Callable[..., Any]]
+
+
+@dataclass(slots=True)
+class RuntimeServices:
+    """One typed service graph for FastMCP and durable workflow dispatch."""
+
+    ops: HwpxOps = field(default_factory=lambda: HwpxOps(auto_backup=False))
+    idempotency_cache: dict[str, dict[str, Any]] = field(default_factory=dict)
+    max_idempotency_cache_entries: int = 512
+    active_advanced: bool = False
+    mcp: FastMCP | None = None
+    tool_registry: RegisteredToolRegistry | None = None
+    tool_bindings: ToolBindings | None = None
+
+    def configure_runtime(
+        self,
+        *,
+        mcp: FastMCP,
+        active_advanced: bool,
+        tool_bindings: ToolBindings,
+    ) -> None:
+        """Bind transport and the one immutable callable map exactly once."""
+
+        if self.mcp is not None and self.mcp is not mcp:
+            raise RuntimeError("RuntimeServices FastMCP runtime is already bound")
+        if self.tool_bindings is not None and self.tool_bindings is not tool_bindings:
+            raise RuntimeError("RuntimeServices tool bindings are already bound")
+        self.mcp = mcp
+        self.active_advanced = active_advanced
+        self.tool_bindings = tool_bindings
+
+    def reconfigure_runtime(
+        self,
+        *,
+        mcp: FastMCP,
+        active_advanced: bool,
+        tool_bindings: ToolBindings,
+    ) -> None:
+        """Replace only the import-time transport/profile composition.
+
+        This preserves the released ``reload(server)`` environment-profile seam
+        without replacing the singleton service graph referenced by handlers.
+        """
+
+        if self.tool_bindings is not None and self.tool_bindings is not tool_bindings:
+            raise RuntimeError("RuntimeServices tool bindings are already bound")
+        self.mcp = mcp
+        self.active_advanced = active_advanced
+        self.tool_bindings = tool_bindings
+        self.tool_registry = None
+
+    def install_registry(self, registry: RegisteredToolRegistry) -> None:
+        if self.tool_registry is not None and self.tool_registry is not registry:
+            if self.tool_registry.binding_hash() != registry.binding_hash():
+                raise RuntimeError("RuntimeServices canonical registry is already bound")
+        self.tool_registry = registry
+
+    def replace_ops(self, ops: HwpxOps) -> None:
+        """Replace the stable compatibility facade for an authorized workspace."""
+
+        self.ops = ops
+
+    def require_mcp(self) -> FastMCP:
+        if self.mcp is None:
+            raise RuntimeError("FastMCP runtime is not configured")
+        return self.mcp
+
+    def require_tool_bindings(self) -> ToolBindings:
+        if self.tool_bindings is None:
+            raise RuntimeError("canonical tool bindings are not configured")
+        return self.tool_bindings
+
+
+RUNTIME_SERVICES = RuntimeServices()
+
+
+__all__ = ["RUNTIME_SERVICES", "RuntimeServices", "ToolBindings"]

hwpx_automation/server.py

@@ -0,0 +1,259 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Stable FastMCP import and CLI facade over cohesive handler owners."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+
+from .configuration import env_int, env_value
+from .handlers import _shared, authoring, quality_render, read_export, specialized
+from . import quality as _quality_contract
+from .hwpx_ops import HwpxOps
+from . import runtime as _runtime
+from .runtime_services import RUNTIME_SERVICES
+from .storage import LocalDocumentStorage
+from .tool_bindings import TOOL_BINDINGS
+from .workspace import (
+    WORKSPACE_ROOTS_ENV,
+    WorkspaceConfigurationError,
+)
+
+
+_runtime.refresh_runtime_for_environment()
+ACTIVE_ADVANCED = _runtime.ACTIVE_ADVANCED
+TOOL_REGISTRY = _runtime.TOOL_REGISTRY
+_strict_call_tool_handler = _runtime._strict_call_tool_handler
+mcp = _runtime.mcp
+quality_contract = _quality_contract
+save_doc = _shared.save_doc
+build_hwpx_verification_report = _shared.build_hwpx_verification_report
+_save_generated_document = authoring._save_generated_document
+resolve_oracle = specialized.resolve_oracle
+measure_question_splits = specialized.measure_question_splits
+render_glyph_boxes = specialized.render_glyph_boxes
+extract_image_boxes = specialized.extract_image_boxes
+RemoteRenderClientV2 = _shared.RemoteRenderClientV2
+
+
+# Explicit stable re-exports.  These are the exact objects in TOOL_BINDINGS.
+get_document_node = TOOL_BINDINGS["get_document_node"]
+query_document_nodes = TOOL_BINDINGS["query_document_nodes"]
+apply_document_commands = TOOL_BINDINGS["apply_document_commands"]
+dump_document_blueprint = TOOL_BINDINGS["dump_document_blueprint"]
+replay_document_blueprint = TOOL_BINDINGS["replay_document_blueprint"]
+get_document_text = TOOL_BINDINGS["get_document_text"]
+get_document_info = TOOL_BINDINGS["get_document_info"]
+get_document_outline = TOOL_BINDINGS["get_document_outline"]
+get_document_map = TOOL_BINDINGS["get_document_map"]
+get_paragraph_text = TOOL_BINDINGS["get_paragraph_text"]
+get_paragraphs_text = TOOL_BINDINGS["get_paragraphs_text"]
+get_location_text = TOOL_BINDINGS["get_location_text"]
+get_table_text = TOOL_BINDINGS["get_table_text"]
+get_table_map = TOOL_BINDINGS["get_table_map"]
+find_text = TOOL_BINDINGS["find_text"]
+list_available_documents = TOOL_BINDINGS["list_available_documents"]
+hwpx_to_markdown = TOOL_BINDINGS["hwpx_to_markdown"]
+document_to_markdown = TOOL_BINDINGS["document_to_markdown"]
+hwpx_to_html = TOOL_BINDINGS["hwpx_to_html"]
+hwpx_extract_json = TOOL_BINDINGS["hwpx_extract_json"]
+document_extract_json = TOOL_BINDINGS["document_extract_json"]
+package_parts = TOOL_BINDINGS["package_parts"]
+package_get_text = TOOL_BINDINGS["package_get_text"]
+package_get_xml = TOOL_BINDINGS["package_get_xml"]
+object_find_by_attr = TOOL_BINDINGS["object_find_by_attr"]
+object_find_by_tag = TOOL_BINDINGS["object_find_by_tag"]
+create_document = TOOL_BINDINGS["create_document"]
+create_document_from_plan = TOOL_BINDINGS["create_document_from_plan"]
+copy_document = TOOL_BINDINGS["copy_document"]
+create_government_report_document = TOOL_BINDINGS["create_government_report_document"]
+create_proposal_document = TOOL_BINDINGS["create_proposal_document"]
+create_comparison_table_document = TOOL_BINDINGS["create_comparison_table_document"]
+get_document_plan_schema = TOOL_BINDINGS["get_document_plan_schema"]
+validate_document_plan = TOOL_BINDINGS["validate_document_plan"]
+analyze_document_plan = TOOL_BINDINGS["analyze_document_plan"]
+markdown_to_document_plan = TOOL_BINDINGS["markdown_to_document_plan"]
+parse_government_report_text = TOOL_BINDINGS["parse_government_report_text"]
+compute_report_value = TOOL_BINDINGS["compute_report_value"]
+register_template = TOOL_BINDINGS["register_template"]
+list_templates = TOOL_BINDINGS["list_templates"]
+describe_template = TOOL_BINDINGS["describe_template"]
+add_heading = TOOL_BINDINGS["add_heading"]
+add_paragraph = TOOL_BINDINGS["add_paragraph"]
+insert_paragraph = TOOL_BINDINGS["insert_paragraph"]
+delete_paragraph = TOOL_BINDINGS["delete_paragraph"]
+add_page_break = TOOL_BINDINGS["add_page_break"]
+apply_edits = TOOL_BINDINGS["apply_edits"]
+undo_last_edit = TOOL_BINDINGS["undo_last_edit"]
+replace_by_anchor = TOOL_BINDINGS["replace_by_anchor"]
+replace_in_paragraph = TOOL_BINDINGS["replace_in_paragraph"]
+search_and_replace = TOOL_BINDINGS["search_and_replace"]
+batch_replace = TOOL_BINDINGS["batch_replace"]
+byte_preserving_patch = TOOL_BINDINGS["byte_preserving_patch"]
+insert_picture = TOOL_BINDINGS["insert_picture"]
+replace_picture = TOOL_BINDINGS["replace_picture"]
+add_table = TOOL_BINDINGS["add_table"]
+set_table_cell_text = TOOL_BINDINGS["set_table_cell_text"]
+merge_table_cells = TOOL_BINDINGS["merge_table_cells"]
+split_table_cell = TOOL_BINDINGS["split_table_cell"]
+format_table = TOOL_BINDINGS["format_table"]
+table_compute = TOOL_BINDINGS["table_compute"]
+list_styles = TOOL_BINDINGS["list_styles"]
+create_custom_style = TOOL_BINDINGS["create_custom_style"]
+set_paragraph_format = TOOL_BINDINGS["set_paragraph_format"]
+set_list_format = TOOL_BINDINGS["set_list_format"]
+format_text = TOOL_BINDINGS["format_text"]
+extract_style_profile = TOOL_BINDINGS["extract_style_profile"]
+apply_style_profile_to_plan = TOOL_BINDINGS["apply_style_profile_to_plan"]
+compare_style_profiles = TOOL_BINDINGS["compare_style_profiles"]
+set_page_setup = TOOL_BINDINGS["set_page_setup"]
+set_header_footer = TOOL_BINDINGS["set_header_footer"]
+set_page_number = TOOL_BINDINGS["set_page_number"]
+add_toc = TOOL_BINDINGS["add_toc"]
+add_cross_reference = TOOL_BINDINGS["add_cross_reference"]
+verify_toc = TOOL_BINDINGS["verify_toc"]
+add_memo = TOOL_BINDINGS["add_memo"]
+add_memo_by_anchor = TOOL_BINDINGS["add_memo_by_anchor"]
+remove_memo = TOOL_BINDINGS["remove_memo"]
+scan_form_guidance = TOOL_BINDINGS["scan_form_guidance"]
+apply_table_ops = TOOL_BINDINGS["apply_table_ops"]
+apply_body_ops = TOOL_BINDINGS["apply_body_ops"]
+inspect_fill_residue = TOOL_BINDINGS["inspect_fill_residue"]
+verify_form_fill = TOOL_BINDINGS["verify_form_fill"]
+list_form_fields = TOOL_BINDINGS["list_form_fields"]
+fill_form_field = TOOL_BINDINGS["fill_form_field"]
+find_cell_by_label = TOOL_BINDINGS["find_cell_by_label"]
+fill_by_path = TOOL_BINDINGS["fill_by_path"]
+analyze_form_fill = TOOL_BINDINGS["analyze_form_fill"]
+apply_form_fill = TOOL_BINDINGS["apply_form_fill"]
+analyze_template_formfit = TOOL_BINDINGS["analyze_template_formfit"]
+apply_template_formfit = TOOL_BINDINGS["apply_template_formfit"]
+apply_evalplan_fill = TOOL_BINDINGS["apply_evalplan_fill"]
+score_form_fill = TOOL_BINDINGS["score_form_fill"]
+add_tracked_edit = TOOL_BINDINGS["add_tracked_edit"]
+scan_personal_info = TOOL_BINDINGS["scan_personal_info"]
+compose_exam = TOOL_BINDINGS["compose_exam"]
+verify_question_splits = TOOL_BINDINGS["verify_question_splits"]
+place_seal = TOOL_BINDINGS["place_seal"]
+check_seal_compliance = TOOL_BINDINGS["check_seal_compliance"]
+mail_merge = TOOL_BINDINGS["mail_merge"]
+inspect_mail_merge_placeholders = TOOL_BINDINGS["inspect_mail_merge_placeholders"]
+build_image_grid = TOOL_BINDINGS["build_image_grid"]
+build_meeting_nameplates = TOOL_BINDINGS["build_meeting_nameplates"]
+build_organization_chart = TOOL_BINDINGS["build_organization_chart"]
+render_submit = TOOL_BINDINGS["render_submit"]
+render_status = TOOL_BINDINGS["render_status"]
+render_cancel = TOOL_BINDINGS["render_cancel"]
+render_health = TOOL_BINDINGS["render_health"]
+render_preview = TOOL_BINDINGS["render_preview"]
+repair_hwpx = TOOL_BINDINGS["repair_hwpx"]
+mcp_server_health = TOOL_BINDINGS["mcp_server_health"]
+describe_capabilities = TOOL_BINDINGS["describe_capabilities"]
+doc_diff = TOOL_BINDINGS["doc_diff"]
+validate_structure = TOOL_BINDINGS["validate_structure"]
+lint_text_conventions = TOOL_BINDINGS["lint_text_conventions"]
+inspect_document_quality = TOOL_BINDINGS["inspect_document_quality"]
+inspect_document_authoring_quality = TOOL_BINDINGS["inspect_document_authoring_quality"]
+inspect_operating_plan_quality = TOOL_BINDINGS["inspect_operating_plan_quality"]
+inspect_official_document_style = TOOL_BINDINGS["inspect_official_document_style"]
+inspect_reference_consistency = TOOL_BINDINGS["inspect_reference_consistency"]
+start_workflow = TOOL_BINDINGS["start_workflow"]
+get_workflow = TOOL_BINDINGS["get_workflow"]
+get_workflow_result = TOOL_BINDINGS["get_workflow_result"]
+continue_workflow = TOOL_BINDINGS["continue_workflow"]
+approve_workflow_decision = TOOL_BINDINGS["approve_workflow_decision"]
+cancel_workflow = TOOL_BINDINGS["cancel_workflow"]
+resume_workflow = TOOL_BINDINGS["resume_workflow"]
+
+_SERVER_TOOL_BINDINGS = TOOL_BINDINGS
+_TOOL_REGISTRY = TOOL_REGISTRY
+_ACTIVE_ADVANCED = ACTIVE_ADVANCED
+_OPS = RUNTIME_SERVICES.ops
+_fastmcp_tool_names = quality_render._fastmcp_tool_names
+_render_client = quality_render._render_client
+_table_count = read_export._table_count
+
+
+def _replace_ops(ops: HwpxOps) -> None:
+    global _OPS
+    RUNTIME_SERVICES.replace_ops(ops)
+    _OPS = ops
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="hwpx-automation-mcp")
+    parser.add_argument(
+        "--transport",
+        choices=("stdio", "streamable-http", "http"),
+        default=env_value("TRANSPORT", "stdio"),
+        help="MCP transport to use",
+    )
+    parser.add_argument(
+        "--host",
+        default=env_value("HOST", "127.0.0.1"),
+        help="Host interface for streamable HTTP transport",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=max(1, env_int("PORT", 8000)),
+        help="TCP port for streamable HTTP transport",
+    )
+    parser.add_argument(
+        "--workspace-root",
+        action="append",
+        default=None,
+        help=(
+            "Authorized local workspace root. Repeat for multiple roots; relative paths use the first. "
+            f"Equivalent to {WORKSPACE_ROOTS_ENV}."
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    if args.workspace_root:
+        os.environ[WORKSPACE_ROOTS_ENV] = json.dumps(args.workspace_root)
+    try:
+        storage = LocalDocumentStorage(auto_backup=False)
+    except WorkspaceConfigurationError as exc:
+        # Explicit HWPX_AUTOMATION_WORKSPACE_ROOTS (or its supported 6.x
+        # HWPX_MCP_WORKSPACE_ROOTS fallback) / --workspace-root configuration is
+        # invalid: fail fast so the operator fixes the value. An unconfigured
+        # degenerate cwd instead defers inside LocalDocumentStorage so the server
+        # still boots and every document tool call reports WORKSPACE_ROOT_INVALID.
+        parser.error(
+            f"invalid HWPX workspace configuration: {exc}. "
+            f"Set {WORKSPACE_ROOTS_ENV} to existing project directories or launch from the project workspace."
+        )
+    _replace_ops(HwpxOps(storage=storage))
+
+    selected_transport = args.transport
+    if selected_transport == "http":
+        selected_transport = "streamable-http"
+
+    if selected_transport == "stdio":
+        mcp.run(transport="stdio")
+        return
+
+    # TODO: add pluggable auth middleware/headers for production HTTP deployments.
+    try:  # HTTP transport is an optional [http] extra
+        import uvicorn
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise RuntimeError(
+            "HTTP transport requires the 'uvicorn' package. Install it with: "
+            "pip install 'python-hwpx-automation[http]' "
+            "(or 'hwpx-mcp-server[http]', or pip install uvicorn). "
+            "The default stdio transport needs no extra."
+        ) from exc
+
+    app = mcp.streamable_http_app()
+    uvicorn.run(
+        app,
+        host=args.host,
+        port=args.port,
+        log_level=os.environ.get("LOG_LEVEL", "info").lower(),
+    )
+
+
+if __name__ == "__main__":
+    main()