lda-wf/docs/historical/superpowers/plans/2026-06-06-wf-sources-mcp-source-registry-slice.md

wf_sources_mcp Source Registry Slice Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Move MCP-as-upstream-source registry models, file store, and conversion helpers from wf_mcp.source_registry into canonical wf_sources_mcp.source_registry while preserving compatibility imports.

Architecture: wf_sources_mcp owns MCP upstream source details. wf_mcp remains a compatibility facade and old entrypoint package. This slice is a pure move/refactor: no JSON shape changes, no config behavior changes, no live MCP session movement.

Tech Stack: Python 3.14, Pydantic v2, pytest, Ruff, basedpyright, src/ package layout.

---

Boundaries

Move only source registry code:

• StdioSourceTransport
• HttpSourceTransport
• SourceTransport
• McpSourceRegistryEntry
• SourceRegistryFile
• SourceRegistryStore
• FileSourceRegistryStore
• registry_entry_to_connection_config
• connection_config_to_registry_entry
• workflow_mcp_source_to_connection_config

Do not move:

• wf_mcp.sdk.adapter
• wf_mcp.runtime.*
• wf_mcp.broker.service.upstream_transport
• wf_mcp.capabilities
• wf_mcp.catalog.models
• generic wf_api.source_registry
• JSON-RPC or CLI source registry admin surfaces

Temporary dependencies are acceptable if documented:

• wf_sources_mcp.source_registry may import wf_mcp.connections.parse_connection_id and wf_mcp.shared.names.RESERVED_CONNECTION_IDS.
• wf_sources_mcp.source_registry may use lazy imports for wf_mcp.models.ConnectionConfig to avoid pulling broker runtime DTOs at module import time.

File Map

Create:

• src/wf_sources_mcp/source_registry.py — canonical MCP upstream source registry models/store/conversions.
• tests/wf_sources_mcp/test_source_registry.py — canonical tests for moved behavior.

Modify:

• src/wf_sources_mcp/__init__.py — export the moved source registry symbols.
• src/wf_mcp/source_registry.py — replace with compatibility shim.
• src/wf_mcp/broker/config.py — canonical imports from wf_sources_mcp.source_registry.
• src/wf_mcp/broker/server.py — canonical imports from wf_sources_mcp.source_registry.
• src/wf_mcp/broker/service/connection_service.py — canonical imports.
• src/wf_mcp/broker/service/core.py — canonical imports.
• src/wf_mcp/broker/service/source_registry_admin.py — canonical imports.
• src/wf_mcp/server/core.py — canonical import for FileSourceRegistryStore.
• tests/wf_mcp/test_compat_imports.py — shim identity tests.
• Existing tests importing wf_mcp.source_registry may stay as compatibility tests unless they are production-facing import examples.
• docs/current_roadmap.md — mark source registry slice complete.
• docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md — mark source registry slice complete.

After implementation, move this plan to:

• docs/historical/superpowers/plans/2026-06-06-wf-sources-mcp-source-registry-slice.md

---

Task 1: Canonical Source Registry Module

Files:

• Create: src/wf_sources_mcp/source_registry.py

• Modify: src/wf_sources_mcp/__init__.py

• Test: tests/wf_sources_mcp/test_source_registry.py

• Step 1: Create canonical source registry module

Copy the current contents of src/wf_mcp/source_registry.py into src/wf_sources_mcp/source_registry.py, then apply these import edits exactly:

from wf_mcp.connections import parse_connection_id
from wf_mcp.shared.names import RESERVED_CONNECTION_IDS

Keep this type-checking import:

if TYPE_CHECKING:
    from wf_mcp.models import ConnectionConfig

Change lazy runtime imports inside conversion helpers to:

from wf_mcp.models import ConnectionConfig

Add this module docstring at the top:

"""MCP upstream-source registry models and conversion helpers.

This module is canonical for MCP-as-source desired registry state. The temporary
runtime dependency on `wf_mcp.models.ConnectionConfig` remains until broker
runtime DTOs move out of the compatibility MCP facade.
"""

• Step 2: Export symbols from wf_sources_mcp.__init__

Add imports and __all__ entries for the source registry symbols:

from .source_registry import (
    FileSourceRegistryStore,
    HttpSourceTransport,
    McpSourceRegistryEntry,
    SourceRegistryFile,
    SourceRegistryStore,
    SourceTransport,
    StdioSourceTransport,
    connection_config_to_registry_entry,
    registry_entry_to_connection_config,
    workflow_mcp_source_to_connection_config,
)

