lda-wf/docs/superpowers/research/2026-06-02-wfmcpservice-remaining-responsibilities.md

WfMcpService Remaining Responsibility Audit

Date: 2026-06-02

Summary

WfMcpService is now mostly a compatibility coordinator. The major ownership areas have moved into focused services:

• ConnectionService: connection registry, connection registration, config sync.
• SourceCatalogService: capability sources, catalog snapshots, source/resource/prompt inventory.
• UpstreamTransportService: adapters, auth, upstream reads/prompts/raw calls, catalog refresh.
• WorkflowRuntimeService: plan compilation and run/resume execution.
• BrokerEventRecorder: broker-local event recording and catalog change fanout.

The remaining class still has two kinds of code:

• Thin compatibility delegates that can stay until callers move to service/domain APIs.
• One meaningful mixed responsibility: local documentation resource/prompt handling before forwarding to upstream transport.

Remaining Members

Member	Current role	Classification	Recommendation
__post_init__	Wires focused services together and installs builtin/admin sources	Coordinator	Keep for now; eventually move construction to a factory/builder if HTTP/API frontends need the same bundle without WfMcpService.
capability_sources	Property returning source_catalog.capability_sources	Compatibility facade	Keep while wf_api operation context and tests use it; prefer direct SourceCatalogService in new internals.
connections	Property returning connection_service.connections	Compatibility facade	Keep for admin/CLI/tests; do not add new logic here.
adapters	Property returning upstream.adapters	Compatibility facade	Keep for config/server reload code; eventually expose adapter registration through UpstreamTransportService.
register_connection	Delegates to ConnectionService	Compatibility facade	Keep for old service callers; new broker internals should call connection_service.
sync_connections_from_config	Delegates to ConnectionService	Compatibility facade	Keep for server/core.py reload callback until that code depends on ConnectionService directly.
register_adapter	Delegates to UpstreamTransportService	Compatibility facade	Keep for config and tests; new code should call upstream.
_tool_executor_for	Delegates to UpstreamTransportService	Compatibility/private shim	Remove after confirming no callers outside tests/legacy paths need it.
save_auth, load_auth	Delegate to UpstreamTransportService	Compatibility facade	Keep until admin/control surfaces use upstream service directly.
register_specs	Delegates to SourceCatalogService with event fanout callback	Thin coordinator	Acceptable for now; later expose source_catalog.register_specs(..., record_catalog_change_events=events.record_catalog_change_events) through a smaller service bundle.
Catalog/source list/inspect methods	Delegate to SourceCatalogService	Compatibility facade	Keep while admin/MCP surfaces use WfMcpService; new code should call source_catalog.
workflow_artifact_catalog_entry	Removed from WfMcpService	Completed cleanup	wf_api.artifacts now calls wf_artifacts.artifact_catalog_entry() directly.
read_resource	Delegates to ContentAccessService	Compatibility facade	Keep for admin/MCP callers; new code should call content_access.
invoke_method, send_notification	Lookup connection, forward upstream	Compatibility facade	Could move with resource/prompt access or leave as upstream delegates.
render_prompt	Delegates to ContentAccessService	Compatibility facade	Keep for admin/MCP callers; new code should call content_access.
refresh_connection_catalog	Lookup connection, call upstream refresh with source/event callbacks	Thin coordinator	Could move to UpstreamTransportService if it accepts connection id + connection lookup, or stay as facade. Not as urgent as resources/prompts.
Runtime methods	Delegate to WorkflowRuntimeService	Compatibility facade	Keep while wf_api runtime adapter points through service; new internals should use workflow_runtime.
list_events	Delegates to BrokerEventRecorder	Compatibility facade	Keep for admin/tests; new code should call events.
register_capability_source	Delegates to SourceCatalogService	Compatibility facade	Keep for old service callers; source ownership is explicit.
_get_qualified_spec	Delegates to SourceCatalogService	Compatibility/private shim	Keep only for tests/legacy paths; new code should call source_catalog.get_qualified_spec.
_record_event, _record_catalog_change_events	Delegate to BrokerEventRecorder	Compatibility/private shim	Remove when remaining WfMcpService methods stop needing local event helpers.

Best Next Slice (Completed)

Extract a resource/prompt access service, tentatively named BrokerContentAccessService or ResourcePromptAccessService.

Done: ContentAccessService now owns read_resource and render_prompt. WfMcpService delegates both methods. See plan: docs/historical/superpowers/plans/2026-06-02-wfmcpservice-resource-prompt-access-extraction.md.

Keep out of scope for that slice:

• Catalog refresh. It has different semantics and should stay with upstream/catalog coordination until there is a clearer need.
• Workflow runtime methods. They are already clean delegates.
• workflow_artifact_catalog_entry. Completed: wf_api.artifacts now calls the pure wf_artifacts projection directly.

Small Cleanup Before Or After Next Slice

These are safe, low-risk cleanups:

• Completed: register_capability_source() delegates to self.source_catalog.register_capability_source(source) instead of mutating the dict.
• Completed: workflow_artifact_catalog_entry() was removed from WfMcpService; wf_api.artifacts calls wf_artifacts.artifact_catalog_entry() directly.
• Completed: WfMcpService now has a class docstring stating that it is a compatibility coordinator around focused broker services.

Durable API Implication

This audit supports the durable API direction: most backend concerns are now behind focused services. A future wf_api/HTTP server can compose these services directly instead of depending on MCP tool handlers. The remaining blocker is not runtime execution; it is choosing a durable service bundle/factory that owns process-local stores, event recorder, connection service, source catalog, upstream transport, and workflow runtime without requiring WfMcpService as the public object.