wf-mcp reorg 5 the root import cleanup

docs/wf_mcp_architecture.md

@@ -20,6 +20,11 @@ Root modules such as `wf_mcp.store`, `wf_mcp.service`, and
 `wf_mcp.mcp_sdk_adapter` are compatibility shims. New internal imports should
 prefer the concern package directly.
 
+The root `wf_mcp` package is a small public facade for common user entrypoints,
+not a dump of every internal helper. If a caller needs broker internals, SDK
+adapter protocols, proxy admin pieces, or shared name parsing, import the
+relevant concern package directly.
+
 ## Dependency Rules
 
 - `wf_mcp.sdk` should not import `wf_core` or `wf_authoring`.

src/wf_mcp/__init__.py

@@ -1,117 +1,45 @@
-from .sdk import (
-    BackendAdapter,
-    McpSdkAdapter,
-    ToolCallResult,
-)
 from .broker import (
-    build_service_from_config,
-    CombinedCatalog,
-    create_broker_server,
-    DiscoveredConnectionCapabilities,
-    discover_connection_capabilities,
     load_broker_config,
-    McpEvent,
-    make_event,
     run_broker_server,
     run_transparent_proxy_server,
-    specs_from_discovered_tools,
     WfMcpService,
 )
 from .capabilities import (
-    CatalogNodeEntry,
-    CatalogPromptEntry,
-    CatalogResourceEntry,
     DiscoveredPrompt,
     DiscoveredResource,
     DiscoveredTool,
 )
-from .connections import ConnectionRegistry, parse_connection_id, qualify_node_name
-from .control import (
-    BrokerConfigManager,
-    ConfigMutationError,
-    BrokerConfigFile,
-    ConnectionConfigFile,
-    HttpConnectionMetadata,
-    StdioConnectionMetadata,
-)
 from .models import (
     AuthRecord,
     BrokerConfig,
-    CatalogSnapshot,
     ConnectionConfig,
     RawWorkflowPlan,
 )
-from .shared.names import (
-    ADMIN_NAMESPACE,
-    ProxyToolName,
-    is_admin_tool_name,
-    namespaced_tool_name,
-    parse_namespaced_tool_name,
-)
 from .proxy_validation import ProxyConfigError, validate_transparent_proxy_config
-from .proxy_config import (
+from .sdk import McpSdkAdapter
-    broker_config_to_fastmcp_config,
-    connection_to_fastmcp_server_config,
-)
 from .storage import FileStore, Store
 from .transparent_proxy import (
-    TransparentProxyRuntime,
-    create_proxy_admin_server,
     create_transparent_proxy_client,
     create_transparent_proxy_server,
 )
-from .workflow import wrap_discovered_tool
 
 __all__ = [
     "AuthRecord",
-    "ADMIN_NAMESPACE",
-    "BackendAdapter",
     "BrokerConfig",
-    "BrokerConfigManager",
-    "CatalogNodeEntry",
-    "CatalogPromptEntry",
-    "CatalogResourceEntry",
-    "CatalogSnapshot",
-    "CombinedCatalog",
     "ConnectionConfig",
-    "ConnectionConfigFile",
-    "ConnectionRegistry",
-    "ConfigMutationError",
-    "DiscoveredConnectionCapabilities",
     "DiscoveredPrompt",
     "DiscoveredResource",
     "DiscoveredTool",
     "FileStore",
-    "BrokerConfigFile",
-    "HttpConnectionMetadata",
-    "McpEvent",
     "McpSdkAdapter",
     "ProxyConfigError",
-    "ProxyToolName",
     "RawWorkflowPlan",
     "Store",
-    "StdioConnectionMetadata",
-    "ToolCallResult",
-    "TransparentProxyRuntime",
     "WfMcpService",
-    "build_service_from_config",
-    "broker_config_to_fastmcp_config",
-    "connection_to_fastmcp_server_config",
-    "create_broker_server",
-    "create_proxy_admin_server",
     "create_transparent_proxy_client",
     "create_transparent_proxy_server",
-    "discover_connection_capabilities",
-    "is_admin_tool_name",
     "load_broker_config",
-    "make_event",
-    "namespaced_tool_name",
-    "parse_connection_id",
-    "parse_namespaced_tool_name",
-    "qualify_node_name",
     "run_broker_server",
     "run_transparent_proxy_server",
-    "specs_from_discovered_tools",
     "validate_transparent_proxy_config",
-    "wrap_discovered_tool",
 ]

tests/wf_mcp/test_broker_server.py

@@ -3,15 +3,14 @@ from __future__ import annotations
 import asyncio
 import json
 
