547 lines
18 KiB
Markdown
547 lines
18 KiB
Markdown
# MCP-Backed Workflow Server Construction 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:** Build a concrete MCP-backed `WorkflowServer` composition so JSON-RPC/CLI can target a long-lived server with real MCP broker sources, admin data, and source-registry mutation.
|
|
|
|
**Architecture:** Keep `wf_server` transport-neutral and MCP-free. Add the MCP-specific constructor in `wf_mcp`, adapting an existing `WfMcpService` into the neutral `WorkflowServer` dataclass using `context_from_service`, `WorkflowApi`, `WorkflowAdminApi`, `WorkflowSourceAdminApi`, and `WorkflowSourceRegistryApi`. This proves remote RPC can use MCP-backed source registry/admin surfaces without making `wf_server` depend on `WfMcpService`.
|
|
|
|
**Tech Stack:** Python 3.14, dataclasses, Pydantic v2 models, `wf_api`, `wf_server`, `wf_mcp` broker services, `wf_transport_rpc_http`, pytest-asyncio, ruff, basedpyright.
|
|
|
|
---
|
|
|
|
## Current Context
|
|
|
|
Implemented pieces:
|
|
|
|
- `wf_server.context.WorkflowServer` is the neutral process-host shape.
|
|
- `wf_server.build_local_static_workflow_server()` builds a local/static server and intentionally leaves `source_registry_admin=None`.
|
|
- `wf_mcp.broker.config.build_service_from_config(config)` builds a `WfMcpService` with workflow stores, MCP adapters, source-registry startup merge, and configured connections.
|
|
- `wf_mcp.broker.service.workflow_operation_context.context_from_service(service)` adapts `WfMcpService` into a neutral `WorkflowOperationContext`.
|
|
- `wf_mcp.broker.service.source_registry_admin.SourceRegistryAdminProvider` provides desired-registry reads/mutations over `FileSourceRegistryStore`.
|
|
- `wf_transport_rpc_http.create_rpc_app(server)` registers workflow, source, source-registry, and admin JSON-RPC methods over any `WorkflowServer`.
|
|
|
|
Boundary rule:
|
|
|
|
- `wf_server` must not import `wf_mcp`.
|
|
- The MCP-backed constructor belongs in `wf_mcp` and returns a `wf_server.WorkflowServer`.
|
|
|
|
Out of scope:
|
|
|
|
- No new HTTP server process CLI.
|
|
- No hot reload/live remount after registry mutation.
|
|
- No auth redesign.
|
|
- No WebSocket/MCP transport sibling.
|
|
- No persisted run/resume process-restart implementation.
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
- Create `src/wf_mcp/broker/server.py`
|
|
- MCP-specific adapter constructors returning `WorkflowServer`.
|
|
- Wires `WorkflowApi`, source admin, admin, and desired source registry admin.
|
|
- Keeps the dependency direction `wf_mcp -> wf_server`, not `wf_server -> wf_mcp`.
|
|
- Modify `src/wf_mcp/broker/__init__.py`
|
|
- Re-export the constructor for callers/tests.
|
|
- Modify `src/wf_server/__init__.py`
|
|
- No MCP import. Only add exports if current `WorkflowServerConfig` is not exported and tests need it.
|
|
- Test `tests/wf_mcp/test_mcp_workflow_server.py`
|
|
- Direct construction tests for the MCP-backed server adapter.
|
|
- Test `tests/wf_transport_rpc_http/test_mcp_backed_server_rpc.py`
|
|
- RPC tests proving source-registry read/mutation and admin connections work against the MCP-backed server.
|
|
- Modify `docs/current_roadmap.md`
|
|
- Mark concrete MCP-backed `WorkflowServer` construction complete.
|
|
- Modify `docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md`
|
|
- Add implementation status for this slice.
|
|
|
|
---
|
|
|
|
### Task 1: Add MCP-Backed Server Adapter
|
|
|
|
**Files:**
|
|
- Create: `src/wf_mcp/broker/server.py`
|
|
- Modify: `src/wf_mcp/broker/__init__.py`
|
|
- Test: `tests/wf_mcp/test_mcp_workflow_server.py`
|
|
|
|
- [ ] **Step 1: Write direct construction tests**
|
|
|
|
Create `tests/wf_mcp/test_mcp_workflow_server.py`:
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
import ast
|
|
|
|
from wf_mcp.broker.config import build_service_from_config
|
|
from wf_mcp.broker.server import (
|
|
build_workflow_server_from_config,
|
|
workflow_server_from_service,
|
|
)
|
|
from wf_mcp.models import BrokerConfig, ConnectionConfig
|
|
from wf_mcp.source_registry import (
|
|
FileSourceRegistryStore,
|
|
McpSourceRegistryEntry,
|
|
SourceRegistryFile,
|
|
)
|
|
from wf_server import WorkflowServer
|
|
|
|
|
|
def _registry_entry(source_id: str) -> McpSourceRegistryEntry:
|
|
return McpSourceRegistryEntry.model_validate(
|
|
{
|
|
"id": source_id,
|
|
"kind": "mcp",
|
|
"enabled": True,
|
|
"provider": "demo",
|
|
"account": "registry",
|
|
"transport": {"kind": "stdio", "command": "demo-server"},
|
|
}
|
|
)
|
|
|
|
|
|
def test_wf_server_package_stays_mcp_free() -> None:
|
|
path = "src/wf_server/context.py"
|
|
tree = ast.parse(open(path, encoding="utf-8").read(), filename=path)
|
|
|
|
violations: list[str] = []
|
|
for node in ast.walk(tree):
|
|
if isinstance(node, ast.ImportFrom) and node.module:
|
|
if node.module.startswith("wf_mcp"):
|
|
violations.append(f"{node.lineno}: from {node.module} import ...")
|
|
elif isinstance(node, ast.Import):
|
|
for alias in node.names:
|
|
if alias.name.startswith("wf_mcp"):
|
|
violations.append(f"{node.lineno}: import {alias.name}")
|
|
|
|
assert violations == []
|
|
|
|
|
|
def test_workflow_server_from_service_wires_neutral_surfaces(tmp_path) -> None:
|
|
config = BrokerConfig(
|
|
store_root=tmp_path / "store",
|
|
connections=[
|
|
ConnectionConfig(id="demo.default", server="demo", account="default")
|
|
],
|
|
)
|
|
service = build_service_from_config(config)
|
|
|
|
server = workflow_server_from_service(
|
|
service,
|
|
config=config,
|
|
source_registry_store=FileSourceRegistryStore(config.store_root),
|
|
)
|
|
|
|
assert isinstance(server, WorkflowServer)
|
|
assert server.config.store_root == config.store_root
|
|
assert server.api.context is server.context
|
|
assert server.source_registry_admin is not None
|
|
assert server.admin.connections is service.connection_service
|
|
assert server.admin.events is service.events
|
|
|
|
|
|
def test_build_workflow_server_from_config_exposes_registry_admin(tmp_path) -> None:
|
|
config = BrokerConfig(store_root=tmp_path / "store", connections=[])
|
|
FileSourceRegistryStore(config.store_root).save_registry(
|
|
SourceRegistryFile(sources=[_registry_entry("demo.registry")])
|
|
)
|
|
|
|
server = build_workflow_server_from_config(config)
|
|
|
|
assert server.source_registry_admin is not None
|
|
assert "demo.registry" in server.context.specs.capability_sources
|
|
```
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/test_mcp_workflow_server.py -q
|
|
```
|
|
|
|
Expected: FAIL because `wf_mcp.broker.server` does not exist.
|
|
|
|
- [ ] **Step 2: Implement `src/wf_mcp/broker/server.py`**
|
|
|
|
Create `src/wf_mcp/broker/server.py`:
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
from wf_api import (
|
|
WorkflowAdminApi,
|
|
WorkflowApi,
|
|
WorkflowSourceAdminApi,
|
|
WorkflowSourceRegistryApi,
|
|
durable_workflow_api,
|
|
)
|
|
from wf_api.stores import WorkflowStores
|
|
from wf_server import WorkflowServer, WorkflowServerConfig
|
|
|
|
from .config import build_service_from_config
|
|
from .service import WfMcpService
|
|
from .service.source_registry_admin import SourceRegistryAdminProvider
|
|
from .service.workflow_operation_context import context_from_service
|
|
from ..models import BrokerConfig
|
|
from ..source_registry import FileSourceRegistryStore, SourceRegistryStore
|
|
|
|
|
|
def workflow_server_from_service(
|
|
service: WfMcpService,
|
|
*,
|
|
config: BrokerConfig,
|
|
source_registry_store: SourceRegistryStore,
|
|
) -> WorkflowServer:
|
|
"""Adapt an MCP broker service into the neutral WorkflowServer shape.
|
|
|
|
This is intentionally in wf_mcp, not wf_server: MCP owns upstream source
|
|
management, while wf_server stays transport-neutral and MCP-free.
|
|
"""
|
|
context = context_from_service(service)
|
|
api: WorkflowApi = durable_workflow_api(context)
|
|
source_admin = WorkflowSourceAdminApi(context)
|
|
admin = WorkflowAdminApi(
|
|
connections=service.connection_service,
|
|
events=service.events,
|
|
)
|
|
source_registry_admin = WorkflowSourceRegistryApi(
|
|
provider=SourceRegistryAdminProvider(
|
|
source_registry_store=source_registry_store,
|
|
config_connections=config.connections,
|
|
),
|
|
mutation_provider=SourceRegistryAdminProvider(
|
|
source_registry_store=source_registry_store,
|
|
config_connections=config.connections,
|
|
),
|
|
)
|
|
stores = WorkflowStores(
|
|
artifact_store=service.artifact_store,
|
|
draft_workspace_store=service.draft_workspace_store,
|
|
run_store=service.run_store,
|
|
)
|
|
return WorkflowServer(
|
|
config=WorkflowServerConfig(store_root=config.store_root),
|
|
stores=stores,
|
|
context=context,
|
|
api=api,
|
|
source_admin=source_admin,
|
|
admin=admin,
|
|
events=service.events,
|
|
source_registry_admin=source_registry_admin,
|
|
)
|
|
|
|
|
|
def build_workflow_server_from_config(config: BrokerConfig) -> WorkflowServer:
|
|
"""Build a neutral WorkflowServer backed by MCP broker runtime services."""
|
|
service = build_service_from_config(config)
|
|
return workflow_server_from_service(
|
|
service,
|
|
config=config,
|
|
source_registry_store=FileSourceRegistryStore(config.store_root),
|
|
)
|
|
|
|
|
|
__all__ = [
|
|
"build_workflow_server_from_config",
|
|
"workflow_server_from_service",
|
|
]
|
|
```
|
|
|
|
If basedpyright rejects `WorkflowStores(...)` because stores are optional on
|
|
`WfMcpService`, add explicit fail-fast guards before constructing it:
|
|
|
|
```python
|
|
if (
|
|
service.artifact_store is None
|
|
or service.draft_workspace_store is None
|
|
or service.run_store is None
|
|
):
|
|
raise ValueError("MCP-backed WorkflowServer requires workflow stores")
|
|
```
|
|
|
|
- [ ] **Step 3: Re-export the constructor**
|
|
|
|
Modify `src/wf_mcp/broker/__init__.py` to export:
|
|
|
|
```python
|
|
from .server import build_workflow_server_from_config, workflow_server_from_service
|
|
|
|
__all__ = [
|
|
# keep existing exports here
|
|
"build_workflow_server_from_config",
|
|
"workflow_server_from_service",
|
|
]
|
|
```
|
|
|
|
Do not remove existing exports. If the file currently has no `__all__`, add only
|
|
the imports and let existing import behavior continue.
|
|
|
|
- [ ] **Step 4: Run direct construction tests**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/test_mcp_workflow_server.py -q
|
|
```
|
|
|
|
Expected: PASS.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/wf_mcp/broker/server.py src/wf_mcp/broker/__init__.py tests/wf_mcp/test_mcp_workflow_server.py
|
|
git commit -m "feat: build mcp backed workflow server"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 2: Prove JSON-RPC Uses MCP-Backed Registry and Admin Surfaces
|
|
|
|
**Files:**
|
|
- Create: `tests/wf_transport_rpc_http/test_mcp_backed_server_rpc.py`
|
|
|
|
- [ ] **Step 1: Write RPC integration tests**
|
|
|
|
Create `tests/wf_transport_rpc_http/test_mcp_backed_server_rpc.py`:
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
import httpx
|
|
|
|
from wf_mcp.broker.server import build_workflow_server_from_config
|
|
from wf_mcp.models import BrokerConfig, ConnectionConfig
|
|
from wf_mcp.source_registry import (
|
|
FileSourceRegistryStore,
|
|
McpSourceRegistryEntry,
|
|
SourceRegistryFile,
|
|
)
|
|
from wf_transport_rpc_http import RpcWorkflowApiClient, create_rpc_app
|
|
|
|
|
|
def _registry_entry(source_id: str, *, enabled: bool = True) -> McpSourceRegistryEntry:
|
|
return McpSourceRegistryEntry.model_validate(
|
|
{
|
|
"id": source_id,
|
|
"kind": "mcp",
|
|
"enabled": enabled,
|
|
"provider": "demo",
|
|
"account": "registry",
|
|
"transport": {"kind": "stdio", "command": "demo-server"},
|
|
}
|
|
)
|
|
|
|
|
|
async def _rpc(client: httpx.AsyncClient, method: str, params: dict) -> dict:
|
|
response = await client.post(
|
|
"/rpc",
|
|
json={"jsonrpc": "2.0", "id": "test", "method": method, "params": params},
|
|
)
|
|
assert response.status_code == 200
|
|
return response.json()
|
|
|
|
|
|
async def test_mcp_backed_rpc_lists_and_mutates_source_registry(tmp_path) -> None:
|
|
config = BrokerConfig(store_root=tmp_path / "store", connections=[])
|
|
FileSourceRegistryStore(config.store_root).save_registry(
|
|
SourceRegistryFile(sources=[_registry_entry("demo.registry")])
|
|
)
|
|
server = build_workflow_server_from_config(config)
|
|
app = create_rpc_app(server)
|
|
transport = httpx.ASGITransport(app=app)
|
|
|
|
async with httpx.AsyncClient(
|
|
transport=transport, base_url="http://test"
|
|
) as http_client:
|
|
client = RpcWorkflowApiClient(http_client)
|
|
|
|
listed = await client.list_registry_entries(limit=10)
|
|
disabled = await client.disable_registry_entry("demo.registry")
|
|
inspected = await client.inspect_registry_entry("demo.registry")
|
|
|
|
assert listed["entries"][0]["id"] == "demo.registry"
|
|
assert disabled["entry"]["enabled"] is False
|
|
assert inspected["entry"]["enabled"] is False
|
|
|
|
|
|
async def test_mcp_backed_rpc_reports_connections_and_events(tmp_path) -> None:
|
|
config = BrokerConfig(
|
|
store_root=tmp_path / "store",
|
|
connections=[
|
|
ConnectionConfig(
|
|
id="demo.default",
|
|
server="demo",
|
|
account="default",
|
|
)
|
|
],
|
|
)
|
|
server = build_workflow_server_from_config(config)
|
|
app = create_rpc_app(server)
|
|
transport = httpx.ASGITransport(app=app)
|
|
|
|
async with httpx.AsyncClient(
|
|
transport=transport, base_url="http://test"
|
|
) as http_client:
|
|
connections = await _rpc(
|
|
http_client, "workflow.admin.connections.list", {"limit": 20}
|
|
)
|
|
events = await _rpc(http_client, "workflow.admin.events.list", {"limit": 20})
|
|
|
|
assert connections["result"]["connections"][0]["id"] == "demo.default"
|
|
assert any(
|
|
event["kind"] == "connection_registered"
|
|
for event in events["result"]["events"]
|
|
)
|
|
```
|
|
|
|
If `RpcWorkflowApiClient` method names differ, inspect
|
|
`src/wf_transport_rpc_http/client_source_registry.py` and use the exact names.
|
|
Do not change client method names in this slice unless the tests reveal a real
|
|
bug.
|
|
|
|
- [ ] **Step 2: Run RPC integration tests**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_transport_rpc_http/test_mcp_backed_server_rpc.py -q
|
|
```
|
|
|
|
Expected: PASS after Task 1.
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add tests/wf_transport_rpc_http/test_mcp_backed_server_rpc.py
|
|
git commit -m "test: cover mcp backed workflow server rpc"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 3: Add Server Construction Docs Status
|
|
|
|
**Files:**
|
|
- Modify: `docs/current_roadmap.md`
|
|
- Modify: `docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md`
|
|
|
|
- [ ] **Step 1: Update current roadmap**
|
|
|
|
In `docs/current_roadmap.md`, under **Durable API service shape**, replace the
|
|
remaining "concrete MCP-backed `WorkflowServer` construction remains future
|
|
work" language with:
|
|
|
|
```markdown
|
|
- Completed: MCP-backed `WorkflowServer` construction is available through
|
|
`wf_mcp.broker.server.build_workflow_server_from_config`. JSON-RPC can now
|
|
expose real MCP-backed workflow, source-admin, admin, and desired source
|
|
registry surfaces without making `wf_server` import `wf_mcp`.
|
|
```
|
|
|
|
Keep any longer-term note about shrinking/retiring old `wf_mcp` server entry
|
|
points; this slice does not retire them.
|
|
|
|
- [ ] **Step 2: Update long-lived API spec status**
|
|
|
|
In `docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md`,
|
|
update the status paragraph near the top to mention this slice:
|
|
|
|
```markdown
|
|
Status: Slices 1-4 implemented. `wf_server` provides
|
|
`build_local_static_workflow_server`; `wf_mcp.broker.server` can adapt MCP
|
|
broker config/services into the neutral `WorkflowServer`; `wf_transport_rpc_http`
|
|
provides JSON-RPC methods and client support; `wf_cli` has target-aware context;
|
|
and `wf_config` owns neutral config models. WebSocket transport, auth,
|
|
streaming/progress, database backend, and live source hot reload remain future
|
|
work.
|
|
```
|
|
|
|
Under **First Slice** implementation status, add:
|
|
|
|
```markdown
|
|
- Slice 4 complete: `wf_mcp.broker.server.build_workflow_server_from_config()`
|
|
returns a neutral `WorkflowServer` backed by MCP broker runtime services,
|
|
including source registry admin and platform admin surfaces.
|
|
```
|
|
|
|
- [ ] **Step 3: Run link/status search**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
rg -n "concrete MCP-backed `WorkflowServer` construction remains future work|Slices 1-3 implemented|MCP-backed `WorkflowServer`" docs/current_roadmap.md docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md
|
|
```
|
|
|
|
Expected:
|
|
|
|
- No stale "remains future work" claim for MCP-backed server construction.
|
|
- Status says Slices 1-4 implemented.
|
|
- The new constructor path is named.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add docs/current_roadmap.md docs/superpowers/specs/2026-06-03-long-lived-workflow-api-boundary.md
|
|
git commit -m "docs: record mcp backed workflow server"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 4: Final Verification
|
|
|
|
**Files:**
|
|
- Verify only.
|
|
|
|
- [ ] **Step 1: Run focused test set**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/test_mcp_workflow_server.py tests/wf_transport_rpc_http/test_mcp_backed_server_rpc.py tests/wf_server/test_local_static_server.py tests/wf_transport_rpc_http/test_source_registry_rpc.py -q
|
|
```
|
|
|
|
Expected: all tests pass.
|
|
|
|
- [ ] **Step 2: Run lint/type checks**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run ruff check src/wf_mcp/broker/server.py tests/wf_mcp/test_mcp_workflow_server.py tests/wf_transport_rpc_http/test_mcp_backed_server_rpc.py
|
|
uv run basedpyright --level error src/wf_mcp/broker/server.py tests/wf_mcp/test_mcp_workflow_server.py tests/wf_transport_rpc_http/test_mcp_backed_server_rpc.py
|
|
git diff --check
|
|
```
|
|
|
|
Expected: all commands exit 0. CRLF warnings from Git are acceptable; whitespace
|
|
errors are not.
|
|
|
|
- [ ] **Step 3: Review package dependency direction**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
rg -n "wf_mcp" src/wf_server
|
|
```
|
|
|
|
Expected: no matches.
|
|
|
|
- [ ] **Step 4: Final report**
|
|
|
|
Report:
|
|
|
|
- files created/modified
|
|
- verification output
|
|
- whether `wf_server` stayed MCP-free
|
|
- whether local/static source-registry unavailable behavior still passes
|
|
- any deviations from this plan
|
|
|
|
Do not run the full suite unless focused verification is green.
|
|
|
|
---
|
|
|
|
## Self-Review
|
|
|
|
- Spec coverage: covers the active roadmap gap "concrete MCP-backed `WorkflowServer` construction remains future work".
|
|
- Dependency direction: constructor lives in `wf_mcp`; `wf_server` remains MCP-free.
|
|
- Scope: no hot reload, auth redesign, process CLI, or persisted resume restart behavior.
|
|
- Testing: direct adapter tests plus JSON-RPC integration tests prove this is product-visible, not only internal wiring.
|
|
- Risk: `WorkflowServer.events` is currently typed as `InMemoryWorkflowEventRecorder`; if basedpyright rejects assigning `BrokerEventRecorder`, change that field type to `WorkflowEventRecorder` in `src/wf_server/context.py` and update no behavior. This is a type-only broadening and should be documented in the implementation report.
|