Ensure __all__ includes the same symbol names.

• Step 3: Add canonical tests

Create tests/wf_sources_mcp/test_source_registry.py with tests copied from tests/wf_mcp/test_source_registry.py, but import from wf_sources_mcp.source_registry.

Use this import block:

from __future__ import annotations

from pathlib import Path

import pytest

from wf_mcp.models import ConnectionConfig
from wf_sources_mcp.source_registry import (
    FileSourceRegistryStore,
    HttpSourceTransport,
    McpSourceRegistryEntry,
    SourceRegistryFile,
    StdioSourceTransport,
    connection_config_to_registry_entry,
    registry_entry_to_connection_config,
)

Keep the existing test bodies unchanged except for import paths.

• Step 4: Run canonical tests

Run:

uv run pytest tests/wf_sources_mcp/test_source_registry.py -q

Expected: all copied canonical source registry tests pass.

---

Task 2: Replace wf_mcp.source_registry With Compatibility Shim

Files:

• Modify: src/wf_mcp/source_registry.py

• Modify: tests/wf_mcp/test_compat_imports.py

• Test: tests/wf_mcp/test_compat_imports.py

• Step 1: Replace old module with shim

Replace src/wf_mcp/source_registry.py with:

"""Compatibility shim for MCP source registry models.

Canonical implementation lives in `wf_sources_mcp.source_registry`.
"""

from __future__ import annotations

from wf_sources_mcp.source_registry import (
    FileSourceRegistryStore,
    HttpSourceTransport,
    McpSourceRegistryEntry,
    SourceRegistryFile,
    SourceRegistryStore,
    SourceTransport,
    StdioSourceTransport,
    connection_config_to_registry_entry,
    registry_entry_to_connection_config,
    workflow_mcp_source_to_connection_config,
)

__all__ = [
    "FileSourceRegistryStore",
    "HttpSourceTransport",
    "McpSourceRegistryEntry",
    "SourceRegistryFile",
    "SourceRegistryStore",
    "SourceTransport",
    "StdioSourceTransport",
    "connection_config_to_registry_entry",
    "registry_entry_to_connection_config",
    "workflow_mcp_source_to_connection_config",
]

• Step 2: Add shim identity tests

Append to tests/wf_mcp/test_compat_imports.py:

def test_wf_mcp_source_registry_shim_reexports_wf_sources_mcp_registry() -> None:
    from wf_mcp.source_registry import FileSourceRegistryStore as CompatFileStore
    from wf_mcp.source_registry import McpSourceRegistryEntry as CompatEntry
    from wf_mcp.source_registry import SourceRegistryFile as CompatFile
    from wf_sources_mcp.source_registry import (
        FileSourceRegistryStore,
        McpSourceRegistryEntry,
        SourceRegistryFile,
    )

    assert CompatFileStore is FileSourceRegistryStore
    assert CompatEntry is McpSourceRegistryEntry
    assert CompatFile is SourceRegistryFile

• Step 3: Run compatibility tests

Run:

uv run pytest tests/wf_mcp/test_compat_imports.py tests/wf_mcp/test_source_registry.py -q

Expected: compatibility tests and old source registry tests pass.

---

Task 3: Rewrite Production Imports to Canonical Package

Files:

• Modify: src/wf_mcp/broker/config.py

• Modify: src/wf_mcp/broker/server.py

• Modify: src/wf_mcp/broker/service/connection_service.py

• Modify: src/wf_mcp/broker/service/core.py

• Modify: src/wf_mcp/broker/service/source_registry_admin.py

• Modify: src/wf_mcp/server/core.py

• Step 1: Rewrite imports

Change production imports that currently point at wf_mcp.source_registry or relative ...source_registry to wf_sources_mcp.source_registry.

Use these canonical import examples:

from wf_sources_mcp.source_registry import (
    FileSourceRegistryStore,
    SourceRegistryStore,
)

from wf_sources_mcp.source_registry import (
    SourceRegistryFile,
    connection_config_to_registry_entry,
    registry_entry_to_connection_config,
)

from wf_sources_mcp.source_registry import (
    FileSourceRegistryStore,
    workflow_mcp_source_to_connection_config,
)

Do not rewrite tests/ imports in this task except if a test is specifically asserting canonical production wiring.

• Step 2: Confirm no production imports use the shim

Run:

rg -n "from (\\.\\.|wf_mcp)\\.source_registry|import wf_mcp\\.source_registry|source_registry import" src

Expected: no src/ production import uses wf_mcp.source_registry except the shim file itself. Imports from wf_sources_mcp.source_registry are expected.