-from wf_mcp import (
+from wf_mcp.broker import (
-    BrokerConfig,
-    ConnectionConfig,
-    FileStore,
     WfMcpService,
     build_service_from_config,
     create_broker_server,
     load_broker_config,
 )
+from wf_mcp.models import BrokerConfig, ConnectionConfig
+from wf_mcp.storage import FileStore
 
 from .test_support import (
     FailingDiscoveryAdapter,

tests/wf_mcp/test_compat_imports.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+
+def test_root_facade_exports_core_entrypoints() -> None:
+    from wf_mcp import (
+        AuthRecord,
+        BrokerConfig,
+        ConnectionConfig,
+        DiscoveredTool,
+        FileStore,
+        McpSdkAdapter,
+        WfMcpService,
+        create_transparent_proxy_client,
+        load_broker_config,
+    )
+
+    assert AuthRecord.__name__ == "AuthRecord"
+    assert BrokerConfig.__name__ == "BrokerConfig"
+    assert ConnectionConfig.__name__ == "ConnectionConfig"
+    assert DiscoveredTool.__name__ == "DiscoveredTool"
+    assert FileStore.__name__ == "FileStore"
+    assert McpSdkAdapter.__name__ == "McpSdkAdapter"
+    assert WfMcpService.__name__ == "WfMcpService"
+    assert callable(create_transparent_proxy_client)
+    assert callable(load_broker_config)
+
+
+def test_legacy_shim_imports_still_resolve() -> None:
+    from wf_mcp.broker_server import load_broker_config
+    from wf_mcp.mcp_sdk_adapter import McpSdkAdapter
+    from wf_mcp.service import WfMcpService
+    from wf_mcp.store import FileStore
+
+    assert FileStore.__name__ == "FileStore"
+    assert McpSdkAdapter.__name__ == "McpSdkAdapter"
+    assert WfMcpService.__name__ == "WfMcpService"
+    assert callable(load_broker_config)

tests/wf_mcp/test_sdk_adapter.py

@@ -4,7 +4,10 @@ import asyncio
 
 import pytest
 
-from wf_mcp import ConnectionConfig, FileStore, McpSdkAdapter, WfMcpService
+from wf_mcp.broker import WfMcpService
+from wf_mcp.models import ConnectionConfig
+from wf_mcp.sdk import McpSdkAdapter
+from wf_mcp.storage import FileStore
 
 from .test_support import (
     everything_server_connection,

tests/wf_mcp/test_service.py

@@ -4,14 +4,10 @@ import asyncio
 import shutil
 
 from wf_core import END, RunStatus
-from wf_mcp import (
+from wf_mcp.broker import WfMcpService
-    AuthRecord,
+from wf_mcp.models import AuthRecord, ConnectionConfig, RawWorkflowPlan
-    ConnectionConfig,
+from wf_mcp.shared.errors import error_payload
-    FileStore,
+from wf_mcp.storage import FileStore
-    RawWorkflowPlan,
-    WfMcpService,
-)
-from wf_mcp.error_info import error_payload
 
 from .test_support import (
     FailingDiscoveryAdapter,

tests/wf_mcp/test_store.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from wf_mcp import AuthRecord, FileStore
+from wf_mcp.models import AuthRecord
+from wf_mcp.storage import FileStore
 
 from .test_support import local_temp_root
 

tests/wf_mcp/test_support.py

@@ -9,14 +9,9 @@ from pydantic import BaseModel
 
 from wf_authoring import NodeReturn, node
 from wf_core import RuntimeContext
-from wf_mcp import (
+from wf_mcp.capabilities import DiscoveredPrompt, DiscoveredResource, DiscoveredTool
-    AuthRecord,
+from wf_mcp.models import AuthRecord, ConnectionConfig
-    ConnectionConfig,
+from wf_mcp.sdk import ToolCallResult
-    DiscoveredPrompt,
-    DiscoveredResource,
-    DiscoveredTool,
-    ToolCallResult,
-)
 
 
 class EchoInput(BaseModel):

tests/wf_mcp/test_transparent_proxy.py

@@ -7,13 +7,9 @@ from typing import Any
 
 import pytest
 
-from wf_mcp import (
+from wf_mcp.models import BrokerConfig, ConnectionConfig
-    BrokerConfig,
+from wf_mcp.proxy_validation import ProxyConfigError, validate_transparent_proxy_config
-    ConnectionConfig,
+from wf_mcp.transparent_proxy import create_transparent_proxy_client
-    ProxyConfigError,
-    create_transparent_proxy_client,
-    validate_transparent_proxy_config,
-)
 from wf_mcp.broker_server import load_broker_config
 
 from .test_support import fixture_server_path, local_temp_root