refactor(mcp): relocate tool result envelope into core to clear a layering back-edge

packages/mcp/src/pipefy_mcp/core/tool_middleware.py

@@ -34,6 +34,7 @@
 from mcp.server.lowlevel.server import request_ctx
 
 from pipefy_mcp.auth.request_identity import CallerIdentity, caller_identity
+from pipefy_mcp.core.tool_error_envelope import tool_error
 
 if TYPE_CHECKING:
     from mcp.server.fastmcp import FastMCP
@@ -201,11 +202,6 @@ def short_circuit_error(
     (where an in-tool error carries it too) and in ``structuredContent``. The match to
     an in-tool error is on the decoded envelope, not the byte serialization.
     """
-    # Imported lazily: pipefy_mcp.tools.tool_error_envelope pulls the tools
-    # package, which imports the runtime, which imports this module. A top-level
-    # import would form a cycle at load time.
-    from pipefy_mcp.tools.tool_error_envelope import tool_error
-
     envelope = tool_error(message, code=code, details=details)
     return types.ServerResult(
         types.CallToolResult(

packages/mcp/src/pipefy_mcp/tools/ai_automation_tools.py

@@ -16,6 +16,7 @@
 )
 from pydantic import ValidationError
 
+from pipefy_mcp.core.tool_error_envelope import tool_error_message
 from pipefy_mcp.tools.ai_tool_helpers import (
     build_ai_tool_error,
     build_create_automation_success,
@@ -29,7 +30,6 @@
 )
 from pipefy_mcp.tools.destructive_tool_guard import check_destructive_confirmation
 from pipefy_mcp.tools.tool_context import get_pipefy_client
-from pipefy_mcp.tools.tool_error_envelope import tool_error_message
 from pipefy_mcp.tools.validation_helpers import (
     validate_optional_tool_id,
     validate_tool_id,

packages/mcp/src/pipefy_mcp/tools/ai_tool_helpers.py

@@ -19,16 +19,16 @@
 )
 from typing_extensions import TypedDict
 
-from pipefy_mcp.tools.graphql_error_helpers import (
-    extract_error_strings,
-    strip_internal_api_diagnostic_markers,
-)
-from pipefy_mcp.tools.tool_error_envelope import (
+from pipefy_mcp.core.tool_error_envelope import (
     ToolErrorDetail,
     is_unified_envelope_enabled,
     tool_error,
     tool_success,
 )
+from pipefy_mcp.tools.graphql_error_helpers import (
+    extract_error_strings,
+    strip_internal_api_diagnostic_markers,
+)
 
 logger = logging.getLogger(__name__)
 

packages/mcp/src/pipefy_mcp/tools/attachment_tool_helpers.py

@@ -6,8 +6,8 @@
 
 from pydantic import ValidationError
 
+from pipefy_mcp.core.tool_error_envelope import tool_error
 from pipefy_mcp.tools.graphql_error_helpers import extract_error_strings
-from pipefy_mcp.tools.tool_error_envelope import tool_error
 
 UploadFlowStep = Literal[
     "validation",

packages/mcp/src/pipefy_mcp/tools/automation_tool_helpers.py

@@ -13,6 +13,7 @@
 )
 from typing_extensions import TypedDict
 
+from pipefy_mcp.core.tool_error_envelope import ToolErrorDetail, tool_error
 from pipefy_mcp.tools.graphql_error_helpers import (
     extract_error_strings,
     extract_graphql_correlation_id,
@@ -21,7 +22,6 @@
     try_enrich_graphql_error,
     with_debug_suffix,
 )
-from pipefy_mcp.tools.tool_error_envelope import ToolErrorDetail, tool_error
 
 AutomationReadToolData = (
     AutomationRuleRecord

packages/mcp/src/pipefy_mcp/tools/automation_tools.py

@@ -11,6 +11,7 @@
 from pipefy_sdk.automation_preflight import AutomationPreflightError
 from pydantic import ValidationError
 
+from pipefy_mcp.core.tool_error_envelope import tool_error_message
 from pipefy_mcp.tools.automation_tool_helpers import (
     build_automation_error_payload,
     build_automation_mutation_success_payload,
@@ -21,7 +22,6 @@
 from pipefy_mcp.tools.destructive_tool_guard import check_destructive_confirmation
 from pipefy_mcp.tools.graphql_error_helpers import enrich_permission_denied_error
 from pipefy_mcp.tools.tool_context import get_pipefy_client
-from pipefy_mcp.tools.tool_error_envelope import tool_error_message
 from pipefy_mcp.tools.validation_helpers import (
     mutation_error_if_not_optional_dict,
     validate_optional_tool_id,

packages/mcp/src/pipefy_mcp/tools/field_condition_tools.py

@@ -9,6 +9,7 @@
 from mcp.types import ToolAnnotations
 from pipefy_sdk import PipefyId
 
+from pipefy_mcp.core.tool_error_envelope import tool_error
 from pipefy_mcp.tools.destructive_tool_guard import check_destructive_confirmation
 from pipefy_mcp.tools.pipe_config_tool_helpers import (
     build_field_condition_delete_payload,
@@ -18,7 +19,6 @@
     handle_pipe_config_tool_graphql_error,
 )
 from pipefy_mcp.tools.tool_context import get_pipefy_client
-from pipefy_mcp.tools.tool_error_envelope import tool_error
 from pipefy_mcp.tools.validation_helpers import (
     validate_tool_id,
 )

packages/mcp/src/pipefy_mcp/tools/graphql_error_helpers.py

@@ -35,7 +35,7 @@
     from pipefy_sdk import PipefyClient
 
 import pipefy_mcp.settings as _settings_mod
-from pipefy_mcp.tools.tool_error_envelope import tool_error
+from pipefy_mcp.core.tool_error_envelope import tool_error
 
 # Suffixes appended by the Internal API executor for service-layer diagnostics;
 # MCP tools strip these from default user-visible errors.

packages/mcp/src/pipefy_mcp/tools/introspection_tool_helpers.py

@@ -5,7 +5,7 @@
 import json
 from typing import Any
 
-from pipefy_mcp.tools.tool_error_envelope import tool_error
+from pipefy_mcp.core.tool_error_envelope import tool_error
 
 
 def _format_graphql_data_for_llm(data: dict[str, Any]) -> str:

packages/mcp/src/pipefy_mcp/tools/member_tool_helpers.py

@@ -6,10 +6,10 @@
 
 from typing_extensions import TypedDict
 
+from pipefy_mcp.core.tool_error_envelope import tool_error
 from pipefy_mcp.tools.graphql_error_helpers import (
     handle_tool_graphql_error,
 )
-from pipefy_mcp.tools.tool_error_envelope import tool_error
 
 
 class MemberMutationSuccessPayload(TypedDict):

packages/mcp/src/pipefy_mcp/tools/observability_tool_helpers.py

@@ -6,10 +6,10 @@
 
 from typing_extensions import TypedDict
 
+from pipefy_mcp.core.tool_error_envelope import tool_error
 from pipefy_mcp.tools.graphql_error_helpers import (
     handle_tool_graphql_error,
 )
-from pipefy_mcp.tools.tool_error_envelope import tool_error
 
 
 class ObservabilityReadSuccessPayload(TypedDict):

packages/mcp/src/pipefy_mcp/tools/pagination_helpers.py

@@ -6,7 +6,7 @@
 
 from typing_extensions import TypedDict
 
-from pipefy_mcp.tools.tool_error_envelope import tool_error
+from pipefy_mcp.core.tool_error_envelope import tool_error
 
 __all__ = [
     "DEFAULT_PAGE_SIZE",

packages/mcp/src/pipefy_mcp/tools/phase_transition_helpers.py

@@ -11,7 +11,7 @@
     format_allowed_destinations_phrase,
 )
 
-from pipefy_mcp.tools.tool_error_envelope import tool_error
+from pipefy_mcp.core.tool_error_envelope import tool_error
 
 logger = logging.getLogger(__name__)
 

packages/mcp/src/pipefy_mcp/tools/pipe_config_tool_helpers.py

@@ -6,10 +6,10 @@
 from pipefy_sdk import PipefyClient
 from typing_extensions import TypedDict
 
+from pipefy_mcp.core.tool_error_envelope import ToolErrorDetail, tool_error
 from pipefy_mcp.tools.graphql_error_helpers import (
     handle_tool_graphql_error,
 )
-from pipefy_mcp.tools.tool_error_envelope import ToolErrorDetail, tool_error
 from pipefy_mcp.tools.validation_helpers import UUID_RE, format_json_preview
 
 

packages/mcp/src/pipefy_mcp/tools/pipe_config_tools.py

@@ -11,6 +11,11 @@
     is_get_phase_not_found_error,
 )
 
+from pipefy_mcp.core.tool_error_envelope import (
+    is_unified_envelope_enabled,
+    tool_error_message,
+    tool_success,
+)
 from pipefy_mcp.tools.destructive_tool_guard import check_destructive_confirmation
 from pipefy_mcp.tools.graphql_error_helpers import (
     extract_error_strings,
@@ -38,11 +43,6 @@
 from pipefy_mcp.tools.pipe_tool_helpers import find_label_dependents
 from pipefy_mcp.tools.remote_profile import REMOTE
 from pipefy_mcp.tools.tool_context import get_pipefy_client
-from pipefy_mcp.tools.tool_error_envelope import (
-    is_unified_envelope_enabled,
-    tool_error_message,
-    tool_success,
-)
 from pipefy_mcp.tools.validation_helpers import (
     validate_optional_tool_id,
     validate_tool_id,

packages/mcp/src/pipefy_mcp/tools/pipe_tool_helpers.py

@@ -14,18 +14,18 @@
 from pydantic import ValidationError
 from typing_extensions import TypedDict
 
-from pipefy_mcp.tools.destructive_tool_guard import (
-    DestructiveCancelledPayload,
-    DestructivePreviewPayload,
-)
-from pipefy_mcp.tools.graphql_error_helpers import extract_error_strings
-from pipefy_mcp.tools.tool_error_envelope import (
+from pipefy_mcp.core.tool_error_envelope import (
     ToolErrorDetail,
     ToolSuccessPayload,
     is_unified_envelope_enabled,
     tool_error,
     tool_success,
 )
+from pipefy_mcp.tools.destructive_tool_guard import (
+    DestructiveCancelledPayload,
+    DestructivePreviewPayload,
+)
+from pipefy_mcp.tools.graphql_error_helpers import extract_error_strings
 
 
 class UserCancelledError(Exception):

packages/mcp/src/pipefy_mcp/tools/pipe_tools.py

@@ -25,6 +25,12 @@
 from pipefy_sdk.models.form import MalformedFieldDefinitionError
 from pydantic import ValidationError
 
+from pipefy_mcp.core.tool_error_envelope import (
+    is_unified_envelope_enabled,
+    tool_error,
+    tool_error_message,
+    tool_success,
+)
 from pipefy_mcp.tools.destructive_tool_guard import check_destructive_confirmation
 from pipefy_mcp.tools.graphql_error_helpers import (
     enrich_permission_denied_error,
@@ -70,12 +76,6 @@
 )
 from pipefy_mcp.tools.remote_profile import REMOTE
 from pipefy_mcp.tools.tool_context import get_pipefy_client
-from pipefy_mcp.tools.tool_error_envelope import (
-    is_unified_envelope_enabled,
-    tool_error,
-    tool_error_message,
-    tool_success,
-)
 from pipefy_mcp.tools.validation_helpers import validate_tool_id
 
 # Key for findCards response; used when reading edges and adding empty message.

packages/mcp/src/pipefy_mcp/tools/portal_tool_helpers.py

@@ -15,6 +15,7 @@
 from pipefy_sdk.exceptions import PortalPermissionError
 from pydantic import ValidationError
 
+from pipefy_mcp.core.tool_error_envelope import tool_error
 from pipefy_mcp.tools.graphql_error_helpers import (
     extract_error_strings,
     extract_graphql_error_codes,
@@ -24,7 +25,6 @@
     build_error_payload,
     build_success_payload,
 )
-from pipefy_mcp.tools.tool_error_envelope import tool_error
 from pipefy_mcp.tools.validation_helpers import validate_tool_id
 
 _PORTAL_PERMISSION_GUIDANCE = (

packages/mcp/src/pipefy_mcp/tools/portal_tools.py

@@ -16,6 +16,7 @@
 )
 from pydantic import ValidationError
 
+from pipefy_mcp.core.tool_error_envelope import tool_error
 from pipefy_mcp.tools.destructive_tool_guard import check_destructive_confirmation
 from pipefy_mcp.tools.introspection_tool_helpers import (
     build_error_payload,
@@ -32,7 +33,6 @@
     validate_tool_ids,
 )
 from pipefy_mcp.tools.tool_context import get_pipefy_client
-from pipefy_mcp.tools.tool_error_envelope import tool_error
 from pipefy_mcp.tools.validation_helpers import validate_tool_id
 
 

packages/mcp/src/pipefy_mcp/tools/relation_tool_helpers.py

@@ -6,10 +6,10 @@
 
 from typing_extensions import TypedDict
 
+from pipefy_mcp.core.tool_error_envelope import tool_error
 from pipefy_mcp.tools.graphql_error_helpers import (
     handle_tool_graphql_error,
 )
-from pipefy_mcp.tools.tool_error_envelope import tool_error
 
 
 class RelationReadSuccessPayload(TypedDict):

packages/mcp/src/pipefy_mcp/tools/report_tool_helpers.py

@@ -6,14 +6,14 @@
 
 from typing_extensions import TypedDict
 
-from pipefy_mcp.tools.graphql_error_helpers import (
-    handle_tool_graphql_error,
-)
-from pipefy_mcp.tools.tool_error_envelope import (
+from pipefy_mcp.core.tool_error_envelope import (
     is_unified_envelope_enabled,
     tool_error,
     tool_success,
 )
+from pipefy_mcp.tools.graphql_error_helpers import (
+    handle_tool_graphql_error,
+)
 
 # The ``Legacy*SuccessPayload`` TypedDicts below describe the flag=false shape
 # only. Under the default ``PIPEFY_MCP_UNIFIED_ENVELOPE=true``, helpers return

packages/mcp/src/pipefy_mcp/tools/report_tools.py

@@ -9,6 +9,10 @@
 from mcp.types import ToolAnnotations
 from pipefy_sdk import PipefyId
 
+from pipefy_mcp.core.tool_error_envelope import (
+    is_unified_envelope_enabled,
+    tool_success,
+)
 from pipefy_mcp.tools.destructive_tool_guard import check_destructive_confirmation
 from pipefy_mcp.tools.pagination_helpers import (
     build_pagination_info,
@@ -21,10 +25,6 @@
     handle_report_tool_graphql_error,
 )
 from pipefy_mcp.tools.tool_context import get_pipefy_client
-from pipefy_mcp.tools.tool_error_envelope import (
-    is_unified_envelope_enabled,
-    tool_success,
-)
 from pipefy_mcp.tools.validation_helpers import validate_tool_id
 
 

packages/mcp/src/pipefy_mcp/tools/table_tool_helpers.py

@@ -6,10 +6,10 @@
 
 from typing_extensions import TypedDict
 
+from pipefy_mcp.core.tool_error_envelope import ToolErrorDetail, tool_error
 from pipefy_mcp.tools.graphql_error_helpers import (
     handle_tool_graphql_error,
 )
-from pipefy_mcp.tools.tool_error_envelope import ToolErrorDetail, tool_error
 from pipefy_mcp.tools.validation_helpers import format_json_preview
 
 

packages/mcp/src/pipefy_mcp/tools/table_tools.py

@@ -13,6 +13,11 @@
     PipefyId,
 )
 
+from pipefy_mcp.core.tool_error_envelope import (
+    is_unified_envelope_enabled,
+    tool_error_message,
+    tool_success,
+)
 from pipefy_mcp.tools.destructive_tool_guard import check_destructive_confirmation
 from pipefy_mcp.tools.graphql_error_helpers import (
     extract_graphql_correlation_id,
@@ -36,11 +41,6 @@
     map_delete_table_error_to_message,
 )
 from pipefy_mcp.tools.tool_context import get_pipefy_client
-from pipefy_mcp.tools.tool_error_envelope import (
-    is_unified_envelope_enabled,
-    tool_error_message,
-    tool_success,
-)
 from pipefy_mcp.tools.validation_helpers import (
     mutation_error_if_not_optional_dict,
     validate_optional_tool_id,

packages/mcp/src/pipefy_mcp/tools/validation_envelope.py

@@ -27,7 +27,7 @@
 from mcp.server.fastmcp.tools.tool_manager import ToolManager
 from pydantic import ValidationError
 
-from pipefy_mcp.tools.tool_error_envelope import tool_error
+from pipefy_mcp.core.tool_error_envelope import tool_error
 
 if TYPE_CHECKING:
     from collections.abc import Callable