• Step 3: Run broker and server focused tests

Run:

uv run pytest tests/wf_mcp/service/test_connection_service.py tests/wf_mcp/service/test_source_registry_admin.py tests/wf_mcp/test_broker_server.py tests/wf_mcp/test_mcp_workflow_server.py tests/wf_mcp/server/test_docs.py -q

Expected: all focused broker/server source registry tests pass.

---

Task 4: Strengthen Import Direction Guard

Files:

• Modify: tests/wf_sources_mcp/test_import_direction_guard.py

• Test: tests/wf_sources_mcp/test_import_direction_guard.py

• Step 1: Add allowed temporary dependency note

Update the guard file to include this comment above FORBIDDEN_WF_MCP_PREFIXES:

# Temporary low-level wf_mcp imports are allowed for connection id parsing,
# reserved names, and broker DTO conversion. Frontend/proxy/workflow-surface
# imports are forbidden because wf_sources_mcp is upstream-source code.

• Step 2: Ensure frontend/proxy modules remain forbidden

Keep these forbidden prefixes:

FORBIDDEN_WF_MCP_PREFIXES = (
    "wf_mcp.admin_surface",
    "wf_mcp.workflow_surface",
    "wf_mcp.server",
    "wf_mcp.proxy",
    "wf_mcp.cli",
)

• Step 3: Run guard test

Run:

uv run pytest tests/wf_sources_mcp/test_import_direction_guard.py -q

Expected: guard passes.

---

Task 5: Docs Status and Plan Archival

Files:

• Modify: docs/current_roadmap.md

• Modify: docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md

• Move: docs/superpowers/plans/2026-06-06-wf-sources-mcp-source-registry-slice.md to docs/historical/superpowers/plans/2026-06-06-wf-sources-mcp-source-registry-slice.md

• Step 1: Update roadmap

In docs/current_roadmap.md, under the MCP package split section, add a short completion note:

     Second `wf_sources_mcp` slice complete: MCP desired source registry
     models, file store, and conversion helpers now live in
     `wf_sources_mcp.source_registry`, with `wf_mcp.source_registry` retained
     as a compatibility shim.

• Step 2: Update long-lived API boundary spec

In docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md, in the wf_sources_mcp status/list section, update the source registry line to mark it complete:

2. Complete: MCP source registry models/conversion moved to `wf_sources_mcp.source_registry`, with `wf_mcp.source_registry` retained as a shim.

• Step 3: Move completed plan to historical

Run:

git mv docs/superpowers/plans/2026-06-06-wf-sources-mcp-source-registry-slice.md docs/historical/superpowers/plans/2026-06-06-wf-sources-mcp-source-registry-slice.md

Expected: git status --short shows an R rename for this plan.

---

Task 6: Final Verification

Files:

• All changed files

• Step 1: Run focused extraction tests

Run:

uv run pytest tests/wf_sources_mcp tests/wf_mcp/test_source_registry.py tests/wf_mcp/test_compat_imports.py tests/wf_mcp/service/test_connection_service.py tests/wf_mcp/service/test_source_registry_admin.py tests/wf_mcp/test_broker_server.py tests/wf_mcp/test_mcp_workflow_server.py -q

Expected: all focused tests pass.

• Step 2: Run lint and type checks

Run:

uv run ruff check src tests
uv run basedpyright --level error src

Expected: Ruff reports All checks passed!; basedpyright reports 0 errors.

• Step 3: Run full suite

Run:

uv run pytest -q

Expected: full suite passes with the current expected skip/xfail counts.

• Step 4: Review final import shape

Run:

rg -n "from wf_mcp\\.source_registry|import wf_mcp\\.source_registry" src tests

Expected: only compatibility tests may import wf_mcp.source_registry; production code should import wf_sources_mcp.source_registry.

• Step 5: Report

Report:

• files created/modified
• focused/full verification output
• whether any temporary wf_mcp dependencies remain in wf_sources_mcp.source_registry
• whether compatibility shims remain
• deviations from this plan

Do not commit unless the user explicitly asks. If committing, use:

git add -A
git commit -m "refactor: move mcp source registry to wf_sources_mcp"

---

Self-Review

• Spec coverage: covers the second listed wf_sources_mcp slice: source registry models/conversion. Does not move upstream sessions/adapters, by design.
• Placeholder scan: no TODO, TBD, or unspecified "add tests" steps.
• Type consistency: all moved symbols match the existing wf_mcp.source_registry names, preserving compatibility import names and production behavior.