544 lines
15 KiB
Markdown
544 lines
15 KiB
Markdown
# RPC Transport Config Boundary Cleanup 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:** Remove direct `wf_mcp` imports from `wf_transport_rpc_http` now that neutral `wf_config.server.sources[]` can describe MCP sources.
|
|
|
|
**Architecture:** Keep JSON-RPC transport modules focused on serving a `WorkflowServer`. Move config-to-server composition into a server-layer module that can select local/static or MCP-backed composition by config source kind. `wf_server.context` remains MCP-free; the new config composition module is the explicit boundary for source-provider selection.
|
|
|
|
**Tech Stack:** Typer CLI, `wf_config.WorkflowConfigFile`, `wf_server.WorkflowServer`, existing MCP-backed builder in `wf_mcp.broker.server`, AST import-direction tests.
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
- Create `src/wf_server/config.py`: server composition from neutral workflow config and legacy MCP config path.
|
|
- Modify `src/wf_transport_rpc_http/cli.py`: import server composition helpers from `wf_server.config`, not `wf_mcp.broker`.
|
|
- Modify `tests/wf_transport_rpc_http/test_cli.py`: monkeypatch new helper paths.
|
|
- Modify `tests/wf_transport_rpc_http/test_import_direction.py`: no change expected; it should pass once direct imports are removed.
|
|
- Create `tests/wf_server/test_config_composition.py`: cover local/static and MCP-source selection.
|
|
- Modify docs after implementation.
|
|
|
|
## Current Context
|
|
|
|
`src/wf_transport_rpc_http/cli.py` currently imports:
|
|
|
|
```python
|
|
from wf_mcp.broker import (
|
|
build_workflow_server_from_config,
|
|
build_workflow_server_from_workflow_config,
|
|
load_broker_config,
|
|
)
|
|
```
|
|
|
|
That makes `tests/wf_transport_rpc_http/test_import_direction.py` fail:
|
|
|
|
```python
|
|
def test_wf_transport_rpc_http_imports_no_wfmcp_modules() -> None:
|
|
...
|
|
assert violations == []
|
|
```
|
|
|
|
Do not remove the test. The transport package should not import MCP modules directly.
|
|
|
|
`src/wf_server/context.py` has a narrower guard in `tests/wf_server/test_local_static_server.py` that only checks `context.py` for `WfMcpService`. Keep `context.py` untouched.
|
|
|
|
## Task 1: Add Server Composition Tests
|
|
|
|
**Files:**
|
|
- Create: `tests/wf_server/test_config_composition.py`
|
|
|
|
- [ ] **Step 1: Create test file**
|
|
|
|
Create `tests/wf_server/test_config_composition.py`:
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
from wf_config import WorkflowConfigFile
|
|
from wf_server.config import (
|
|
build_workflow_server_from_legacy_mcp_config,
|
|
build_workflow_server_from_workflow_config,
|
|
)
|
|
from wf_server.context import WorkflowServer
|
|
|
|
|
|
def test_build_workflow_server_from_workflow_config_uses_local_static_for_no_mcp_sources(
|
|
tmp_path,
|
|
) -> None:
|
|
config = WorkflowConfigFile.model_validate(
|
|
{
|
|
"version": 1,
|
|
"server": {
|
|
"store": {"kind": "filesystem", "root": str(tmp_path / "store")},
|
|
"sources": [{"kind": "stdlib", "id": "wf.std"}],
|
|
},
|
|
}
|
|
)
|
|
|
|
server = build_workflow_server_from_workflow_config(config)
|
|
|
|
assert isinstance(server, WorkflowServer)
|
|
assert server.config.store_root == tmp_path / "store"
|
|
assert server.source_registry_admin is None
|
|
|
|
|
|
def test_build_workflow_server_from_workflow_config_uses_mcp_builder_for_mcp_sources(
|
|
monkeypatch, tmp_path
|
|
) -> None:
|
|
captured = {}
|
|
|
|
def fake_builder(config):
|
|
captured["source_kinds"] = [source.kind for source in config.server.sources]
|
|
return "mcp-server"
|
|
|
|
monkeypatch.setattr(
|
|
"wf_server.config._build_mcp_workflow_server_from_workflow_config",
|
|
fake_builder,
|
|
)
|
|
config = WorkflowConfigFile.model_validate(
|
|
{
|
|
"version": 1,
|
|
"server": {
|
|
"store": {"kind": "filesystem", "root": str(tmp_path / "store")},
|
|
"sources": [
|
|
{
|
|
"kind": "mcp",
|
|
"id": "everything.default",
|
|
"provider": "everything",
|
|
"account": "default",
|
|
"transport": {"kind": "stdio", "command": "uvx"},
|
|
}
|
|
],
|
|
},
|
|
}
|
|
)
|
|
|
|
server = build_workflow_server_from_workflow_config(config)
|
|
|
|
assert server == "mcp-server"
|
|
assert captured["source_kinds"] == ["mcp"]
|
|
|
|
|
|
def test_build_workflow_server_from_legacy_mcp_config_delegates_to_mcp_builder(
|
|
monkeypatch, tmp_path
|
|
) -> None:
|
|
captured = {}
|
|
|
|
def fake_builder(path):
|
|
captured["path"] = path
|
|
return "legacy-mcp-server"
|
|
|
|
monkeypatch.setattr(
|
|
"wf_server.config._build_mcp_workflow_server_from_legacy_config",
|
|
fake_builder,
|
|
)
|
|
legacy_path = tmp_path / "wf_mcp.config.json"
|
|
legacy_path.write_text('{"store_root": "store", "connections": []}', encoding="utf-8")
|
|
|
|
server = build_workflow_server_from_legacy_mcp_config(legacy_path)
|
|
|
|
assert server == "legacy-mcp-server"
|
|
assert captured["path"] == legacy_path
|
|
```
|
|
|
|
- [ ] **Step 2: Run tests and verify failure**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_server/test_config_composition.py -q
|
|
```
|
|
|
|
Expected: fail because `wf_server.config` does not exist.
|
|
|
|
## Task 2: Implement Server Config Composition Module
|
|
|
|
**Files:**
|
|
- Create: `src/wf_server/config.py`
|
|
|
|
- [ ] **Step 1: Create module**
|
|
|
|
Create `src/wf_server/config.py`:
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
from pathlib import Path
|
|
|
|
from wf_config import FilesystemStoreConfig, WorkflowConfigFile
|
|
|
|
from .context import WorkflowServer, build_local_static_workflow_server
|
|
|
|
|
|
def _has_mcp_sources(config: WorkflowConfigFile) -> bool:
|
|
return any(getattr(source, "kind", None) == "mcp" for source in config.server.sources)
|
|
|
|
|
|
def _build_mcp_workflow_server_from_workflow_config(
|
|
config: WorkflowConfigFile,
|
|
) -> WorkflowServer:
|
|
"""Build an MCP-backed server from neutral config.
|
|
|
|
This import is intentionally isolated here: transport packages should not
|
|
import MCP modules, while this server composition boundary is allowed to
|
|
select source-provider implementations by source kind.
|
|
"""
|
|
from wf_mcp.broker import build_workflow_server_from_workflow_config
|
|
|
|
return build_workflow_server_from_workflow_config(config)
|
|
|
|
|
|
def _build_mcp_workflow_server_from_legacy_config(path: Path) -> WorkflowServer:
|
|
"""Build an MCP-backed server from legacy broker config."""
|
|
from wf_mcp.broker import build_workflow_server_from_config, load_broker_config
|
|
|
|
return build_workflow_server_from_config(load_broker_config(path))
|
|
|
|
|
|
def build_workflow_server_from_workflow_config(
|
|
config: WorkflowConfigFile,
|
|
) -> WorkflowServer:
|
|
"""Build a WorkflowServer from neutral workflow config.
|
|
|
|
Local/static configs use built-in sources. Configs with `kind: "mcp"`
|
|
sources delegate to the MCP provider adapter.
|
|
"""
|
|
if _has_mcp_sources(config):
|
|
return _build_mcp_workflow_server_from_workflow_config(config)
|
|
store = config.server.store
|
|
if not isinstance(store, FilesystemStoreConfig):
|
|
raise ValueError("wf-rpc-server currently requires filesystem store")
|
|
return build_local_static_workflow_server(store.root)
|
|
|
|
|
|
def build_workflow_server_from_legacy_mcp_config(path: str | Path) -> WorkflowServer:
|
|
"""Build a WorkflowServer from legacy wf_mcp.config.json.
|
|
|
|
Prefer neutral `wf_config` for new setups. This compatibility hook keeps the
|
|
transport CLI free of direct MCP imports while existing users migrate.
|
|
"""
|
|
return _build_mcp_workflow_server_from_legacy_config(Path(path))
|
|
```
|
|
|
|
- [ ] **Step 2: Run tests**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_server/test_config_composition.py -q
|
|
```
|
|
|
|
Expected: pass.
|
|
|
|
- [ ] **Step 3: Run import-boundary check**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_server/test_local_static_server.py::test_wf_server_context_imports_no_wfmcp_service -q
|
|
```
|
|
|
|
Expected: pass because `context.py` was not changed.
|
|
|
|
## Task 3: Update RPC CLI to Use Server Composition Helpers
|
|
|
|
**Files:**
|
|
- Modify: `src/wf_transport_rpc_http/cli.py`
|
|
- Modify: `tests/wf_transport_rpc_http/test_cli.py`
|
|
|
|
- [ ] **Step 1: Update imports**
|
|
|
|
Replace:
|
|
|
|
```python
|
|
from wf_mcp.broker import (
|
|
build_workflow_server_from_config,
|
|
build_workflow_server_from_workflow_config,
|
|
load_broker_config,
|
|
)
|
|
|
|
from wf_server import build_local_static_workflow_server
|
|
```
|
|
|
|
with:
|
|
|
|
```python
|
|
from wf_server.config import (
|
|
build_workflow_server_from_legacy_mcp_config,
|
|
build_workflow_server_from_workflow_config,
|
|
)
|
|
from wf_server.context import build_local_static_workflow_server
|
|
```
|
|
|
|
- [ ] **Step 2: Update legacy mcp config branch**
|
|
|
|
Replace:
|
|
|
|
```python
|
|
if mcp_config is not None:
|
|
broker_config = load_broker_config(mcp_config)
|
|
server = build_workflow_server_from_config(broker_config)
|
|
```
|
|
|
|
with:
|
|
|
|
```python
|
|
if mcp_config is not None:
|
|
server = build_workflow_server_from_legacy_mcp_config(mcp_config)
|
|
```
|
|
|
|
- [ ] **Step 3: Remove duplicated mcp source detection from CLI**
|
|
|
|
Inside the `if config is not None:` block, remove:
|
|
|
|
```python
|
|
has_mcp_sources = any(
|
|
getattr(source, "kind", None) == "mcp"
|
|
for source in workflow_config.server.sources
|
|
)
|
|
if server is None and has_mcp_sources:
|
|
server = build_workflow_server_from_workflow_config(workflow_config)
|
|
```
|
|
|
|
Then replace the local/static store handling block:
|
|
|
|
```python
|
|
store = workflow_config.server.store
|
|
if server is None and not isinstance(store, FilesystemStoreConfig):
|
|
raise typer.BadParameter(
|
|
"wf-rpc-server currently requires filesystem store"
|
|
)
|
|
if server is None:
|
|
resolved_store_root = resolved_store_root or store.root
|
|
```
|
|
|
|
with:
|
|
|
|
```python
|
|
store = workflow_config.server.store
|
|
if server is None and store_root is None:
|
|
server = build_workflow_server_from_workflow_config(workflow_config)
|
|
elif server is None:
|
|
if not isinstance(store, FilesystemStoreConfig):
|
|
raise typer.BadParameter(
|
|
"wf-rpc-server currently requires filesystem store"
|
|
)
|
|
resolved_store_root = resolved_store_root or store.root
|
|
```
|
|
|
|
Keep `--store-root` as an override for local/static configs. `--store-root` is still forbidden with `--mcp-config`; do not add new behavior there.
|
|
|
|
- [ ] **Step 4: Update tests monkeypatch paths**
|
|
|
|
In `tests/wf_transport_rpc_http/test_cli.py`, update existing monkeypatches to
|
|
match the new boundary.
|
|
|
|
For `test_rpc_server_cli_uses_configured_store_and_transport`, stop monkeypatching
|
|
`build_local_static_workflow_server`; the CLI now delegates config-based server
|
|
composition to `build_workflow_server_from_workflow_config`.
|
|
|
|
Replace:
|
|
|
|
```python
|
|
def fake_build_server(root):
|
|
captured["store_root"] = root
|
|
return object()
|
|
```
|
|
|
|
with:
|
|
|
|
```python
|
|
def fake_build_server(config):
|
|
captured["store_root"] = config.server.store.root
|
|
return object()
|
|
```
|
|
|
|
Replace this monkeypatch:
|
|
|
|
```python
|
|
monkeypatch.setattr(
|
|
"wf_transport_rpc_http.cli.build_local_static_workflow_server",
|
|
fake_build_server,
|
|
)
|
|
```
|
|
|
|
with:
|
|
|
|
```python
|
|
monkeypatch.setattr(
|
|
"wf_transport_rpc_http.cli.build_workflow_server_from_workflow_config",
|
|
fake_build_server,
|
|
)
|
|
```
|
|
|
|
Keep the assertion:
|
|
|
|
```python
|
|
assert captured["store_root"] == (tmp_path / ".wf_store").resolve()
|
|
```
|
|
|
|
For legacy MCP config tests, replace monkeypatch paths:
|
|
|
|
```python
|
|
"wf_transport_rpc_http.cli.build_workflow_server_from_config"
|
|
"wf_transport_rpc_http.cli.build_workflow_server_from_workflow_config"
|
|
```
|
|
|
|
with:
|
|
|
|
```python
|
|
"wf_transport_rpc_http.cli.build_workflow_server_from_legacy_mcp_config"
|
|
"wf_transport_rpc_http.cli.build_workflow_server_from_workflow_config"
|
|
```
|
|
|
|
If a test currently monkeypatches `load_broker_config`, remove that monkeypatch and have the fake legacy builder capture the config path directly.
|
|
|
|
For `test_rpc_server_cli_uses_mcp_config_server`, replace the two fake helpers:
|
|
|
|
```python
|
|
def fake_load_broker_config(path):
|
|
captured["mcp_config_path"] = path
|
|
return "broker-config"
|
|
|
|
def fake_build_mcp_server(config):
|
|
captured["mcp_config"] = config
|
|
return object()
|
|
```
|
|
|
|
with one helper:
|
|
|
|
```python
|
|
def fake_build_mcp_server(path):
|
|
captured["mcp_config_path"] = path
|
|
return object()
|
|
```
|
|
|
|
Replace the two monkeypatches:
|
|
|
|
```python
|
|
monkeypatch.setattr("wf_transport_rpc_http.cli.load_broker_config", fake_load_broker_config)
|
|
monkeypatch.setattr(
|
|
"wf_transport_rpc_http.cli.build_workflow_server_from_config",
|
|
fake_build_mcp_server,
|
|
)
|
|
```
|
|
|
|
with:
|
|
|
|
```python
|
|
monkeypatch.setattr(
|
|
"wf_transport_rpc_http.cli.build_workflow_server_from_legacy_mcp_config",
|
|
fake_build_mcp_server,
|
|
)
|
|
```
|
|
|
|
Remove the assertion:
|
|
|
|
```python
|
|
assert captured["mcp_config"] == "broker-config"
|
|
```
|
|
|
|
- [ ] **Step 5: Run CLI tests**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_transport_rpc_http/test_cli.py -q
|
|
```
|
|
|
|
Expected: pass.
|
|
|
|
## Task 4: Restore Transport Import-Direction Guard
|
|
|
|
**Files:**
|
|
- Test: `tests/wf_transport_rpc_http/test_import_direction.py`
|
|
|
|
- [ ] **Step 1: Run guard**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_transport_rpc_http/test_import_direction.py -q
|
|
```
|
|
|
|
Expected: pass. If it fails, inspect `src/wf_transport_rpc_http` for any remaining `wf_mcp` imports and remove them.
|
|
|
|
- [ ] **Step 2: Run wider RPC subset**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_transport_rpc_http tests/wf_cli/test_remote_target.py -q
|
|
```
|
|
|
|
Expected: pass. The prior known failure should be gone.
|
|
|
|
## Task 5: Update Docs and Mark Cleanup Complete
|
|
|
|
**Files:**
|
|
- Modify: `docs/current_roadmap.md`
|
|
- Modify: `docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md`
|
|
|
|
- [ ] **Step 1: Update roadmap**
|
|
|
|
In `docs/current_roadmap.md`, under "Transport package boundary cleanup", append:
|
|
|
|
```markdown
|
|
Completed: `wf_transport_rpc_http` no longer imports `wf_mcp`; server
|
|
composition from neutral or legacy MCP config lives behind `wf_server.config`.
|
|
```
|
|
|
|
- [ ] **Step 2: Update long-lived API spec**
|
|
|
|
In `docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md`, under "Transport package boundary cleanup", append:
|
|
|
|
```markdown
|
|
Completed when `tests/wf_transport_rpc_http/test_import_direction.py` passes
|
|
and the RPC transport CLI imports only `wf_config`, `wf_server`, and transport
|
|
modules for server construction.
|
|
```
|
|
|
|
## Task 6: Final Verification and Commit
|
|
|
|
**Files:**
|
|
- All touched files.
|
|
|
|
- [ ] **Step 1: Run focused tests**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_server/test_config_composition.py tests/wf_transport_rpc_http tests/wf_cli/test_remote_target.py -q
|
|
```
|
|
|
|
Expected: pass.
|
|
|
|
- [ ] **Step 2: Run lint/type checks**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run ruff check src/wf_server src/wf_transport_rpc_http tests/wf_server tests/wf_transport_rpc_http
|
|
uv run basedpyright --level error src/wf_server src/wf_transport_rpc_http tests/wf_server tests/wf_transport_rpc_http
|
|
```
|
|
|
|
Expected: pass with 0 errors.
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
git add src/wf_server src/wf_transport_rpc_http tests/wf_server tests/wf_transport_rpc_http docs/current_roadmap.md docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md
|
|
git commit -m "refactor: isolate rpc server config composition"
|
|
```
|
|
|
|
## Self-Review Checklist
|
|
|
|
- `src/wf_transport_rpc_http` contains no direct `wf_mcp` imports.
|
|
- `src/wf_server/context.py` remains MCP-free.
|
|
- The MCP-specific import is isolated in `src/wf_server/config.py` with a docstring explaining the boundary.
|
|
- `wf-rpc-server --config` still works for local/static and MCP-source neutral configs.
|
|
- `wf-rpc-server --mcp-config` still works as a legacy compatibility path.
|